Akinon Release Notes 06/22/2026) are now live! Click here to learn what's new.
Ctrlk
Docs Portal
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Masterpass Payment

Checkout Masterpass Payment

Integrate 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.

Authentication

These endpoints support both authenticated and anonymous sessions.

  • Authenticated users: Session cookie (sessionid) tracks checkout progress.

  • Anonymous users: Guest checkout is available when the CAN_GUEST_PURCHASE setting is enabled.

Request Format

Include the following header in all checkout requests:

  • x-requested-with: XMLHttpRequest

Dynamic Settings

The following settings are managed at runtime through the admin interface and do not require a server restart.

THREE_D_SECURE_ENABLED

Master switch for 3D Secure verification. When disabled, 3D Secure is skipped regardless of other rules.

THREE_D_SECURE_RULES

Rule-based conditions that determine when 3D Secure is required. When enabled, an amount-based rule is available specifically for Masterpass transactions.

INSTALLMENT_FILTERS

Filters that restrict which installment options are presented. Applied during both standard and REST installment selection.

Static Settings

The following settings are configured in the server environment and require a restart to take effect.

DEFAULT_CARD_SLUG

Fallback card identifier used when a BIN number lookup returns no match. Defaults to other.

Get Masterpass BIN Number Page context

get

Returns the context for the Masterpass BIN number entry step. Card details are collected on the client side via the Masterpass JS SDK; only the BIN and a flag indicating whether the card is a stored Masterpass card are submitted so the server can identify the card type and determine the available installment options.

Preconditions:

  • Basket must not be empty

  • Payment option must be of Masterpass type

Page Context:

  • Returns an empty object {}. No additional data is exposed at GET time — the card data flow runs through the Masterpass JS SDK.

Step Completion: This page is considered already completed when both of the following are true:

  • Card information has been recorded, and

  • The selected payment option is of Masterpass type.

available_for_post_order: true

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses
200

Masterpass BIN number page context retrieved

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=MasterpassBinNumberPage
200

Masterpass BIN number page context retrieved

Submit Card BIN Number for Masterpass

post

Submits the card BIN number captured by the Masterpass JS SDK. The BIN is used to identify the card type (bank, card type, available installment records). If the BIN cannot be matched in the database, the system falls back to the default card configuration.

Required Fields:

  • bin_number: First 6 or 8 digits of the card. Must contain only digits.

Optional Fields:

  • is_masterpass_stored_card: Indicates whether the card is from the user's stored Masterpass cards. Defaults to false.

Validation:

  • bin_number must be a 6 or 8 digit numeric string. A non-matching value returns "Please enter a valid bin number.".

  • When the active payment option has provisioning enabled and the resolved card is a debit card, the submission is rejected with "You can only use credit cards.".

State Update:

  • Card information is stored, containing the submitted BIN and the resolved card record.

  • The stored card flag and the detected card brand (Mastercard or not) are saved to the session.

Backward Navigation:

  • On backward navigation, the stored card flag and the card brand indicator are removed from the session.

Next Page:

  • MasterpassInstallmentPage

available_for_post_order: true

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body
bin_numberstringRequired

First 6 or 8 digits of the card (BIN — Bank Identification Number). Captured by the Masterpass JS SDK on the client side. Must contain only digits and have a length of 6 or 8.

Example: 542119Pattern: ^\d{6,8}$
is_masterpass_stored_cardbooleanOptional

Indicates whether the card BIN comes from the user's stored Masterpass cards. Saved to the session so later steps can distinguish stored-card and fresh-card flows.

Default: falseExample: false
Responses
200

BIN submitted successfully

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=MasterpassBinNumberPage
200

BIN submitted successfully

Get Masterpass Installment Selection Page context

get

Returns the available installment options for the Masterpass flow. Installments are derived from the card identified in the previous step and filtered by the active installment filter rules.

Preconditions:

  • Basket must not be empty

  • Card information must have been entered (MasterpassBinNumberPage must have been completed)

  • Payment option must be of Masterpass type

Page Context:

  • installments: List of available installment options for the resolved card. Each entry contains pk, installment_count, label, price_with_accrued_interest, and monthly_price_with_accrued_interest calculated against the current unpaid basket amount.

  • card_type: Card type details (name, slug, logo), derived from the resolved card's card type.

  • installment_messages: List of informational strings returned by the installment filter service (e.g. filter messages or promotion notices).

Step Completion: This page is considered already completed when both of the following are true:

  • An installment has been selected, and

  • The selected payment option is of Masterpass type.

available_for_post_order: true

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses
200

Masterpass installment selection page context retrieved

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=MasterpassInstallmentPage
200

Masterpass installment selection page context retrieved

Select Installment Option for Masterpass

post

Sets the selected installment option for the Masterpass flow.

Required Fields:

  • installment: Primary key of the installment record to apply. The value must reference an active installment linked to the card resolved in MasterpassBinNumberPage.

Validation:

  • The submitted installment PK must belong to an active installment for the resolved card. A PK outside this set returns a validation error.

State Update:

  • The selected installment is stored on the pre-order.

  • Any previously selected campaign and reward selections are cleared.

Backward Navigation:

  • On backward navigation, the selected installment is cleared.

Next Page:

  • MasterpassOrderNoPage

available_for_post_order: true

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body
installmentintegerRequired

Primary key (pk) of the Installment record to select. The PK must reference an active installment linked to the card resolved in MasterpassBinNumberPage.

Example: 2
Responses
200

Installment selected successfully

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=MasterpassInstallmentPage
200

Installment selected successfully

Get Masterpass Order Number Page context

get

Returns the context for the Masterpass order number assignment page. This page assigns the order number that will be used for the subsequent Masterpass payment request and evaluates whether the transaction must be completed via 3D Secure.

Preconditions:

  • Basket must not be empty

  • Payment option must be of Masterpass type

  • Card information must be present

  • An installment must be selected

Page Context:

  • Returns an empty object {}.

Step Completion: This page is considered already completed when both of the following are true:

  • The order number has been assigned, and

  • The 3D Secure routing decision has been made (either true or false).

available_for_post_order: true

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses
200

Masterpass order number page context retrieved

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=MasterpassOrderNoPage
200

Masterpass order number page context retrieved

Assign Order Number and Decide 3D Secure Routing

post

Assigns the order number that will be sent to Masterpass and evaluates whether the transaction must be processed under 3D Secure.

Fields:

  • No fields are required. Submit an empty form body to trigger order number assignment.

Processing:

  1. The client IP is captured and stored for the order.

  2. The order number is generated.

  3. The 3D Secure decision is evaluated using the gateway's POS configuration, the user, the basket total, the resolved card, and the BIN number. The result is stored so that MasterpassCompletePage can route the transaction correctly.

Backward Navigation:

  • On backward navigation: the client IP is cleared, the order number is reset, and the 3D Secure routing flag is cleared.

Next Page:

  • MasterpassCompletePage

available_for_post_order: true

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body
object · MasterpassOrderNoPageInputOptional

No input fields are required for this step. Submit an empty form body to trigger order number assignment and 3D Secure routing evaluation.

Responses
200

Order number assigned successfully

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=MasterpassOrderNoPage
200

Order number assigned successfully

Get Masterpass Remote Installment Selection Page context

get

Returns the available installment options for the Masterpass REST flow when a remote installment service is configured for the active POS. Installments are fetched from the external installment service using the card BIN and the current basket amount, then filtered by the active installment filter rules.

Preconditions:

  • Basket must not be empty

  • Payment option must be of Masterpass REST type

Page Context:

  • installments: List of installment options returned by the remote installment service. Each entry contains id, label, bin_number, installment_count, interest_rate, interest_amount, final_price_with_interest, monthly_price_with_interest, and is_active.

  • installment_messages: List of informational strings returned by the installment filter service.

Step Completion: This page is considered already completed when both of the following are true:

  • The remote installment selection has been saved, and

  • The selected payment option is of Masterpass REST type.

available_for_post_order: true

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses
200

Masterpass remote installment selection page context retrieved

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=MasterpassRemoteInstallmentPage
200

Masterpass remote installment selection page context retrieved

Select Remote Installment Option for Masterpass REST

post

Saves the selected remote installment option for the Masterpass REST flow. The submitted ID is validated against the remote installment service and the active filter rules before being stored.

Required Fields:

  • remote_installment_id: The identifier of the installment option returned by the remote installment service (max 32 characters).

Validation:

  • The ID must match an installment returned by the remote service. An unknown or inactive ID returns "Installment doesn't match.".

  • The matched installment must pass the active filter rules. A filtered-out installment returns the filter's error message.

State Update:

  • The remote installment ID and the computed installment details (installment count, interest rate, interest amount) are saved to the session.

Backward Navigation:

  • On backward navigation, the remote installment ID and installment details are removed from the session.

Next Page:

  • MasterpassRestOrderNoPage

available_for_post_order: true

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body
remote_installment_idstring · max: 32Required

Identifier of the installment option returned by the remote installment service. Must match an active, filter-passing installment for the current card and basket amount.

Example: remote-inst-003
Responses
200

Remote installment selected successfully

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=MasterpassRemoteInstallmentPage
200

Remote installment selected successfully

Get Masterpass Complete Page context

get

Returns the context required to drive the final Masterpass payment request from the client. The context contains the MSISDN, the order number, the 3D Secure routing flag, signed request tokens for the Masterpass JS SDK, and a set of gateway-specific extras.

Preconditions:

  • Basket must not be empty

  • Payment option must be of Masterpass type

  • Card information must be present

  • An installment must be selected

  • Order number must have been generated

  • The 3D Secure routing decision must have been made

Page Context:

  • msisdn: The user's phone number in E.164 format (e.g. "905551234567"). null for guest checkouts or when the user has no phone number on file.

  • order_no: The previously assigned order number. For payment gateways with a custom merchant type this value may differ from the raw pre_order.number.

  • three_d: true when a 3D Secure challenge is required for this transaction, false otherwise.

  • token: A signed request token for the Masterpass JS SDK, generated with the user's identity (user ID and MSISDN) when the customer is logged in. When provisioning is enabled for the payment option, the provision flag is included.

  • direct_token: A variant of the above token where the MSISDN is set to null, used for direct and guest purchase flows.

  • extras: Gateway-specific data (installment, amounts, addresses, user information) forwarded to the Masterpass JS SDK.

Step Completion:

  • This page is considered already completed when the order has been finalised.

available_for_post_order: true

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses
200

Masterpass complete page context retrieved

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=MasterpassCompletePage
200

Masterpass complete page context retrieved

Finalise Masterpass Order

post

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_<order_number>_<suffix>".

  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

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

Final Masterpass submission payload. The endpoint also merges any request query string parameters into the form data (with the form amount key removed before merging) so that 3D Secure callback parameters appended by the bank are captured automatically.

tokenstringRequired

Masterpass payment token received from the gateway.

Example: mp-token-abc123
three_d_securebooleanRequired

Indicates whether the transaction went through 3D Secure. When true, the hash and MD status are validated. Defaults to false.

Default: falseExample: false
oidstringOptional

Order ID echoed back by the bank on 3D callback.

Example: ORD-2026-0042
mdstringOptional

3D Secure md parameter from the bank callback.

xidstringOptional

3D Secure xid parameter from the bank callback.

ecistringOptional

3D Secure ECI value from the bank callback.

Example: 05
cavvstringOptional

3D Secure CAVV value from the bank callback.

rndstringOptional

3D Secure random nonce from the bank callback.

hashstringOptional

Bank-issued response hash. Validated via the gateway when three_d_secure is true.

hashParamsstringOptional

3D Secure hash params list from the bank callback.

hashParamsValstringOptional

3D Secure hash params values from the bank callback.

mdStatusstringOptional

3D Secure MD status. Validated via the gateway when three_d_secure is true. A failure returns "Transaction failed. Please try again.".

Example: 1
bankIcastringOptional

Bank ACQ ICA value passed back by the gateway.

paymentReceivedstringOptional

Payment received indicator returned by the gateway.

amountstring · decimalOptional

Total amount 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 into the body, so the value used is the one supplied by the bank callback when present.

Example: 16559
clientIdstringOptional

Merchant client ID echoed back by the gateway.

signstringOptional

Signature value from the bank callback.

Responses
200

Masterpass order finalised successfully

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=MasterpassCompletePage
200

Masterpass order finalised successfully

Get Masterpass REST BIN Number Page context

get

Returns the context for the Masterpass REST BIN number page. The card details are collected on the client side via the Masterpass JS SDK; only the BIN (and a flag indicating whether the card is a stored Masterpass card) is sent back to the server so it can identify the card type and determine the available installment options.

Preconditions:

  • Basket must not be empty

  • Payment option must be of Masterpass REST type (is_masterpass_rest())

Page Context:

  • Returns an empty object {}. No additional data is exposed at GET time — the card data flow runs through the Masterpass JS SDK.

Step Completion: This page is considered already completed (is_already_done) when both of the following are true:

  • pre_order.card_info is populated, and

  • The selected payment option is Masterpass REST.

available_for_post_order: true

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses
200

Masterpass REST BIN number page context retrieved

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=MasterpassRestBinNumberPage
200

Masterpass REST BIN number page context retrieved

Submit Card BIN Number for Masterpass REST

post

Submits the card BIN number captured by the Masterpass JS SDK. The BIN is used to identify the card type (bank, card type, available installment records). If the BIN cannot be matched in the BinNumber table, the system falls back to the default card configuration (DEFAULT_CARD_SLUG).

Required Fields:

  • bin_number: First 6 or 8 digits of the card. Must contain only digits.

Optional Fields:

  • is_masterpass_stored_card: Boolean flag indicating whether the card is being used from the user's Masterpass stored cards. Defaults to false.

Validation:

  • bin_number must be a 6 or 8 digit numeric string. A non-matching value returns the error "Please enter a valid bin number.".

  • If the active payment option has provision_enabled = true and the resolved card is a debit card, a validation error is raised: "You can only use credit cards.".

State Update:

  • pre_order.card_info is set to a CardInfo object containing the bin_number and the resolved card.

  • pre_order.data["is_masterpass_stored_card"] is set to the submitted flag.

  • pre_order.data["is_mastercard"] is set based on the card type detected from the BIN (true when the card brand is master).

Backward Navigation:

  • On backward navigation, both is_masterpass_stored_card and is_mastercard keys are removed from pre_order.data.

Next Pages:

  • MasterpassRemoteInstallmentPage — when the active payment option's config has an installment_slug set (i.e., a remote installment service is configured for this Masterpass POS).

  • MasterpassRestInstallmentPage — otherwise (default flow).

available_for_post_order: true

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body
bin_numberstringRequired

First 6 or 8 digits of the card (BIN - Bank Identification Number). Captured by the Masterpass JS SDK on the client side. Must contain only digits and have a length of 6 or 8.

Example: 542119Pattern: ^\d{6,8}$
is_masterpass_stored_cardbooleanOptional

Flag indicating whether the card BIN comes from the user's stored Masterpass cards. Stored on the pre-order as pre_order.data["is_masterpass_stored_card"].

Default: falseExample: false
Responses
200

BIN submitted successfully

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=MasterpassRestBinNumberPage
200

BIN submitted successfully

Get Masterpass REST Installment Selection Page context

get

Returns the available installment options for the Masterpass REST flow. Installments are derived from the card identified in the previous step (MasterpassRestBinNumberPage) and filtered by the INSTALLMENT_FILTERS rules through InstallmentService.

Preconditions:

  • Basket must not be empty

  • Card information must have been entered (pre_order.card_info must be set, i.e., MasterpassRestBinNumberPage must have been completed)

Page Context:

  • installments: List of available installment options for the resolved card. Each entry contains pk, installment_count, label, price_with_accrued_interest, and monthly_price_with_accrued_interest calculated against the current unpaid basket amount.

  • card_type: Card type details (name, slug, logo), derived from pre_order.card_info.card.card_type.

  • installment_messages: List of informational strings returned by InstallmentService (e.g., filter messages or promotion notices).

Skip Conditions:

  • This page is considered already completed (is_already_done) when pre_order.installment is set and the active payment option is Masterpass REST.

available_for_post_order: true

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses
200

Masterpass REST installment selection page context retrieved

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=MasterpassRestInstallmentPage
200

Masterpass REST installment selection page context retrieved

Select Installment Option for Masterpass REST

post

Sets the selected installment option for the Masterpass REST flow.

Required Fields:

  • installment: Primary key (pk) of the Installment record to apply. The PK must reference an active installment linked to the card resolved in MasterpassRestBinNumberPage.

Validation:

  • installment must be the PK of an active Installment belonging to the card in pre_order.card_info. Submitting a PK outside of that set returns a validation error.

State Update:

  • pre_order.installment is set to the resolved Installment.

  • pre_order.selected_campaign and pre_order.selected_rewards are reset to null (inherited from InstallmentSelectionPage).

  • pre_order.payment_choice is reset to null.

Backward Navigation:

  • On backward navigation, pre_order.installment is reset to null.

Next Pages:

  • MasterpassRestOrderNoPage

available_for_post_order: true

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body
installmentintegerRequired

Primary key (pk) of the Installment record to select. The PK must reference an active installment linked to the card resolved in MasterpassRestBinNumberPage.

Example: 2
Responses
200

Installment selected successfully

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=MasterpassRestInstallmentPage
200

Installment selected successfully

Get Masterpass REST Order Number Page context

get

Returns the context for the Masterpass REST order number assignment page. This page assigns the order number that will be used for the subsequent Masterpass payment request and decides whether the transaction must be completed via 3D Secure.

Preconditions:

  • Basket must not be empty

  • Payment option must be Masterpass REST (check_masterpass_selected)

  • Card information must be present (check_card_info_not_empty)

  • An installment must be selected, either through pre_order.installment (default flow) or pre_order.data["installment_alt"] (remote installment flow)

Page Context:

  • Returns an empty object {}.

Skip Conditions: This page is considered already completed (is_already_done) when both:

  • The order number has been assigned (pre_order.order_number_empty() is false), and

  • pre_order.redirect_to_three_d is set (either true or false).

available_for_post_order: true

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses
200

Masterpass REST order number page context retrieved

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=MasterpassRestOrderNoPage
200

Masterpass REST order number page context retrieved

Assign Order Number and Decide 3D Secure Routing

post

Assigns the order number that will be sent to Masterpass and evaluates whether the transaction must be processed under 3D Secure.

Optional Fields:

  • use_three_d: Boolean flag forwarded to the 3D Secure decision rule (check_three_d_secure). When the rule resolves to true, the user will be required to complete a 3D Secure challenge before the subsequent MasterpassRestCompletePage step. Defaults to false.

Processing:

  1. The client IP is captured from the request and stored as pre_order.remote_addr.

  2. The order number is generated via pre_order.set_number().

  3. The 3D Secure decision is computed by check_three_d_secure(...) using the gateway's POS configuration, the user, the basket total, the resolved card, the BIN number, and the submitted use_three_d flag. If the gateway's merchant_type is "custom", the regular pre-order POS is used as the underlying POS and the Masterpass POS is supplied as proxy_pos; otherwise the Masterpass POS is used directly.

  4. pre_order.redirect_to_three_d is set to either true or false accordingly.

Backward Navigation:

  • On backward navigation: pre_order.remote_addr is cleared, pre_order.reset_number() is called, and redirect_to_three_d is reset to null.

Next Pages:

  • MasterpassRestCompletePage

Previous Page (computed dynamically):

  • MasterpassRemoteInstallmentPage — when the payment option's config has an installment_slug set

  • MasterpassRestInstallmentPage — otherwise

available_for_post_order: true

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body
use_three_dbooleanOptional

Hint forwarded to check_three_d_secure(...). When the rule resolves to true, the user must complete a 3D Secure challenge before the subsequent MasterpassRestCompletePage step.

Default: falseExample: false
Responses
200

Order number assigned successfully

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=MasterpassRestOrderNoPage
200

Order number assigned successfully

Get Masterpass REST Reward List Page context

get

Returns the context for the Masterpass REST reward list page. Unlike the regular RewardListPage, this page does not collect raw card details — the card has already been registered with Masterpass — so only a card alias is required to query the gateway for available rewards.

This is an independent page — submitting it does not advance the main checkout flow.

Preconditions:

  • Basket must not be empty

  • Payment option must be Masterpass REST (check_masterpass_selected)

  • The Masterpass POS gateway must have enable_rewards = true and has_rewards() returning true (check_gateway_has_rewards)

Page Context:

  • Returns an empty object {}.

Skip Conditions:

  • This page is considered already completed when pre_order.rewards is not None (rewards have already been queried).

Next Pages:

  • MasterpassRestRewardSelectionPage

available_for_post_order: inherited from RewardListPage

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses
200

Masterpass REST reward list page context retrieved

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=MasterpassRestRewardListPage
200

Masterpass REST reward list page context retrieved

Query available rewards for the Masterpass REST card

post

Submits the Masterpass card alias to the gateway and retrieves the list of available rewards. The returned reward list is stored in pre_order.rewards and used by the subsequent MasterpassRestRewardSelectionPage.

This is an independent page — submitting it does not advance the main checkout flow.

Required Fields:

  • card_alias: Alias of the Masterpass card the user wants to query rewards for. The alias is the value the Masterpass JS SDK uses to identify a stored card.

Processing:

  1. pre_order.rewards and pre_order.selected_rewards are reset to null.

  2. The Masterpass POS gateway is resolved through pre_order.get_pos_using_slug(). If no POS is found, the page is a no-op and rewards remains null.

  3. When enable_rewards is true and the gateway reports has_rewards(), gateway.query_rewards(...) is called with the current pre-order currency, the user, and the validated input data.

  4. The returned reward list is stored in pre_order.rewards.

Next Pages:

  • MasterpassRestRewardSelectionPage

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body
card_aliasstringRequired

Alias of the Masterpass stored card to query rewards for. The alias is the value the Masterpass JS SDK uses to identify a card. The value is forwarded to gateway.query_rewards(...).

Example: MP-CARD-ALIAS-001
Responses
200

Rewards retrieved or empty list returned

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=MasterpassRestRewardListPage
200

Rewards retrieved or empty list returned

Get Masterpass REST Reward Selection Page context

get

Returns the list of rewards fetched in the preceding MasterpassRestRewardListPage step. The user picks how much of each reward type to apply to the order. Behaviour and request format are identical to RewardSelectionPage — only the entry pre-conditions differ (Masterpass REST must be the active payment option).

This is an independent page — submitting it does not advance the main checkout flow.

Preconditions:

  • Basket must not be empty

  • Payment option must be Masterpass REST (check_masterpass_selected)

  • Reward data must have been fetched (check_reward_available, i.e., pre_order.rewards is not None)

Page Context:

  • rewards: The reward list obtained in MasterpassRestRewardListPage, where each entry contains an amount and a type (RewardType enum value).

Skip Conditions:

  • This page is considered already completed when pre_order.selected_rewards is not None.

Next Pages:

  • No further checkout page (EmptyPage — independent terminal step)

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses
200

Masterpass REST reward selection page context retrieved

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=MasterpassRestRewardSelectionPage
200

Masterpass REST reward selection page context retrieved

Apply selected reward amounts to the Masterpass REST order

post

Accepts the user's reward amount selections and stores them in pre_order.selected_rewards. The request body is dynamic — each field name corresponds to a RewardType value present in the rewards list returned by MasterpassRestRewardListPage. Each value is a decimal amount the user chooses to apply, between 0 and the maximum available for that type.

This is an independent page — submitting it does not advance the main checkout flow.

Dynamic Fields:

  • One field per reward type (e.g., general, special).

  • Field type: decimal with up to 12 digits and 2 decimal places.

  • Minimum value: 0

  • Maximum value: the amount value for that reward type from the pre-order state.

Validation:

  • The sum of all selected reward amounts must not exceed the order total (pre_order.get_total_amount_with_interest()). If it does, a validation error is returned: "Selected reward amount cannot be higher than total amount.".

State Update:

  • On success, pre_order.selected_rewards is populated with the chosen amounts keyed by RewardType enum values.

Backward Navigation:

  • When navigating backward, pre_order.selected_rewards is reset to null.

Next Pages:

  • No further checkout page (EmptyPage)

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

Dynamic input schema — the fields are determined at runtime based on the reward types returned by the payment gateway in the preceding RewardListPage step. Each field name is a RewardType enum value (general or special) and each value is a decimal amount between 0 and the maximum available for that type. The sum of all submitted amounts must not exceed the order total.

Other propertiesstring · decimalOptional

Amount of this reward type to apply. Between 0 and the maximum available for this type (12 digits, 2 decimal places).

Example: 25.00
Responses
200

Rewards applied or validation error

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=MasterpassRestRewardSelectionPage
200

Rewards applied or validation error

Get Masterpass REST Complete Page context

get

Returns the context required to drive the final Masterpass REST payment request from the client. The context contains the MSISDN, the order number, the 3D Secure routing flag, and a set of gateway-specific extras that are passed through to the Masterpass JS SDK.

Preconditions:

  • Basket must not be empty

  • Payment option must be Masterpass REST (check_masterpass_selected)

  • Card information must be present (check_card_info_not_empty)

  • An installment must be selected (check_installment_selected)

  • Order number must have been generated (check_order_no_generated)

  • pre_order.redirect_to_three_d must be set (check_redirect_to_three_d_not_none)

Page Context:

  • msisdn: The user's phone number formatted with the country code, obtained from payment_gateway._get_msisdn(...).

  • order_no: The previously assigned pre_order.number.

  • three_d: pre_order.redirect_to_three_d — true if a 3D Secure challenge is required, otherwise false.

  • extras:

    • user_id: The user's PK as a string. null for guest checkouts.

    • bank_ica: ACQ ICA value when the gateway's merchant_type is "custom" (resolved via payment_gateway.get_pos_config(vpos)). null for non-custom gateways.

    • additional_fields: Free-form dict returned by payment_gateway.get_additional_fields(...). Includes user, billing/shipping addresses, remote address, the total with interest, and reward state.

Step Completion:

  • is_already_done returns true when the order is finalised (pre_order.order_finalized() is true).

available_for_post_order: true

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Responses
200

Masterpass REST complete page context retrieved

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
get/orders/checkout/?page=MasterpassRestCompletePage
200

Masterpass REST complete page context retrieved

Finalise Masterpass REST Order

post

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_<order_number>_<suffix>" 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

Header parameters
x-requested-withstring · enumRequired

Required header for AJAX requests. Must be set to XMLHttpRequest for all checkout requests.

Default: XMLHttpRequestPossible values:
CookiestringOptional

Session cookie header (e.g. sessionid=abc123 or osessionid=<session_id>)

Body

Final Masterpass REST submission payload. The endpoint also merges any request query string parameters into the form data (with the form amount key removed before merging) so that 3D Secure callback parameters appended by the bank are captured automatically.

three_d_securebooleanRequired

Must match pre_order.redirect_to_three_d set in MasterpassRestOrderNoPage. A mismatch returns "Transaction failed. Please try again.".

Example: true
tokenstringOptional

Masterpass payment token issued by the SDK.

Example: mp-token-abc123
oidstringOptional

Order id echoed back by the bank on 3D callback.

Example: ORD-2026-0042
mdstringOptional

3D Secure md parameter from the bank callback.

xidstringOptional

3D Secure xid parameter from the bank callback.

ecistringOptional

3D Secure ECI value from the bank callback.

Example: 05
cavvstringOptional

3D Secure CAVV value from the bank callback.

rndstringOptional

3D Secure random nonce from the bank callback.

hashstringOptional

Bank-issued response hash. Validated via gateway.is_hash_valid when three_d_secure is true and the gateway has hash_validation_enabled (skipped for iOS/Android client types).

hashParamsstringOptional

3D Secure hash params list from the bank callback.

hashParamsValstringOptional

3D Secure hash params values from the bank callback.

mdStatusstringOptional

3D Secure MD status. Validated via gateway.is_md_status_valid when three_d_secure is true. A failure returns "Transaction failed. Please try again.".

Example: 1
bankIcastringOptional

Bank ACQ ICA value passed back by the gateway.

paymentReceivedstringOptional

Payment received indicator returned by the gateway.

amountstring · decimalOptional

Total amount in minor units returned by the bank. Divided by 100 during validation and compared against pre_order.get_total_amount_with_interest(). A mismatch returns "Transaction failed. Please try again.". Note: any amount form field is dropped before request query parameters are merged into the body, so the value used is the one supplied by the bank callback when present.

Example: 16559
clientIdstringOptional

Merchant client id echoed back by the gateway.

signstringOptional

Signature value from the bank callback.

transactionTypestring · enumOptional

Masterpass transaction type.

Example: PURCHASE_3DPossible values:
statusstringOptional

Masterpass status string.

completeStatusstringOptional

Masterpass complete status string.

paymentIdstringOptional

Masterpass payment id.

conversationDatastringOptional

Masterpass conversation data.

conversationIdstringOptional

Masterpass conversation id.

callbackStatusstringOptional

Masterpass callback status string.

Responses
200

Masterpass REST order finalised successfully

application/json
errorsone of · nullableOptional
or
string[]Optional
template_namestringOptional
post/orders/checkout/?page=MasterpassRestCompletePage
200

Masterpass REST order finalised successfully

PreviousAlternative Payment MethodsNextMobil Express Payment

Last updated

Was this helpful?