openapi: 3.2.0 info: title: Tyro Pay Requests API version: '0.9' contact: {} description: 'Operations tagged Pay Requests across 2 of this provider''s published API definitions: tyro-connect-pay.yml, tyro-pos-pay-terminal.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://api.tyro.com/connect description: Production tags: - name: Pay Requests paths: /pay/requests: post: summary: Create a Pay Request operationId: create-pay-request tags: - Pay Requests description: 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. security: - JWT: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/new-pay-request' examples: Simple Pay Request: value: locationId: tc-cool-3000 origin: orderId: 0f448ac1-862a-4c7b-bdb4-a3b7cdbf444 provider: name: TYRO method: CARD total: amount: 10000 currency: AUD responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/pay-request-response' examples: Simple Pay Response: value: id: 0f448ac1-862a-4c7b-bdb4-a3b7cdbf6149 locationId: tc-cool-3000 provider: name: TYRO method: CARD origin: orderId: 1f448ac1-862a-4c7b-bdb4-a3b7cdbf6145 status: AWAITING_PAYMENT_INPUT supportedNetworks: - visa - mastercard action: null capture: method: AUTOMATIC paySecret: $2a$10$20qRi3XjN1PkTlEVDiYjHefra7c6i2i7yVNu9o5GGTO7ADsWNDuya total: amount: 10000 currency: AUD headers: {} '400': description: When the provided payload is not valid. content: application/json: schema: type: object properties: error: type: string description: The validation error message. errorCode: type: string description: The unique error code for message. examples: Missing property: value: error: '"locationId" is required' errorCode: VALIDATION_ERROR '403': description: When you don't have the right permissions to create a Pay Request for the provided location. parameters: - $ref: '#/components/parameters/header-bearer-token' - $ref: '#/components/parameters/header-content-json' servers: - url: https://api.tyro.com/connect description: Production /pay/requests/{payRequestId}: get: operationId: get-pay-request tags: - Pay Requests description: This endpoint is for fetching Pay Requests. summary: Retrieve a Pay Request responses: '200': description: The Pay Request response content: application/json: schema: $ref: '#/components/schemas/pay-request-response' '404': description: When the provided `payRequestId` does not match a Pay Request stored in the system. security: - JWT: [] parameters: - $ref: '#/components/parameters/header-bearer-token' - schema: type: string name: payRequestId in: path required: true patch: operationId: patch-pay-request tags: - Pay Requests summary: Update or execute actions on the Pay Request description: This endpoint is for updating a Pay Request or executing actions on the Pay Request. responses: '200': description: The Pay Request response content: application/json: schema: $ref: '#/components/schemas/pay-request-response' '400': description: When the provided payload is not valid. content: application/json: schema: type: object properties: error: type: string description: The validation error message. errorCode: type: string description: The unique error code for message. examples: Missing property: value: error: Requested capture amount exceeds authorised amount errorCode: PAY_REQUEST_CAPTURE_AMOUNT_EXCEEDED '404': description: When the provided `payRequestId` does not match a Pay Request stored in the system. security: - JWT: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/update-pay-request' examples: Perform Capture Action: value: action: CAPTURE Update Authorisation: value: action: UPDATE_AUTHORISATION authorisation: total: amount: 5000 currency: AUD Cancel a Pay Request: value: action: VOID Update Pay Total: value: total: amount: 10000 currency: AUD parameters: - $ref: '#/components/parameters/header-bearer-token' - schema: type: string name: payRequestId in: path required: true servers: - url: https://api.tyro.com/connect description: Production /pay-terminal/requests: post: summary: Create a Pay Request operationId: create-pay-terminal-request description: 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, given the terminal is not busy, or offline, the process to pay will be initialised. security: - JWT: [] tags: - Pay Requests requestBody: content: application/json: schema: $ref: '#/components/schemas/new-pay-request_2' examples: Simple Pay Request: value: mid: '123' tid: '456' origin: orderId: 2e6174ae-ba4f-4a02-8072-9304d862e320 transactionId: 2e6174ae-ba4f-4a02-8072-9304d862e320 total: goodsAndServicesAmount: 1000 cashoutAmount: 500 refundAmount: 0 currency: AUD responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/pay-request-response_2' examples: Simple Pay Response: value: id: 0f448ac1-862a-4c7b-bdb4-a3b7cdbf6149 mid: '123' tid: '456' status: AWAITING_INITIALISATION origin: orderId: 2e6174ae-ba4f-4a02-8072-9304d862e320 transactionId: 2e6174ae-ba4f-4a02-8072-9304d862e320 options: integratedReceipt: true receiptWidth: 60 total: goodsAndServicesAmount: 1000 cashoutAmount: 500 refundAmount: 0 currency: AUD headers: {} '400': description: When the provided payload is not valid. content: application/json: schema: type: object properties: error: type: string description: The validation error message. errorCode: type: string description: The unique error code for message. examples: Missing property: value: error: '"mid" is required' errorCode: VALIDATION_ERROR '403': description: When you don't have the right permissions to create a Pay Request for the provided mid. '404': description: When the provided mid is not found. content: application/json: schema: type: object properties: error: type: string description: The validation error message. errorCode: type: string description: The unique error code for message. examples: Missing property: value: error: Merchant ID not found. errorCode: MID_NOT_FOUND '412': description: When the terminal is not paired. content: application/json: schema: type: object properties: error: type: string description: The validation error message. errorCode: type: string description: The unique error code for message. examples: Missing property: value: error: Terminal is not paired. errorCode: TERMINAL_NOT_PAIRED parameters: - $ref: '#/components/parameters/header-bearer-token' - $ref: '#/components/parameters/header-content-json' servers: - url: https://api.tyro.com/connect description: Production /pay-terminal/requests/{payRequestId}: get: operationId: get-pay-terminal-request description: This endpoint is for fetching Pay Requests. summary: Retrieve a Pay Request tags: - Pay Requests responses: '200': description: The Pay Request response content: application/json: schema: $ref: '#/components/schemas/pay-request-response_2' examples: Simple Pay Response: value: id: a2be1eaf-b873-4aa9-9530-fc3007231572 mid: '123' tid: '456' status: SUCCESS total: currency: AUD cashoutAmount: 1000 goodsAndServicesAmount: 5000 refundAmount: 0 options: integratedReceipt: true receiptWidth: 60 origin: name: Example orderId: Pay Terminal Example transactionId: cffd6564-0023-44d8-996e-2932292277c2 transactionProgress: id: COMPLETE description: The transaction is processed pendingDecision: decisionId: 0f448ac1-862a-4c7b-bdb4-a3b7cdbf6149 question: Would you like to print a receipt? options: - 'YES' - 'NO' receipts: customer: merchant: signature: transactionOutcome: transactionResult: Approved approvalCode: '00' transactionReference: xa29boybbo authorisationNumber: '674574564' cardType: visa elidedPan: XXXXXXXXXXXX8635 retrievalReferenceNumber: '63594680046125834000' surchargeAmount: 300 tipAmount: 500 totalAmount: 6800 '404': description: When the provided `payRequestId` does not match a Pay Request stored in the system. security: - JWT: [] parameters: - $ref: '#/components/parameters/header-bearer-token' - schema: type: string name: payRequestId in: path required: true put: summary: Answer a Terminal Prompt operationId: answer-pay-terminal-prompt description: An async endpoint used for attempting to answer a pending decision prompt on a terminal. The decisionId & answer is returned by the payRequest in the pendingDecision object, and is required to differentiate prompt messages. There is no result to acknowledge that this decision was received by the terminal. parameters: - $ref: '#/components/parameters/header-bearer-token' - $ref: '#/components/parameters/header-content-json' - schema: type: string name: payRequestId in: path required: true security: - JWT: [] tags: - Pay Requests requestBody: content: application/json: schema: type: object properties: decisionId: type: string description: The corresponding decisionId as provided by the pendingDecision object of the payRequest example: 0f448ac1-862a-4c7b-bdb4-a3b7cdbf6149 answer: type: string description: The exact case-sensitive answer as provided by the list of answers in the pendingDecision object of the payRequest example: 'YES' required: - decisionId - answer responses: '202': description: Accepted headers: {} '400': description: When the provided payload is not valid. content: application/json: schema: type: object properties: error: type: string description: The validation error message. errorCode: type: string description: The unique error code for message. examples: Missing property: value: error: '"decisionId" is required' errorCode: VALIDATION_ERROR '403': description: When you don't have the right permissions to answer a pending decision for the provided payRequest. '412': description: When the terminal is not paired. content: application/json: schema: type: object properties: error: type: string description: The validation error message. errorCode: type: string description: The unique error code for message. examples: Missing property: value: error: Terminal is not paired. errorCode: TERMINAL_NOT_PAIRED delete: summary: Cancel a Pay Request operationId: cancel-pay-terminal-request description: An async endpoint used for attempting to cancel a pending decision prompt on a terminal. There is no result to acknowledge that this cancellation was processed by the terminal. If the transaction is already in a fully processed state, this call will be rejected. parameters: - $ref: '#/components/parameters/header-bearer-token' - schema: type: string name: payRequestId in: path required: true security: - JWT: [] tags: - Pay Requests responses: '202': description: Accepted headers: {} '403': description: When you don't have the right permissions to cancel a pending payRequest. '412': description: When the terminal is not paired. content: application/json: schema: type: object properties: error: type: string description: The validation error message. errorCode: type: string description: The unique error code for message. examples: Missing property: value: error: Terminal is not paired. errorCode: TERMINAL_NOT_PAIRED servers: - url: https://api.tyro.com/connect description: Production components: schemas: update-pay-request: title: Update Pay Request type: object oneOf: - title: Updating Authorisation required: - action - authorisation description: 'When the capture method is `MANUAL_ESTIMATED`, submitting this request will extend the authorisation holding period and allow you to increase the authorised amount. **Note:** This feature is only supported for Visa and Mastercard transactions and may not enabled by default for your account. ' properties: action: type: string enum: - UPDATE_AUTHORISATION authorisation: type: object required: - total properties: total: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: The new total amount to authorise (in smallest currency unit). It has to be greater than the original authorised amount. - title: Capturing Authorisation required: - action properties: action: type: string enum: - CAPTURE capture: type: object required: - total properties: total: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: The total amount to capture (in smallest currency unit). You cannot capture more than the authorised amount. - title: Voiding Authorisation required: - action properties: action: type: string enum: - VOID - title: Updating Pay Request without performing an action properties: total: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: The total amount (in smallest currency unit). The total can be updated without performing an action. payMethod: type: object properties: customerId: type: string description: The Tyro generated ID of the customer linked to this Pay Method. Pass `null` to remove a `customerId` from the pay request. save: type: boolean description: Indicates whether the pay method should be saved after a successful payment. required: - save transaction-result: title: Transaction Result type: object properties: merchant: type: string description: Merchant for this transaction authentication: type: object description: 3ds authentication details for this transaction properties: accessControlServerEci: type: string accessControlServerTransactionId: type: string acceptVersions: type: string amount: type: string additionalInfo: type: string authenticationToken: type: string 3dsServerTransactionId: type: string channel: type: string directoryServerId: type: string directoryServerTransactionId: type: string method: type: string methodCompleted: type: string methodSupported: type: string enum: - SUPPORTED - NOT_SUPPORTED payerInteraction: type: string protocolVersion: type: string redirectedDomainName: type: string requestorId: type: string requestorName: type: string statusReasonCode: type: string transactionId: type: string transactionStatus: type: string enum: - 'YES' - 'NO' - UNAVAILABLE - ATTEMPTED - CHALLENGE - REJECTED - DECOUPLED - INFORMATIONAL time: type: string version: type: string order: type: object description: Order for this transaction properties: id: type: string status: type: string currency: type: string reference: type: string amount: type: number authorisedAmount: type: number capturedAmount: type: number refundedAmount: type: number merchantCurrency: type: string merchantAmount: type: number createdAt: type: string updatedAt: type: string card: type: object description: Card used for this transaction properties: brand: type: string scheme: type: string expiry: type: object properties: month: type: string year: type: string nameOnCard: type: string number: type: string fundingMethod: type: string firstSixDigits: type: string lastFourDigits: type: string operationResult: type: object description: The result of this operation properties: result: type: string enum: - FAILURE - PENDING - SUCCESS - UNKNOWN acquirerCode: type: string gatewayCode: type: string authorisationCode: type: string errorCode: type: string errorMessage: type: string transaction: type: object description: The transaction for the operation properties: id: type: string type: type: string amount: type: number currency: type: string retrievalReferenceNumber: type: string acquirer: type: object properties: id: type: string merchantId: type: string additionalResponse: type: string new-pay-request: title: New Pay Request type: object properties: locationId: type: string description: The id of the location as specified by the Tyro Connect system provider: type: object description: Details about the financial institution that processed the payment. properties: name: type: string description: The name of the provider that processed the payment. More providers will be supported at a later date. enum: - TYRO method: type: string description: The payment method used. More methods will be supported at a later date. enum: - CARD required: - name - method origin: description: Contains information about the partner that created the Pay Request. type: object properties: orderId: type: string maxLength: 50 description: An identifier that has been generated by the origin. This can be used for reconciliation of orders in the app partner’s system. orderReference: type: string description: Easily identifiable reference for the order. name: type: string description: Name of the app partner that created the Pay Request. required: - orderId payMethod: description: The Pay Method associated with the Pay Request type: object properties: id: type: string description: 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. customerId: type: string description: 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. save: type: boolean description: 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: type: string description: When the `payMethod.id` and `payMethod.customerId` are provided. An action can be executed immediately without prompting the customer for input. enum: - SUBMIT capture: description: Optional field that can be used to specify how the funds will be captured. type: object properties: method: type: string description: '- `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 total: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: The total amount to capture (in smallest currency unit). You cannot capture more than the authorised amount. required: - method total: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: The total amount (in smallest currency unit) statementDescriptor: type: string description: 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: type: string description: 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. required: - locationId - total - provider - origin money-positive-aud: title: Money Positive Amount type: object properties: amount: type: integer description: This is the amount in smallest currency unit. e.g 12520 (in cents) is $125.20 example: 12520 minimum: 0 currency: type: string default: AUD enum: - AUD example: AUD description: This is always AUD required: - amount - currency pay-request-response: title: Pay Request Response type: object properties: id: type: string description: The ID of the Pay Request generated by Tyro. paySecret: type: string description: 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: type: string description: The id of the location as specified by the Tyro Connect system provider: type: object description: Details about the provider that processed the payment. properties: name: type: string description: The name of the provider that processed the payment. More providers will be supported at a later date. enum: - TYRO method: type: string description: The payment method used enum: - CARD origin: description: Contains information about the partner that created the Pay Request. type: object properties: orderId: type: string maxLength: 50 description: An identifier that has been generated by the origin. This can be used for reconciliation of orders in the app partner’s system. orderReference: type: string description: Easily identifiable reference for the order. name: type: string description: Name of the app partner that created the Pay Request. payMethod: description: The Pay Method details for the Pay Request type: object properties: id: type: string description: The id of the Pay Method attached to the Pay Request. customerId: type: string description: The Tyro generated ID of the customer linked to the Pay Method. save: type: boolean description: When set to true, the pay method will be saved after a successful payment. capture: type: object properties: method: type: string description: '- `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 total: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: The total amount to capture (in smallest currency unit). You cannot capture more than the authorised amount. status: type: string description: The current status of this Pay Request managed by Tyro. enum: - AWAITING_PAYMENT_INPUT - AWAITING_AUTHENTICATION - PROCESSING - SUCCESS - FAILED - VOIDED - PARTIALLY_REFUNDED - REFUNDED supportedNetworks: type: array description: List of supported card type/brand/networks for this Pay Request. If null it is unrestricted. items: type: string enum: - visa - mastercard - amex - jcb - maestro - diners total: allOf: - $ref: '#/components/schemas/money-positive-aud' - description: The total amount (in smallest currency unit) transactionResults: type: array description: List of Transaction Results items: $ref: '#/components/schemas/transaction-result' threeDSecureDetails: type: object description: 3D Secure details for this Pay Request properties: status: type: string description: Current 3D Secure status for this Pay Request enum: - AWAITING_3DS_METHOD - AWAITING_AUTH - AWAITING_CHALLENGE - AWAITING_CHALLENGE_RESULT - SUCCESS - FAILED example: AWAITING_3DS_METHOD additionalData: type: object description: Additional data for this transaction properties: customerIP: type: string example: 127.0.0.1 new-pay-request_2: title: New Pay Request type: object properties: mid: type: string description: The merchant ID of the terminal as specified by the Tyro Account. tid: type: string description: The terminal ID of the Tyro Terminal. origin: description: Contains information from the partner that created the Pay Request. type: object properties: orderId: type: string maxLength: 50 description: An identifier that has been generated by the origin. This can be used for reconciliation of orders in the app partner’s system. transactionId: type: string description: A UUIDv4 provided by the partner to be used for preventing duplicate transactions, for us in reinitialisation of the terminal on an already attempted pending transaction. name: type: string description: Name or reference for this transaction used by the partner that created the Pay Request. required: - orderId - transactionId options: description: Configurable options for the terminal for this Pay Request. type: object properties: integratedReceipt: type: boolean default: true description: Whether or not a receipt will be printed from an integrated printer for this transaction in the event of an approval or decline. receiptWidth: type: integer minimum: 28 maximum: 500 default: 60 description: The number of characters allowed on each line of any receipt generated for this transaction. total: allOf: - $ref: '#/components/schemas/pay-terminal-total' - description: The terminal amounts (in smallest currency unit) required: - mid - tid - total - origin pay-terminal-total: title: Pay Terminal Money Amounts type: object properties: goodsAndServicesAmount: type: integer description: This is the goods and services amount in smallest currency unit. e.g 12520 (in cents) is $125.20. It can be used in combination with cashoutAmount. It cannot be used in combination with refundAmount. example: 12520 minimum: 0 cashoutAmount: type: integer description: This is the requested cashout amount in smallest currency unit. e.g 5000 (in cents) is $50.00. It can be used in combination with goodsAndServicesAmount. It cannot be used in combination with refundAmount. example: 5000 minimum: 0 refundAmount: type: integer description: This is the refund amount in smallest currency unit. e.g 12520 (in cents) is $125.20. It cannot be used in combination with goodsAndServicesAmount or cashoutAmount. example: 12520 minimum: 0 currency: type: string default: AUD enum: - AUD example: AUD description: This is always AUD required: - goodsAndServicesAmount - cashoutAmount - refundAmount - currency pay-request-response_2: title: Pay Request Response type: object properties: id: type: string description: The ID of the Pay Request generated by Tyro. mid: type: string description: The merchant ID of the terminal as specified by the Tyro Account. tid: type: string description: The terminal ID of the Tyro Terminal. origin: description: Contains information from the partner that created the Pay Request. type: object properties: orderId: type: string maxLength: 50 description: An identifier that has been generated by the origin. This can be used for reconciliation of orders in the app partner’s system. transactionId: type: string description: A UUIDv4 provided by the partner to be used for preventing duplicate transactions, for us in reinitialisation of the terminal on an already attempted pending transaction. name: type: string description: Name or reference for this transaction used by the partner that created the Pay Request. status: type: string description: The current status of this Pay Request managed by Tyro. enum: - AWAITING_INITIALISATION - PENDING - SUCCESS - FAILED transactionProgress: type: object description: Additional information about the status of the transaction. properties: id: type: string description: The id of the transaction progress message. This can be used to determine further detail of what occurred during processing such as "COMPLETE", "PENDING", "REJECTED", "DEAD" description: type: string description: The free text description of the transaction progress message. total: allOf: - $ref: '#/components/schemas/pay-terminal-total' - description: The total amount (in smallest currency unit) pendingDecision: type: object description: The pending decision to be displayed on the POS. Values for this may be related to printing a receipt, or asking for a signature. properties: decisionId: type: string description: The ID of the pending decision. question: type: string description: The question to be displayed on the POS. options: type: array items: type: string description: The options to be displayed on the POS. terminalProgress: type: object description: The progress message displayed on the terminal. properties: id: type: string description: The id of the terminal progress message. You can use this to filter what messages you would wish to display on the POS, or to customize messages. description: type: string description: The free text description of the terminal progress message. transactionOutcome: type: object description: The outcome of the transaction after it has been processed by the terminal. properties: transactionResult: type: string description: The outcome of the transaction after it has been processed by the terminal. "Approved", "Declined", "Terminated", "Cancelled" approvalCode: type: string description: The response code from the terminal. This is a numeric string that represents the outcome of the transaction. transactionReference: type: string description: The transaction reference number from the terminal. This is a unique identifier for the transaction. authorisationNumber: type: string description: The authorisation number from the acquirer. This is a unique identifier for the transaction. cardType: type: string description: The card type used in the transaction. elidedPan: type: string description: The PAN with all but the last 4 digits replaced with 'X'. retrievalReferenceNumber: type: string description: The retrieval reference number. This is a unique identifier for the transaction. surchargeAmount: type: number description: The surcharge amount in the smallest currency unit. tipAmount: type: number description: The tip amount in the smallest currency unit. totalAmount: type: number description: The total amount including any surcharge or tip in the smallest currency unit. receipts: type: object description: This object contains printable receipts for the customer and merchant. properties: customer: type: string description: This will be a printable receipt for the customer merchant: type: string description: This will be a printable receipt for the merchant signature: type: string description: This will be a printable receipt for the merchant if signature is required parameters: header-bearer-token: schema: type: string default: Bearer {$$.env.access_token} in: header name: Authorization required: true header-content-json: schema: type: string enum: - application/json in: header name: Content-Type required: true securitySchemes: JWT: type: openIdConnect openIdConnectUrl: https://auth.connect.tyro.com/.well-known/openid-configuration x-refined-from: - tyro-connect-pay.yml - tyro-pos-pay-terminal.yml