HitPay Product Guide and API docs.

Overview

APM Tokenisation lets your customer link a digital wallet (e.g., ShopeePay or GrabPay) once and reuse it securely for future payments. Use this flow when you want to:

Let customers link their wallet once and skip re-entering payment details for future orders.
Offer one-click repeat checkouts for returning buyers.
Support recurring or subscription-based payments, enabling automatic billing at fixed intervals.
Support on-demand or usage-based payments, where the final amount is confirmed only after the service is delivered.

This feature is particularly useful for merchants who want to improve payment completion rates and reduce friction for repeat buyers using local APMs. It also gives customers a convenient alternative to cards for ongoing payments, providing more flexibility across preferred local wallets. By supporting APM tokenisation, you can increase payment flexibility and boost conversions through smoother, familiar checkout experiences. This API integration includes 3 Steps

Create APM Tokenisation session

Generate a secure session and checkout link for the customer to connect their wallet.

Customer links wallet

Redirect the customer to the HitPay-hosted page where they authorise wallet linking.

Charge the linked wallet

Use the stored token to charge the linked wallet anytime in the future.

Step 1 - Create Tokenisation Session

HTTP Request

POST https://api.sandbox.hit-pay.com/v1/apm/tokenisation

Query Parameters

Mandatory fields are customer_name and customer_email. Remember to include the header Content-Type: application/x-www-form-urlencoded.

Parameter	Description	Example
name	Display name shown on the checkout page	Spotify Premium
description	Description displayed below the name on the checkout page	Spotify Membership
customer_email	Customer email	[email protected]
customer_name	Customer name	Paul
payment_methods[]	Choice of payment methods you want to offer the customer.	shopee_pay, grab_pay, giro
redirect_url	URL where hitpay redirects the user after the users link their wallet.	https://spotify.com/subscription-completed
reference	Arbitrary reference number that you can map to your internal reference number. This value cannot be edited by the customer	XXXX123
webhook	Optional URL value to which hitpay will send a POST request when there is a new charge or if there is an error charging the wallet	https://webhoo.site/test
send_email	Hitpay to send email receipts to the customer. Default value is false	true

curl --location --request POST 'https://api.staging.hit-pay.com/v1/apm/tokenisation' \
--header 'X-BUSINESS-API-KEY: meowmeowmeow' \
--header 'X-Requested-With: XMLHttpRequest' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'name=Spotify Premium' \
--data-urlencode 'description=Spotify Membership' \
--data-urlencode '[email protected]' \
--data-urlencode 'customer_name=Paul' \
--data-urlencode 'payment_methods[]=shopee_pay' \
--data-urlencode 'payment_methods[]=grab_pay' \
--data-urlencode 'redirect_url=https://spotify.com/subscription-completed' \
--data-urlencode 'reference=cust_id_123' \
--data-urlencode 'webhook=https://webhoo.site/test' \
--data-urlencode 'send_email=true'

Response

{
    "id": "9741164c-06a1-4dd7-a649-72cca8f9603a",
    "customer_name": "Paul",
    "customer_email": "[email protected]",
    "name": "Spotify Premium",
    "description": "Spotify Membership",
    "reference": "cust_id_123",
    "status": "scheduled",
    "send_email": true,
    "redirect_url": "https://github.com/",
    "payment_methods": ["shopee_pay", "grab_pay"],
    "created_at": "2025-09-13T16:33:47",
    "updated_at": "2025-09-13T16:33:47",
    "url": "https://securecheckout.staging.hit-pay.com/9673bdea-058c-44b5-a957-845a7c487bc2/recurring-plan/9741164c-06a1-4dd7-a649-72cca8f9603a",
    "webhook": "https://webhoo.site/test"
}

Step 2 - Redirect customer to checkout page (One time set up)

Redirect the customer to the “url” value.

Once the customer completes wallet linking, you can charge the linked wallet anytime using the Charge Linked Wallet API.

Step 3 - Charge Linked Wallet

Once the wallet is linked, you can charge it anytime using the endpoint below

HTTP Request

POST https://api.sandbox.hit-pay.com/v1/charge/tokenisation/{id}

id is the id value from step 1 response.

Query Parameters

Parameter	Description	Example
currency	Currency related to the recurring billing	SGD
amount	Amount related to the recurring billing	9.90
description	Description of the charge	Membership charge

curl --location --request POST 'https://api.sandbox.hit-pay.com/v1/charge/tokenisation/{id}' \
--header 'X-BUSINESS-API-KEY: meowmeowmeow' \
--header 'X-Requested-With: XMLHttpRequest' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiI4YjdiYzdhYS1iZGUxLTQzODAtYjQ5ZS03ZjFiYWViOGMzY2UiLCJqdGkiOiJjYTA4NjVmMjMxYzA2Yjg2NTY5ODc1ZTFkNjVlMmUwM2EwMmI1ZDcxZTBiMTEwMWUwYzE4Y2Y3NWU2ZjYwZmM0MTIxYmVkMTExZWI4YjRlZSIsImlhdCI6MTY2MzExNzUxOCwibmJmIjoxNjYzMTE3NTE4LCJleHAiOjE2OTQ2NTM1MTcsInN1YiI6IjkwMjdjYTRkLTBhYmItNDk2NC04MzIxLTQ0NWQ0YjMyNzY5NCIsInNjb3BlcyI6W119.VfQoR_luqIZKSBTEXMv_srTVRApk9OfimbX_ghmRkCjrnvZUm-gCSHUbVnBUSzUcjRbVs-rCFs5wKZX4V0bL_76_WqBwxmNzsxRFf-QXFHSt1dDG7TnH6OSduHFeI-6akfQX0DGqal2pStz-UQY07lUiJ_aRe6QnvYqKZaA_eKsAn5XnEo0vn92mk8_i9KTxhvPH85qinfpg23-j3RJNlTDXeRWPn7CmufsrFfdRGtDL2h2thyqEQvju47XAM_Nyar2IjHw_ZcT9ZWnS7sskSwrsrBmOvjSuHA-ANr55ufc11GwjdRyzBPLu3SOUJ8kHJnprdep70VIpYLtO_nKG1xMzJRJzSno-Hvhn7RzjT-xpSudfUzRKb6M9z_BVmSQ8eUfuigwcmadH-pAFP67noNQAL5zeOjlr4RXGRKoMdeOOM4hxciojZRqoiBT-i74aAHg0AAlJHx4NQnM4LcDkN_Sh0kK4Ip4BHZHuxE4t9CZ24erizjXcdwvzv0UG0QCYRSfWN41PcHTbljDXQWmV719PDtPVwoAb1Ht2EKzuAQ4umuLx6NzOpBFuXpElZfwVT9XoDr22Dwts-7cW2fqj_C6igptqoAeRuCGEejDRgq2dA-UJTpRxfi6J02XXKpeDv-hGyFCYE8TUHBqTg5HMRQeHtga3-Hq05IPFhp9fmyk' \
--data-urlencode 'amount=9.90' \
--data-urlencode 'currency=SGD

Response

{
    "payment_id": "9746f906-bdbb-4064-8372-642cf5877e0c",
    "id": "9746f8c2-2b7c-4c78-8832-012f203ae687",
    "amount": 9.9,
    "currency": "sgd",
    "status": "succeeded"
}

FAQs

Is there an initial charge during wallet linking?

No, customers will not be charged during the linking process. The tokenisation flow is used purely to authorise future payments securely.

What if the customer’s wallet has insufficient balance?

If the wallet does not have enough funds at the time of charge, the payment will fail, and HitPay will send an charge.failed webhook event. You can prompt the customer to top up and retry the charge.

Can I modify the amount I will charge my customer later on?

Yes, once your customer has attached the wallet, you can charge any amount using the Charge Linked Wallet API

Product Checklist

Ensure the following before moving to production - Change the base URL for all API calls to https://api.hit-pay.com/v1/ - Update API keys and Salt values from the production dashboard

Getting Started

Developers

Point of Sale

Online Store

Tools

Finance

Manage Payments

Integrations

Appendix

APM Tokenisation

Overview

Create APM Tokenisation session

Customer links wallet

Charge the linked wallet

Step 1 - Create Tokenisation Session

HTTP Request

Query Parameters

Response

Step 2 - Redirect customer to checkout page (One time set up)

Step 3 - Charge Linked Wallet

HTTP Request

Query Parameters

FAQs

​Overview

Create APM Tokenisation session

Customer links wallet

Charge the linked wallet

​Step 1 - Create Tokenisation Session

​HTTP Request

​Query Parameters

​Response

​Step 2 - Redirect customer to checkout page (One time set up)

​Step 3 - Charge Linked Wallet

​HTTP Request

​Query Parameters

​FAQs

Overview

Step 1 - Create Tokenisation Session

HTTP Request

Query Parameters

Response

Step 2 - Redirect customer to checkout page (One time set up)

Step 3 - Charge Linked Wallet

HTTP Request

Query Parameters

FAQs