Skip to main content

Create a Hosted Payment

POST 
/hosted-payments

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 webook. The resultCode field may contain additional information about the failure.

Request​

Header Parameters

    Idempotency-Key string

    A unique value, eg. a UUID.

Body

    amount integerrequired

    A positive integer value in specified currency's smallest unit. e.g. $10 would be represented as 1000 (cents).

    currency stringrequired

    Possible values: [SGD]

    Three-letter ISO 4217 currency code in full uppercase. Must be a supported currency.

    method stringrequired

    Possible values: [PAYLAH, PAYNOW]

    channel stringrequired

    Possible values: [APP_IOS, APP_ANDROID, WEB_BROWSER_DESKTOP, WEB_BROWSER_MOBILE]

    returnUrl string

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

    referenceId string

    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.

    tokenization boolean

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

    hostedPaymentMethodId string

    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 payment
    • hpm_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.

Responses​

OK

Response Headers

  • Acme-Mode

    string

    Has the value LIVE if the data exists in live production mode or the value TEST if the data exists in test sandbox mode.

Schema

    id stringrequired
    status stringrequired

    Possible values: [REQUIRES_ACTION, PENDING, SUCCEEDED, FAILED]

    Status of the payment

    resultCode string

    Possible values: [PAYLAH_WALLET_DELINKED, PAYLAH_WALLET_ALREADY_LINKED, INSUFFICIENT_FUNDS_PENDING_TOP_UP, OTHERS]

    Result code of the payment, if available. Possible values are:

    • PAYLAH_WALLET_DELINKED: The payer has delinked their PayLah! Wallet and the specified hostedPaymentMethodId can no longer be used for creating payments.
    • PAYLAH_WALLET_ALREADY_LINKED: The specified PayLah! Wallet number has already been linked before. You should set the hostedPaymentMethodId in the request body.
    • INSUFFICIENT_FUNDS_PENDING_TOP_UP: The payer has insufficient funds in their PayLah! Wallet and the payer needs to top up their wallet in 5 minutes. You should keep polling the hosted payment status.
    • OTHERS
    amount integerrequired
    currency stringrequired

    Possible values: [SGD]

    Three-letter ISO 4217 currency code in full uppercase.

    method string

    Possible values: [PAYLAH, PAYNOW]

    channel stringrequired

    Possible values: [APP_IOS, APP_ANDROID, WEB_BROWSER_DESKTOP, WEB_BROWSER_MOBILE]

    returnUrl stringrequired

    For web browser based channel, use a HTTPS URL. For native mobile based channel, use an App Deep Link URL.

    redirectUrl string

    Redirect the payer to this URL for payment.

    referenceId string

    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.

    tokenization boolean

    Only applicable to method=PAYLAH. If set to true, this is a tokenized payment, and you can find the token representing the customer's payment method information in the hostedPaymentMethodId field after the payment is completed.

    hostedPaymentMethodId string

    Token representing your customer's payment method information.

    If this is a tokenized payment (tokenization=true), this field is set after the customer has completed the payment. Listen to the hosted-payments.succeeded webhook or use GET /v1/hosted-payments/{id} to retrieve this token. You should save and associate this token with the customer, so that you may collect future payments from the same customer without requiring them to key in their payment method information again.

    createdAt stringrequired
    updatedAt stringrequired
Loading...