PromptPay

Integration

Using MyCheckout Hosted Payment Pages

MyCheckout hosted payment pages are the optimal solution if you're looking for the quickest way to accept payments and provide a hassle-free experience for your consumers.

Before you begin

Make sure you are boarded with PromptPay
Build your server integration
Make POST /{merchantId}/payments API call, submitting the required properties.

Below, you'll find an example request containing the essential data. For more information, please refer to our API Reference.

Additionally, you can add hostedCheckoutSpecificInput object, featuring the following strings:

returnUrl - the URL that the consumer is redirected to after the payment flow has finished.
variant - the created styling of the checkout page tailored to your consumer's preferences.
locale - the language that will be used for your hosted checkout page.

Property	Data type	Required
order	object	yes
amountOfMoney	object	yes
currencyCode	string	yes
amount	integer	yes
customer	object	yes
merchantCustomerId	string	no
merchantCustomerId	string	no
billingAddress	object	yes
countryCode	string	yes
hostedCheckoutSpecificInput	object	no
returnUrl	string	no
locale	string	no
variant	string	no

POST HOSTEDCHECKOUT REQUEST


{   "order",
      "amountOfMoney" : {
      "currencyCode" : "THB"
         "amount" : 15000,
      },
      "customer" : {
         "billingAddress" : {
      },
      "countryCode" : "TH"
      }
   }
}

POST HOSTEDCHECKOUT RESPONSE


{   "RETURNMAC": "89084bf6-d736-40a0-a5a0-2e6fb50baeae",
  "hostedCheckoutId": "067f7c64-6969-71ff-ba79-2d1cf4246ae1",
  "partialRedirectUrl": "pay1.checkout.worldline-solutions.com/checkout/9991-04b38b3ce0f5443599838b4fec060e76:067f7c64-6969-71ff-ba79-2d1cf4246ae1:41a98d29c2d347ff9582ea0d691fe883"
   }

From the response, the important properties are:

hostedCheckoutId – can be used in subsequent API calls to retrieve the transaction details, such as GET/v1/{merchantId}/hostedcheckouts/{hostedCheckoutId}
partialRedirectUrl – is used to create the URL to which the customer needs to be redirected, By default, we configure every account with the subdomain payment, so you can always connect https://payment/. with the partialRedirectUrl, for example:

https://payment.pay1.preprod.checkout.worldline-solutions.com/checkout/9992-6ce05357a95344********

For more information on customizing the checkout page, please refer to our detailed guide on MyCheckout hosted payment pages.

The hostedCheckoutId is only valid for 2 hours, please ensure to store the createdPaymentOutput.payment.id from the GET /v1/{merchantId}/hostedcheckouts/{hostedCheckoutId} response to be able to retrieve data after 2 hours have elapsed via the GET /v1/{merchantId}/payments/{paymentId} API call. Alternatively, we can also send a webhook event that will contain it.

Using your own checkout page

Using this integration option implies that you have your own checkout page design ready and only need to use our API's to accept payment on your website.

Before you begin

Make sure you are boarded with PromptPay
Build your server integration
Build your payment product selection form
Build your payment product details form

Make a POST /v1/{merchantId}/payments API call submitting the required properties.

Below, you'll find an example request containing the essential data. For more information, please refer to our API Reference.

Property	Data type	Required
order	object	yes
amountOfMoney	object	yes
currencyCode	string	yes
amount	integer	yes
customer	object	yes
billingAddress	object	yes
countryCode	string	yes
redirectPaymentMethodSpecificInput	object	yes
redirectionData	object	yes
returnUrl	string	yes
paymentProductId	integer	yes

POST PAYMENTS REQUEST


   "id" : "000008800510000157710000100001",
   "order" : {
      "amountOfMoney" : {
         "currencyCode" : THB,
         "amount" : "1000"
      },
      "customer" : {
         "billingAddress" : {
         "countryCode": "TH"
      }
   }
 },  
   "redirectPaymentMethodSpecificInput": {
   "redirectionData": {
      "returnUrl": "https://example.org/return"
      },
      "paymentProductId": 740
   }
}

POST PAYMENTS RESPONSE


   "id" : "000008800510000157710000100001",
   {
  "creationOutput": {
    "additionalReference": "00000099911000002053",
    "externalReference": "000000999110000020530000100001"
  },
  "merchantAction": {
    "actionType": "SHOW_FORM",
    "formFields": [],
    "showData": [
      {
        "key": "QRCODE_IMAGE_URL",
        "value": "https://api.omise.co/charges/chrg_63ce6sqhxsa40n9ysth/documents/docu_63ce6sxyqhnnhz2c1ip/downloads/10F036E5A82C4936"
      },
      {
        "key": "COUNTDOWN_DATETIME",
        "value": "20250410142513"
      }
    ]
  },
  "payment": {
    "id": "000000999110000020530000100001",
    "paymentOutput": {
      "amountOfMoney": {
        "amount": 1000,
        "currencyCode": "THB"
      },
      "references": {
        "paymentReference": "999100018462"
      },
      "paymentMethod": "redirect",
      "redirectPaymentMethodSpecificOutput": {
        "paymentProductId": 740
      }
    },
    "status": "PENDING_PAYMENT",
    "statusOutput": {
      "isCancellable": true,
      "isRetriable": false,
      "statusCategory": "PENDING_PAYMENT",
      "statusCode": 55,
      "statusCodeChangeDateTime": "20250410152515",
      "isAuthorized": false,
      "isRefundable": false
    }
  }
}

Consumer redirection

If you use POST /{merchantId}/payments API call, you also need to take care of the consumer redirection (in the case of POST /{merchantId}/hostedcheckouts, we handle it ourselves). In the API response to this call we'll return a merchantAction object.

While there are several different actionType values for PromptPay transactions, we consistently return the actionType value as SHOW_FORM. The show data will have QRCODE_IMAGE_URL object included, containing a QR code. You'll need to show this QR code to your consumer, which can be scanned or uploaded using the consumers' bank application. Alongside, we will also send the COUNTDOWN_DATETIME, which shows how long the QR code will be active for payment.

The merchantAction is only returned in the response to POST /{merchantId}/payments as shown in the following example:

POST PAYMENTS REQUEST

{
   "id" : "000008800510000157710000100001",
   "merchantAction": {
    "actionType": "SHOW_FORM",
    "formFields": [],
    "showData": [
      {
        "key": "QRCODE_IMAGE_URL",
        "value": "https://api.omise.co/charges/chrg_63ce6sqhxsa40n9ysth/documents/docu_63ce6sxyqhnnhz2c1ip/downloads/10F036E5A82C4936"
      },
      {
        "key": "COUNTDOWN_DATETIME",
        "value": "20250410142513"
      }
    ]
  }

The merchantAction is omitted from the GET /payments/{paymentId} API call and will return the following API response:

POST PAYMENTS RESPONSE

{
   "id" : "000008800510000157710000100001",
  {
  "id": "000000999110000020570000100001",
  "paymentOutput": {
    "amountOfMoney": {
      "amount": 1000,
      "currencyCode": "THB"
    },
    "references": {
      "paymentReference": "999100018492"
    },
    "paymentMethod": "redirect",
    "redirectPaymentMethodSpecificOutput": {
      "paymentProductId": 740
    }
  },
  "status": "PENDING_PAYMENT",
  "statusOutput": {
    "isCancellable": true,
    "isRetriable": false,
    "statusCategory": "PENDING_PAYMENT",
    "statusCode": 55,
    "statusCodeChangeDateTime": "20250414164329",
    "isAuthorized": false,
    "isRefundable": false
  }
}