> 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/masterpass-payment/finalise-masterpass-order.md). # Finalise Masterpass Order Finalises the Masterpass order. All query string parameters from the request URL are merged into the submitted form data, and the `amount` form key is removed before validation. This is the mechanism used to consume 3D Secure return parameters appended as query string by the gateway. **Required Fields**: * `token`: The Masterpass payment token received from the gateway. * `three_d_secure`: Boolean indicating whether the transaction went through 3D Secure. Defaults to `false`. **Optional / 3D Secure Callback Fields**: * `oid`, `md`, `xid`, `eci`, `cavv`, `rnd`, `hash`, `hashParams`, `hashParamsVal`, `mdStatus`, `bankIca`, `paymentReceived`, `clientId`, `sign`: 3D Secure callback parameters returned by the bank. * `amount`: Decimal value from the bank callback. When present, it is validated against the order total. A mismatch returns `"Transaction failed. Please try again."`. Note: any `amount` form field is removed before query string parameters are merged. **3D Secure Validation**: * When `three_d_secure` is `true`: * The hash is validated against the gateway. A failure returns `"Hash values doesn't match."`. * The MD status is validated. A failure returns `"Transaction failed. Please try again."`. **Processing**: 1. Query string parameters from the bank callback are merged into the request body (form `amount` is removed first). 2. Order defaults are applied without regenerating the order number, as it was already assigned in `MasterpassOrderNoPage`. 3. When `pre_order.redirect_to_three_d` is `false`, no separate transaction record is created at this step. Otherwise a transaction is created with id `"MASTERPASS__"`. 4. The payment is processed and the order is finalised. **Backward Navigation**: * This page does not perform any backward state changes. **Next Page**: * `ThankYouPage` **available\_for\_post\_order**: `true` ```json {"openapi":"3.1.0","info":{"title":"Overview","version":"1.0.0"},"tags":[{"name":"Masterpass Payment","description":"# Checkout Masterpass Payment\n\nIntegrate the Masterpass digital wallet into your checkout. The flow covers both the standard Masterpass integration and the Masterpass REST variant, including BIN lookup, installment selection, order number assignment, remote installment options, reward selection, and payment 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. When enabled, an amount-based rule is available specifically for Masterpass transactions.\n\n### INSTALLMENT_FILTERS\nFilters that restrict which installment options are presented. Applied during both standard and REST installment selection.\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 lookup returns no match. Defaults to `other`."}],"servers":[{"description":"Akinon Checkout API","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com"}}}],"paths":{"/orders/checkout/?page=MasterpassCompletePage":{"post":{"tags":["Masterpass Payment"],"operationId":"submitMasterpassComplete","summary":"Finalise Masterpass Order","description":"Finalises the Masterpass order. All query string parameters from the\nrequest URL are merged into the submitted form data, and the `amount`\nform key is removed before validation. This is the mechanism used to\nconsume 3D Secure return parameters appended as query string by the\ngateway.\n\n**Required Fields**:\n- `token`: The Masterpass payment token received from the gateway.\n- `three_d_secure`: Boolean indicating whether the transaction went\n through 3D Secure. Defaults to `false`.\n\n**Optional / 3D Secure Callback Fields**:\n- `oid`, `md`, `xid`, `eci`, `cavv`, `rnd`, `hash`, `hashParams`,\n `hashParamsVal`, `mdStatus`, `bankIca`, `paymentReceived`,\n `clientId`, `sign`: 3D Secure callback parameters returned by the\n bank.\n- `amount`: Decimal value from the bank callback. When present, it is\n validated against the order total. A mismatch returns\n `\"Transaction failed. Please try again.\"`. Note: any `amount` form\n field is removed before query string parameters are merged.\n\n**3D Secure Validation**:\n- When `three_d_secure` is `true`:\n - The hash is validated against the gateway. A failure returns\n `\"Hash values doesn't match.\"`.\n - The MD status is validated. A failure returns\n `\"Transaction failed. Please try again.\"`.\n\n**Processing**:\n1. Query string parameters from the bank callback are merged into the\n request body (form `amount` is removed first).\n2. Order defaults are applied without regenerating the order number,\n as it was already assigned in `MasterpassOrderNoPage`.\n3. When `pre_order.redirect_to_three_d` is `false`, no separate\n transaction record is created at this step. Otherwise a transaction\n is created with id `\"MASTERPASS__\"`.\n4. The payment is processed and the order is finalised.\n\n**Backward Navigation**:\n- This page does not perform any backward state changes.\n\n**Next Page**:\n- `ThankYouPage`\n\n**available_for_post_order**: `true`","parameters":[{"$ref":"#/components/parameters/AjaxRequestHeader"},{"$ref":"#/components/parameters/SessionCookieHeader"}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/MasterpassCompleteInput"}}}},"responses":{"200":{"description":"Masterpass order finalised successfully","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":{"MasterpassCompleteInput":{"type":"object","required":["token","three_d_secure"],"description":"Final Masterpass submission payload. The endpoint also merges any\nrequest **query string parameters** into the form data (with the form\n`amount` key removed before merging) so that 3D Secure callback\nparameters appended by the bank are captured automatically.","properties":{"token":{"type":"string","description":"Masterpass payment token received from the gateway."},"three_d_secure":{"type":"boolean","default":false,"description":"Indicates whether the transaction went through 3D Secure. When\n`true`, the hash and MD status are validated. Defaults to `false`."},"oid":{"type":"string","description":"Order ID echoed back by the bank on 3D callback."},"md":{"type":"string","description":"3D Secure `md` parameter from the bank callback."},"xid":{"type":"string","description":"3D Secure `xid` parameter from the bank callback."},"eci":{"type":"string","description":"3D Secure ECI value from the bank callback."},"cavv":{"type":"string","description":"3D Secure CAVV value from the bank callback."},"rnd":{"type":"string","description":"3D Secure random nonce from the bank callback."},"hash":{"type":"string","description":"Bank-issued response hash. Validated via the gateway when\n`three_d_secure` is `true`."},"hashParams":{"type":"string","description":"3D Secure hash params list from the bank callback."},"hashParamsVal":{"type":"string","description":"3D Secure hash params values from the bank callback."},"mdStatus":{"type":"string","description":"3D Secure MD status. Validated via the gateway when\n`three_d_secure` is `true`. A failure returns\n`\"Transaction failed. Please try again.\"`."},"bankIca":{"type":"string","description":"Bank ACQ ICA value passed back by the gateway."},"paymentReceived":{"type":"string","description":"Payment received indicator returned by the gateway."},"amount":{"type":"string","format":"decimal","description":"Total amount from the bank callback. When present, it is validated\nagainst the order total. A mismatch returns\n`\"Transaction failed. Please try again.\"`. Note: any `amount` form\nfield is removed before query string parameters are merged into\nthe body, so the value used is the one supplied by the bank\ncallback when present."},"clientId":{"type":"string","description":"Merchant client ID echoed back by the gateway."},"sign":{"type":"string","description":"Signature value from the bank callback."}}},"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/masterpass-payment/finalise-masterpass-order.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.