Select payment method

API references

Search documentation... ⌘K

SDK API

All our references

This endpoint creates a new payment session with the customer's chosen payment method. It returns a payment session ID that you'll use in subsequent API calls to complete the payment flow.

The flow after calling this endpoint depends on the selected payment method:

For card payments: You must provide a card token obtained from tokenize-card
For QR code payments: Call retrieve-qr-data to get the QR code data to display
For redirect-based payments: Call get-redirect-url to get the URL to redirect the customer to

Card installments:

To charge a card in monthly installments instead of a single payment, pass an installment_plan_id obtained from list-installment-plans. The amount and currency must match the values you passed to list-installment-plans, and the card you tokenize must be the card whose BIN (or token) you used there, so the chosen plan stays eligible and the customer's quote remains consistent. Omit installment_plan_id to charge the card as a one-time payment.

After starting the payment flow, you should poll discover-next-action to track the payment status and determine the next steps.

Endpoint signature

POST https://api.reservepay.com/sdk/select-payment-method HTTP/1.1

Content-Type: application/json

Accept: application/json

{

merchant_id: string,

installation_id: string,

installment_plan_id: string?,

amount: string,

currency: string,

payment_method: string,

token: string?,

customer_email: string?,

customer_mobile: string?,

customer_name: string?,

customer_language: string?,

interest_bearer: string?,

street_address_1: string?,

street_address_2: string?,

postal_code: string?,

city: string?,

state: string?,

country: string?,

}

Returns: string

New to Reservepay? Read our guide on how to call endpoints to get started.

Request arguments

merchant_id string

Required. Your merchant ID that uniquely identifies your account.

installation_id string

Required. The installation ID for this platform (e.g. your iOS app, Android app, website, or terminal).

installment_plan_id string

Optional. For card installment payments only: the plan ID chosen from list-installment-plans. Omit for one-time card payments.

amount string

Required. The payment amount in the smallest currency unit (e.g. cents). Must be a positive integer.

currency string

Required. The three-letter ISO currency code (e.g. THB). Must match the funding currency configured for your provider.

payment_method string

Required. The payment method code (e.g. CARD, PROMPTPAY, K_PLUS). Must be enabled for your account.

token string

Optional. For card payments only: The card token obtained from tokenize-card. Required when payment_method is CARD.

customer_email string

Optional. Customer's email address. Required if the installation is configured to require email capture.

customer_mobile string

Optional. Customer's mobile phone number. Required if the installation is configured to require mobile capture.

customer_name string

Optional. Customer's name.

customer_language string

Optional. Customer's preferred language for communications. Defaults to en when omitted.

Allowed values:

en
th

interest_bearer string

Optional. Who bears the installment interest: customer or merchant. When omitted, the merchant's configured default is used; if the merchant has no default configured this argument is required. Must match the value passed to list-installment-plans so the customer's displayed quote matches the locked snapshot. Ignored when installment_plan_id is omitted.

Allowed values:

customer
merchant

street_address_1 string

Optional. The first line of the address (e.g. street number and name).

street_address_2 string

Optional. The second line of the address (e.g. apartment, suite, or unit).

postal_code string

Optional. The postal or ZIP code of the address.

city string

Optional. The city of the address.

state string

Optional. The state, province, or region of the address.

country string

Optional. The country of the address.

Errors specific to this endpoint


          INVALID_ARGUMENTS

This error occurs when the request contains invalid or missing parameters. Common cases include:

A missing merchant_id, installation_id, amount, currency, or payment_method
An unsupported currency (must match the funding currency configured for your provider)
An installation that could not be found or does not have the requested payment method enabled
Missing customer email or mobile when required by the installation
Missing address fields when required by the installation and payment method


          NOT_FOUND

This error occurs when we cannot find the merchant account, installation, or card token with the IDs provided. Double check that you are using the correct IDs.


          TOKEN_ALREADY_USED

This token has already been used to create a payment session. Each token can only be used once. Request a new token from tokenize-card.


          NOT_ENABLED

This installation is currently disabled.


          INSTALLMENT_NOT_ELIGIBLE

The installment plan you provided is no longer available for this amount/card combination. Re-fetch eligible plans via list-installment-plans and try again.

Errors common to all endpoints


          UNHANDLED_ERROR

This error occurs when the server encounters an unexpected internal error that it cannot handle gracefully. This typically happens due to bugs, infrastructure issues, or edge cases that weren't anticipated during development.


          INVALID_ARGUMENTS

This error occurs when the request contains invalid or missing parameters. Common cases include missing required fields, or values that don't match the expected format or type.


          BAD_VERSION

This error occurs when making requests to an API version that is either deprecated or not yet released. This commonly happens when using an outdated SDK or when the API version specified in the request URL is incorrect.

Open in Markdown

CODE SAMPLES

curl

curl "https://api.reservepay.com/sdk/select-payment-method" \
  -X POST
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "merchant_id": "123456789012",
        "installation_id": "ins_xhBi6ypq9G",
        "amount": 100000,
        "currency": "THB",
        "payment_method": "CARD",
        "token": "IC3949UCOE6U93"
      }'

Learn how to run these code samples in your terminal by reading our guide.