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
terminal_id	string	No	Pass terminal id when need to use specific mid
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	Yes	Customer first name
lastName	string	Yes	Customer last name
email	string	Yes	Customer email address
phoneNumber	string	No	Customer phone number
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	Yes	Webhook URL for transaction notifications
returnUrl	string	Yes	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"
  }
}

Response: 3D Secure (Production)

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

3DS redirect (production)

200

{
  "success": true,
  "status": "REDIRECT",
  "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"
  },
  "is3DS": "https://acquirer-3ds.example.com/authenticate?transactionId=FP260231SJWKL80027"
}

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
4111111111111110	3D Secure — redirect to issuer (response includes `is3DS` URL)
4111111111111111	2D — Success (no 3DS, immediate success)
4111111111111112	2D — Declined (no 3DS, immediate failure)

Response: 3D Secure (card 4111111111111110)

When the card requires 3DS, the response has status: "REDIRECT" and an is3DS URL. Redirect the customer to that URL to complete authentication.

3DS redirect

200

{
  "success": true,
  "status": "REDIRECT",
  "data": {
    "amount": 11,
    "currency": "USD",
    "order_id": "e21be056-d0c2-4003-be28-28dc88684b35",
    "txn_id": "FP2603YFGPKSWF0060",
    "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://api.finvypay.com/payment/sandbox/card?transactionId=FP2603YFGPKSWF0060"
}

Response: 2D Success (card 4111111111111111)

For 2D cards that succeed, the response has status: "SUCCESS". There is no is3DS field.

2D success

200

{
  "success": true,
  "status": "SUCCESS",
  "data": {
    "amount": 11,
    "currency": "USD",
    "order_id": "e21be056-d0c2-4003-be28-28dc88684b35",
    "txn_id": "FP2603YFGPKSWF0060",
    "firstName": "John",
    "lastName": "Doe",
    "address": "12, Hill",
    "city": "Nevada",
    "state": "Nevada",
    "country": "US",
    "email": "john@example.com",
    "webhookUrl": "https://your-domain.com/webhook"
  }
}

Response: 2D Failed (card 4111111111111112)

For 2D cards that are declined, the response has success: false. There is no is3DS field.

2D declined

200

{
  "success": false,
  "status": "FAILED",
  "error": {
    "code": "DECLINED",
    "message": "Transaction declined by issuer"
  }
}

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.