Create a Hosted Payment
Create a Hosted Payment to collect payment from your customer. When this request succeeds, redirect the customer to the URL in the redirectUrl field of the response so that they can make the payment. They will be redirected back to the URL in returnUrl when they complete the payment flow.
When the customer has successfully made the payment, the status field will be updated to SUCCEEDED, and Acme will send a hosted-payments.succeeded webhook to you.
Should the payment fail, the status field will be updated to FAILED, and Acme will send a corresponding hosted-payments.failed webhook. The resultCode field may contain additional information about the failure.
Authorization
authorization Set Your Secret API Key
In: header
Header Parameters
A unique value, eg. a UUID.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
A positive integer value in the specified currency's smallest unit. e.g. $10 would be represented as 1000 (cents).
1 <= value <= 20000000Channel the customer pays from. Not applicable for FPX payments.
Value in
- "APP_IOS"
- "APP_ANDROID"
- "WEB_BROWSER_DESKTOP"
- "WEB_BROWSER_MOBILE"
Three-letter ISO 4217 currency code in full uppercase.
^SGD$Token from a previously tokenized Hosted Payment to use for creating this payment without requiring your customer to key in their payment method information again.
The token can be found in this field of a previous successful Hosted Payment that was created with tokenization=true.
Use these values to simulate specific success and failure scenarios:
hpm_TESTMODESUCCEEDED: successful paymenthpm_TESTMODEFAILED_PAYLAHWALLETDELINKED: customer has unlinked their PayLah! wallet.hpm_TESTMODEPENDING_INSUFFICIENTFUNDSPENDINGTOPUP: there is insufficient balance in the customer's PayLah! wallet, and they have been prompted to top up.
Payment method.
Value in
- "PAYLAH"
- "PAYNOW"
- "FPX_ONLINEBANKING"
A string to reference (e.g. your order ID, a payment ID, etc.) which can be used to reconcile the hosted payment with your own systems. This cannot exceed 255 characters.
0 <= length <= 255For a web browser based channel, use a HTTPS URL. For a native mobile based channel, use an App Deep Link URL. This should not be set if hostedPaymentMethodId is provided in the request.
^[A-Za-z][A-Za-z0-9+\-\.]+:\/\/[^:\?\/]+(:[0-9]+)?((\/[^\/\?]*)*\/?(\?[^\?\/]*)?)?$0 <= length <= 2048Only applicable to method=PAYLAH. Set to true to tokenize your customer's payment method information, allowing you to collect future payments from this customer using Hosted Payments without requiring them to key in their payment method information again.
You can find the token in the hostedPaymentMethodId field, after your customer has successfully completed this payment.
Tokenization is also sometimes known as binding or linking your digital wallet.
Response Body
*/*
application/json
application/json
curl -X POST "https://example.com/v1/hosted-payments" \
-H "Content-Type: application/json" \
-d '{
"amount": 1,
"channel": "APP_IOS",
"currency": "string",
"method": "PAYLAH"
}'Redirect the customer to redirectUrl to pay with PayNow. They return to returnUrl afterwards.
{
"id": "hpymt_0J7Q9A2M8V5X1",
"status": "REQUIRES_ACTION",
"resultCode": null,
"underlyingErrorCode": null,
"underlyingErrorMessage": null,
"transactionReference": null,
"amount": 4242,
"currency": "SGD",
"channel": "WEB_BROWSER_DESKTOP",
"method": "PAYNOW",
"returnUrl": "https://example.com/return",
"redirectUrl": "https://api.tryacme.com/redirection/hosted-payments/hpymt_0J7Q9A2M8V5X1/submit",
"referenceId": "ORDER-10042",
"tokenization": false,
"hostedPaymentMethodId": null,
"customerProxy": null,
"payer": null,
"paymentInformation": null,
"createdAt": "2026-09-09T04:00:27.967830Z",
"updatedAt": "2026-09-09T04:00:27.967830Z",
"expiredAt": null
}