A general card payment transaction with Iqono 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.). Iqono 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.
If the returned transactionStatus is PROCESSING, no customer action is needed. The provider has started handling the authorization flow, and a callback with the final outcome will follow shortly. This state means the transaction proceeds without any 3DS redirect.

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:

Redirect the customer to the challengeUrl, or embed the challengeUrlIframe in your page.
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.

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

3. Webhook Notification

Iqono 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 Iqono) to ensure authenticity.