> ## Documentation Index
> Fetch the complete documentation index at: https://docs-v2.reeple.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokenized charge

> Charge a saved card token server-side, without the customer present

Creates and charges an order in one call using a stored card token. This is the off-session
path — for subscriptions, retries and repeat billing where there is no customer at a checkout
page to complete an authentication step.

Unlike every other payment route, there is no separate create-then-pay: one request does both.

## Endpoint

```
POST https://api-v4.reeple.ai/charge/order/card/tokenized/pay
```

## Authentication

Authenticate with your **secret key** in the `api-key` header.

```
api-key: YOUR_SECRET_KEY
```

<Warning>
  This endpoint moves money with no customer interaction. Keep the secret key server-side and
  charge only with a mandate the customer has actually agreed to.
</Warning>

## Request body

Plain JSON — this endpoint is **not** encrypted.

| Field           | Type   | Description                                                      |
| --------------- | ------ | ---------------------------------------------------------------- |
| `customer`      | Object | **Required.** See [Customer object](#customer-object).           |
| `order`         | Object | **Required.** See [Order object](#order-object).                 |
| `payment`       | Object | **Required.** See [Payment object](#payment-object).             |
| `authorization` | Object | **Required.** See [Authorization object](#authorization-object). |

### Customer object

| Field       | Type   | Description                                                |
| ----------- | ------ | ---------------------------------------------------------- |
| `firstname` | String | **Required.**                                              |
| `lastname`  | String | **Required.**                                              |
| `email`     | String | **Required.**                                              |
| `mobile`    | String | **Required.** International format, e.g. `+2348158200000`. |
| `country`   | String | **Required.** Two-letter country code.                     |

### Order object

| Field         | Type   | Description                                                                                   |
| ------------- | ------ | --------------------------------------------------------------------------------------------- |
| `amount`      | Number | **Required.** In the currency's standard unit — see [Amount units](/currencies#amount-units). |
| `reference`   | String | **Required.** Your own unique reference for this charge.                                      |
| `currency`    | String | **Required.** See [Supported currencies](/currencies).                                        |
| `description` | String | **Required.** Shown to the customer.                                                          |

### Payment object

| Field         | Type   | Description                                                          |
| ------------- | ------ | -------------------------------------------------------------------- |
| `RedirectUrl` | String | **Required.** Used only if the issuer forces an authentication step. |

### Authorization object

| Field       | Type   | Description                          |
| ----------- | ------ | ------------------------------------ |
| `cardToken` | String | **Required.** The stored card token. |

## Request example

```bash theme={null}
curl -X POST https://api-v4.reeple.ai/charge/order/card/tokenized/pay \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_SECRET_KEY" \
  -d '{
    "customer": {
      "firstname": "Ada",
      "lastname": "Lovelace",
      "mobile": "+2348158200000",
      "country": "NG",
      "email": "ada@example.com"
    },
    "order": {
      "amount": 2,
      "reference": "subscription-2026-08",
      "description": "August subscription",
      "currency": "NGN"
    },
    "payment": {
      "RedirectUrl": "https://yourdomain.com/payment/callback"
    },
    "authorization": {
      "cardToken": "TKNMDU4MzU4NzUwNTk0Mjg5NzQwMzgwNDA0NzQ1ODkz2173"
    }
  }'
```

## Response

Returns the same shape as [Pay an order](/api-reference/orders/pay-order): a
`paymentDetail` and an `orderPayment`.

<Warning>
  A successful response still isn't proof of payment. Poll
  [Verify an order](/api-reference/verification/verify-order) with the reference you supplied,
  exactly as you would for an interactive payment.
</Warning>

<Note>
  If the issuer requires authentication despite the token, `paymentDetail.redirectUrl` comes back
  populated. Off-session, there is no one to send there — treat that as "this charge needs the
  customer" and fall back to an interactive payment rather than dropping the redirect.
</Note>

## Where the token comes from

`cardToken` is issued when a card is stored:

<CardGroup cols={2}>
  <Card title="Save a card" href="/api-reference/orders/save-card">
    Store the card after a successful order.
  </Card>

  <Card title="Save at charge time" href="/api-reference/payments/pay-with-card#saving-a-card-at-charge-time">
    Set `saveCard: true` on the original charge.
  </Card>
</CardGroup>

<Note>
  `cardToken` here is a different identifier from the `savedCardId` used by
  [Pay with a card](/api-reference/payments/pay-with-card#charging-a-saved-card). `savedCardId`
  is an in-session convenience with your public key; `cardToken` is the off-session credential
  used with your secret key. Confirm with Reeple how the token is surfaced for your account.
</Note>

## Common errors

| Code  | Message                                          | Cause                                               |
| ----- | ------------------------------------------------ | --------------------------------------------------- |
| `401` | `Invalid SECRET key. Please check and try again` | Wrong key type, or a key from the other environment |
| `13`  | `Order payment is currently pending`             | A charge for this reference is already in flight    |

<Warning>
  Use a fresh, idempotent `reference` for every billing period. Reusing one returns an error
  rather than charging twice — which is the safe outcome, but it means a genuine retry needs a
  reference you can recognise as the same attempt.
</Warning>