Charge a card (S2S)

For merchants handling raw card data on their own server as part of a fully embedded checkout — see Choosing a flow for how this compares to Create a hosted checkout link. Encrypt cardData (full card JSON) with AES-256-GCM using your secret key as key material — do not send the secret key itself in headers. Only when the referenced payment’s currency is NGN, also encrypt and send pin. Then POST cardData, optional pin (NGN only), plain paymentReference, and requestMetadata.

Endpoint

POST https://api-v3.reeple.ai/s2s/payments/charge

Authentication

Send your dashboard public key in a public-key header — same key as ApiKey.publicKey in the dashboard. See the S2S Payments overview.

Encrypting card data

Card data fields

Serialize as UTF-8 JSON (minified or pretty). All values are strings.

Field	Description
`bin`	First 6 digits of the PAN (BIN).
`brand`	Card brand (e.g. `visa`, `mastercard`).
`cvv`	Card verification value.
`number`	Full card number.
`expiry_month`	Two-digit month (e.g. `01`–`12`).
`expiry_year`	Two- or four-digit year (e.g. `25` or `2025`).

Example before encryption:

{
  "bin": "506066",
  "brand": "visa",
  "cvv": "123",
  "number": "4111111111111111",
  "expiry_month": "12",
  "expiry_year": "25"
}

Encrypt that JSON string and send the result as cardData. Only for NGN payments, encrypt the PIN as a separate UTF-8 string and send as pin; omit pin entirely for non-NGN payments. paymentReference is sent in plain text.

Key derivation

Must match the server:

Take the exact secret key string (UTF-8).
AES-256 key = SHA-256 hash of that string → 32 bytes.

Never send your secret key itself in a request or header — only the derived ciphertext.

Algorithm

AES-256-GCM
IV: 12 random bytes (a new IV for every encryption)
Auth tag: 16 bytes (GCM tag; required for decryption)

Ciphertext format

Concatenate three hex strings with colons (no spaces):

<ivHex>:<tagHex>:<cipherHex>

ivHex: 24 hex chars (12 bytes)
tagHex: 32 hex chars (16 bytes)
cipherHex: variable length

Example (TypeScript, Node.js `crypto`)

import * as crypto from 'crypto';

const IV_LENGTH = 12;

function deriveKey(secret: string): Buffer {
  return crypto.createHash('sha256').update(String(secret), 'utf8').digest();
}

/** Plaintext UTF-8 → `ivHex:tagHex:cipherHex` (AES-256-GCM). */
function encryptS2S(plainText: string, secretKey: string): string {
  const key = deriveKey(secretKey);
  const iv = crypto.randomBytes(IV_LENGTH);
  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
  const ciphertext = Buffer.concat([
    cipher.update(plainText, 'utf8'),
    cipher.final(),
  ]);
  const tag = cipher.getAuthTag();
  return [iv, tag, ciphertext].map((b) => b.toString('hex')).join(':');
}

const secretKey = 'your-secret-key'; // from dashboard; do NOT send in headers

const cardJson = JSON.stringify({
  bin: '506066',
  brand: 'visa',
  cvv: '123',
  number: '4111111111111111',
  expiry_month: '12',
  expiry_year: '25',
});

const cardData = encryptS2S(cardJson, secretKey);
const pin = encryptS2S('1234', secretKey); // NGN only: encrypt the PIN string only

// POST body: { cardData, pin, paymentReference: '...' }

Request body

Field	Type	Description
`cardData`	String	Required. AES-256-GCM ciphertext (`ivHex:tagHex:cipherHex`) of UTF-8 JSON with fields: `bin`, `brand`, `cvv`, `number`, `expiry_month`, `expiry_year` (all strings).
`paymentReference`	String	Required. Plain text.
`pin`	String	Optional. AES-256-GCM ciphertext of the card PIN; send only when the referenced payment is NGN.
`requestMetadata`	Object	Required. `{ clientIp, userAgent }` sourced from the cardholder’s HTTP request, forwarded for fraud detection and audit. Send `{}` if neither value is available — the charge still proceeds normally.

NGN example

Encrypted card + encrypted PIN + required metadata:

{
  "cardData": "<ivHex:tagHex:cipherHex — encrypt UTF-8 JSON {\"bin\":\"506066\",\"brand\":\"visa\",\"cvv\":\"123\",\"number\":\"4111111111111111\",\"expiry_month\":\"12\",\"expiry_year\":\"25\"}>",
  "pin": "<ivHex:tagHex:cipherHex — encrypt UTF-8 PIN>",
  "paymentReference": "pay_ref_abc123",
  "requestMetadata": {
    "clientIp": "203.0.113.45",
    "userAgent": "Mozilla/5.0 ..."
  }
}

Non-NGN example

Encrypted card only, no PIN, required metadata:

{
  "cardData": "<ivHex:tagHex:cipherHex>",
  "paymentReference": "pay_ref_def456",
  "requestMetadata": {
    "clientIp": "203.0.113.45",
    "userAgent": "Mozilla/5.0 ..."
  }
}

Minimal example

Encrypted card only, no PIN, metadata unavailable:

{
  "cardData": "<ivHex:tagHex:cipherHex>",
  "paymentReference": "pay_ref_ghi789",
  "requestMetadata": {}
}

Response

{
  "success": true,
  "statusCode": 200,
  "message": "Charge successful",
  "data": {
    "status": "success",
    "reference": "a1b2c3d4e5f6g7h8",
    "amount": 2500,
    "fee": 125,
    "currency": "NGN",
    "message": "Charge successful"
  }
}

A 400 on this endpoint specifically means the charge failed (the provider declined it or the encrypted payload couldn’t be decrypted) — distinct from the generic “bad request” meaning elsewhere in this API.

See Errors for the shape of 401/500 responses.

Next steps

Verify a payment order to confirm the final status.
Webhooks fires charge.success/charge.failed events as the charge resolves.

Get Started

Bank Accounts

Bill Payments

Collections

Compliance

Customer

External Services

Gift Cards

Payment Links

Payouts

Refunds

S2S Payments

Transactions

Tuition

Endpoint

Authentication

Encrypting card data

Card data fields

Key derivation

Algorithm

Ciphertext format

Example (TypeScript, Node.js `crypto`)

Request body

NGN example

Non-NGN example

Minimal example

Response

Next steps

​Endpoint

​Authentication

​Encrypting card data

​Card data fields

​Key derivation

​Algorithm

​Ciphertext format

​Example (TypeScript, Node.js crypto)

​Request body

​NGN example

​Non-NGN example

​Minimal example

​Response

​Next steps

Endpoint

Authentication

Encrypting card data

Card data fields

Key derivation

Algorithm

Ciphertext format

Example (TypeScript, Node.js `crypto`)

Request body

NGN example

Non-NGN example

Minimal example

Response

Next steps