Akinon Release Notes 07/06/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.

Payments

Payment card and stored card management operations

Get Available Cards for Basket

get

Retrieves available payment cards with installment options for the current basket.

This endpoint returns cards that pass business rule validation for the basket, filtered by amount and basket state. Each card includes its bank, card type, and available installment plans with calculated interest amounts.

Card Filtering Logic:

  • Only cards with active installments are returned

  • Amount calculated from basket total

Response Structure:

  • Paginated list of cards (unlimited pagination)

  • Each card includes bank and card type details

  • Installments array with detailed breakdown

  • Amount context passed to serializer

Responses
200

Successfully retrieved available cards for basket

application/json
countintegerOptional

Total number of cards

Example: 5
nextstring · uri · nullableOptional

Next page URL

previousstring · uri · nullableOptional

Previous page URL

get/payments/cards/basket/
200

Successfully retrieved available cards for basket

Get Available Cards for Pre-Order

get

Retrieves available payment cards with installment options for the current pre-order.

This endpoint returns cards filtered for pre-order checkout, calculated based on pre-order total amount. Used during the checkout flow when a pre-order has been created.

Pre-Order Context:

  • Pre-order created from basket during checkout

  • Business rules applied based on pre-order state

Filtering Logic:

  • Checks basket associated with pre-order

  • Only active installments returned

  • Payment option rules evaluated

  • Card availability based on pre-order amount

Response Behavior:

  • If no pre-order exists, returns empty list

  • Cards include full installment breakdown

  • Interest calculated on pre-order total

  • Sorted by default ordering

Responses
200

Successfully retrieved available cards for pre-order

application/json
countintegerOptional

Total number of cards

Example: 5
nextstring · uri · nullableOptional

Next page URL

previousstring · uri · nullableOptional

Previous page URL

get/payments/cards/pre-order/
200

Successfully retrieved available cards for pre-order

Get Available Cards for Product

get

Retrieves available payment cards with installment options for a specific product.

This endpoint returns cards filtered for product purchase, calculated based on product price. Useful for "Buy Now" flows or product detail page installment display.

Product Context:

  • Amount calculated from product price

  • Business rules applied for single product purchase

Price Calculation:

  • Uses product's current price

  • Does not consider inventory strategy adjustments

  • Fixed quantity of 1 assumed

  • No discount calculations

Filtering Logic:

  • Only active installment plans returned

  • Payment option rules evaluated

  • Card availability based on product price

  • Bank/card type restrictions applied

Use Cases:

  • Display installment options on product detail page

  • Show "Buy with installments" information

  • Calculate monthly payment amounts

  • Compare installment plans across cards

Path parameters
pkintegerRequired

Product unique identifier

Example: 123
Responses
200

Successfully retrieved available cards for product

application/json
countintegerOptional

Total number of cards

Example: 5
nextstring · uri · nullableOptional

Next page URL

previousstring · uri · nullableOptional

Previous page URL

get/payments/cards/product/{pk}/

Get Phone Number for OTP

get

Retrieves the authenticated user's phone number for display before OTP verification.

This endpoint returns the user's registered phone number, which will be used to send the OTP code for card storage verification.

Response Data:

  • Phone number from user profile

  • Leading 0 removed if present (normalization)

  • Pre-filled for user convenience

Use Cases:

  • Display phone number on card storage form

  • Confirm phone number before OTP send

  • Allow user to verify correct number

Header parameters
X-CookiestringRequired

Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. When testing via Postman or other external tools, continue using the standard Cookie header. Some commerce applications may use 'sessionid' instead of 'osessionid'. Set 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. This setting should be applied only for the “TEST IT” button.

Example: osessionid=abc123; csrftoken=def456
X-CsrftokenstringRequired

CSRF token for state-changing requests

Example: def456
Accept-Languagestring · enumOptional

Language preference (for multilingual content). Supported languages: tr, en, ar, ru, de, fr

Default: trExample: trPossible values:
Responses
200

Successfully retrieved user's phone number

application/json
phone_numberstringOptional

Current user's phone number

Example: 5551234567
get/payments/stored-cards/phone-number/

Send OTP for Card Storage

post

Sends OTP verification code to the provided phone number for secure card storage authorization.

This endpoint initiates the card storage flow by sending an OTP code via SMS to the user's phone number. The phone number is cached for later verification.

OTP Flow:

  • User submits phone number

  • System validates phone format (10-14 digits)

  • Leading 0 removed if present (normalization)

  • OTP code generated and sent via SMS gateway

  • Phone number cached with user identifier

  • Empty 204 response returned on success

Phone Number Normalization:

  • Leading 0 automatically removed

  • Example: "05551234567" becomes "5551234567"

  • Spaces removed during validation

  • Must be 10-14 digits after normalization

Use Cases:

  • Initiate card storage verification

  • Send OTP before card save

  • Verify user phone number ownership

Header parameters
X-CookiestringRequired

Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. When testing via Postman or other external tools, continue using the standard Cookie header. Some commerce applications may use 'sessionid' instead of 'osessionid'. Set 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. This setting should be applied only for the “TEST IT” button.

Example: osessionid=abc123; csrftoken=def456
X-CsrftokenstringRequired

CSRF token for state-changing requests

Example: def456
Accept-Languagestring · enumOptional

Language preference (for multilingual content). Supported languages: tr, en, ar, ru, de, fr

Default: trExample: trPossible values:
Body
phone_numberstring · min: 10 · max: 14Required

Phone number for OTP verification (leading 0 removed automatically)

Example: 5551234567
Responses
204

OTP sent successfully (no content returned)

No content
post/payments/stored-cards/phone-number/
No content

Verify OTP and Save Card

post

Verifies the OTP code and saves the credit card with secure tokenization.

This endpoint completes the card storage flow by validating the OTP code and creating a tokenized card record. The card data is retrieved from cache, sent to the payment gateway for tokenization, and stored locally with the token.

Verification Process:

  • User submits OTP code

  • System validates OTP format (4-8 digits)

  • Phone number retrieved from cache

  • Credit card data retrieved from cache

  • Gateway tokenization request sent

  • Token and masked number returned

  • SavedCard record created with token

  • Empty 200 response on success

Card Data Flow:

  • Card number, expiry, CVV cached during earlier step

  • Card data passed to gateway for tokenization

  • Card number never stored in database

  • Only token and masked number persisted

  • Original card data deleted from cache

Tokenization:

  • Gateway-specific tokenization

  • Token format varies by POS/gateway

  • Masked number format: 123456******1234

  • Token associated with user and POS

  • Multiple cards per user supported

Security Features:

  • OTP verification required

  • Card number never logged or persisted

  • Secure token storage

  • POS isolation (tokens not shared across gateways)

  • Cache timeout prevents replay

Error Handling:

  • Invalid OTP: Validation error returned

  • Gateway failure: Error message from gateway

  • Cache miss: Missing phone/card data error

  • Token creation failure: Card not saved

Use Cases:

  • Complete card storage after OTP verification

  • Save card for future purchases

Header parameters
X-CookiestringRequired

Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. When testing via Postman or other external tools, continue using the standard Cookie header. Some commerce applications may use 'sessionid' instead of 'osessionid'. Set 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. This setting should be applied only for the “TEST IT” button.

Example: osessionid=abc123; csrftoken=def456
X-CsrftokenstringRequired

CSRF token for state-changing requests

Example: def456
Accept-Languagestring · enumOptional

Language preference (for multilingual content). Supported languages: tr, en, ar, ru, de, fr

Default: trExample: trPossible values:
Body
otpstring · min: 4 · max: 8Required

OTP verification code received via SMS

Example: 123456
Responses
200

Card successfully saved (no content returned)

No content
post/payments/stored-cards/otp/
No content

Get Masterpass JavaScript Configuration

get

Retrieves Masterpass JavaScript configuration for client-side integration.

This endpoint returns configuration parameters required to initialize the Masterpass payment widget on the frontend. It includes the JavaScript library URL, client credentials, and return URLs for 3D Secure flow.

Configuration Elements:

  • js: Masterpass JavaScript library URL from payment gateway config

  • client_id: OAuth client identifier for Masterpass API authentication

  • merchant_id: Merchant identifier (empty string for custom merchant type)

  • s3d_return_url: Return URL after 3D Secure verification (includes query params)

Merchant Type Logic:

  • If merchant_type == "custom": merchant_id is empty string

  • Otherwise: merchant_id from gateway configuration

  • Custom merchants use alternative authentication

Availability:

  • Requires active Masterpass payment option

  • PaymentOption with payment_type=PaymentType.masterpass

  • POS configured for Masterpass gateway

  • Returns 404 if Masterpass not configured

Frontend Integration:

  1. Call /masterpass-js/ to get config

  2. Load JavaScript library from js URL

  3. Initialize Masterpass widget with client_id and merchant_id

  4. Set return URL to s3d_return_url

  5. User completes Masterpass authentication

  6. 3D Secure verification if enabled

  7. Return to checkout with payment token

Use Cases:

  • Initialize Masterpass payment widget

  • Configure 3D Secure authentication

  • Set up OAuth credentials for Masterpass API

Responses
200

Successfully retrieved Masterpass configuration

application/json
jsstring · uriOptional

Masterpass JavaScript library URL

Example: https://masterpass.example.com/v2/masterpass.js
client_idstringOptional

OAuth client identifier for Masterpass API

Example: abc123def456ghi789
merchant_idstringOptional

Merchant identifier (empty for custom merchant type)

Example: merchant_123456
s3d_return_urlstring · uriOptional

Return URL after 3D Secure verification

Example: https://shop.example.com/orders/checkout/?three_d_secure=true&page=MasterpassCompletePage
get/masterpass-js/
PreviousMasterpass Integration FlowNextModels

Last updated

Was this helpful?