Payments

Card Payments API

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

Server-to-Server Card Payment (Production)

POST

ProductionAPI 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

json

{
  "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",
  "ipaddress": "185.23.44.91",
  "webhookUrl": "https://your-domain.com/webhook",
  "returnUrl": "https://your-domain.com/payment/callback"
}

Request Parameters

Parameter	Type	Description
`orderId`required	string	Unique order identifier from your system
`amount`required	number	Payment amount (minimum 0.01)
`currency`required	string	Currency code (3 letters, e.g., USD, EUR)
`merchantProfileId`optional	number	Merchant Profile ID. Defaults to user's PRIMARY profile if not provided
`terminal_id`optional	string	Pass terminal id when need to use specific mid
`cardNumber`required	string	Card number (13-19 digits)
`cardExpiryMonth`required	number	Expiry month (1-12)
`cardExpiryYear`required	number	Expiry year (4 digits)
`cvv`required	string	CVV code (3-4 digits)
`cardholderName`optional	string	Cardholder name
`firstName`required	string	Customer first name
`lastName`required	string	Customer last name
`email`required	string	Customer email address
`phoneNumber`optional	string	Customer phone number
`address`required	string	Customer billing street address
`city`required	string	Customer billing city
`state`required	string	Customer billing state / region
`country`required	string	Customer billing country (2-letter ISO code)
`zip`required	string	Customer billing ZIP / postal code
`ipaddress`optional	string	Customer IP address (IPv4). Used for risk and fraud checks; if not provided, the request IP is used.
`webhookUrl`required	string	Webhook URL for transaction notifications
`returnUrl`required	string	URL to redirect the customer after payment (optional)

Success Response

200

json

{
  "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

json

{
  "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

json

{
  "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

SandboxAPI Key

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

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

Request Body

json

{
  "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",
  "ipaddress": "185.23.44.91",
  "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

json

{
  "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

json

{
  "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

json

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

Transaction Flow

Card payment transactions follow this execution order:

1
Merchant ownership validation
Validated via API key
2
merchantProfileId validation
Defaults to PRIMARY if not provided
3
merchant_acquirer_account validation
MANDATORY — fails if not assigned
4
IP whitelist check
5
Risk management checks
6
Card risk checks
7
Routing & cascading logic
If configured
8
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)

Warning

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

PreviousOverview NextAPM Payments