## Request a payment

Start a card payment directly from your server without requiring customer
interaction. This is a merchant-initiated transaction (MIT) endpoint that
combines payment method selection and payment initiation into a single call.

This endpoint supports card payments only. You can pay using either a saved
card ID or a card token from the `tokenize-card` endpoint.

Since this is a merchant-initiated transaction, the 3D Secure (3DS)
authentication flow is skipped.

Your merchant account must have the MIT flag enabled for the card payment
method to use this endpoint.

## Endpoint signature

```http
POST https://api.reservepay.com/merchants/request-payment HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>

{
  card_id: string?,
  token: string?,
  amount: string,
  currency: string,
  installation_id: string,
  capture: boolean,
  external_id: string?,
  customer_id: string?,
  customer_email: string?,
  customer_mobile: string?,
  customer_name: string?,
  save_card: string?,
}
```

Returns: string

## Request arguments

### `card_id` (string)

_Optional_. The ID of a previously saved card (starting with `crd_`) or your own
external card identifier. The card must belong to the customer specified
by one of the customer fields.

If neither `card_id` nor `token` is provided, the customer's
default card will be used.

### `token` (string)

_Optional_. A card token obtained from the `tokenize-card` endpoint. Each token
can only be used once.

If neither `card_id` nor `token` is provided, the customer's
default card will be used.

### `amount` (string)

**Required**. The payment amount in the smallest currency unit (e.g. satang). For example,
use 10000 for 100 THB. Must be a positive integer.

### `currency` (string)

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

### `installation_id` (string)

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

### `capture` (boolean)

**Required**. Controls when funds are captured. Set to true to capture funds
immediately upon payment authorization, or false to only authorize
funds for later capture.

### `external_id` (string)

_Optional_. Your unique reference for this payment, such as an order or invoice number. You
can use this ID later to look up the payment instead of our payment ID. Must be
unique across all your payments.

### `customer_id` (string)

_Optional_. Either a Customer ID (starting with `ctc_`) or your own external
customer identifier. We'll link this payment to an existing customer
if found, or create a new customer if not.

### `customer_email` (string)

_Optional_. The customer's email address.

### `customer_mobile` (string)

_Optional_. The customer's mobile number.

### `customer_name` (string)

_Optional_. The customer's name.

### `save_card` (string)

_Optional_. Option to save the card used in this payment to the contact. Only
applicable when using a token (not a card_id). The card will be saved
if the token is multi-use.

- `ADD`: Add the card to the contact without setting it as default
- `DEFAULT`: Add the card to the contact and set it as the default card

If any error occurs while saving the card, it will be silently ignored and
will not block the payment flow.

## Errors specific to this endpoint

### `NOT_FOUND`

The installation, card, or token could not be found. Double check that
you are using the correct IDs and that the card belongs to the specified
customer.

### `NOT_ALLOWED`

Merchant initiated transactions are not allowed for this payment method.
Contact support to enable the MIT flag on your card payment method.

### `TOKEN_ALREADY_USED`

This token has already been used. Request a new token from tokenize-card.

### `NOT_SUPPORTED`

The payment method does not support the requested operation.
This occurs when capture is set to false but the payment method's
integrations do not support authorization without capture.

## 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 does not exist.
This commonly happens when using an outdated SDK or when the API version
specified in the request URL is incorrect.