Live API

Charge

Process live card charges using server-to-server integration. Use your live API key with /api/live/charge.

Card Charge

POST/api/live/charge

EncryptedAPI Key

Payload encryption required. Encrypt the request JSON and send { "payload": "<iv>:<ciphertext>" }. Decrypt the response payload field. Encryption guide →. Do not share your API key or Encryption Key with anyone.

Processes a charge directly without redirecting the user. This endpoint is suitable for server-side integrations where you handle card data securely.

Important

All payment API requests must be encrypted on your server before sending. Build the JSON below, encrypt it with your Encryption Key, and POST {"payload": "<iv_hex>:<ciphertext_hex>"}. Do not share your API key or Encryption Key with anyone — use them only on your backend. See the Encryption guide for code examples.

Request structure (encrypt this JSON)

{
  "merchantOrderId": "ORD-12345",

  "payment": {
    "amount": 100,
    "currency": "USD"
  },

  "card": {
    "number": "4539148800003011",
    "expiryMonth": 12,
    "expiryYear": 2031,
    "cvv": "123",
    "holderName": "John Doe"
  },

  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "ip": "185.23.44.91"
  },

  "billing": {
    "addressLine1": "12, Hill",
    "city": "Nevada",
    "state": "Nevada",
    "country": "US",
    "postalCode": "12345"
  },

  "callback": {
    "webhookUrl": "https://your-domain.com/webhook",
    "returnUrl": "https://your-domain.com/payment/callback"
  }
}

Wire format (send this to the API)

Encrypted request body

{
  "payload": "3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a:8e4f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0"
}

Request Parameters

Single reference table grouped by JSON object. Nested fields use dot notation (e.g. payment.amount).

Field	Type	Required	Description
Order
merchantOrderId	string	Required	Unique order identifier from your system
merchantProfileId	number	Optional	Merchant profile ID. Defaults to your PRIMARY profile if omitted
terminalId	string	Optional	Terminal ID to route the charge to a specific MID (skips routing/cascading)
description	string	Optional	Human-readable payment description
metadata	string	Optional	Additional data as a JSON string
source	string	Optional	Payment source. Use 'link' when charging via a payment link token
token	string	Optional	Payment link token (required when source is 'link')
Paymentpayment
payment.amount	number	Required	Payment amount (minimum 0.01)
payment.currency	string	Required	Currency code (3 letters, e.g. USD, EUR)
Cardcard
card.number	string	Required	Card number (13–19 digits)
card.expiryMonth	number	Required	Expiry month (1–12)
card.expiryYear	number	Required	Expiry year (4 digits)
card.cvv	string	Optional	CVV code (3–4 digits)
card.holderName	string	Optional	Name printed on the card
Customercustomer
customer.firstName	string	Required	Customer first name
customer.lastName	string	Required	Customer last name
customer.email	string	Required	Customer email address
customer.phoneNumber	string	Optional	Customer phone number
customer.ip	string	Optional	Customer IPv4 address for risk checks. Falls back to the request IP if omitted
Billingbilling
billing.addressLine1	string	Required	Billing street address
billing.city	string	Required	Billing city
billing.state	string	Required	Billing state or region
billing.country	string	Required	Billing country (2-letter ISO code)
billing.postalCode	string	Required	Billing ZIP or postal code
Callbackcallback
callback.webhookUrl	string	Required	Webhook URL for transaction status notifications
callback.returnUrl	string	Required	URL to redirect the customer after payment or 3DS
callback.cancelUrl	string	Optional	URL to redirect if the customer cancels

Important

All payment API responses — including success, declined, failed, and validation errors — are returned encrypted when you are authenticated. The wire body is {"success": true|false, "payload": "<iv_hex>:<ciphertext_hex>"}. Decrypt payload with your Encryption Key to read the standard JSON documented below. Outer success mirrors the decrypted outcome (false for declines and errors). Do not share your Encryption Key or API key — keep both on your server only.

Wire format (from API)

{
  "success": true,
  "payload": "7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7:4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8"
}

After decryption

Success Response

200

{
  "success": true,
  "status": "SUCCESS",
  "data": {
    "amount": 100,
    "currency": "USD",
    "merchantOrderId": "ORD-12345",
    "transactionId": "FP260231SJWKL80027",
    "firstName": "John",
    "lastName": "Doe",
    "address": "12, Hill",
    "city": "Nevada",
    "state": "Nevada",
    "country": "US",
    "email": "john@example.com",
    "webhookUrl": "https://your-domain.com/webhook"
  }
}

Wire format (from API)

{
  "success": true,
  "payload": "7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7:4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8"
}

After decryption

Declined Response

400

{
  "success": false,
  "status": "FAILED",
  "message": "Transaction declined by issuer",
  "error": {
    "code": "DECLINED",
    "message": "Transaction declined by issuer"
  },
  "data": {
    "amount": 100.5,
    "currency": "USD",
    "merchantOrderId": "ORD-12345",
    "transactionId": "FP260231SJWKL80027",
    "firstName": "John",
    "lastName": "Doe",
    "address": "12, Hill",
    "city": "Nevada",
    "state": "Nevada",
    "country": "US",
    "email": "john@example.com",
    "webhookUrl": "https://your-domain.com/webhook"
  }
}

Wire format (from API)

{
  "success": true,
  "payload": "7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7:4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8"
}

After decryption

Validation Error Response

400

{
  "success": false,
  "message": "Card has expired. Use a current or future expiry date",
  "errorTrace": {
    "errorType": "VALIDATION_ERROR",
    "code": "VALIDATION_ERROR",
    "errors": [
      "Card has expired. Use a current or future expiry date"
    ]
  }
}

Response: 3D Secure (Production)

Important

When the card requires 3D Secure authentication, the response has status: "REDIRECT" and an is3DS field containing the redirect URL. The URL is the gateway 3DS URL (provided by your gateway; format and domain depend on the gateway name). Redirect the customer to this URL to complete 3DS, then they will return to your returnUrl.

Wire format (from API)

{
  "success": true,
  "payload": "7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7:4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8"
}

After decryption

3DS redirect (production)

200

{
  "success": true,
  "status": "REDIRECT",
  "data": {
    "amount": 100,
    "currency": "USD",
    "merchantOrderId": "ORD-12345",
    "transactionId": "FP260231SJWKL80027",
    "firstName": "John",
    "lastName": "Doe",
    "address": "12, Hill",
    "city": "Nevada",
    "state": "Nevada",
    "country": "US",
    "email": "john@example.com",
    "webhookUrl": "https://your-domain.com/webhook"
  },
  "is3DS": "https://gateway-3ds.example.com/authenticate?transactionId=FP260231SJWKL80027"
}

Important

This endpoint requires a merchant gateway account to be assigned to your merchant profile. If no assignment exists, the transaction will fail immediately with a clear error message.

Transaction Flow

Charge transactions follow this execution order:

Merchant ownership validation (via API key)
merchantProfileId validation (defaults to PRIMARY if not provided)
merchant_gateway_account validation (MANDATORY - fails if not assigned)
IP whitelist check
Risk management checks
Card risk checks
Routing & cascading logic (if configured)
Gateway API call

Critical

All transactions MUST execute through an assigned merchant_gateway_account. If no assignment exists, the transaction will fail immediately with a clear error message.

Security & Risk Management

For charge requests, the following security checks are performed:

IP Whitelist: Validates that the request IP is whitelisted (if IP whitelist is enabled)
Risk Rules: Checks for blocked cards, emails, IPs, domains, and BINs
Card Whitelist: Validates that the card is in trusted cards list (if card whitelist is enabled)

Critical

If any risk check fails, the transaction is immediately blocked with status BLOCKED and a webhook is triggered.