> 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-rest-order.md). # Finalise Masterpass REST Order Finalises the Masterpass REST order. The body of this request reflects the Masterpass / 3D Secure callback payload. Note that **all query string parameters from the request URL are merged into the submitted form data**, while the `amount` form key (if any) is removed before validation. This is the mechanism used to consume 3D Secure return parameters that are appended as query string by the gateway. **Required Fields**: * `three_d_secure`: Must match `pre_order.redirect_to_three_d` (set during `MasterpassRestOrderNoPage`). Submitting a mismatching value returns the error `"Transaction failed. Please try again."`. **Optional / 3D Secure Callback Fields**: * `token`: Masterpass payment token. * `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 (12 digits, 2 decimal places). When provided, it is divided by 100 and validated against `pre_order.get_total_amount_with_interest()`. A mismatch returns `"Transaction failed. Please try again."`. Note that the `amount` form key in the body is stripped before merging the query string, so the value used is the one provided via the bank callback if any. * `transactionType`: One of `PURCHASE`, `PURCHASE_3D`, `DIRECT_PURCHASE`, `DIRECT_PURCHASE_3D`, `REGISTER_AND_PURCHASE`, `REGISTER_AND_PURCHASE_3D`. * `status`, `completeStatus`, `paymentId`, `conversationData`, `conversationId`, `callbackStatus`: Additional Masterpass status fields. **3D Secure Validation**: * When `three_d_secure` is `true`: * If the gateway has `hash_validation_enabled` and the request comes from a non-mobile client (`client_type` is neither `ios` nor `android`), the hash is validated via `gateway.is_hash_valid(...)`. A failure returns `"Hash values don't match."`. * The MD status is validated via `gateway.is_md_status_valid(...)`. A failure returns `"Transaction failed. Please try again."`. **Processing**: 1. The base `process()` is called with the merged data (form body + request query string, with the form `amount` removed). 2. The `set_defaults` step runs with `set_number=False` because the order number was already assigned in `MasterpassRestOrderNoPage`. 3. When `pre_order.redirect_to_three_d` is `false`, `skip_create_transaction` returns `true` and no separate transaction record is created at this step. Otherwise a transaction with id `"MASTERPASS__"` is created. 4. The Masterpass payment is processed via the `PaymentPageMixin.process_order` flow, which submits the basket, saves contracts, and triggers post-completion notifications. **Next Pages**: * `ThankYouPage` **Backward Navigation**: * This page does not perform any backward state changes (`backward()` is a no-op). **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=MasterpassRestCompletePage":{"post":{"tags":["Masterpass Payment"],"operationId":"submitMasterpassRestComplete","summary":"Finalise Masterpass REST Order","description":"Finalises the Masterpass REST order. The body of this request reflects\nthe Masterpass / 3D Secure callback payload. Note that **all query\nstring parameters from the request URL are merged into the submitted\nform data**, while the `amount` form key (if any) is removed before\nvalidation. This is the mechanism used to consume 3D Secure return\nparameters that are appended as query string by the gateway.\n\n**Required Fields**:\n- `three_d_secure`: Must match `pre_order.redirect_to_three_d` (set\n during `MasterpassRestOrderNoPage`). Submitting a mismatching value\n returns the error `\"Transaction failed. Please try again.\"`.\n\n**Optional / 3D Secure Callback Fields**:\n- `token`: Masterpass payment token.\n- `oid`, `md`, `xid`, `eci`, `cavv`, `rnd`, `hash`, `hashParams`,\n `hashParamsVal`, `mdStatus`, `bankIca`, `paymentReceived`, `clientId`,\n `sign`: 3D Secure callback parameters returned by the bank.\n- `amount`: Decimal value (12 digits, 2 decimal places). When provided,\n it is divided by 100 and validated against\n `pre_order.get_total_amount_with_interest()`. A mismatch returns\n `\"Transaction failed. Please try again.\"`. Note that the `amount`\n form key in the body is stripped before merging the query string,\n so the value used is the one provided via the bank callback if any.\n- `transactionType`: One of `PURCHASE`, `PURCHASE_3D`,\n `DIRECT_PURCHASE`, `DIRECT_PURCHASE_3D`, `REGISTER_AND_PURCHASE`,\n `REGISTER_AND_PURCHASE_3D`.\n- `status`, `completeStatus`, `paymentId`, `conversationData`,\n `conversationId`, `callbackStatus`: Additional Masterpass status fields.\n\n**3D Secure Validation**:\n- When `three_d_secure` is `true`:\n - If the gateway has `hash_validation_enabled` and the request comes\n from a non-mobile client (`client_type` is neither `ios` nor\n `android`), the hash is validated via `gateway.is_hash_valid(...)`.\n A failure returns `\"Hash values don't match.\"`.\n - The MD status is validated via `gateway.is_md_status_valid(...)`.\n A failure returns `\"Transaction failed. Please try again.\"`.\n\n**Processing**:\n1. The base `process()` is called with the merged data (form body +\n request query string, with the form `amount` removed).\n2. The `set_defaults` step runs with `set_number=False` because the\n order number was already assigned in `MasterpassRestOrderNoPage`.\n3. When `pre_order.redirect_to_three_d` is `false`,\n `skip_create_transaction` returns `true` and no separate\n transaction record is created at this step. Otherwise a transaction\n with id `\"MASTERPASS__\"` is created.\n4. The Masterpass payment is processed via the\n `PaymentPageMixin.process_order` flow, which submits the basket,\n saves contracts, and triggers post-completion notifications.\n\n**Next Pages**:\n- `ThankYouPage`\n\n**Backward Navigation**:\n- This page does not perform any backward state changes\n (`backward()` is a no-op).\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/MasterpassRestCompleteInput"}}}},"responses":{"200":{"description":"Masterpass REST 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":{"MasterpassRestCompleteInput":{"type":"object","required":["three_d_secure"],"description":"Final Masterpass REST 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":{"three_d_secure":{"type":"boolean","description":"Must match `pre_order.redirect_to_three_d` set in\n`MasterpassRestOrderNoPage`. A mismatch returns\n`\"Transaction failed. Please try again.\"`."},"token":{"type":"string","description":"Masterpass payment token issued by the SDK."},"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 `gateway.is_hash_valid` when\n`three_d_secure` is `true` and the gateway has\n`hash_validation_enabled` (skipped for iOS/Android client types)."},"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 `gateway.is_md_status_valid`\nwhen `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 in minor units returned by the bank. Divided by 100\nduring validation and compared against\n`pre_order.get_total_amount_with_interest()`. A mismatch returns\n`\"Transaction failed. Please try again.\"`. Note: any `amount` form\nfield is dropped before request query 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."},"transactionType":{"type":"string","description":"Masterpass transaction type.","enum":["PURCHASE","PURCHASE_3D","DIRECT_PURCHASE","DIRECT_PURCHASE_3D","REGISTER_AND_PURCHASE","REGISTER_AND_PURCHASE_3D"]},"status":{"type":"string","description":"Masterpass status string."},"completeStatus":{"type":"string","description":"Masterpass complete status string."},"paymentId":{"type":"string","description":"Masterpass payment id."},"conversationData":{"type":"string","description":"Masterpass conversation data."},"conversationId":{"type":"string","description":"Masterpass conversation id."},"callbackStatus":{"type":"string","description":"Masterpass callback status string."}}},"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-rest-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.