> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/checkout/wallet-and-redirection-payments/initiate-redirection-payment.md). # Initiate Redirection Payment Initiates the external payment gateway redirect for the selected redirection-based payment option. After successful submission, the system advances to `RedirectionPageCompletePage`, where the customer is sent to the payment provider's hosted page. The customer must accept the terms and conditions (`agreement: true`) before the redirect can be initiated. Optionally, browser metadata fields may be submitted to support gateway-level installment selection or device fingerprinting. **Preconditions**: * The basket must not be empty * A payment option with `payment_type: redirection` must be selected on the pre-order * No active transaction must exist for the current payment attempt **Processing Flow**: 1. Stores submitted browser metadata (`browser_installments`, `browser_client_type`) on the pre-order for use by the payment gateway strategy 2. Captures the customer's IP address and attaches it to the pre-order 3. Assigns an order number to the pre-order 4. Queries available installment options from the payment provider 5. Constructs success and failure callback URLs pointing to `RedirectionPageCompletePage` 6. Appends a single-use session token to both callback URLs to prevent session replay on return (controlled by `USE_ONE_TIME_TOKEN`) 7. Optionally embeds an encoded order number in the callback URLs to support isolated session recovery on return from the provider (controlled by `ORDERS_USE_ISOLATED_PRE_ORDER_ON_RETURN`) 8. Calls the gateway strategy to start the redirect; the strategy contacts the external payment provider and retrieves the redirect URL 9. On success: stores the redirect URL, remote redirect URL, inline HTML content (if applicable), transaction identifier, and marks the redirection as started on the pre-order 10. On failure: rolls back the assigned order number and returns a validation error so the customer may retry **Configuration**: * `USE_ONE_TIME_TOKEN` (dynamic setting, default: `true`): When enabled, a single-use token is appended to both the success and failure callback URLs. The token is validated on return to prevent session replay attacks. * `ORDERS_USE_ISOLATED_PRE_ORDER_ON_RETURN` (static setting, default: `false`): When enabled, an encoded order number is embedded in the callback URLs (`n` query parameter) to allow the system to recover the correct pre-order session when the customer returns from the payment provider. **Post-order support**: * This page is available for post-order flows (`available_for_post_order: true`), allowing the payment step to be re-initiated on an existing order. **Forward page invalidation**: * Submitting this page invalidates all subsequent checkout pages (`invalidate_forward_pages: true`), ensuring that downstream steps (such as `RedirectionPageCompletePage`) reflect the freshly initiated payment state. ```json {"openapi":"3.1.0","info":{"title":"Overview","version":"1.0.0"},"tags":[{"name":"Wallet & Redirection Payments","description":"# Checkout Wallet & Redirection Payments\n\nIntegrate digital wallet payments and external payment provider redirects into your checkout.\n\n**Wallet** payments let customers pay using a pre-funded account balance. The flow covers wallet selection, payment initiation, redirect-based completion, and a return callback page.\n\n**Redirection payments** redirect the customer to an external payment provider. On return, the result is processed via a callback URL.\n\n**Confirmation Payment Complete** is the final step of the deferred confirmation payment flow initiated in the alternative payments section.\n\n## Authentication\n\nThese endpoints support both authenticated and anonymous sessions.\n\n- **Authenticated users**: Session cookie (`sessionid`) tracks checkout progress.\n- **Anonymous users**: Guest checkout is available when the `CAN_GUEST_PURCHASE` setting is enabled.\n## Request Format\n\nInclude the following header in all checkout requests:\n\n- **x-requested-with**: `XMLHttpRequest`\n\n## Dynamic Settings\n\nThe following settings are managed at runtime through the admin interface and do not require a server restart.\n\n### USE_ONE_TIME_TOKEN\nControls whether a single-use token is appended to redirect callback URLs to prevent replay attacks. When enabled, the token is validated on return before the payment result is processed.\n\n## Static Settings\n\nThe following settings are configured in the server environment and require a restart to take effect.\n\n### ORDERS_USE_ISOLATED_PRE_ORDER_ON_RETURN\nWhen enabled, an encoded order number is embedded in callback URLs so the correct session can be restored after a redirect, even if the browser session has changed (for example, in mobile app redirect flows)."}],"servers":[{"description":"Akinon Checkout API","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com"}}}],"paths":{"/orders/checkout/?page=RedirectionPaymentSelectedPage":{"post":{"tags":["Wallet & Redirection Payments"],"operationId":"submitRedirectionPaymentSelectedPage","summary":"Initiate Redirection Payment","description":"Initiates the external payment gateway redirect for the selected redirection-based\npayment option. After successful submission, the system advances to\n`RedirectionPageCompletePage`, where the customer is sent to the payment\nprovider's hosted page.\n\nThe customer must accept the terms and conditions (`agreement: true`) before\nthe redirect can be initiated. Optionally, browser metadata fields may be\nsubmitted to support gateway-level installment selection or device fingerprinting.\n\n**Preconditions**:\n- The basket must not be empty\n- A payment option with `payment_type: redirection` must be selected on the\n pre-order\n- No active transaction must exist for the current payment attempt\n\n**Processing Flow**:\n1. Stores submitted browser metadata (`browser_installments`,\n `browser_client_type`) on the pre-order for use by the payment\n gateway strategy\n2. Captures the customer's IP address and attaches it to the pre-order\n3. Assigns an order number to the pre-order\n4. Queries available installment options from the payment provider\n5. Constructs success and failure callback URLs pointing to\n `RedirectionPageCompletePage`\n6. Appends a single-use session token to both callback URLs to prevent\n session replay on return (controlled by `USE_ONE_TIME_TOKEN`)\n7. Optionally embeds an encoded order number in the callback URLs to\n support isolated session recovery on return from the provider\n (controlled by `ORDERS_USE_ISOLATED_PRE_ORDER_ON_RETURN`)\n8. Calls the gateway strategy to start the redirect; the strategy\n contacts the external payment provider and retrieves the redirect URL\n9. On success: stores the redirect URL, remote redirect URL, inline HTML\n content (if applicable), transaction identifier, and marks the\n redirection as started on the pre-order\n10. On failure: rolls back the assigned order number and returns a\n validation error so the customer may retry\n\n**Configuration**:\n- `USE_ONE_TIME_TOKEN` (dynamic setting, default: `true`): When enabled,\n a single-use token is appended to both the success and failure callback\n URLs. The token is validated on return to prevent session replay attacks.\n- `ORDERS_USE_ISOLATED_PRE_ORDER_ON_RETURN` (static setting,\n default: `false`): When enabled, an encoded order number is embedded in\n the callback URLs (`n` query parameter) to allow the system to recover\n the correct pre-order session when the customer returns from the payment\n provider.\n\n**Post-order support**:\n- This page is available for post-order flows (`available_for_post_order: true`),\n allowing the payment step to be re-initiated on an existing order.\n\n**Forward page invalidation**:\n- Submitting this page invalidates all subsequent checkout pages\n (`invalidate_forward_pages: true`), ensuring that downstream steps\n (such as `RedirectionPageCompletePage`) reflect the freshly initiated\n payment state.","parameters":[{"$ref":"#/components/parameters/AjaxRequestHeader"},{"$ref":"#/components/parameters/SessionCookieHeader"}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/RedirectionPaymentSelectedInput"}}}},"responses":{"200":{"description":"Redirect initiated. On success the system advances to `RedirectionPageCompletePage`. On failure the order number is rolled back and a validation error is returned so the customer may retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}}},"302":{"description":"Redirect to basket (empty basket) or login (guest purchase not allowed)"}}}}},"components":{"parameters":{"AjaxRequestHeader":{"name":"x-requested-with","in":"header","required":true,"description":"Required header for AJAX requests. Must be set to `XMLHttpRequest` for all checkout requests.","schema":{"type":"string","enum":["XMLHttpRequest"],"default":"XMLHttpRequest"}},"SessionCookieHeader":{"name":"Cookie","in":"header","required":false,"description":"Session cookie header (e.g. `sessionid=abc123` or `osessionid=`)","schema":{"type":"string"}}},"schemas":{"RedirectionPaymentSelectedInput":{"type":"object","description":"Submission payload for initiating a redirection-based payment. Accepting the\nterms and conditions is mandatory. Browser metadata fields are optional and\nare forwarded to the payment gateway strategy to support installment\npre-selection and device fingerprinting at the provider level.","required":["agreement"],"properties":{"agreement":{"type":"boolean","enum":[true],"description":"Customer's acceptance of the terms and conditions. Must be `true`; any other value prevents the redirect from being initiated."},"browser_installments":{"type":["string","null"],"maxLength":64,"description":"Colon-separated list of installment counts supported by the customer's browser environment (e.g., `\"1:3:6:9:12\"`). Each value must be an integer between 0 and 120 inclusive. Forwarded to the payment gateway to pre-select compatible installment options on the provider's hosted page."},"browser_client_type":{"type":["string","null"],"maxLength":64,"description":"Identifier for the type of client or browser environment initiating the payment (e.g., `\"web\"`, `\"mobile\"`). Forwarded to the payment gateway strategy for device-aware routing or display decisions."}}},"CheckoutResponse":{"type":"object","properties":{"context_list":{"type":"array","items":{"$ref":"#/components/schemas/PageContext"}},"pre_order":{"$ref":"#/components/schemas/PreOrder"},"errors":{"oneOf":[{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},{"type":"null"},{"type":"array","items":{"type":"string"}}]},"template_name":{"type":"string"}}},"PageContext":{"type":"object","properties":{"page_name":{"type":"string","description":"Class name of the page (e.g., \"IndexPage\", \"AddressSelectionPage\")"},"page_slug":{"type":"string","description":"URL-friendly slug for the page"},"page_context":{"type":"object","description":"Page-specific context data","additionalProperties":true}}},"PreOrder":{"type":"object","description":"Pre-order state containing basket, addresses, shipping, payment information","properties":{"basket":{"$ref":"#/components/schemas/Basket"},"shipping_address":{"oneOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"billing_address":{"oneOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"shipping_option":{"oneOf":[{"$ref":"#/components/schemas/ShippingOptionDetail"},{"type":"null"}]},"billing_and_shipping_same":{"oneOf":[{"type":"boolean"},{"type":"null"}]},"payment_option":{"oneOf":[{"$ref":"#/components/schemas/PaymentOptionDetail"},{"type":"null"}]},"notifications":{"type":"array","items":{"type":"object"}},"shipping_amount":{"oneOf":[{"type":"string","pattern":"^\\d+\\.\\d{2}$"},{"type":"null"}]},"total_amount":{"oneOf":[{"type":"string","pattern":"^\\d+\\.\\d{2}$"},{"type":"null"}]},"unpaid_amount":{"oneOf":[{"type":"string","pattern":"^\\d+\\.\\d{2}$"},{"type":"null"}]},"loyalty_money":{"oneOf":[{"type":"string","pattern":"^\\d+\\.\\d{2}$"},{"type":"null"}]},"currency_type_label":{"type":"string"},"installment":{"oneOf":[{"$ref":"#/components/schemas/Installment"},{"type":"null"}]},"card_info":{"oneOf":[{"type":"object","description":"Card information from BIN lookup","properties":{"bin_number":{"type":"string","description":"Card BIN (first 6-8 digits)"},"card":{"type":"object","description":"Card details from BIN database","properties":{"pk":{"type":"integer"},"name":{"type":"string","description":"Card type name (e.g., \"Visa\", \"Mastercard\")"}}}}},{"type":"null"}]},"redirect_to_three_d":{"oneOf":[{"type":"boolean"},{"type":"null"}]},"delivery_option":{"oneOf":[{"$ref":"#/components/schemas/DeliveryOption"},{"type":"null"}]},"retail_store":{"oneOf":[{"$ref":"#/components/schemas/RetailStore"},{"type":"null"}]},"funds_transfer_bank":{"oneOf":[{"$ref":"#/components/schemas/BankAccount"},{"type":"null"}]},"number":{"oneOf":[{"type":"string","description":"Pre-order/order number"},{"type":"null"}]},"order":{"oneOf":[{"type":"object","description":"Created order (after checkout completion)","properties":{"pk":{"type":"integer"},"number":{"type":"string"},"status":{"type":"string"}}},{"type":"null"}]},"payment_choice":{"oneOf":[{"$ref":"#/components/schemas/PaymentChoice"},{"type":"null"}]},"user_email":{"oneOf":[{"type":"string"},{"type":"null"}]},"phone_number":{"oneOf":[{"type":"string"},{"type":"null"}]},"user_phone_number":{"oneOf":[{"type":"string"},{"type":"null"}]},"gift_box":{"oneOf":[{"type":"object","properties":{"note":{"type":"string"},"gift_video":{"type":"boolean"},"gift_video_notification_sent":{"type":"boolean"},"price":{"type":"string"}}},{"type":"null"}]},"delivery_range":{"oneOf":[{"type":"object","properties":{"lower":{"type":"string","format":"date-time"},"upper":{"type":"string","format":"date-time"}}},{"type":"null"}]},"total_amount_with_interest":{"oneOf":[{"type":"string","pattern":"^\\d+\\.\\d{2}$"},{"type":"null"}]},"is_guest":{"type":"boolean"},"is_post_order":{"type":"boolean"},"data_source_shipping_options":{"oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/DataSourceShippingOptionDetail"}},{"type":"null"}]},"attribute_based_shipping_options":{"oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/PreOrderAttributeBasedShippingOption"}},{"type":"null"}]}}},"Basket":{"type":"object","properties":{"pk":{"type":"integer"},"total_amount":{"type":"string","pattern":"^\\d+\\.\\d{2}$"}}},"Address":{"type":"object","properties":{"pk":{"type":"integer"},"email":{"type":"string"},"phone_number":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"country":{"$ref":"#/components/schemas/Country"},"city":{"$ref":"#/components/schemas/City"},"line":{"type":"string"},"title":{"type":"string"},"township":{"$ref":"#/components/schemas/Township"},"district":{"oneOf":[{"$ref":"#/components/schemas/District"},{"type":"null"}]},"postcode":{"type":"string"},"notes":{"type":"string"},"company_name":{"type":"string"},"tax_office":{"type":"string"},"tax_no":{"type":"string"},"e_bill_taxpayer":{"type":"boolean"},"is_corporate":{"type":"boolean"},"primary":{"type":"boolean"},"identity_number":{"type":"string"}}},"Country":{"type":"object","properties":{"pk":{"type":"integer"},"code":{"type":"string"},"name":{"type":"string"}}},"City":{"type":"object","properties":{"pk":{"type":"integer"},"name":{"type":"string"}}},"Township":{"type":"object","properties":{"pk":{"type":"integer"},"name":{"type":"string"}}},"District":{"type":"object","properties":{"pk":{"type":"integer"},"name":{"type":"string"}}},"ShippingOptionDetail":{"type":"object","description":"Detailed shipping option with calculated amount","properties":{"pk":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"logo":{"oneOf":[{"type":"string","format":"uri"},{"type":"null"}]},"shipping_amount":{"type":"string","pattern":"^\\d+\\.\\d{2}$"},"description":{"oneOf":[{"type":"string"},{"type":"null"}]},"kwargs":{"type":"object","additionalProperties":true}}},"PaymentOptionDetail":{"type":"object","description":"Detailed payment option with type information","properties":{"pk":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"payment_type":{"type":"string","enum":["credit_card","funds_transfer","bkm_express","loyalty_money","cash_register","gpay","redirection","stored_card","masterpass","masterpass_rest","credit_payment","pay_later","saved_card","confirmation","b2b","wallet","pay_on_delivery"]},"payment_type_label":{"type":"string"}}},"Installment":{"type":"object","properties":{"pk":{"type":"integer"},"installment_count":{"type":"integer"},"label":{"type":"string"},"price_with_accrued_interest":{"type":"string","pattern":"^\\d+\\.\\d{2}$"},"monthly_price_with_accrued_interest":{"type":"string","pattern":"^\\d+\\.\\d{2}$"}}},"DeliveryOption":{"type":"object","properties":{"pk":{"type":"integer"},"name":{"type":"string"},"delivery_option_type":{"type":"string","enum":["customer","retail_store","pickup_location"]},"is_active":{"type":"boolean"}}},"RetailStore":{"type":"object","properties":{"pk":{"type":"integer"},"name":{"type":"string"},"erp_code":{"type":"string"},"township":{"$ref":"#/components/schemas/Township"},"click_and_collect":{"type":"boolean"},"is_active":{"type":"boolean"}}},"BankAccount":{"type":"object","description":"Bank account for funds transfer payments","properties":{"pk":{"type":"integer"},"bank_name":{"type":"string","description":"Name of the bank"},"account_holder":{"type":"string","description":"Account holder name"},"iban":{"type":"string","description":"International Bank Account Number"},"currency":{"type":"string","description":"Currency code (e.g., \"USD\", \"EUR\", \"TRY\")"},"is_active":{"type":"boolean"}}},"PaymentChoice":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"price":{"type":"string","pattern":"^\\d+\\.\\d{2}$"}}},"DataSourceShippingOptionDetail":{"type":"object","description":"Data source shipping option for multi-vendor shipping","properties":{"pk":{"type":"integer"},"shipping_amount":{"type":"string","pattern":"^\\d+\\.\\d{2}$"},"shipping_option_name":{"type":"string"},"shipping_option_logo":{"oneOf":[{"type":"string","format":"uri"},{"type":"null"}]},"data_source":{"type":"object","properties":{"pk":{"type":"integer"},"title":{"type":"string"}}},"description":{"oneOf":[{"type":"string"},{"type":"null"}]}}},"PreOrderAttributeBasedShippingOption":{"type":"object","description":"Attribute-based shipping option selected for a product group","properties":{"pk":{"type":"integer"},"shipping_option_name":{"type":"string"},"shipping_option_logo":{"oneOf":[{"type":"string","format":"uri"},{"type":"null"}]},"shipping_amount":{"type":"string","pattern":"^\\d+\\.\\d{2}$"},"product_ids":{"type":"array","items":{"type":"integer"}},"attribute_value":{"type":"string"},"attribute_key":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://apidocs.akinon.com/commerce-openapis/checkout/wallet-and-redirection-payments/initiate-redirection-payment.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.