Integration Guides
SUPPORT CENTREEZYPAY

Tap to Pay Integration

Suggest Edits

Ezypay Tap to Pay: Turn mobile devices into payment terminals

Ezypay’s Tap to Pay solution lets NFC-enabled mobile devices accept credit and debit card payments. It currently supports Mastercard and Visa in Australia.

Merchants install the Ezypay mobile app on a compatible device to enable payments. Before use, the device must be registered and activated via the integrator’s platform.

Device Registration and Activation

1. Install the Terminal Application

Install the Ezypay mobile application for terminal on a compatible device. Once installed, the application will display a Device ID on screen.

2. Collect Device Information

Integrators will need to build a new UI to collect the following information from the merchant:

  • Device ID - Provided by the terminal application
  • Device Name - A label used to identify the terminal

🚧

Important

The Device ID must be stored in integrators database as it is required when creating a terminal invoice.

3. Register the Device

Authenticate with Ezypay using the Authentication API. Then call the new Terminal Registration API, passing the captured Device ID and Device Name.

4. Display Activation Code

The Terminal Registration API will return an activation code. Display this code in your UI so that the merchant can input it into the terminal application to complete the registration.

5. Handle Activation Webhook

Once registration is complete, Ezypay will send a new terminal_registration webhook to confirm the device is successfully activated.

Terminal Invoice Creation

1. Authentication

Integrators authenticate with Ezypay using the Authentication API.

2. Create Terminal Invoice

A new create terminal invoice API is available to create terminal invoices.

Depending on the integrator’s platform, a new UI or an update to the existing UI is required to support this step.

3. Capture Invoice ID

Store the invoice ID returned from the API to track the payment status.

4. Prompt for Payment

Ezypay will wake the registered terminal device and prompt the customer to tap their card.

5. Payment Processing

Payment details captured by the terminal is used to process they payment.

6. Handle Payment Webhook

A new terminal_response webhook is sent by Ezypay to notify the payment outcome: success or fail. If the payment fails and needs to be retried, start again from Step 2.

🚧

Attention

After receiving the terminal_response webhook, no actions can be performed on the invoice other than refund. E.g. failed invoices cannot be retry, invoice details cannot be update etc.

Refunds

Refunds cannot be processed directly on the terminal device. You can initiate a normal refund using Ezypay's APIs.

Terminal Payment Status APIs

Ezypay provides two new APIs for terminal payment status retrieval:

  1. List Terminal Invoices
    1. Retrieves a list of payments made via terminals for the merchant, including their latest statuses.
    2. Useful for displaying all terminal payments on your platform.
  2. Retrieve Terminal Invoice
    1. Provides detailed information on a specific payment based on the Invoice ID.
    2. Use this to confirm payment outcomes.

These APIs are optional. If your integration already processes webhook notifications, you can use the information stored in your database instead.

Terminal Device Requirements

AndroidiPhone
Minimum Android 12, with March 5th 2022 security patchMinimum iOS 17.0
Must not be a payment terminalMust not be a payment terminal
Must not have an integrated card readerMust not have an integrated card reader.
Must have an integrated NFC readerMust have a screen lock passcode configured on the device
Must have an integrated touch screenThe iPhone model must be iPhone XS or later
Must support hardware key attestation and be Google-certified .

❗️

Important!

Whenever Android stops supporting security patches for an OS version, the device is no longer compatible. Therefore, it is important to ensure your Android devices are easy to update.

Terminal Registration API

Endpoint: [POST] https://api-sandbox.ezypay.com/v2/billing/terminal/register

Important Request Field:

ParameterExplanationMandatory
appDeviceIdReturn by the terminal application after installed in the terminal device in UUID form.Yes
deviceNameA label for user to identify the relevant terminal device.Yes
{
  "appDeviceId": "XYZ-test-ezypay-9" ,
  "deviceName":"Ezypay-test-1"
}

{
  "code": 499088,
  "deviceName": "Ezypay-test-1"
}

Display the value of the code in the response on screen and prompt user to input into the terminal application to complete registration.

New Webhook terminal_registration

A terminal_registration webhook return the terminal registration outcome to integrators.

🚧

Attention

The terminal_registration only triggered when the terminal registration is successful. If you did not received this webhook in an hour after completing your terminal registration, please reach out to Ezypay team to check on the terminal status.

{
  "requestId": "3d869c4e-1bf6-4316-b0ff-0e7574bb6596",
  "merchantId": "9d262c1f-0ee3-430d-be8a-3cd9006a5002",
  "eventType": "TERMINAL_REGISTRATION",
  "createdOn": "2025-04-28T01:53:02.419",
  "data": {
    "merchantId": "9d262c1f-0ee3-430d-be8a-3cd9006a5002",
    "appDeviceId": "e2c92b449942b080",
    "deviceName": "Azizan-test-1000J",
    "status": "SUCCESS",
    "modifiedOn": "2025-04-28T01:53:02.419",
    "failReason": null
  }
}

Sandbox Testing Guide

Terminal Registration

You do not need a physical device to perform sandbox testing. To simulate terminal registration:

  1. Send a registration request with any arbitrary value for the appDeviceId in the request body.
  2. Upon receiving a successful response, contact the Ezypay team to activate the device on the backend.
  3. Once activated, a terminal_registration webhook will be triggered and returned to your system, confirming the successful registration of the test device.

Terminal Invoice Simulation

In the sandbox environment, terminal invoices will return a PAID status for any entered amount, except for the specific values listed below. These amounts are preconfigured to simulate common payment failures, allowing you to test your error handling logic.

AmountSimulated Failure Reason
1951: Insufficient funds / Over credit limit / Not sufficient funds
2954: Expired card
49905_1: Could not find an acquirer account for the provided txvariant (amex), currency (AUD), and action (AUTH)

Create Terminal Invoice API

Endpoint: [POST] https://api-sandbox.ezypay.com/v2/billing/terminal/invoices

Important Request Field:

ParameterExplanationMandatory
customerIdEzypay's customer ID in UUID format.No
terminalIdUsed to identified which device will be waked up and prompt customer for payment.Yes
itemsArray of objects representing items to bill.Yes
items.amountAmount object, including currency and valueYes
items.descriptionDescription of each item billed.Yes
items.accountingCodeUsed to group similar items in the report.No
externalInvoiceIdUsed to specify the invoice ID from integrators' platform. Requires unique value to achieves idempotency.No
memoMore detailed description on the invoice. Max of 100 charactersNo
{
    "customerId": "491cbfa2-7225-4b5e-bf1a-1ac9a292df7a",    
    "memo": "this is a test invoice for terminal",
    "terminalId": "<from device>",
    "externalInvoiceId": "<from merchant>",
    "items": [{
    	"amount": {
        	"currency": "AUD",
        	"value": 100
    	},
    	"description": "this is a test invoice for Terminal Invoice ",
      "accountingCode": "TERMINAL"
    }]
}

{
    "id": "eeb642f9-01e1-441b-8b16-4ebd10cd3809",
    "creditNoteId": null,
    "documentNumber": "IN0000000000013975",
    "date": "2025-03-14",
    "dueDate": "2025-03-14",
    "scheduledPaymentDate": null,
    "status": "PENDING_TAP_PAYMENT",
    "memo": "this is a test invoice for tap to pay",
    "items": [
      {
        "description": "this is a test invoice for FRS ",
        "amount": {
          "currency": "AUD",
          "value": 1000,
          "type": null
        },
        "tax": {
          "rate": 10
        },
        "id": "1b98fb12-5022-4390-ac4c-02ef30165687",
        "type": "on_demand_payment",
        "discounted": {
          "currency": "AUD",
          "value": 0,
          "type": null
        },
        "accountingCode": null
      },
      {
        "description": "Transaction fee Terminal",
        "amount": {
          "currency": "AUD",
          "value": 2,
          "type": null
        },
        "tax": {
          "rate": 10
        },
        "id": "6cb5fb6b-3054-4f61-9bac-d3128d8da8c8",
        "type": "transaction_fee",
        "discounted": {
          "currency": "AUD",
          "value": 0,
          "type": null
        },
        "accountingCode": null
      }
    ],
    "amount": {
      "currency": "AUD",
      "value": 1002,
      "type": null
    },
    "amountWithoutDiscount": {
      "currency": "AUD",
      "value": 1002,
      "type": null
    },
    "totalDiscounted": {
      "currency": "AUD",
      "value": 0,
      "type": null
    },
    "totalRefunded": {
      "currency": "AUD",
      "value": 0,
      "type": null
    },
    "totalTax": {
      "currency": "AUD",
      "value": 91.09,
      "type": null
    },
    "customerId": null,
    "subscriptionId": null,
    "checkoutId": null,
    "subscriptionName": null,
    "paymentMethodToken": null,
    "paymentMethodData": null,
    "autoPayment": false,
    "processingModel": "TAP_TO_PAY",
    "transactionSource": null,
    "createdOn": "2025-03-14T00:49:42.016",
    "payNowUrl": null,
    "channel": "MOBILE_POINT_OF_SALE",
    "checkoutResult": null,
    "customerFirstName": null,
    "customerLastName": null,
    "terminalId": "195a48b4-735f-4697-8702-102b1facaad8",
    "externalInvoiceId":"195a48b4-735f-4697-8702-102b1facaad7"
}

New Webhook terminal_response

A terminal_response webhook return result for the corresponding terminal payment. Use the field data.status to identify the payment outcome and data.id field to link it back to an Ezypay invoice.

📘

Attention

Make sure you have updated your webhook to receive the new terminal_response event, else it won't be sent to you.

{
    "requestId": "3d869c4e-1bf6-4316-b0ff-0e7574bb6596",
    "merchantId": "9d262c1f-0ee3-430d-be8a-3cd9006a5002",
    "eventType": "TERMINAL_RESPONSE",
    "createdOn": "2025-04-28T01:53:02.419",
    "data": {
      "id": "eb8643b1-aba8-40bb-bc89-354851639d8f",
      "creditNoteId": null,
      "documentNumber": "IN0000000000000275",
      "date": "2025-04-28",
      "dueDate": "2025-04-28",
      "scheduledPaymentDate": null,
      "status": "PAID",
      "memo": null,
      "items": [
        {
          "description": "this is a test invoice for Terminal ",
          "amount": {
            "currency": "AUD",
            "value": 1000,
            "type": null
          },
          "tax": {
            "rate": 10
          },
          "id": "a2cba906-a4b6-4ae8-9146-65f689d6945e",
          "type": "on_demand_payment",
          "discounted": null,
          "accountingCode": null
        },
        {
          "description": "Transaction fee Terminal",
          "amount": {
            "currency": "AUD",
            "value": 2,
            "type": null
          },
          "tax": {
            "rate": 10
          },
          "id": "662f46e3-186f-4661-a310-3514ce156001",
          "type": "transaction_fee",
          "discounted": null,
          "accountingCode": null
        },
        {
          "description": "Transaction fee Terminal",
          "amount": {
            "currency": "AUD",
            "value": 200,
            "type": null
          },
          "tax": {
            "rate": 10
          },
          "id": "8ddb3369-7e05-4350-89c8-fc25c9dab94f",
          "type": "transaction_fee",
          "discounted": null,
          "accountingCode": null
        }
      ],
      "amount": {
        "currency": "AUD",
        "value": 1202,
        "type": null
      },
      "amountWithoutDiscount": {
        "currency": "AUD",
        "value": 1202,
        "type": null
      },
      "totalDiscounted": {
        "currency": "AUD",
        "value": 0,
        "type": null
      },
      "totalRefunded": {
        "currency": "AUD",
        "value": 0,
        "type": null
      },
      "totalTax": {
        "currency": "AUD",
        "value": 109.27,
        "type": null
      },
      "customerId": null,
      "subscriptionId": null,
      "checkoutId": null,
      "subscriptionName": null,
      "paymentMethodToken": null,
      "paymentMethodData": {
        "paymentMethodToken": null,
        "customerId": null,
        "type": "TERMINAL",
        "bank": null,
        "payTo": null,
        "card": {
          "first6": "976543",
          "last4": "7777",
          "accountHolderName": "J. De Tester",
          "type": "visa",
          "expiryMonth": "12",
          "expiryYear": "2030",
          "origin": null,
          "tokenDetails": null,
          "tokenized": false
        },
        "invalidReason": null,
        "lastUsedOn": null,
        "replacedPaymentMethodData": null,
        "wallet": null,
        "valid": true,
        "primary": false
      },
      "autoPayment": false,
      "processingModel": "IN_PERSON_PAYMENT",
      "transactionSource": null,
      "createdOn": "2025-04-28T01:52:19.255",
      "payNowUrl": null,
      "channel": "MOBILE_POINT_OF_SALE",
      "checkoutResult": null,
      "customerFirstName": null,
      "customerLastName": null,
      "terminalId": "ce11b4ca-84e8-4e25-8b3d-8b8189a427eb"
  }
}

{
    "requestId": "44fa7b03-57fe-4922-8a4c-50965f96858d",
    "merchantId": "9d262c1f-0ee3-430d-be8a-3cd9006a5002",
    "eventType": "TERMINAL_RESPONSE",
    "createdOn": "2025-04-29T01:42:30.224",
    "data": {
      "id": "6b66df43-8793-4c0d-9ca5-e3d33abf8639",
      "creditNoteId": null,
      "documentNumber": "IN0000000000000271",
      "date": "2025-04-28",
      "dueDate": "2025-04-28",
      "scheduledPaymentDate": null,
      "status": "FAILED",
      "memo": null,
      "items": [
        {
          "description": "this is a test invoice for Terminal ",
          "amount": {
            "currency": "AUD",
            "value": 1000,
            "type": null
          },
          "tax": {
            "rate": 10
          },
          "id": "c37875ad-8284-44bb-b472-724924decd55",
          "type": "on_demand_payment",
          "discounted": null,
          "accountingCode": null
        },
        {
          "description": "Transaction fee Terminal",
          "amount": {
            "currency": "AUD",
            "value": 2,
            "type": null
          },
          "tax": {
            "rate": 10
          },
          "id": "a58b44a2-72ba-4faf-8300-e367fca0e9f5",
          "type": "transaction_fee",
          "discounted": null,
          "accountingCode": null
        },
        {
          "description": "Transaction fee Terminal",
          "amount": {
            "currency": "AUD",
            "value": 200,
            "type": null
          },
          "tax": {
            "rate": 10
          },
          "id": "d8ad0e01-3166-470e-a553-01fc219ade98",
          "type": "transaction_fee",
          "discounted": null,
          "accountingCode": null
        }
      ],
      "amount": {
        "currency": "AUD",
        "value": 1202,
        "type": null
      },
      "amountWithoutDiscount": {
        "currency": "AUD",
        "value": 1202,
        "type": null
      },
      "totalDiscounted": {
        "currency": "AUD",
        "value": 0,
        "type": null
      },
      "totalRefunded": {
        "currency": "AUD",
        "value": 0,
        "type": null
      },
      "totalTax": {
        "currency": "AUD",
        "value": 109.27,
        "type": null
      },
      "customerId": null,
      "subscriptionId": null,
      "checkoutId": null,
      "subscriptionName": null,
      "paymentMethodToken": null,
      "paymentMethodData": {
        "paymentMethodToken": null,
        "customerId": null,
        "type": "TERMINAL",
        "bank": null,
        "payTo": null,
        "card": {
          "first6": "541333",
          "last4": "9999",
          "accountHolderName": "Test Name",
          "type": "mc",
          "expiryMonth": "02",
          "expiryYear": "2028",
          "origin": null,
          "tokenDetails": null,
          "tokenized": false
        },
        "invalidReason": null,
        "lastUsedOn": null,
        "replacedPaymentMethodData": null,
        "wallet": null,
        "valid": true,
        "primary": false
      },
      "autoPayment": false,
      "processingModel": "IN_PERSON_PAYMENT",
      "transactionSource": null,
      "createdOn": "2025-04-28T01:52:10.110",
      "payNowUrl": null,
      "channel": "MOBILE_POINT_OF_SALE",
      "checkoutResult": null,
      "customerFirstName": null,
      "customerLastName": null,
      "terminalId": "ce11b4ca-84e8-4e25-8b3d-8b8189a427eb"
 		}
}

List Terminal Invoices

Endpoint: [GET] https://api-sandbox.ezypay.com/v2/billing/terminal/invoices

Available query parameters:

ParameterExplanation
customerIdFilter by unique identifier of the customer
terminalIdFilter by the unique identifier of the terminal device used.
externalInvoieIdFilter by unique identifier from the integrators' platform.
statusFilter by the invoice status. Supported values are PAID, FAILED, VOIDED, PENDING_TERMINAL_PAYMENT
fromStart date for range of invoices to view. Filter by date defined in the invoice date.
untilEnd date for range of invoices to view. Filter by date defined in the invoice date.
limitTo paginate a large result set, Each request will only show number of invoices defined here. Default to 100.
cursorAn cursor for use in pagination. Specify the number of invoices to skip and retrieve the invoices after that. For example, limit=10 and cursor=10 will show results for record 11 - 20.
{
  "data": [
    {
      "id": "eeb642f9-01e1-441b-8b16-4ebd10cd3809",
      "creditNoteId": null,
      "documentNumber": "IN0000000000013975",
      "date": "2025-03-14",
      "dueDate": "2025-03-14",
      "scheduledPaymentDate": null,
      "status": "VOIDED",
      "memo": "this is a test invoice for tap to pay",
      "items": [
        {
          "description": "this is a test invoice for FRS ",
          "amount": {
            "currency": "AUD",
            "value": 1000,
            "type": null
          },
          "tax": {
            "rate": 10
          },
          "id": "1b98fb12-5022-4390-ac4c-02ef30165687",
          "type": "on_demand_payment",
          "discounted": {
            "currency": "AUD",
            "value": 0,
            "type": null
          },
          "accountingCode": null
        },
        {
          "description": "Transaction fee Terminal",
          "amount": {
            "currency": "AUD",
            "value": 2,
            "type": null
          },
          "tax": {
            "rate": 10
          },
          "id": "6cb5fb6b-3054-4f61-9bac-d3128d8da8c8",
          "type": "transaction_fee",
          "discounted": {
            "currency": "AUD",
            "value": 0,
            "type": null
          },
          "accountingCode": null
        }
      ],
      "amount": {
        "currency": "AUD",
        "value": 1002,
        "type": null
      },
      "amountWithoutDiscount": {
        "currency": "AUD",
        "value": 1002,
        "type": null
      },
      "totalDiscounted": {
        "currency": "AUD",
        "value": 0,
        "type": null
      },
      "totalRefunded": {
        "currency": "AUD",
        "value": 0,
        "type": null
      },
      "totalTax": {
        "currency": "AUD",
        "value": 91.09,
        "type": null
      },
      "customerId": null,
      "subscriptionId": null,
      "checkoutId": null,
      "subscriptionName": null,
      "paymentMethodToken": null,
      "paymentMethodData": null,
      "autoPayment": false,
      "processingModel": "IN_PERSON_PAYMENT",
      "transactionSource": null,
      "createdOn": "2025-03-14T00:49:42.016",
      "payNowUrl": null,
      "channel": "MOBILE_POINT_OF_SALE",
      "checkoutResult": null,
      "customerFirstName": null,
      "customerLastName": null,
      "terminalId": "195a48b4-735f-4697-8702-102b1facaad8",
      "externalInvoiceId": "195a48b4-735f-4697-8702-102b1facaad7"
    },
    {
      "id": "eeb642f9-01e1-441b-8b16-4ebd10cd3809",
      "creditNoteId": null,
      "documentNumber": "IN0000000000013975",
      "date": "2025-03-14",
      "dueDate": "2025-03-14",
      "scheduledPaymentDate": null,
      "status": "FAILED",
      "memo": "this is a test invoice for tap to pay",
      "items": [
        {
          "description": "this is a test invoice for FRS ",
          "amount": {
            "currency": "AUD",
            "value": 1000,
            "type": null
          },
          "tax": {
            "rate": 10
          },
          "id": "1b98fb12-5022-4390-ac4c-02ef30165687",
          "type": "on_demand_payment",
          "discounted": {
            "currency": "AUD",
            "value": 0,
            "type": null
          },
          "accountingCode": null
        },
        {
          "description": "Transaction fee Terminal",
          "amount": {
            "currency": "AUD",
            "value": 2,
            "type": null
          },
          "tax": {
            "rate": 10
          },
          "id": "6cb5fb6b-3054-4f61-9bac-d3128d8da8c8",
          "type": "transaction_fee",
          "discounted": {
            "currency": "AUD",
            "value": 0,
            "type": null
          },
          "accountingCode": null
        }
      ],
      "amount": {
        "currency": "AUD",
        "value": 1002,
        "type": null
      },
      "amountWithoutDiscount": {
        "currency": "AUD",
        "value": 1002,
        "type": null
      },
      "totalDiscounted": {
        "currency": "AUD",
        "value": 0,
        "type": null
      },
      "totalRefunded": {
        "currency": "AUD",
        "value": 0,
        "type": null
      },
      "totalTax": {
        "currency": "AUD",
        "value": 91.09,
        "type": null
      },
      "customerId": null,
      "subscriptionId": null,
      "checkoutId": null,
      "subscriptionName": null,
      "paymentMethodToken": null,
      "paymentMethodData": {
        "paymentMethodToken": null,
        "customerId": null,
        "type": "TERMINAL",
        "bank": null,
        "payTo": null,
        "card": {
          "first6": "976543",
          "last4": "7777",
          "accountHolderName": "J. De Tester",
          "type": "visa",
          "expiryMonth": "12",
          "expiryYear": "2030",
          "origin": null,
          "tokenDetails": null,
          "tokenized": false
        },
        "invalidReason": null,
        "lastUsedOn": null,
        "replacedPaymentMethodData": null,
        "wallet": null,
        "valid": true,
        "primary": false
      },
      "autoPayment": false,
      "processingModel": "IN_PERSON_PAYMENT",
      "transactionSource": null,
      "createdOn": "2025-03-14T00:49:42.016",
      "payNowUrl": null,
      "channel": "MOBILE_POINT_OF_SALE",
      "checkoutResult": null,
      "customerFirstName": null,
      "customerLastName": null,
      "terminalId": "195a48b4-735f-4697-8702-102b1facaad8",
      "externalInvoiceId": "195a48b4-735f-4697-8702-102b1facaad7"
    },
    {
      "id": "eeb642f9-01e1-441b-8b16-4ebd10cd3809",
      "creditNoteId": null,
      "documentNumber": "IN0000000000013975",
      "date": "2025-03-14",
      "dueDate": "2025-03-14",
      "scheduledPaymentDate": null,
      "status": "PAID",
      "memo": "this is a test invoice for tap to pay",
      "items": [
        {
          "description": "this is a test invoice for FRS ",
          "amount": {
            "currency": "AUD",
            "value": 1000,
            "type": null
          },
          "tax": {
            "rate": 10
          },
          "id": "1b98fb12-5022-4390-ac4c-02ef30165687",
          "type": "on_demand_payment",
          "discounted": {
            "currency": "AUD",
            "value": 0,
            "type": null
          },
          "accountingCode": null
        },
        {
          "description": "Transaction fee Terminal",
          "amount": {
            "currency": "AUD",
            "value": 2,
            "type": null
          },
          "tax": {
            "rate": 10
          },
          "id": "6cb5fb6b-3054-4f61-9bac-d3128d8da8c8",
          "type": "transaction_fee",
          "discounted": {
            "currency": "AUD",
            "value": 0,
            "type": null
          },
          "accountingCode": null
        }
      ],
      "amount": {
        "currency": "AUD",
        "value": 1002,
        "type": null
      },
      "amountWithoutDiscount": {
        "currency": "AUD",
        "value": 1002,
        "type": null
      },
      "totalDiscounted": {
        "currency": "AUD",
        "value": 0,
        "type": null
      },
      "totalRefunded": {
        "currency": "AUD",
        "value": 0,
        "type": null
      },
      "totalTax": {
        "currency": "AUD",
        "value": 91.09,
        "type": null
      },
      "customerId": null,
      "subscriptionId": null,
      "checkoutId": null,
      "subscriptionName": null,
      "paymentMethodToken": null,
      "paymentMethodData": {
        "paymentMethodToken": null,
        "customerId": null,
        "type": "TERMINAL",
        "bank": null,
        "payTo": null,
        "card": {
          "first6": "976543",
          "last4": "7777",
          "accountHolderName": "J. De Tester",
          "type": "visa",
          "expiryMonth": "12",
          "expiryYear": "2030",
          "origin": null,
          "tokenDetails": null,
          "tokenized": false
        },
        "invalidReason": null,
        "lastUsedOn": null,
        "replacedPaymentMethodData": null,
        "wallet": null,
        "valid": true,
        "primary": false
      },
      "autoPayment": false,
      "processingModel": "IN_PERSON_PAYMENT",
      "transactionSource": null,
      "createdOn": "2025-03-14T00:49:42.016",
      "payNowUrl": null,
      "channel": "MOBILE_POINT_OF_SALE",
      "checkoutResult": null,
      "customerFirstName": null,
      "customerLastName": null,
      "terminalId": "195a48b4-735f-4697-8702-102b1facaad8",
      "externalInvoiceId": "195a48b4-735f-4697-8702-102b1facaad7"
    },
    {
      "id": "eeb642f9-01e1-441b-8b16-4ebd10cd3809",
      "creditNoteId": null,
      "documentNumber": "IN0000000000013975",
      "date": "2025-03-14",
      "dueDate": "2025-03-14",
      "scheduledPaymentDate": null,
      "status": "PENDING_TAP_PAYMENT",
      "memo": "this is a test invoice for tap to pay",
      "items": [
        {
          "description": "this is a test invoice for FRS ",
          "amount": {
            "currency": "AUD",
            "value": 1000,
            "type": null
          },
          "tax": {
            "rate": 10
          },
          "id": "1b98fb12-5022-4390-ac4c-02ef30165687",
          "type": "on_demand_payment",
          "discounted": {
            "currency": "AUD",
            "value": 0,
            "type": null
          },
          "accountingCode": null
        },
        {
          "description": "Transaction fee Terminal",
          "amount": {
            "currency": "AUD",
            "value": 2,
            "type": null
          },
          "tax": {
            "rate": 10
          },
          "id": "6cb5fb6b-3054-4f61-9bac-d3128d8da8c8",
          "type": "transaction_fee",
          "discounted": {
            "currency": "AUD",
            "value": 0,
            "type": null
          },
          "accountingCode": null
        }
      ],
      "amount": {
        "currency": "AUD",
        "value": 1002,
        "type": null
      },
      "amountWithoutDiscount": {
        "currency": "AUD",
        "value": 1002,
        "type": null
      },
      "totalDiscounted": {
        "currency": "AUD",
        "value": 0,
        "type": null
      },
      "totalRefunded": {
        "currency": "AUD",
        "value": 0,
        "type": null
      },
      "totalTax": {
        "currency": "AUD",
        "value": 91.09,
        "type": null
      },
      "customerId": null,
      "subscriptionId": null,
      "checkoutId": null,
      "subscriptionName": null,
      "paymentMethodToken": null,
      "paymentMethodData": null,
      "autoPayment": false,
      "processingModel": "IN_PERSON_PAYMENT",
      "transactionSource": null,
      "createdOn": "2025-03-14T00:49:42.016",
      "payNowUrl": null,
      "channel": "MOBILE_POINT_OF_SALE",
      "checkoutResult": null,
      "customerFirstName": null,
      "customerLastName": null,
      "terminalId": "195a48b4-735f-4697-8702-102b1facaad8",
      "externalInvoiceId": "195a48b4-735f-4697-8702-102b1facaad7"
    }
  ],
  "paging": {
    "nextUrl": null,
    "nextCursor": 0,
    "limit": 0,
    "totalCount": 4
  }
}

Retrieve Terminal Invoices

Endpoint: [GET] https://api-sandbox.ezypay.com/v2/billing/terminal/invoices/{invoiceId}

{
    "id": "eb8643b1-aba8-40bb-bc89-354851639d8f",
    "creditNoteId": null,
    "documentNumber": "IN0000000000000275",
    "date": "2025-04-28",
    "dueDate": "2025-04-28",
    "scheduledPaymentDate": null,
    "status": "PAID",
    "memo": null,
    "items": [
      {
        "description": "this is a test invoice for Terminal ",
        "amount": {
          "currency": "AUD",
          "value": 1000,
          "type": null
        },
        "tax": {
          "rate": 10
        },
        "id": "a2cba906-a4b6-4ae8-9146-65f689d6945e",
        "type": "on_demand_payment",
        "discounted": null,
        "accountingCode": null
      },
      {
        "description": "Transaction fee Terminal",
        "amount": {
          "currency": "AUD",
          "value": 2,
          "type": null
        },
        "tax": {
          "rate": 10
        },
        "id": "662f46e3-186f-4661-a310-3514ce156001",
        "type": "transaction_fee",
        "discounted": null,
        "accountingCode": null
      },
      {
        "description": "Transaction fee Terminal",
        "amount": {
          "currency": "AUD",
          "value": 200,
          "type": null
        },
        "tax": {
          "rate": 10
        },
        "id": "8ddb3369-7e05-4350-89c8-fc25c9dab94f",
        "type": "transaction_fee",
        "discounted": null,
        "accountingCode": null
      }
    ],
    "amount": {
      "currency": "AUD",
      "value": 1202,
      "type": null
    },
    "amountWithoutDiscount": {
      "currency": "AUD",
      "value": 1202,
      "type": null
    },
    "totalDiscounted": {
      "currency": "AUD",
      "value": 0,
      "type": null
    },
    "totalRefunded": {
      "currency": "AUD",
      "value": 0,
      "type": null
    },
    "totalTax": {
      "currency": "AUD",
      "value": 109.27,
      "type": null
    },
    "customerId": null,
    "subscriptionId": null,
    "checkoutId": null,
    "subscriptionName": null,
    "paymentMethodToken": null,
    "paymentMethodData": {
      "paymentMethodToken": null,
      "customerId": null,
      "type": "TERMINAL",
      "bank": null,
      "payTo": null,
      "card": {
        "first6": "976543",
        "last4": "7777",
        "accountHolderName": "J. De Tester",
        "type": "visa",
        "expiryMonth": "12",
        "expiryYear": "2030",
        "origin": null,
        "tokenDetails": null,
        "tokenized": false
      },
      "invalidReason": null,
      "lastUsedOn": null,
      "replacedPaymentMethodData": null,
      "wallet": null,
      "valid": true,
      "primary": false
    },
    "autoPayment": false,
    "processingModel": "IN_PERSON_PAYMENT",
    "transactionSource": null,
    "createdOn": "2025-04-28T01:52:19.255",
    "payNowUrl": null,
    "channel": "MOBILE_POINT_OF_SALE",
    "checkoutResult": null,
    "customerFirstName": null,
    "customerLastName": null,
    "terminalId": "ce11b4ca-84e8-4e25-8b3d-8b8189a427eb"
 }

Terminal Invoice Statuses

Table below shows all the possible statuses for a terminal invoice.

StatusDescription
PENDING_TERMINAL_PAYMENTThe terminal invoice has been created and is awaiting a card tap from the customer on the terminal device.
VOIDEDThe invoice has been cancelled and is no longer payable. This may occur if the customer did not tap within the timeout window or if the transaction was cancelled.
PAIDThe terminal invoice was successfully paid.
FAILEDThe payment attempt failed after the customer tapped their card.

📘

Role Control

Integrators are responsible for handling role control on accessing device registration and terminal invoice creation functionalities.

Updated 3 days ago