Create a 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, given the terminal is not busy, or offline, the process to pay will be initialised.

Security

JWT

Headers

Authorizationstringrequired

Default Bearer {$$.env.access_token}

Content-Typestringrequired

Value"application/json"

Bodyapplication/json

midstringrequired

The merchant ID of the terminal as specified by the Tyro Account.

tidstringrequired

The terminal ID of the Tyro Terminal.

originobjectrequired

Contains information from 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.transactionIdstringrequired

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.

origin.namestring

Name or reference for this transaction used by the partner that created the Pay Request.

optionsobject

Configurable options for the terminal for this Pay Request.

totalobject(Pay Terminal Money Amounts)required

The terminal amounts (in smallest currency unit)

total.goodsAndServicesAmountinteger>= 0required

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

total.cashoutAmountinteger>= 0required

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

total.refundAmountinteger>= 0required

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

total.currencystringrequired

This is always AUD

Default "AUD"

Value"AUD"

Example: "AUD"

curl -i -X POST \
  https://api.tyro.com/connect/pay-terminal/requests \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "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

Created

Bodyapplication/json

idstring

The ID of the Pay Request generated by Tyro.

midstring

The merchant ID of the terminal as specified by the Tyro Account.

tidstring

The terminal ID of the Tyro Terminal.

originobject

Contains information from the partner that created the Pay Request.

statusstring

The current status of this Pay Request managed by Tyro.

Enum"AWAITING_INITIALISATION""PENDING""SUCCESS""FAILED"

transactionProgressobject

Additional information about the status of the transaction.

totalobject(Pay Terminal Money Amounts)

The total amount (in smallest currency unit)

pendingDecisionobject

The pending decision to be displayed on the POS. Values for this may be related to printing a receipt, or asking for a signature.

terminalProgressobject

The progress message displayed on the terminal.

transactionOutcomeobject

The outcome of the transaction after it has been processed by the terminal.

receiptsobject

This object contains printable receipts for the customer and merchant.

Response

application/json

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

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-terminal/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.

midstring

The merchant ID of the terminal as specified by the Tyro Account.

tidstring

The terminal ID of the Tyro Terminal.

originobject

Contains information from the partner that created the Pay Request.

statusstring

The current status of this Pay Request managed by Tyro.

Enum"AWAITING_INITIALISATION""PENDING""SUCCESS""FAILED"

transactionProgressobject

Additional information about the status of the transaction.

totalobject(Pay Terminal Money Amounts)

The total amount (in smallest currency unit)

pendingDecisionobject

The pending decision to be displayed on the POS. Values for this may be related to printing a receipt, or asking for a signature.

terminalProgressobject

The progress message displayed on the terminal.

transactionOutcomeobject

The outcome of the transaction after it has been processed by the terminal.

receiptsobject

This object contains printable receipts for the customer and merchant.

Response

application/json

{
  "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": [ … ]
  },
  "receipts": {
    "customer": "<This will be a printable receipt for the customer>",
    "merchant": "<This will be a printable receipt for the merchant>",
    "signature": "<This will be a printable receipt for the merchant if signature is required>"
  },
  "transactionOutcome": {
    "transactionResult": "Approved",
    "approvalCode": "00",
    "transactionReference": "xa29boybbo",
    "authorisationNumber": "674574564",
    "cardType": "visa",
    "elidedPan": "XXXXXXXXXXXX8635",
    "retrievalReferenceNumber": "63594680046125834000",
    "surchargeAmount": 300,
    "tipAmount": 500,
    "totalAmount": 6800
  }
}

Answer a Terminal Prompt

Request

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.

Security

JWT

Path

payRequestIdstringrequired

Headers

Authorizationstringrequired

Default Bearer {$$.env.access_token}

Content-Typestringrequired

Value"application/json"

Bodyapplication/json

decisionIdstringrequired

The corresponding decisionId as provided by the pendingDecision object of the payRequest

Example: "0f448ac1-862a-4c7b-bdb4-a3b7cdbf6149"

answerstringrequired

The exact case-sensitive answer as provided by the list of answers in the pendingDecision object of the payRequest

Example: "YES"

curl -i -X PUT \
  'https://api.tyro.com/connect/pay-terminal/requests/{payRequestId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "decisionId": "0f448ac1-862a-4c7b-bdb4-a3b7cdbf6149",
    "answer": "YES"
  }'

Responses

Accepted

Response

No content

Cancel a Pay Request

Request

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.

Security

JWT

Path

payRequestIdstringrequired

Headers

Authorizationstringrequired

Default Bearer {$$.env.access_token}

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

Responses

Accepted

Response

No content

Merchants

Operations

Pay Terminal API (0.9)

Pay Requests