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.

Card Payment

Checkout Card Payment

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

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. Rules are evaluated in order; the first match triggers 3D Secure. Only active when THREE_D_SECURE_ENABLED is enabled.

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

INSTALLMENT_FILTERS

Filters that restrict which installment options are presented. Filters are applied in sequence; each may remove options or stop further filtering.

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 is submitted but no matching record is found. Defaults to other.

Get BIN Number Page context

get

Returns the context for entering the card BIN (Bank Identification Number). This page captures the first 6-8 digits of the credit card to determine card type, bank, and available installment options.

Preconditions:

  • Payment option must be selected and must be credit card type (is_credit_card())

  • Basket must not be empty

BIN Number Validation:

  • BIN number must be 6 or 8 digits

  • System looks up the BIN in the BinNumber database to determine card type

  • If BIN not found, falls back to default card configuration

Card Information Extraction:

  • Card type (Visa, Mastercard, Amex, etc.)

  • Issuing bank

  • Available installment options

  • Card category (credit, debit, prepaid)

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

BIN Number page context retrieved

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

BIN Number page context retrieved

Submit Card BIN Number

post

Submits the card BIN number to determine card type and available installments.

BIN Number Processing:

  1. Validates that BIN is 6 or 8 digits

  2. Looks up BIN in database to find matching card

  3. If found: Uses card configuration (bank, type, installments)

  4. If not found: Uses default card configuration

Card Info Object:

  • bin_number: The submitted BIN (first 6-8 digits)

  • card: Card model with bank, type, and installment relationships

Next Pages:

  • InstallmentSelectionPage

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 credit card (BIN - Bank Identification Number). Used to determine card type, bank, and available installment options. Must contain only digits.

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

BIN number submitted successfully

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

BIN number submitted successfully

Get Installment Selection Page context

get

Returns available installment options for the card. Displays installment options with interest rates and monthly payments.

Preconditions:

  • Card info must be entered (check_card_info_entered)

  • Basket must not be empty

Installment Calculation:

  • Installment options are retrieved from the card's installment configuration

  • Each installment includes:

    • Installment count (1, 3, 6, 9, 12, etc.)

    • Interest rate percentage

    • Total amount with interest

    • Monthly payment amount

  • Installment count of 1 means no installment (single payment)

Installment Filtering:

  • Installments are filtered through INSTALLMENT_FILTERS dynamic setting

  • Filters can restrict options based on:

    • Basket amount thresholds

    • User segmentation

    • Campaign eligibility

    • Currency requirements

  • Filter messages are returned to inform users of restrictions

Installment Messages:

  • Gateway-specific promotional messages

  • Installment availability notices

  • Special campaign information from payment gateway

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

Installment selection page context retrieved

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

Installment selection page context retrieved

Select Installment Option

post

Sets the selected installment option for the credit card payment.

Validation:

  • Selected installment must belong to the card's available installments

  • Installment must be active

Interest Calculation:

  • Total amount is recalculated with selected installment's interest rate

  • Monthly payment amount is calculated (total / installment_count)

  • Interest-free installments may be available based on campaigns

Selected Campaign/Rewards Reset:

  • Selecting an installment clears previously selected campaigns

  • Clears previously selected rewards

  • Campaigns and rewards are re-evaluated based on new total with interest

Next Pages:

  • CreditCardConfirmationPage

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 of the selected installment option. Must be one of the installments available for the card. Installment count of 1 represents single payment (no installment).

Responses
200

Installment selected successfully

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

Installment selected successfully

Get Credit Card 3D Secure Page context

get

Returns the context for 3D Secure verification redirect. This page handles the redirect to the bank's 3D Secure authentication page and processes the return response.

3D Secure Flow:

  1. User is redirected to bank's 3D Secure page

  2. User completes authentication (SMS OTP, biometric, etc.)

  3. Bank redirects back with verification result

  4. System validates the response and completes payment

Redirect URL:

  • redirect_url: Internal endpoint that handles 3D Secure initiation

  • This endpoint generates the bank redirect form with necessary parameters

Cached Card Data:

  • Card details are temporarily cached during 3D Secure flow

  • Cache key is based on pre-order hash

  • Cached data is encrypted using Django's signing framework

Security Considerations:

  • Sensitive card data (number, CVV) marked with @sensitive_variables

  • Card data cleared from cache after successful verification

  • Failed verifications also clear cached data

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

3D Secure page context retrieved

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

3D Secure page context retrieved

Process 3D Secure Return Response

post

Processes the return response from 3D Secure verification and completes payment. This endpoint is called when the bank redirects back after authentication.

Return Parameters: Gateway-specific parameters are passed back from the 3D Secure provider. Common parameters include:

  • three_d_secure: Verification status (boolean)

  • success: Transaction success status (boolean)

  • md: Merchant data passed through 3D Secure flow

  • xid: Transaction identifier from 3D Secure

  • eci: Electronic Commerce Indicator

  • cavv: Cardholder Authentication Verification Value

  • mdStatus: MD status code from provider

  • Additional gateway-specific parameters

MD Status Validation:

  • Gateway validates the mdStatus and other response parameters

  • Each gateway has specific validation logic via is_md_status_valid()

  • Failed validation returns user to payment page with error

Transaction Creation:

  • Successful 3D Secure verification creates order and transaction

  • Transaction ID format: 3D_RETURN_{order_number}_{suffix}

  • Sensitive parameters are filtered from transaction log

Cached Card Retrieval:

  • Card details are retrieved from cache using pre-order hash

  • If cache expired, payment fails and user must restart

  • Successful payment clears cached card data

Save Card After 3D Secure:

  • If user chose to save card, it's tokenized after successful payment

  • Save operation happens asynchronously via Celery task

Next Pages:

  • Success: ThankYouPage (order completed)

  • Failure: Redirects back to CreditCardConfirmationPage with error

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
three_d_secureboolean · enumRequired

3D Secure verification status. Must be true for successful verification.

Possible values:
successboolean · enumRequired

Transaction success status. Must be true for successful transaction.

Possible values:
mdstringOptional

Merchant data passed through 3D Secure flow

xidstringOptional

Transaction identifier from 3D Secure provider

ecistringOptional

Electronic Commerce Indicator from 3D Secure

cavvstringOptional

Cardholder Authentication Verification Value

liqpay_tokenstringOptional

LiqPay-specific token (gateway-specific)

statusstringOptional

Status from payment gateway

paymentIdstringOptional

Payment identifier from gateway

conversationDatastringOptional

Conversation data from gateway

conversationIdstringOptional

Conversation identifier from gateway

mdStatusstringOptional

MD status code from 3D Secure provider. Different values indicate authentication success/failure. Gateway-specific validation logic.

bodyobjectOptional

Additional gateway-specific response data

Responses
200

3D Secure verification processed

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

3D Secure verification processed

Get Credit Card Confirmation Page context

get

Returns the context for entering full credit card details and completing payment. This is the final step before payment processing or 3D Secure verification.

Preconditions:

  • Installment must be selected (check_installment_selected)

  • Basket must not be empty

Credit Card Fields Required:

  • Card number (full 16-digit number)

  • Card holder name

  • Expiration month and year

  • CVV/CVC security code

  • Card nickname (optional, for saving card)

Campaign and Rewards Integration:

  • Gateway may support bank-specific campaigns

  • Gateway may support loyalty rewards (points/miles)

  • Context indicates if these features are available

3D Secure Support:

  • Page checks if 3D Secure is required for the transaction

  • Browser information is collected for 3D Secure verification

  • If 3D Secure required, routes to CreditCardThreeDSecurePage

Save Card Feature:

  • Authenticated users can save card for future purchases

  • Guest users cannot save cards

  • Card details are tokenized and stored securely

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

Credit card confirmation page context retrieved

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

Credit card confirmation page context retrieved

Submit Credit Card Details and Process Payment

post

Submits full credit card details and processes the payment. May route to 3D Secure verification or complete order directly.

Required Fields:

  • card_number: Full 16-digit card number

  • card_holder: Cardholder name as printed on card

  • card_month: Expiration month (MM format, e.g., "01", "12")

  • card_year: Expiration year (YYYY format, e.g., "2026")

  • card_cvv: CVV/CVC security code (3-4 digits)

  • agreement: User must accept terms and conditions (boolean, must be true)

Optional Fields:

  • card_name: Nickname for saved card (required if save is true)

  • save: Whether to save card for future use (boolean, default false)

  • use_three_d: User preference for 3D Secure (may be overridden by rules)

  • client_time: Client-side timestamp for fraud detection

  • Browser information fields for 3D Secure:

    • browser_java_enabled: Boolean

    • browser_language: Language code (e.g., "en-US")

    • browser_color_depth: Screen color depth (e.g., "24")

    • browser_screen_height: Screen height in pixels

    • browser_screen_width: Screen width in pixels

    • browser_time_zone: Timezone offset in minutes

    • browser_header: Accept header (auto-captured)

    • browser_user_agent: User agent string (auto-captured)

Card Validation:

  • Card number validated using Luhn algorithm

  • Expiration date must be in the future

  • CVV must be 3-4 digits

  • Cardholder name validated against format rules

3D Secure Decision: System determines if 3D Secure is required based on:

  • Payment gateway configuration

  • Card type and BIN rules

  • Transaction amount thresholds

  • User risk profile

  • Bank requirements

Save Card Processing:

  • If save is true and user is authenticated: Card is tokenized and saved

  • Card details are encrypted and stored securely

  • Only token and last 4 digits are retained

  • Saved cards can be used in future checkouts

Identity Number Validation:

  • If IDENTITY_NUMBER_REQUIRED_AMOUNT setting is configured:

    • Validates shipping address has identity_number field

    • Required when order total exceeds configured threshold

3D Secure Decision Logic:

  • Master switch: THREE_D_SECURE_ENABLED must be true

  • If enabled, evaluates THREE_D_SECURE_RULES conditions:

    • Amount limits

    • Guest user checks

    • First order checks

    • POS terminal restrictions

    • Failed attempt limits per user/IP

    • Currency restrictions

  • If ANY rule returns true, 3D Secure is required

Next Pages:

  • If 3D Secure required: CreditCardThreeDSecurePage

  • If 3D Secure not required: ThankYouPage (order completed)

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_numberstringRequired

Full credit card number (16 digits). Validated using Luhn algorithm. Spaces are automatically removed.

Example: 5421190000000004Pattern: ^\d{16}$
card_holderstringRequired

Cardholder name as printed on the card. Must contain only letters and spaces. Validated against format rules.

Example: JOHN DOE
card_monthstringRequired

Card expiration month in MM format. Must be between 01 and 12.

Example: 12Pattern: ^(0[1-9]|1[0-2])$
card_yearstringRequired

Card expiration year in YYYY format. Must be current year or future.

Example: 2026Pattern: ^\d{4}$
card_cvvstringRequired

Card security code (CVV/CVC). Must be 3-4 digits depending on card type.

Example: 123Pattern: ^\d{3,4}$
card_namestringOptional

Nickname for the card if saving for future use. Required when save is true. Optional otherwise.

Example: My Visa Card
agreementboolean · enumRequired

User must accept terms and conditions to proceed. Must be true.

Possible values:
savebooleanOptional

Whether to save the card for future purchases. Only available for authenticated users. Guest users cannot save cards.

Default: false
use_three_dbooleanOptional

User preference for 3D Secure verification. May be overridden by system rules. Optional field.

client_timestring · date-timeOptional

Client-side timestamp for fraud detection

browser_java_enabledbooleanOptional

Whether Java is enabled in the browser

browser_languagestringOptional

Browser language code (e.g., "en-US", "tr-TR")

Example: en-US
browser_color_depthstringOptional

Screen color depth in bits (e.g., "24", "32")

Example: 24
browser_screen_heightstringOptional

Screen height in pixels

Example: 1080
browser_screen_widthstringOptional

Screen width in pixels

Example: 1920
browser_time_zonestringOptional

Timezone offset from UTC in minutes. Example: UTC-4 would be "240" (4 hours * 60 minutes)

Example: 240
Responses
200

Credit card details submitted successfully

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

Credit card details submitted successfully

Get Credit Payment Complete Page context

get

Returns the gateway redirect URL so the frontend can redirect the user to the payment gateway. This page is shown after the confirmation step has initiated the payment redirect.

Preconditions:

  • Basket must not be empty

  • A credit payment option must be selected (check_payment_option)

  • A POS option must have been selected (credit_payment_option_selected)

  • Payment redirect must have been initiated (is_redirection_started)

Skip Conditions:

  • Page is skipped if the order has been finalized (order_finalized())

Page Context:

  • redirect_url: The URL to redirect the user to on the payment gateway.

  • is_iframe: Whether the redirect should be rendered in an iframe (optional).

Next Pages:

  • ThankYouPage

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

Credit Payment Complete Page context retrieved

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

Credit Payment Complete Page context retrieved

Complete credit payment after gateway redirect

post

Processes the payment gateway's callback after the user returns from the payment redirect. The required input fields depend on the specific payment gateway configured for the selected POS option.

Gateway-Specific Input Serializers:

  • compay_credit → Response, acqResponseCode, AuthCode (optional), orderId, amount, productType (optional) — hash-validated

  • garanti_credit → success (must be true), TransactionId, Key, CardToken

  • fiba_credit → success (must be true)

  • zip_credit → checkout_id

  • Default (other gateways) → success (must be true)

Validation:

  • Gateway-specific hash or status validation is performed.

State Update:

  • On success, a transaction is created and the order is finalized.

  • pre_order.data['is_redirected'] is set to false after processing.

Backward Navigation:

  • On error, redirection_started, is_redirected, redirect_url, and token are removed from pre_order.data.

Next Pages:

  • ThankYouPage

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

The active schema depends on the gateway of the selected POS option (pre_order.data['credit_payment_option'].gateway).

or
or
or
or
Responses
200

Payment completed or error

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

Payment completed or error

Get Credit Payment Confirmation Page context

get

Returns the empty confirmation page context. At this step the user reviews the order and accepts the terms and conditions before being redirected to the payment gateway.

Preconditions:

  • Basket must not be empty

  • A credit payment option must be selected (check_payment_option)

  • A POS option must have been selected (check_credit_payment_option_selected)

Skip Conditions:

  • Page is skipped if the redirect URL is already set in the pre-order and the user has not yet been redirected (redirect_url set and is_redirected is false)

Note — is_redirected flag:

  • is_redirected is set to true when the user visits /orders/redirection/ (RedirectionView), which acts as a bridge before forwarding to the payment gateway. Once is_redirected is true, this page is no longer considered done and will be shown again if the user navigates back (e.g. payment failed at the gateway).

Page Context: (empty)

Next Pages:

  • CreditPaymentCompletePage

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

Credit Payment Confirmation Page context retrieved

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

Credit Payment Confirmation Page context retrieved

Confirm credit payment and initiate gateway redirect

post

Accepts the user's agreement and initiates the payment redirect via payment_strategy.start_redirect(). On success, a redirect_url is stored in the pre-order for the frontend to redirect the user to the payment gateway.

Required Fields:

  • agreement: User must accept the terms and conditions. Must be true.

Validation:

  • agreement must be true.

  • Basket amount must be greater than zero.

State Update:

  • pre_order.data['redirection_started'] is set to true.

  • pre_order.data['is_redirected'] is set to false.

  • pre_order.data['redirect_url'] is set to the gateway redirect URL.

  • pre_order.data['remote_redirect_url'] and pre_order.data['token'] may also be set.

Backward Navigation:

  • When navigating backward, redirection_started, is_redirected, redirect_url, and token are removed from pre_order.data.

Next Pages:

  • CreditPaymentCompletePage

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
agreementboolean · enumRequired

User must accept the terms and conditions to initiate the payment redirect. Must be true.

Possible values:
Responses
200

Redirect initiated or error

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

Redirect initiated or error

Get Saved Card Selection Page context

get

Returns the saved cards available for selection by the current user and active payment gateway. When the active payment gateway provides a hosted card selection interface, the response contains the data required to initialise that interface instead of the card list.

Preconditions:

  • Basket must not be empty.

  • The selected payment option must be a saved card type.

Gateway-Specific Page Context:

  • Standard gateways (SavedCardSelectionPageContext): Returns a cards list. Each entry includes a display name, masked card number, and a selection token.

  • Iyzico gateway (IyzicoSavedCardSelectionPageContext): Returns a ucs object instead of a card list. The ucs object contains the data required to initialise the Iyzico UCS hosted card selection widget: the customer's masked phone number, a UCS session token, the widget script URL, and the script type.

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

  • Card information has been recorded, and

  • A card has been selected, and

  • The selected payment option is of saved card type.

available_for_post_order: false

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

Saved card selection page context retrieved

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

Saved card selection page context retrieved

Select a saved card for payment

post

Submits the saved card to use for the transaction. The card is identified by its token and must belong to the current user and the active payment gateway.

The system resolves the card's BIN number to identify the card type and determine the available installment options. If the BIN cannot be matched in the database, the system falls back to the default card configuration.

Gateway-Specific Input:

  • Standard gateways: Submit SavedCardSelectionInput. The card field is required and must contain the token displayed in the page context.

  • Iyzico gateway: Submit IyzicoSavedCardSelectionInput. The card field is optional and carries the token provided by the Iyzico UCS hosted card selection interface.

Required Fields (standard gateways):

  • card: Token of the saved card to use.

Validation:

  • The card token must correspond to an active saved card for the current user and the active payment gateway.

State Update:

  • Card information is recorded based on the resolved BIN.

  • The selected card is stored in the session.

Backward Navigation:

  • On backward navigation, the card information and the selected card are cleared.

Next Page:

  • SavedCardInstallmentSelectionPage

available_for_post_order: false

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
or
Responses
200

Card selected

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

Card selected

Get Saved Card Installment Selection Page context

get

Returns the installment options available for the selected saved card.

Preconditions:

  • Basket must not be empty.

  • The selected payment option must be a saved card type.

  • Card information must have been recorded.

  • A card must have been selected.

Page Context:

  • installments: List of active installment plans for the resolved card. Each plan includes a primary key, the number of instalments, a display label, the total amount with accrued interest, and the monthly amount with accrued interest.

  • card_type: Card type details including name, slug, and logo URL.

  • installment_messages: Informational messages related to the available installment options (may be empty).

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

  • A saved card has been selected and card information recorded, and

  • An installment plan has been selected and is still valid.

available_for_post_order: false

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

Saved card installment selection page context retrieved

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

Saved card installment selection page context retrieved

Select installment plan for saved card payment

post

Submits the selected installment plan for the saved card transaction. The installment must be active and linked to the card resolved in SavedCardSelectionPage.

Required Fields:

  • installment: Primary key of the installment plan to select.

Validation:

  • The installment must be active and associated with the resolved card.

Next Page:

  • SavedCardConfirmationPage

available_for_post_order: false

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 plan to select. Must reference an active installment linked to the card resolved in SavedCardSelectionPage.

Example: 1
Responses
200

Installment selected

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

Installment selected

Get Saved Card 3D Secure Page context

get

Returns the redirect URL for the 3D Secure authentication flow. The customer is redirected to this URL to complete bank authentication before the payment is finalised.

Preconditions:

  • Basket must not be empty.

  • All previous saved card steps must be complete.

  • A 3D Secure redirect must have been flagged during the confirmation step.

  • An order number must have been assigned.

Page Context:

  • redirect_url: The URL the client must redirect the customer to in order to complete 3D Secure authentication with the bank.

Step Completion: This page is considered already completed when the order has been finalised.

available_for_post_order: false

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

3D Secure redirect URL retrieved

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

3D Secure redirect URL retrieved

Submit 3D Secure callback for saved card payment

post

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

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

3D Secure callback payload posted by the bank after the customer completes authentication. The required fields depend on the active payment gateway.

Any GET query string parameters appended by the bank redirect are merged into this payload before validation.

  • Garanti Switch: success, approved, returnCode, reasonCode, hashedData, requestId, message, and txnAmount are required. txnAmount is sent by the bank in cents and divided by 100 before being validated 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 are required.
successboolean · enumOptional

Payment success flag returned by the gateway. Must be true; any other value is treated as a failed transaction.

Possible values:
approvedboolean · enumOptional

(Garanti Switch only) Authorisation approval flag. Must be true.

Possible values:
returnCodestring · enumOptional

(Garanti Switch only) Bank return code. Must be "00" for a successful transaction.

Possible values:
reasonCodestring · enumOptional

(Garanti Switch only) Bank reason code. Must be "00" for a successful transaction.

Possible values:
hashedDatastringOptional

(Garanti Switch only) Gateway-generated hash. Validated server-side before the payment is accepted.

requestIdstringOptional

(Garanti Switch only) Gateway request identifier.

messagestringOptional

(Garanti Switch only) Human-readable status message from the gateway.

txnAmountstring · decimalOptional

(Garanti Switch only) Transaction amount posted by the bank in cents (e.g. "15000" for 150.00). Divided by 100 before being validated against the order total. A mismatch returns a validation error.

Example: 15000
bodyobject · nullableOptional

(PayU RO only) Optional JSON payload posted by the bank alongside the 3D Secure callback.

tap_idstring · max: 256Optional

(Tap only) Tap charge identifier returned by the gateway.

oidstring · max: 256Optional

(Tap only) Order identifier echoed back by the Tap gateway.

pricestringOptional

(Tap only) Transaction amount returned by the Tap gateway.

Responses
200

3D Secure authentication complete

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

3D Secure authentication complete

Get Saved Card Confirmation Page context

get

Returns the context for the saved card payment confirmation step. No additional data is exposed at GET time; the page serves as the final confirmation before the payment transaction is initiated.

Preconditions:

  • Basket must not be empty.

  • The selected payment option must be a saved card type.

  • Card information must have been recorded.

  • An installment plan must have been selected.

  • A card must have been selected.

Page Context:

  • Returns an empty object {}. All required data was collected in previous steps.

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

  • All previous saved card steps are complete, and

  • The order has been finalised or a 3D Secure redirect has been flagged.

available_for_post_order: false

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

Saved card confirmation page context retrieved

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

Saved card confirmation page context retrieved

Confirm and initiate saved card payment

post

Submits the payment confirmation for the saved card transaction. Upon submission, the system evaluates whether 3D Secure authentication is required.

  • If 3D Secure is required, the response routes to SavedCardThreeDSecurePage with the redirect URL for the bank's 3D Secure flow.

  • If 3D Secure is not required, the payment is processed immediately and the response routes to ThankYouPage.

The accepted fields depend on the active payment gateway. Three input schemas are defined:

  • Standard gateways (SavedCardConfirmationInput): Only agreement is required.

  • Iyzico gateway (IyzicoSavedCardConfirmationInput): agreement and register_consumer_card are required. Either card_token (to charge an existing Iyzico card) or card_number with full card details (to pay with a new card) must also be provided.

  • PayU RO gateway (PayURoSavedCardConfirmationInput): agreement is required. Optional browser device fingerprint fields may be submitted for 3D Secure authentication.

Required Fields (all gateways):

  • agreement: Must be true.

Validation:

  • Basket amount must be greater than zero.

  • Available basket items are re-validated before payment is initiated.

Backward Navigation:

  • No state is reset on backward navigation.

Next Page:

  • SavedCardThreeDSecurePage — when 3D Secure authentication is required.

  • ThankYouPage — when payment completes without 3D Secure.

available_for_post_order: false

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
or
or
Responses
200

Payment confirmed

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

Payment confirmed

Get Checkout Provider Thank You Page context

get

Returns the post-order context for the checkout provider thank-you step. This page is shown after the order has been successfully created via the checkout provider flow. It provides the merchant redirect URL and customer account creation timestamps used by the provider.

Preconditions: (none — independent page)

Skip Conditions:

  • Page is skipped if the order is not yet finalized

Page Context:

  • return_url — absolute URL to the order success page on the merchant's storefront, containing a signed order number

  • merchant_customer_id — internal user ID of the customer

  • merchant_customer_date_joined — ISO 8601 timestamp when the customer account was created

  • merchant_customer_akifast_date_joined — ISO 8601 timestamp when the customer's social account (linked to the checkout provider) was created

Previous Page: CheckoutProviderNotificationPage

Next Page: (none — end of flow)

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

Thank You Page context retrieved

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

Thank You Page context retrieved

Acknowledge the checkout provider thank-you step

post

Submits the thank-you acknowledgement. No input data is required. This step has no processing logic — submitting it simply confirms receipt of the final page context. The is_valid condition always returns false, so the page never auto-advances.

Required Fields: (none)

Next Page: (none — end of flow)

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
objectOptional
Responses
200

Thank-you step acknowledged

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

Thank-you step acknowledged

Get Thank You Page context

get

Terminal page returned when an order has been successfully finalised. The page context contains the signed redirect URL, order identifiers, and optionally the user's authentication token for new accounts.

This page is never directly requested via ?page=ThankYouPage; instead it appears in the context_list response after any payment page successfully finalises the order (e.g., after WalletCompletePage, WalletRedirectCompletePage, B2BPage, PayLaterCompletePage, CreditCardConfirmationPage, etc.).

Preconditions:

  • Pre-condition is always false — this page cannot be forced via the page query parameter. It is only served when the order is already finalised.

Page Context (ThankYouPageContext):

  • redirect_url: Signed URL pointing to the order success page (/orders/checkout/success/<signed_order_number>/).

  • order_id: Primary key of the created order.

  • order_number: Human-readable order number.

  • new_user: true if the order was placed by a user who has not yet set a password (account created during guest checkout).

  • token: Authentication token ID for the new user, or null if the user already has an account or is anonymous.

  • campaigns: List of campaign labels applied to the order.

Step Completion: This page is considered already completed when the order has been finalised (order_finalized() returns 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

Thank you page context retrieved — order has been finalised

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

Thank you page context retrieved — order has been finalised

PreviousPayment Method SelectionNextAlternative Payment Methods

Last updated

Was this helpful?