Initiating a Card Payment

`POST /v1/payments/card`

Use this endpoint to initiate a new card payment transaction. This will charge a customer’s card for a
specified amount. The request must include all required payment details as described below.

Request Headers:

Content-Type: application/json
Authorization: Bearer <AUTH_TOKEN>
Replace <AUTH_TOKEN> with the access token obtained from the Authorization Service.

Request Body Parameters

The following JSON fields are required when initiating a card payment:

Field	Type	Required	Description
`requestId`	String	Yes	Unique ID for the payment request. Used for idempotency (to prevent duplicate processing) and traceability.
`mid`	String	Yes	Merchant account ID that the transaction will be associated with.
`card`	Object (Card Object)	Yes	Card information for the payment. See Card Object for details.
`amount`	String	Yes	Transaction amount as a string. It must be a valid decimal number (e.g., `"10"`, `"10.0"`, or `"10.00"`), representing the actual amount in major units (e.g., dollars, not cents). Values with more than two decimal places will be automatically rounded.
`currency`	String	Yes	Currency code in ISO 4217 format (e.g., `"USD"`, `"EUR"`).
`lang`	String	Yes	Language code for localizing payment pages or messages (e.g., `"en"`, `"fr"`).
`callbackUrl`	String	Required in 3D Secure flow	URL on your server to receive the transaction status webhook. Required if 3D Secure is possible. Refer to the Webhook Callback Behavior page.
`successRedirectUrl`	String	Required in 3D Secure flow	URL to redirect the customer after a successful 3D Secure authentication.
`failureRedirectUrl`	String	Required in 3D Secure flow	URL to redirect the customer after a failed 3D Secure authentication.
`billingDetails`	Object BillingDetails	Yes	Customer billing info (name, address, etc.). See BillingDetails Object for fields.
`order`	Object (Order Object)	Yes	Order details (e.g., order ID, description, site). See Order Object.
`device`	Object (Device Object)	Yes	Device and browser info for fraud checks and 3DS. See Device Object.
`kycVerified`	Boolean	No	Flag indicating if the customer has passed KYC (Know Your Customer) verification.
`previousPaymentCount`	Long (int64)	No	Number of previous payments made by this customer.
`metadata`	Object	No	Additional metadata as key-value pairs for custom context or internal use.

Card Object

The card object contains the cardholder and card details needed to process the transaction.

Field	Type	Required	Description
`number`	String	Yes	Card number (PAN) as a numeric string (no spaces or dashes).
`cardHolderName`	String	Yes	Cardholder’s name as printed on the card.
`expMonth`	String	Yes	Card’s expiration month in `MM` format (e.g., `"08"` for August).
`expYear`	String	Yes	Card’s expiration year in `YYYY` format (e.g., `"2027"`).
`cvv`	String	Yes	Card verification code (CVV/CVC), typically a 3- or 4-digit number on the card.
`requestThreeDSecure`	Boolean	Yes	Whether to request 3D Secure authentication for this transaction. Set to `true` to require 3DS if available. Even if set to `false`, some card issuers will still require 3DS.

BillingDetails Object

The billingDetails object contains billing and personal information about the customer, used for
payment processing and risk checks.

Field	Type	Required	Description
`externalUserId`	String	No	An identifier for the customer in your system (useful for reconciliation or linking transactions to user accounts).
`firstName`	String	Yes	Customer’s first name.
`lastName`	String	Yes	Customer’s last name.
`address1`	String	Yes	Billing address line 1 (street address or P.O. box).
`city`	String	Yes	Billing city.
`state`	String	No	Billing state or province.
`country`	String	Yes	Billing country (ISO 3166-1 alpha-2 country code, e.g., `"US"`).
`postalCode`	String	Yes	ZIP or postal code.
`phone`	String	Yes	Customer’s phone number.
`email`	String	Yes	Customer’s email address.
`dateOfBirth`	String	No	Customer’s date of birth in `YYYY-MM-DD` format.

Order Object

The object contains information about the order or purchase associated with the transaction. This order data can help with tracking and reporting.

Field	Type	Required	Description
`date`	String	No	Date of the order in ISO 8601 format (e.g., `"2025-07-17"`).
`orderId`	String	No	Unique identifier for the order in your system.
`title`	String	No	Title or description of the order (e.g., `"Monthly Subscription"` or product name).
`siteId`	String	No	Identifier for the site or platform where the order was placed (if applicable).
`name`	String	No	Name of the customer (if not provided elsewhere).
`domainName`	String	No	Domain name of the site where the order was placed (e.g., `"shop.example.com"`).

Device Object

The device object captures information about the customer’s device and browser environment, used for
fraud prevention and 3D Secure authentication.

Field	Type	Required	Description
`deviceId`	String	No	Unique identifier for the device (if you generate one for the user).
`fingerprintData`	String	No	Device fingerprint or hash for risk assessment.
`ip`	String	Yes	IP address of the customer’s device.
`accept`	String	No	Browser’s `Accept` header value. Required for 3D Secure transactions.
`acceptLanguage`	String	No	Browser’s `Accept-Language` header. Required for 3D Secure.
`userAgent`	String	No	Browser’s `User-Agent` string.
`javaEnabled`	Boolean	No	Whether Java is enabled in the browser. Required for 3D Secure.
`javaScriptEnabled`	Boolean	No	Whether JavaScript is enabled in the browser. Required for 3D Secure.
`deviceLanguage`	String	No	Device’s language setting. Required for 3D Secure.
`colorDepth`	String	No	Screen color depth (e.g., `"24"` for 24-bit). Required for 3D Secure.
`screenHeight`	String	No	Screen height in pixels. Required for 3D Secure.
`screenWidth`	String	No	Screen width in pixels. Required for 3D Secure.
`deviceTimezone`	String	No	Device’s time zone (e.g., `"UTC+05:30"`). Required for 3D Secure.

Example Request

{
  "requestId": "req12345",
  "mid": "merchant456",
  "card": {
    "number": "4111111111111111",
    "cardHolderName": "John Doe",
    "expMonth": "12",
    "expYear": "2025",
    "cvv": "123",
    "requestThreeDSecure": true
  },
  "amount": "100.00",
  "currency": "USD",
  "lang": "en",
  "callbackUrl": "https://yourserver.com/callback",
  "successRedirectUrl": "https://yourserver.com/success",
  "failureRedirectUrl": "https://yourserver.com/failure",
  "billingDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "address1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "country": "US",
    "postalCode": "10001",
    "phone": "+123456789",
    "email": "[email protected]",
    "dateOfBirth": "1990-01-01"
  },
  "order": {
    "date": "2025-07-17",
    "orderId": "ord789",
    "title": "Product Purchase",
    "siteId": "site001",
    "name": "John Doe",
    "domainName": "example.com"
  },
  "device": {
    "deviceId": "device123",
    "fingerprintData": "abcde12345",
    "ip": "192.168.1.1",
    "accept": "*/*",
    "acceptLanguage": "en-US",
    "userAgent": "Mozilla/5.0",
    "javaEnabled": true,
    "javaScriptEnabled": true,
    "deviceLanguage": "en",
    "colorDepth": "24",
    "screenHeight": "1080",
    "screenWidth": "1920",
    "deviceTimezone": "America/New_York"
  },
  "kycVerified": true,
  "previousPaymentCount": 5,
  "metadata": {
    "promoCode": "PROMO123",
    "campaign": "Winter2025"
  }
}

Success Response

After a payment initiation request, the API will return a JSON response with the transaction reference and
status. The key fields in the response include:

Field	Type	Description
`transactionId`	String	Unique identifier for the transaction. You can use this to query status or info later.
`transactionStatus`	String	Current status of the transaction (e.g., `NEW`, `PENDING`, `CUSTOMER_VERIFICATION`, `SUCCEED`, `FAILED`, `REFUNDED`).
`declineCode`	Int	(Optional) A code indicating the reason for a failure, if the transaction was declined.
`challengeUrl`	String	(Conditional) URL to redirect the customer for 3D Secure authentication (if `transactionStatus` requires it).
`challengeUrlIframe`	String	(Conditional) URL for an embeddable 3D Secure challenge (for iframe integration, if supported).

Example Success Response

{
"transactionId": "733609401625775730",
"transactionStatus": "CUSTOMER_VERIFICATION",
"challengeUrl": "https://secure-3ds-url.com/challenge?
id=C8W94B63DBD4STT5_17527427055183026&url=",
"challengeUrlIframe": "https://secure-3ds-url.com/iframe-challenge?
id=C8W94B63DBD4STT5_17527427055183026&url="
}

In the above example, the transaction was created and requires 3D Secure verification
(transactionStatus is "CUSTOMER_VERIFICATION"). The customer should be redirected to the
challengeUrl (or an iframe should load the challengeUrlIframe) to complete authentication.

Example Failure Response:

{
"transactionId": "txn67890",
"transactionStatus": "FAILED",
"declineCode": 101
}

If a transaction fails immediately (for example, due to invalid card details or insufficient funds), the
transactionStatus will be "FAILED" and a declineCode be provided.