Update or execute actions on the Pay Request

Pay Requests

Operations

Create a Pay Request

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.

Security

JWT

Headers

Authorizationstringrequired

Default Bearer {$$.env.access_token}

Content-Typestringrequired

Value"application/json"

Bodyapplication/json

locationIdstringrequired

The id of the location as specified by the Tyro Connect system

providerobjectrequired

Details about the financial institution that processed the payment.

provider.namestringrequired

The name of the provider that processed the payment. More providers will be supported at a later date.

Value"TYRO"

provider.methodstringrequired

The payment method used. More methods will be supported at a later date.

Value"CARD"

originobjectrequired

Contains information about the partner that created the Pay Request.

origin.orderIdstring<= 50 charactersrequired

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

origin.orderReferencestring

Easily identifiable reference for the order.

origin.namestring

Name of the app partner that created the Pay Request.

payMethodobject

The Pay Method associated with the Pay Request

actionstring

When the payMethod.id and payMethod.customerId are provided. An action can be executed immediately without prompting the customer for input.

Value"SUBMIT"

captureobject

Optional field that can be used to specify how the funds will be captured.

totalobject(Money Positive Amount)required

The total amount (in smallest currency unit)

total.amountinteger>= 0required

This is the amount in smallest currency unit. e.g 12520 (in cents) is $125.20

Example: 12520

total.currencystringrequired

This is always AUD

Default "AUD"

Value"AUD"

Example: "AUD"

statementDescriptorstring

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.

statementDescriptorLocationstring

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.

curl -i -X POST \
  https://api.tyro.com/connect/pay/requests \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "locationId": "tc-cool-3000",
    "origin": {
      "orderId": "0f448ac1-862a-4c7b-bdb4-a3b7cdbf444"
    },
    "provider": {
      "name": "TYRO",
      "method": "CARD"
    },
    "total": {
      "amount": 10000,
      "currency": "AUD"
    }
  }'

Responses

Created

Bodyapplication/json

idstring

The ID of the Pay Request generated by Tyro.

paySecretstring

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.

locationIdstring

The id of the location as specified by the Tyro Connect system

providerobject

Details about the provider that processed the payment.

originobject

Contains information about the partner that created the Pay Request.

payMethodobject

The Pay Method details for the Pay Request

captureobject

statusstring

The current status of this Pay Request managed by Tyro.

Enum"AWAITING_PAYMENT_INPUT""AWAITING_AUTHENTICATION""PROCESSING""SUCCESS""FAILED""VOIDED""PARTIALLY_REFUNDED""REFUNDED"

supportedNetworksArray of strings

List of supported card type/brand/networks for this Pay Request. If null it is unrestricted.

Items Enum"visa""mastercard""amex""jcb""maestro""diners"

totalobject(Money Positive Amount)

The total amount (in smallest currency unit)

transactionResultsArray of objects(Transaction Result)

List of Transaction Results

threeDSecureDetailsobject

3D Secure details for this Pay Request

additionalDataobject

Additional data for this transaction

Response

application/json

{
  "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"
  }
}

Retrieve a Pay Request

Request

This endpoint is for fetching Pay Requests.

Security

JWT

Path

payRequestIdstringrequired

Headers

Authorizationstringrequired

Default Bearer {$$.env.access_token}

curl -i -X GET \
  'https://api.tyro.com/connect/pay/requests/{payRequestId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The Pay Request response

Bodyapplication/json

idstring

The ID of the Pay Request generated by Tyro.

paySecretstring

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.

locationIdstring

The id of the location as specified by the Tyro Connect system

providerobject

Details about the provider that processed the payment.

originobject

Contains information about the partner that created the Pay Request.

payMethodobject

The Pay Method details for the Pay Request

captureobject

statusstring

The current status of this Pay Request managed by Tyro.

Enum"AWAITING_PAYMENT_INPUT""AWAITING_AUTHENTICATION""PROCESSING""SUCCESS""FAILED""VOIDED""PARTIALLY_REFUNDED""REFUNDED"

supportedNetworksArray of strings

List of supported card type/brand/networks for this Pay Request. If null it is unrestricted.

Items Enum"visa""mastercard""amex""jcb""maestro""diners"

totalobject(Money Positive Amount)

The total amount (in smallest currency unit)

transactionResultsArray of objects(Transaction Result)

List of Transaction Results

threeDSecureDetailsobject

3D Secure details for this Pay Request

additionalDataobject

Additional data for this transaction

Response

application/json

{
  "id": "string",
  "paySecret": "string",
  "locationId": "string",
  "provider": {
    "name": "TYRO",
    "method": "CARD"
  },
  "origin": {
    "orderId": "string",
    "orderReference": "string",
    "name": "string"
  },
  "payMethod": {
    "id": "string",
    "customerId": "string",
    "save": true
  },
  "capture": {
    "method": "AUTOMATIC",
    "total": { … }
  },
  "status": "AWAITING_PAYMENT_INPUT",
  "supportedNetworks": [
    "visa"
  ],
  "total": {
    "amount": 12520,
    "currency": "AUD"
  },
  "transactionResults": [
    { … }
  ],
  "threeDSecureDetails": {
    "status": "AWAITING_3DS_METHOD"
  },
  "additionalData": {
    "customerIP": "127.0.0.1"
  }
}