Payments
Payment card and stored card management operations
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
Successfully retrieved available cards for basket
Successfully retrieved available cards for basket
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
Successfully retrieved available cards for pre-order
Successfully retrieved available cards for pre-order
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
Product unique identifier
123Successfully retrieved available cards for product
Product not found
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
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.
osessionid=abc123; csrftoken=def456CSRF token for state-changing requests
def456Language preference (for multilingual content). Supported languages: tr, en, ar, ru, de, fr
trExample: trPossible values: Successfully retrieved user's phone number
Authentication required
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
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.
osessionid=abc123; csrftoken=def456CSRF token for state-changing requests
def456Language preference (for multilingual content). Supported languages: tr, en, ar, ru, de, fr
trExample: trPossible values: Phone number for OTP verification (leading 0 removed automatically)
5551234567OTP sent successfully (no content returned)
No content
Validation error
Authentication required
No content
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******1234Token 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
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.
osessionid=abc123; csrftoken=def456CSRF token for state-changing requests
def456Language preference (for multilingual content). Supported languages: tr, en, ar, ru, de, fr
trExample: trPossible values: OTP verification code received via SMS
123456Card successfully saved (no content returned)
Validation error, cache miss, or gateway failure
Authentication required
No content
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 configclient_id: OAuth client identifier for Masterpass API authenticationmerchant_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 stringOtherwise: merchant_id from gateway configuration
Custom merchants use alternative authentication
Availability:
Requires active Masterpass payment option
PaymentOption with
payment_type=PaymentType.masterpassPOS configured for Masterpass gateway
Returns 404 if Masterpass not configured
Frontend Integration:
Call
/masterpass-js/to get configLoad JavaScript library from
jsURLInitialize Masterpass widget with client_id and merchant_id
Set return URL to
s3d_return_urlUser completes Masterpass authentication
3D Secure verification if enabled
Return to checkout with payment token
Use Cases:
Initialize Masterpass payment widget
Configure 3D Secure authentication
Set up OAuth credentials for Masterpass API
Successfully retrieved Masterpass configuration
Masterpass not configured or unavailable (empty response body)
Last updated
Was this helpful?