> 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/card-payment/submit-3d-secure-callback-for-saved-card-payment.md). # Submit 3D Secure callback for saved card payment Receives the 3D Secure authentication callback from the bank and finalises the saved card payment. The request may arrive as a POST body or as GET query string parameters appended by the bank redirect; both are merged before validation. The exact fields required depend on the active payment gateway: * **Garanti Switch**: `success`, `approved`, `returnCode` (must be `"00"`), `reasonCode` (must be `"00"`), `hashedData`, `requestId`, `message`, and `txnAmount` (sent by the bank in cents; divided by 100 before validation against the order total). The full payload is verified against a gateway-generated hash. * **PayU RO**: `success` (must be `true`). An optional `body` JSON payload from the bank may also be submitted. * **Tap**: `success` (must be `true`), `tap_id`, `oid`, and `price`. On failure, the backward navigation state is applied: the selected card, card information, installment, order number, and 3D Secure flag are all cleared so the customer can restart from the card selection step. **Next Page**: * `ThankYouPage` **available\_for\_post\_order**: `false` ```json {"openapi":"3.1.0","info":{"title":"Overview","version":"1.0.0"},"tags":[{"name":"Card Payment","description":"# Checkout Card Payment\n\nAccept credit and debit card payments through a multi-step flow covering BIN lookup, installment selection, 3D Secure verification, payment confirmation, saved card selection, and order completion.\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### THREE_D_SECURE_ENABLED\nMaster switch for 3D Secure verification. When disabled, 3D Secure is skipped regardless of other rules.\n\n### THREE_D_SECURE_RULES\nRule-based conditions that determine when 3D Secure is required. Rules are evaluated in order; the first match triggers 3D Secure. Only active when `THREE_D_SECURE_ENABLED` is enabled.\n\nAvailable rule types: amount threshold, POS terminal identifier, failed attempt limit per email address, failed attempt limit per IP address, guest user status, first-time purchaser, payment currency.\n\n### INSTALLMENT_FILTERS\nFilters that restrict which installment options are presented. Filters are applied in sequence; each may remove options or stop further filtering.\n\n## Static Settings\n\nThe following settings are configured in the server environment and require a restart to take effect.\n\n### DEFAULT_CARD_SLUG\nFallback card identifier used when a BIN number is submitted but no matching record is found. Defaults to `other`."}],"servers":[{"description":"Akinon Checkout API","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com"}}}],"paths":{"/orders/checkout/?page=SavedCardThreeDSecurePage":{"post":{"tags":["Card Payment"],"operationId":"submitSavedCardThreeDSecure","summary":"Submit 3D Secure callback for saved card payment","description":"Receives the 3D Secure authentication callback from the bank and finalises the\nsaved card payment. The request may arrive as a POST body or as GET query string\nparameters appended by the bank redirect; both are merged before validation.\n\nThe exact fields required depend on the active payment gateway:\n\n- **Garanti Switch**: `success`, `approved`, `returnCode` (must be `\"00\"`),\n `reasonCode` (must be `\"00\"`), `hashedData`, `requestId`, `message`, and\n `txnAmount` (sent by the bank in cents; divided by 100 before validation\n against the order total). The full payload is verified against a\n gateway-generated hash.\n- **PayU RO**: `success` (must be `true`). An optional `body` JSON payload\n from the bank may also be submitted.\n- **Tap**: `success` (must be `true`), `tap_id`, `oid`, and `price`.\n\nOn failure, the backward navigation state is applied: the selected card, card\ninformation, installment, order number, and 3D Secure flag are all cleared so\nthe customer can restart from the card selection step.\n\n**Next Page**:\n- `ThankYouPage`\n\n**available_for_post_order**: `false`","parameters":[{"$ref":"#/components/parameters/AjaxRequestHeader"},{"$ref":"#/components/parameters/SessionCookieHeader"}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/SavedCardThreeDSecureInput"}}}},"responses":{"200":{"description":"3D Secure authentication complete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}}}}}}},"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":{"SavedCardThreeDSecureInput":{"type":"object","description":"3D Secure callback payload posted by the bank after the customer completes\nauthentication. The required fields depend on the active payment gateway.\n\nAny GET query string parameters appended by the bank redirect are merged into\nthis payload before validation.\n\n- **Garanti Switch**: `success`, `approved`, `returnCode`, `reasonCode`,\n `hashedData`, `requestId`, `message`, and `txnAmount` are required. `txnAmount`\n is sent by the bank in cents and divided by 100 before being validated against\n the order total. The full payload is verified against a gateway-generated hash.\n- **PayU RO**: `success` (must be `true`). An optional `body` JSON payload from\n the bank may also be submitted.\n- **Tap**: `success` (must be `true`), `tap_id`, `oid`, and `price` are required.","properties":{"success":{"type":"boolean","enum":[true],"description":"Payment success flag returned by the gateway. Must be `true`; any other\nvalue is treated as a failed transaction."},"approved":{"type":"boolean","enum":[true],"description":"(Garanti Switch only) Authorisation approval flag. Must be `true`."},"returnCode":{"type":"string","enum":["00"],"description":"(Garanti Switch only) Bank return code. Must be `\"00\"` for a successful\ntransaction."},"reasonCode":{"type":"string","enum":["00"],"description":"(Garanti Switch only) Bank reason code. Must be `\"00\"` for a successful\ntransaction."},"hashedData":{"type":"string","description":"(Garanti Switch only) Gateway-generated hash. Validated server-side before\nthe payment is accepted."},"requestId":{"type":"string","description":"(Garanti Switch only) Gateway request identifier."},"message":{"type":"string","description":"(Garanti Switch only) Human-readable status message from the gateway."},"txnAmount":{"type":"string","format":"decimal","description":"(Garanti Switch only) Transaction amount posted by the bank in cents\n(e.g. `\"15000\"` for 150.00). Divided by 100 before being validated against\nthe order total. A mismatch returns a validation error."},"body":{"type":"object","nullable":true,"description":"(PayU RO only) Optional JSON payload posted by the bank alongside the\n3D Secure callback."},"tap_id":{"type":"string","maxLength":256,"description":"(Tap only) Tap charge identifier returned by the gateway."},"oid":{"type":"string","maxLength":256,"description":"(Tap only) Order identifier echoed back by the Tap gateway."},"price":{"type":"string","description":"(Tap only) Transaction amount returned by the Tap gateway."}}},"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/card-payment/submit-3d-secure-callback-for-saved-card-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.