Hosted Checkout Flows

Three endpoints share the same WiPay-hosted checkout page and redirect-back-to-response_url pattern:

• Payments API POST /plugins/payments/request
• WAPI Trusted Card POST /trusted-cards/{uuid}/charge
• WAPI Trusted Card POST /trusted-cards

Your integration initiates the transaction, the customer completes payment on a WiPay-hosted page, and WiPay redirects the browser to your response_url with the result. Depending on the request mode, WiPay returns a checkout URL in JSON or accepts a browser form post and redirects directly.

Request and Redirect Lifecycle

1. Your server or browser submits the payment request to WiPay.
2. WiPay returns JSON with a hosted checkout url and transaction_id, or redirects the browser directly to the hosted checkout page.
3. The customer completes checkout on WiPay's domain.
4. The hosted checkout page posts the result back to WiPay.
5. WiPay navigates the browser to your response_url with result parameters in the query string.

Transaction Lifecycle

1. Request Acceptance

• WiPay validates the merchant, country, currency, environment, fee structure, and total.
• A transaction_id is assigned immediately — this is not a payment confirmation.

2. Hosted Checkout

• The customer selects card details and completes the payment flow on a WiPay-hosted page.
• Card-network selection, AVS fields, and 3DS processing may be required before a result is available.
• The customer-facing total reflects the selected fee_structure and the merchant's fee configuration.
• Standard sessions expire after 3 minutes; AVS-enabled sessions expire after 5 minutes.

3. Final Reconciliation

• WiPay determines the final outcome and redirects the browser only after a final payload is ready.
• Treat the redirect to response_url as the point where you evaluate status, verify hash, and decide whether to fulfil the order.
• If the customer abandons checkout or the session expires, WiPay can finalize the transaction as a timeout or recover the latest known outcome.
• An expired checkout becomes eligible for timeout completion once its expiry is at least 30 seconds in the past, provided the transaction was created within the last 240 minutes.
• Separate recovery handling covers transactions between 30 and 240 minutes old that were not completed or timed out.

Sequence Diagram

The hosted checkout page is not the final callback. It posts the checkout result to WiPay first, then navigates the browser to the final URL returned by WiPay.

Response Handling

Payments API and Trusted Card Charge

• Store the transaction_id immediately as your canonical identifier for reconciliation and support.
• Parse status, transaction_id, message, order_id, and total from the redirect.
• Recalculate the MD5 hash server-side before fulfilling the transaction.
• Keep the order unpaid until your response_url handler verifies the final result.
• If you already handle Payments API redirects, you can reuse the same response parser for Trusted Card charge flows — they share the same Transaction Response model.

Trusted Card Create

• Parse status, transaction_id, and uuid from the redirect.
• Persist the uuid for future verify, retrieve, delete, and charge operations.
• In live environments, the micro-charge total is obfuscated on the hosted page and omitted from response parameters. In sandbox, the total is included for verification testing.

Related Guides

• Payment Request and Transaction Response
• Charge Trusted Card and Create Trusted Card