Card Payments API

Process credit and debit card payments using server-to-server integration.

Server-to-Server Card Payment (Production)

POST/api/v1/production/card

Requires API Key

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

Request Body

{
  "orderId": "ORD-12345",
  "amount": 100,
  "currency": "USD",
  "cardNumber": "4111111111111111",
  "cardExpiryMonth": 12,
  "cardExpiryYear": 2025,
  "cvv": "123",
  "cardholderName": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "address": "12, Hill",
  "city": "Nevada",
  "state": "Nevada",
  "country": "US",
  "zip": "12345",
  "webhookUrl": "https://your-domain.com/webhook",
  "returnUrl": "https://your-domain.com/payment/callback"
}

Request Parameters

Parameter	Type	Required	Description
orderId	string	Yes	Unique order identifier from your system
amount	number	Yes	Payment amount (minimum 0.01)
currency	string	Yes	Currency code (3 letters, e.g., USD, EUR)
merchantProfileId	number	No	Merchant Profile ID. Defaults to user's PRIMARY profile if not provided
cardNumber	string	Yes	Card number (13-19 digits)
cardExpiryMonth	number	Yes	Expiry month (1-12)
cardExpiryYear	number	Yes	Expiry year (4 digits)
cvv	string	No	CVV code (3-4 digits)
cardholderName	string	No	Cardholder name
firstName	string	No	Customer first name
lastName	string	No	Customer last name
email	string	No	Customer email address
address	string	Yes	Customer billing street address
city	string	Yes	Customer billing city
state	string	Yes	Customer billing state / region
country	string	Yes	Customer billing country (2-letter ISO code)
zip	string	Yes	Customer billing ZIP / postal code
webhookUrl	string	No	Webhook URL for transaction notifications
returnUrl	string	No	URL to redirect the customer after payment (optional)

Success Response

200

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

Error Response

400

{
  "success": false,
  "error": {
    "code": "INVALID_CARD",
    "message": "The card number is invalid"
  }
}

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

Server-to-Server Card Payment (Sandbox)

POST/api/v1/sandbox/card

Requires API Key

Uses test gateway for sandbox testing. All transactions are simulated and do not process real payments.

Request Body

Same request body as production endpoint. Use test card numbers for testing:

{
  "orderId": "ORD-12345",
  "amount": 100,
  "currency": "USD",
  "cardNumber": "4111111111111111",
  "cardExpiryMonth": 12,
  "cardExpiryYear": 2025,
  "cvv": "123",
  "cardholderName": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "address": "12, Hill",
  "city": "Nevada",
  "state": "Nevada",
  "country": "US",
  "zip": "12345",
  "webhookUrl": "https://your-domain.com/webhook",
  "returnUrl": "https://your-domain.com/payment/callback"
}

Test Card Numbers

Card Number	Result
4111111111111111	Success
4111111111111112	Declined

Transaction Flow

Card payment transactions follow this execution order:

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

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

Security & Risk Management

For card payments, 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)

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