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.

Get Started

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 Terminal Registration API, passing the captured Device ID and Device Name.

{
  "appDeviceId": "XYZ-test-ezypay-9" ,
  "deviceName":"Ezypay-test-1"
}

{
  "code": 499088,
  "deviceName": "Ezypay-test-1",
	"appDeviceId": "XYZ-test-ezypay-9",
  "message": "New activation code sent"
}

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

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

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 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

❗️

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.

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.

Terminal Invoice Statuses

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

📘

Role Control

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