Card Payment Process Flow

A general card payment transaction with Exirom involves the following steps:

1. Initiate Payment

The client (or your server) sends a card payment request via POST /v1/payments/card with all required details (card info, amount, etc.). Exirom responds immediately with a transaction reference (transactionId) and initial status. If further customer action (e.g., 3D Secure authentication) is required, the response will indicate it via transactionStatus and a challengeUrl for 3DS.

2. 3D Secure Authentication (if required)

If a transaction requires 3D Secure (3DS) authentication, the transactionStatus in the response will be CUSTOMER_VERIFICATION.

To proceed, you must:

1. Redirect the customer to the challengeUrl, or embed the challengeUrlIframe in your page.

2. Ensure that successRedirectUrl and failureRedirectUrl are included in your original transaction request – these fields are required for all 3DS flows.

The customer will complete the verification challenge (e.g., entering OTP or authenticating via their bank). After this:

• If the authentication is successful, they will be redirected to the successRedirectUrl.
• If the authentication fails or is declined, they will be redirected to the failureRedirectUrl.

Exirom will also send a webhook with the final transaction status (SUCCEED, FAILED, etc.) to your server.

3. Webhook Notification

Exirom sends webhook notifications to your configured callbackUrl whenever the status of a transaction changes - not just at the final state.

These status updates may include: PENDING, PROCESSING, SUCCEED, FAILED, REFUNDED

Each webhook payload includes the transactionStatus along with key details such as the masked card number, transaction amount, and identifiers to help you track and process the event on your end.

Ensure your server is capable of handling multiple status updates for the same transaction lifecycle.

4. Retrieve Status or Info (optional)

Optionally, use GET /v1/payments/card/status/{id} to poll the current transaction status or GET /v1/payments/card/info/{id} to fetch detailed transaction data. Useful if the webhook was missed.

Note: It’s important to handle all responses and webhooks securely. Use the requestId for
idempotency when retrying requests to avoid duplicate transactions, and always verify
webhook signatures (if provided by Exirom) to ensure authenticity.