Card Payments
The Card Payments API provides access to all endpoints related to processing and managing card-based payment
transactions in the Exirom platform. This includes initiating payments, verifying transaction statuses,
handling refunds, and managing saved payment methods.
To initiate a transaction, send a POST request to the Exirom API with the required payload. Upon processing the request, Exirom may return a terminal transaction status immediately in the synchronous response. If a callbackUrl was provided in the request, Exirom will also trigger a webhook notification reflecting the transaction status.
Note: While the webhook provides a reliable way to track transaction outcomes, it is not the only source of the final status. In some cases, the terminal status may already be available in the initial synchronous response. The webhook will still be fired (if configured), but you should not assume that the final status is only available via callback.
If the payment requires 3D Secure (3DS) authentication, the API response will include a challengeUrl. This URL is intended for the customer to complete the 3DS verification directly with their card issuer, generally by entering a one-time password (OTP) or using biometric/multi-factor authentication.
It is the merchant’s responsibility to either:
- Redirect the customer to the challengeUrl,
OR
- Embed the challengeUrlIframe (if provided) for an in-page experience.
Completing this step is essential for the transaction to proceed. The customer must complete the 3DS challenge to finalize the payment authorization.
Exirom’s card payment endpoints enable seamless integration with a secure and scalable payment
infrastructure, whether you're building a custom checkout flow or embedding payments into your platform.
This guide provides the details needed to manage the card transaction lifecycle.
Card Payment Endpoints
POST /v1/payments/card - Initiate a new card payment transaction.
GET /v1/payments/card/status/{id} - Retrieve the status of a specific card transaction.
GET /v1/payments/card/info/{id} - Retrieve detailed information for a specific card transaction.
POST /v1/payments/card/tokenize - Tokenize (vault) card details for future use.
POST /v1/payments/card/charge - Charge a previously tokenized (saved) card.
POST /v1/payments/card/recurring - Initiate a recurring (subscription) payment using a saved
card.
API Base URL
Use the following base URLs depending on your environment:
https://$host.com/api/v1/payments/cardhttps://sandbox.$host.com/api/v1/payments/cardAuthentication and Request Headers
All requests to these endpoints must include the proper headers for authentication and content type.
Ensure you have a valid authorization token from the Exirom Authorization Service.
| Header | Value | Description |
|---|---|---|
| Content-Type | application/json | Specifies that the request body is in JSON format. |
| Authorization | Bearer <AUTH_TOKEN> | Bearer token for authentication. Replace <AUTH_TOKEN> with the token from the Authorization Service. |
| Referer | <REFERER_URL> | The referring URL of the request (set this to your site’s URL or the appropriate source). |
Pages in this Section
This section provides a walkthrough for card payments. Let’s dive into each topic in detail by navigating to its respective subpages:
✅ Card Payment Process Flow - An end-to-end overview of the card payment lifecycle, from initiating a transaction to final settlement, with visual diagrams.
✅ Initiating a Card Payment - Step-by-step instructions for sending a payment request, including mandatory fields, payload format, and example API calls.
✅ Checking Payment Status - Covers how to query the current status of a card payment using its transaction ID, including possible status values and their meanings.
✅ Retrieving Payment Details - Explains how to fetch the full details of a specific payment, including card information (masked), transaction amounts, and settlement data.
✅ Tokenizing a Card - Describes how to securely store card details by generating a reusable token, enabling future payments without re-entering card information.
✅ Charging a Saved Card - Instructions for initiating a payment using an existing card token, without requiring the customer to re-enter card details.
✅ Recurring Payments - Guidelines for setting up and managing automated recurring billing using stored card tokens.
✅ Webhook Callback & Transaction Lifecycle - Explains how webhook notifications are used to update transaction status asynchronously, and how to handle them securely in your backend.
✅ Completing 3D Secure (3DS) Authentication - Covers the process for handling 3D Secure authentication flows, including redirect handling, OTP validation, and post-authentication processing.
Updated 8 days ago