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

> **Testing your integration:** Use the [test card generator](/tools/test-card-generator) to create Luhn-compliant test card numbers to complete payments on the hosted checkout 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

```ts
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.