# Create a pay request

This endpoint is used for creating a Pay Request. Your server should create a Pay Request as soon as the total payment amount is known. Once the Pay Request is created, your frontend will use Tyro.js to collect the customer's payment details and invoke submit() to execute the payment.

Endpoint: POST /pay/requests
Version: 0.9
Security: JWT

## Header parameters:

  - `Authorization` (string, required)

  - `Content-Type` (string, required)
    Enum: "application/json"

## Request fields (application/json):

  - `locationId` (string, required)
    The id of the location as specified by the Tyro Connect system

  - `provider` (object, required)
    Details about the financial institution that processed the payment.

  - `provider.name` (string, required)
    The name of the provider that processed the payment. More providers will be supported at a later date.
    Enum: "TYRO"

  - `provider.method` (string, required)
    The payment method used. More methods will be supported at a later date.
    Enum: "CARD"

  - `origin` (object, required)
    Contains information about the partner that created the Pay Request.

  - `origin.orderId` (string, required)
    An identifier that has been generated by the origin. This can be used for reconciliation of orders in the app partner’s system.

  - `origin.orderReference` (string)
    Easily identifiable reference for the order.

  - `origin.name` (string)
    Name of the app partner that created the Pay Request.

  - `payMethod` (object)
    The Pay Method associated with the Pay Request

  - `payMethod.id` (string)
    The id of the Pay Method to use for this Pay Request. When the provided Pay Method is valid, the Pay Request can be submitted immediately without prompting the customer for payment details.

  - `payMethod.customerId` (string)
    The Tyro generated ID of the customer linked to this Pay Method. If no payMethod.customerId is provided when payMethod.save is true, then a new payMethod.customerId is generated by Tyro. Otherwise, pass the customerId if this is a returning customer.

  - `payMethod.save` (boolean)
    When set to true, the pay method will be saved after a successful payment. The pay method can then be used to make future payments.

  - `action` (string)
    When the payMethod.id and payMethod.customerId are provided. An action can be executed immediately without prompting the customer for input.
    Enum: "SUBMIT"

  - `capture` (object)
    Optional field that can be used to specify how the funds will be captured.

  - `capture.method` (string, required)
    - AUTOMATIC (default) - captures the funds upon Pay Request submission.
- MANUAL - can be used to put funds on hold and only authorise the payment, with the funds captured later.
- MANUAL_ESTIMATED - can be used when you want to authorise an estimated amount, with the funds captured later. With this option, you can update the authorised amount before capture or expiration.
    Enum: "AUTOMATIC", "MANUAL", "MANUAL_ESTIMATED"

  - `capture.total` (object)
    The total amount to capture (in smallest currency unit). You cannot capture more than the authorised amount.

  - `capture.total.amount` (integer, required)
    This is the amount in smallest currency unit. e.g 12520 (in cents) is $125.20
    Example: 12520

  - `capture.total.currency` (string, required)
    This is always AUD
    Enum: "AUD"

  - `total` (object, required)
    The total amount (in smallest currency unit)

  - `total.amount` (integer, required)
    This is the amount in smallest currency unit. e.g 12520 (in cents) is $125.20
    Example: 12520

  - `total.currency` (string, required)
    This is always AUD
    Enum: "AUD"

  - `statementDescriptor` (string)
    Statement descriptors are used to explain to a customer the charges that appear on their bank statement. There is a maximum of 21 characters and special characters such as {}'" are disallowed. The descriptor should be as clear and recognisable as possible. The descriptor can be dynamic and include invoice numbers or other references to help the customer recognise the charge.

  - `statementDescriptorLocation` (string)
    This is the city or web address where the transaction occurred. There is a maximum of 13 characters and special characters such as {}'" are disallowed.

## Response 201 fields (application/json):

  - `id` (string)
    The ID of the Pay Request generated by Tyro.

  - `paySecret` (string)
    The Pay Secret associated with this Pay Request. This is used by the frontend to submit the Pay Request. Pay Secret expire after 24 hours from the time the Pay Request was created. It’s recommended to avoid logging or storing the pay secret for security reasons.

  - `locationId` (string)
    The id of the location as specified by the Tyro Connect system

  - `provider` (object)
    Details about the provider that processed the payment.

  - `provider.name` (string)
    The name of the provider that processed the payment. More providers will be supported at a later date.
    Enum: "TYRO"

  - `provider.method` (string)
    The payment method used
    Enum: "CARD"

  - `origin` (object)
    Contains information about the partner that created the Pay Request.

  - `origin.orderId` (string)
    An identifier that has been generated by the origin. This can be used for reconciliation of orders in the app partner’s system.

  - `origin.orderReference` (string)
    Easily identifiable reference for the order.

  - `origin.name` (string)
    Name of the app partner that created the Pay Request.

  - `payMethod` (object)
    The Pay Method details for the Pay Request

  - `payMethod.id` (string)
    The id of the Pay Method attached to the Pay Request.

  - `payMethod.customerId` (string)
    The Tyro generated ID of the customer linked to the Pay Method.

  - `payMethod.save` (boolean)
    When set to true, the pay method will be saved after a successful payment.

  - `capture` (object)

  - `capture.method` (string)
    - AUTOMATIC (default) - captures the funds upon Pay Request submission.
- MANUAL - can be used to put funds on hold and only authorise the payment, with the funds captured later.
- MANUAL_ESTIMATED - can be used when you want to authorise an estimated amount, with the funds captured later. With this option, you can update the authorised amount before capture or expiration.
    Enum: "AUTOMATIC", "MANUAL", "MANUAL_ESTIMATED"

  - `capture.total` (object)
    The total amount to capture (in smallest currency unit). You cannot capture more than the authorised amount.

  - `capture.total.amount` (integer, required)
    This is the amount in smallest currency unit. e.g 12520 (in cents) is $125.20
    Example: 12520

  - `capture.total.currency` (string, required)
    This is always AUD
    Enum: "AUD"

  - `status` (string)
    The current status of this Pay Request managed by Tyro.
    Enum: "AWAITING_PAYMENT_INPUT", "AWAITING_AUTHENTICATION", "PROCESSING", "SUCCESS", "FAILED", "VOIDED", "PARTIALLY_REFUNDED", "REFUNDED"

  - `supportedNetworks` (array)
    List of supported card type/brand/networks for this Pay Request. If null it is unrestricted.
    Enum: "visa", "mastercard", "amex", "jcb", "maestro", "diners"

  - `total` (object)
    The total amount (in smallest currency unit)

  - `total.amount` (integer, required)
    This is the amount in smallest currency unit. e.g 12520 (in cents) is $125.20
    Example: 12520

  - `total.currency` (string, required)
    This is always AUD
    Enum: "AUD"

  - `transactionResults` (array)
    List of Transaction Results

  - `transactionResults.merchant` (string)
    Merchant for this transaction

  - `transactionResults.authentication` (object)
    3ds authentication details for this transaction

  - `transactionResults.authentication.accessControlServerEci` (string)

  - `transactionResults.authentication.accessControlServerTransactionId` (string)

  - `transactionResults.authentication.acceptVersions` (string)

  - `transactionResults.authentication.amount` (string)

  - `transactionResults.authentication.additionalInfo` (string)

  - `transactionResults.authentication.authenticationToken` (string)

  - `transactionResults.authentication.3dsServerTransactionId` (string)

  - `transactionResults.authentication.channel` (string)

  - `transactionResults.authentication.directoryServerId` (string)

  - `transactionResults.authentication.directoryServerTransactionId` (string)

  - `transactionResults.authentication.method` (string)

  - `transactionResults.authentication.methodCompleted` (string)

  - `transactionResults.authentication.methodSupported` (string)
    Enum: "SUPPORTED", "NOT_SUPPORTED"

  - `transactionResults.authentication.payerInteraction` (string)

  - `transactionResults.authentication.protocolVersion` (string)

  - `transactionResults.authentication.redirectedDomainName` (string)

  - `transactionResults.authentication.requestorId` (string)

  - `transactionResults.authentication.requestorName` (string)

  - `transactionResults.authentication.statusReasonCode` (string)

  - `transactionResults.authentication.transactionId` (string)

  - `transactionResults.authentication.transactionStatus` (string)
    Enum: "YES", "NO", "UNAVAILABLE", "ATTEMPTED", "CHALLENGE", "REJECTED", "DECOUPLED", "INFORMATIONAL"

  - `transactionResults.authentication.time` (string)

  - `transactionResults.authentication.version` (string)

  - `transactionResults.order` (object)
    Order for this transaction

  - `transactionResults.order.id` (string)

  - `transactionResults.order.status` (string)

  - `transactionResults.order.currency` (string)

  - `transactionResults.order.reference` (string)

  - `transactionResults.order.amount` (number)

  - `transactionResults.order.authorisedAmount` (number)

  - `transactionResults.order.capturedAmount` (number)

  - `transactionResults.order.refundedAmount` (number)

  - `transactionResults.order.merchantCurrency` (string)

  - `transactionResults.order.merchantAmount` (number)

  - `transactionResults.order.createdAt` (string)

  - `transactionResults.order.updatedAt` (string)

  - `transactionResults.card` (object)
    Card used for this transaction

  - `transactionResults.card.brand` (string)

  - `transactionResults.card.scheme` (string)

  - `transactionResults.card.expiry` (object)

  - `transactionResults.card.expiry.month` (string)

  - `transactionResults.card.expiry.year` (string)

  - `transactionResults.card.nameOnCard` (string)

  - `transactionResults.card.number` (string)

  - `transactionResults.card.fundingMethod` (string)

  - `transactionResults.card.firstSixDigits` (string)

  - `transactionResults.card.lastFourDigits` (string)

  - `transactionResults.operationResult` (object)
    The result of this operation

  - `transactionResults.operationResult.result` (string)
    Enum: "FAILURE", "PENDING", "SUCCESS", "UNKNOWN"

  - `transactionResults.operationResult.acquirerCode` (string)

  - `transactionResults.operationResult.gatewayCode` (string)

  - `transactionResults.operationResult.authorisationCode` (string)

  - `transactionResults.operationResult.errorCode` (string)

  - `transactionResults.operationResult.errorMessage` (string)

  - `transactionResults.transaction` (object)
    The transaction for the operation

  - `transactionResults.transaction.id` (string)

  - `transactionResults.transaction.type` (string)

  - `transactionResults.transaction.amount` (number)

  - `transactionResults.transaction.currency` (string)

  - `transactionResults.transaction.retrievalReferenceNumber` (string)

  - `transactionResults.transaction.acquirer` (object)

  - `transactionResults.transaction.acquirer.id` (string)

  - `transactionResults.transaction.acquirer.merchantId` (string)

  - `transactionResults.transaction.acquirer.additionalResponse` (string)

  - `threeDSecureDetails` (object)
    3D Secure details for this Pay Request

  - `threeDSecureDetails.status` (string)
    Current 3D Secure status for this Pay Request
    Enum: "AWAITING_3DS_METHOD", "AWAITING_AUTH", "AWAITING_CHALLENGE", "AWAITING_CHALLENGE_RESULT", "SUCCESS", "FAILED"

  - `additionalData` (object)
    Additional data for this transaction

  - `additionalData.customerIP` (string)
    Example: "127.0.0.1"

## Response 400 fields (application/json):

  - `error` (string)
    The validation error message.

  - `errorCode` (string)
    The unique error code for message.


## Response 403 fields