Hosted checkout

Account setup and configuration

Before you can integrate, you must set up your merchant environment. You’ll need the following:

• Create a merchant account: Sign up and gain access to your merchant dashboard

• Create an SDK installation: In your dashboard, under developer settings, create a new SDK installation for each website or mobile application you plan to deploy on. This process involves:

  • Choosing your platform (e.g., Web, iOS, Android).
    
  • Providing application details like your website domain or app bundle ID.
    
  • Selecting payment methods you want to offer on that platform (e.g., Card, PromptPay).
    
  • Configuring customer data to require (e.g., email address, mobile number).

• Create a new API key: In your dashboard, under developer settings, create a new API key. Keep your API key secret. Your API key is a secret credential. It must only be used on your backend server. Never expose this key in your frontend (client-side) JavaScript, mobile app code, or any public repository.

• Connect a webhook endpoint (optional): In your dashboard, under developer settings, create a new webhook endpoint and listen to the payment_complete event.

Integration flow overview

A complete transaction involves both your frontend (handling user interaction) and your backend (handling secure API calls).

1. On the frontend (aka client-side): Your customer presses the checkout button.

2. On the backend (aka server-side): Your server securely uses its secret API key to call the Reservepay Merchant API and start the checkout flow, then redirect the user to the URL provided in the response.

3. On the hosted checkout page: Reservepay handles the entire payment flow end to end and redirects the user at the end of the flow.

Integration steps

Start the checkout process

First, create the checkout session by making a call to /merchants/start-checkout. The API will return a checkout object in the response. From this object, you need to store the checkout_id, which you'll use for verification later, and extract the redirect_url. Redirect your customer to this redirect_url to send them to the hosted payment page.

Confirming the payment status

After the customer completes the payment, they are sent back to your specified return URL. This redirection does not guarantee the payment was successful. To confirm the status, first retrieve the checkout_id you stored when creating the checkout session. Use this ID to call /merchants/retrieve-checkout from your backend. This endpoint provides the updated checkout object, which includes the payment_id.

To get the final, authoritative status of the transaction, make a call to /merchants/find-payment using the payment_id. This returns the full payment object. Inspect the status field on this object to verify completion before fulfilling the order.

Example

await fetch('https://api.reservepay.com/merchants/retrieve-checkout', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY', // Use your API key here (server-side only!)
    'Api-Version': '2025-04-01',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ checkout_id: checkoutId })
})

Webhooks (optional)

For a more robust integration, we highly recommend using webhooks. Instead of relying only on polling, your server can receive asynchronous notifications. To achieve the same result as the previous step, listen for the payment_complete event.

To verify the signature of incoming events our requests include an X-Webhook-Signature header. You must verify this signature using your webhook endpoint verify key (available in your dashboard) and a libsodium compatible library. This verification is critical to make sure that the request genuinely came from Reservepay and was not forged.