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

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

## Header parameters:

  - `Authorization` (string, required)

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

## Request fields (application/json):

  - `mid` (string, required)
    The merchant ID of the terminal as specified by the Tyro Account.

  - `tid` (string, required)
    The terminal ID of the Tyro Terminal.

  - `origin` (object, required)
    Contains information from 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.transactionId` (string, required)
    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.name` (string)
    Name or reference for this transaction used by the partner that created the Pay Request.

  - `options` (object)
    Configurable options for the terminal for this Pay Request.

  - `options.integratedReceipt` (boolean)
    Whether or not a receipt will be printed from an integrated printer for this transaction in the event of an approval or decline.

  - `options.receiptWidth` (integer)
    The number of characters allowed on each line of any receipt generated for this transaction.

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

  - `total.goodsAndServicesAmount` (integer, required)
    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.cashoutAmount` (integer, required)
    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.refundAmount` (integer, required)
    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.currency` (string, required)
    This is always AUD
    Enum: "AUD"

## Response 201 fields (application/json):

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

  - `mid` (string)
    The merchant ID of the terminal as specified by the Tyro Account.

  - `tid` (string)
    The terminal ID of the Tyro Terminal.

  - `origin` (object)
    Contains information from 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.transactionId` (string)
    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.name` (string)
    Name or reference for this transaction used by the partner that created the Pay Request.

  - `status` (string)
    The current status of this Pay Request managed by Tyro.
    Enum: "AWAITING_INITIALISATION", "PENDING", "SUCCESS", "FAILED"

  - `transactionProgress` (object)
    Additional information about the status of the transaction.

  - `transactionProgress.id` (string)
    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"

  - `transactionProgress.description` (string)
    The free text description of the transaction progress message.

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

  - `total.goodsAndServicesAmount` (integer, required)
    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.cashoutAmount` (integer, required)
    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.refundAmount` (integer, required)
    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.currency` (string, required)
    This is always AUD
    Enum: "AUD"

  - `pendingDecision` (object)
    The pending decision to be displayed on the POS. Values for this may be related to printing a receipt, or asking for a signature.

  - `pendingDecision.decisionId` (string)
    The ID of the pending decision.

  - `pendingDecision.question` (string)
    The question to be displayed on the POS.

  - `pendingDecision.options` (array)

  - `terminalProgress` (object)
    The progress message displayed on the terminal.

  - `terminalProgress.id` (string)
    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.

  - `terminalProgress.description` (string)
    The free text description of the terminal progress message.

  - `transactionOutcome` (object)
    The outcome of the transaction after it has been processed by the terminal.

  - `transactionOutcome.transactionResult` (string)
    The outcome of the transaction after it has been processed by the terminal. "Approved", "Declined", "Terminated", "Cancelled"

  - `transactionOutcome.approvalCode` (string)
    The response code from the terminal. This is a numeric string that represents the outcome of the transaction.

  - `transactionOutcome.transactionReference` (string)
    The transaction reference number from the terminal. This is a unique identifier for the transaction.

  - `transactionOutcome.authorisationNumber` (string)
    The authorisation number from the acquirer. This is a unique identifier for the transaction.

  - `transactionOutcome.cardType` (string)
    The card type used in the transaction.

  - `transactionOutcome.elidedPan` (string)
    The PAN with all but the last 4 digits replaced with 'X'.

  - `transactionOutcome.retrievalReferenceNumber` (string)
    The retrieval reference number. This is a unique identifier for the transaction.

  - `transactionOutcome.surchargeAmount` (number)
    The surcharge amount in the smallest currency unit.

  - `transactionOutcome.tipAmount` (number)
    The tip amount in the smallest currency unit.

  - `transactionOutcome.totalAmount` (number)
    The total amount including any surcharge or tip in the smallest currency unit.

  - `receipts` (object)
    This object contains printable receipts for the customer and merchant.

  - `receipts.customer` (string)
    This will be a printable receipt for the customer

  - `receipts.merchant` (string)
    This will be a printable receipt for the merchant

  - `receipts.signature` (string)
    This will be a printable receipt for the merchant if signature is required

## Response 400 fields (application/json):

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

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

## Response 404 fields (application/json):

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

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

## Response 412 fields (application/json):

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

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


## Response 403 fields