# Payments

Payment card and stored card management operations

## Get Available Cards for Basket

> 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

```json
{"openapi":"3.0.3","info":{"title":"Payments API","version":"1.0.0"},"tags":[{"name":"payments","description":"Payment card and stored card management operations"}],"servers":[{"description":"Server base URL for payment operations","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/payments/cards/basket/":{"get":{"summary":"Get Available Cards for Basket","description":"Retrieves available payment cards with installment options for the current basket.\n\nThis 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.\n\n**Card Filtering Logic:**\n* Only cards with active installments are returned\n* Amount calculated from basket total\n\n**Response Structure:**\n* Paginated list of cards (unlimited pagination)\n* Each card includes bank and card type details\n* Installments array with detailed breakdown\n* Amount context passed to serializer","operationId":"get_basket_cards","responses":{"200":{"description":"Successfully retrieved available cards for basket","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardListResponse"}}}}},"tags":["payments"]}}},"components":{"schemas":{"CardListResponse":{"type":"object","properties":{"count":{"type":"integer","description":"Total number of cards"},"next":{"type":"string","format":"uri","nullable":true,"description":"Next page URL"},"previous":{"type":"string","format":"uri","nullable":true,"description":"Previous page URL"},"results":{"type":"array","description":"List of available cards with installment options","items":{"$ref":"#/components/schemas/CardDetail"}}}},"CardDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"Card unique identifier"},"name":{"type":"string","description":"Card display name"},"card_payment_type":{"type":"string","description":"Payment type (credit or debit)","enum":["credit","debit"]},"card_type":{"$ref":"#/components/schemas/CardTypeDetail"},"bank":{"$ref":"#/components/schemas/BankDetail"},"installments":{"type":"array","description":"Available installment plans for this card","items":{"$ref":"#/components/schemas/InstallmentDetail"}}}},"CardTypeDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"Card type unique identifier"},"name":{"type":"string","description":"Card type name"},"slug":{"type":"string","description":"Card type slug identifier"},"logo":{"type":"string","format":"uri","nullable":true,"description":"Card type logo image URL"},"logo_path":{"type":"string","nullable":true,"description":"Card type logo file path"}}},"BankDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"Bank unique identifier"},"name":{"type":"string","description":"Bank name"},"slug":{"type":"string","description":"Bank slug identifier"},"logo":{"type":"string","format":"uri","nullable":true,"description":"Bank logo image URL"},"logo_path":{"type":"string","nullable":true,"description":"Bank logo file path"}}},"InstallmentDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"Installment plan unique identifier"},"installment_count":{"type":"integer","description":"Number of installments"},"interest_rate":{"type":"number","format":"float","description":"Interest rate percentage"},"label":{"type":"string","description":"Display label for installment plan"},"is_active":{"type":"boolean","description":"Whether installment plan is active"},"amount":{"type":"number","format":"float","description":"Original purchase amount"},"interest_amount":{"type":"number","format":"float","description":"Total interest amount for this installment plan"},"total_amount":{"type":"number","format":"float","description":"Total amount including interest"},"single_installment_amount":{"type":"number","format":"float","description":"Amount per installment"}}}}}}
```

## Get Available Cards for Pre-Order

> 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

```json
{"openapi":"3.0.3","info":{"title":"Payments API","version":"1.0.0"},"tags":[{"name":"payments","description":"Payment card and stored card management operations"}],"servers":[{"description":"Server base URL for payment operations","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/payments/cards/pre-order/":{"get":{"summary":"Get Available Cards for Pre-Order","description":"Retrieves available payment cards with installment options for the current pre-order.\n\nThis 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.\n\n**Pre-Order Context:**\n* Pre-order created from basket during checkout\n* Business rules applied based on pre-order state\n\n**Filtering Logic:**\n* Checks basket associated with pre-order\n* Only active installments returned\n* Payment option rules evaluated\n* Card availability based on pre-order amount\n\n**Response Behavior:**\n* If no pre-order exists, returns empty list\n* Cards include full installment breakdown\n* Interest calculated on pre-order total\n* Sorted by default ordering","operationId":"get_pre_order_cards","responses":{"200":{"description":"Successfully retrieved available cards for pre-order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardListResponse"}}}}},"tags":["payments"]}}},"components":{"schemas":{"CardListResponse":{"type":"object","properties":{"count":{"type":"integer","description":"Total number of cards"},"next":{"type":"string","format":"uri","nullable":true,"description":"Next page URL"},"previous":{"type":"string","format":"uri","nullable":true,"description":"Previous page URL"},"results":{"type":"array","description":"List of available cards with installment options","items":{"$ref":"#/components/schemas/CardDetail"}}}},"CardDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"Card unique identifier"},"name":{"type":"string","description":"Card display name"},"card_payment_type":{"type":"string","description":"Payment type (credit or debit)","enum":["credit","debit"]},"card_type":{"$ref":"#/components/schemas/CardTypeDetail"},"bank":{"$ref":"#/components/schemas/BankDetail"},"installments":{"type":"array","description":"Available installment plans for this card","items":{"$ref":"#/components/schemas/InstallmentDetail"}}}},"CardTypeDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"Card type unique identifier"},"name":{"type":"string","description":"Card type name"},"slug":{"type":"string","description":"Card type slug identifier"},"logo":{"type":"string","format":"uri","nullable":true,"description":"Card type logo image URL"},"logo_path":{"type":"string","nullable":true,"description":"Card type logo file path"}}},"BankDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"Bank unique identifier"},"name":{"type":"string","description":"Bank name"},"slug":{"type":"string","description":"Bank slug identifier"},"logo":{"type":"string","format":"uri","nullable":true,"description":"Bank logo image URL"},"logo_path":{"type":"string","nullable":true,"description":"Bank logo file path"}}},"InstallmentDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"Installment plan unique identifier"},"installment_count":{"type":"integer","description":"Number of installments"},"interest_rate":{"type":"number","format":"float","description":"Interest rate percentage"},"label":{"type":"string","description":"Display label for installment plan"},"is_active":{"type":"boolean","description":"Whether installment plan is active"},"amount":{"type":"number","format":"float","description":"Original purchase amount"},"interest_amount":{"type":"number","format":"float","description":"Total interest amount for this installment plan"},"total_amount":{"type":"number","format":"float","description":"Total amount including interest"},"single_installment_amount":{"type":"number","format":"float","description":"Amount per installment"}}}}}}
```

## Get Available Cards for Product

> 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

```json
{"openapi":"3.0.3","info":{"title":"Payments API","version":"1.0.0"},"tags":[{"name":"payments","description":"Payment card and stored card management operations"}],"servers":[{"description":"Server base URL for payment operations","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/payments/cards/product/{pk}/":{"get":{"summary":"Get Available Cards for Product","description":"Retrieves available payment cards with installment options for a specific product.\n\nThis endpoint returns cards filtered for product purchase, calculated based on product price. Useful for \"Buy Now\" flows or product detail page installment display.\n\n**Product Context:**\n* Amount calculated from product price\n* Business rules applied for single product purchase\n\n**Price Calculation:**\n* Uses product's current price\n* Does not consider inventory strategy adjustments\n* Fixed quantity of 1 assumed\n* No discount calculations\n\n**Filtering Logic:**\n* Only active installment plans returned\n* Payment option rules evaluated\n* Card availability based on product price\n* Bank/card type restrictions applied\n\n**Use Cases:**\n* Display installment options on product detail page\n* Show \"Buy with installments\" information\n* Calculate monthly payment amounts\n* Compare installment plans across cards","operationId":"get_product_cards","parameters":[{"name":"pk","in":"path","required":true,"description":"Product unique identifier","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successfully retrieved available cards for product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardListResponse"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["payments"]}}},"components":{"schemas":{"CardListResponse":{"type":"object","properties":{"count":{"type":"integer","description":"Total number of cards"},"next":{"type":"string","format":"uri","nullable":true,"description":"Next page URL"},"previous":{"type":"string","format":"uri","nullable":true,"description":"Previous page URL"},"results":{"type":"array","description":"List of available cards with installment options","items":{"$ref":"#/components/schemas/CardDetail"}}}},"CardDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"Card unique identifier"},"name":{"type":"string","description":"Card display name"},"card_payment_type":{"type":"string","description":"Payment type (credit or debit)","enum":["credit","debit"]},"card_type":{"$ref":"#/components/schemas/CardTypeDetail"},"bank":{"$ref":"#/components/schemas/BankDetail"},"installments":{"type":"array","description":"Available installment plans for this card","items":{"$ref":"#/components/schemas/InstallmentDetail"}}}},"CardTypeDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"Card type unique identifier"},"name":{"type":"string","description":"Card type name"},"slug":{"type":"string","description":"Card type slug identifier"},"logo":{"type":"string","format":"uri","nullable":true,"description":"Card type logo image URL"},"logo_path":{"type":"string","nullable":true,"description":"Card type logo file path"}}},"BankDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"Bank unique identifier"},"name":{"type":"string","description":"Bank name"},"slug":{"type":"string","description":"Bank slug identifier"},"logo":{"type":"string","format":"uri","nullable":true,"description":"Bank logo image URL"},"logo_path":{"type":"string","nullable":true,"description":"Bank logo file path"}}},"InstallmentDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"Installment plan unique identifier"},"installment_count":{"type":"integer","description":"Number of installments"},"interest_rate":{"type":"number","format":"float","description":"Interest rate percentage"},"label":{"type":"string","description":"Display label for installment plan"},"is_active":{"type":"boolean","description":"Whether installment plan is active"},"amount":{"type":"number","format":"float","description":"Original purchase amount"},"interest_amount":{"type":"number","format":"float","description":"Total interest amount for this installment plan"},"total_amount":{"type":"number","format":"float","description":"Total amount including interest"},"single_installment_amount":{"type":"number","format":"float","description":"Amount per installment"}}},"ErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Field-specific validation errors","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}
```

## Get Phone Number for OTP

> 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

```json
{"openapi":"3.0.3","info":{"title":"Payments API","version":"1.0.0"},"tags":[{"name":"payments","description":"Payment card and stored card management operations"}],"servers":[{"description":"Server base URL for payment operations","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/payments/stored-cards/phone-number/":{"get":{"summary":"Get Phone Number for OTP","description":"Retrieves the authenticated user's phone number for display before OTP verification.\n\nThis endpoint returns the user's registered phone number, which will be used to send the OTP code for card storage verification.\n\n**Response Data:**\n* Phone number from user profile\n* Leading 0 removed if present (normalization)\n* Pre-filled for user convenience\n\n**Use Cases:**\n* Display phone number on card storage form\n* Confirm phone number before OTP send\n* Allow user to verify correct number","operationId":"get_phone_number_for_otp","parameters":[{"$ref":"#/components/parameters/CookieHeaderWithCsrfToken"},{"$ref":"#/components/parameters/CsrfTokenHeader"},{"$ref":"#/components/parameters/AcceptLanguageHeader"}],"responses":{"200":{"description":"Successfully retrieved user's phone number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["payments"]}}},"components":{"parameters":{"CookieHeaderWithCsrfToken":{"name":"X-Cookie","in":"header","description":"Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. \nWhen testing via Postman or other external tools, continue using the standard Cookie header. \nSome commerce applications may use 'sessionid' instead of 'osessionid'. \nSet 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. \nThis setting should be applied only for the “TEST IT” button.","required":true,"schema":{"type":"string"}},"CsrfTokenHeader":{"name":"X-Csrftoken","in":"header","description":"CSRF token for state-changing requests","required":true,"schema":{"type":"string"}},"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","description":"Language preference (for multilingual content).\nSupported languages: tr, en, ar, ru, de, fr","required":false,"schema":{"type":"string","enum":["tr","en","ar","ru","de","fr"],"default":"tr"}}},"schemas":{"PhoneNumberResponse":{"type":"object","properties":{"phone_number":{"type":"string","description":"Current user's phone number"}}},"ErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Field-specific validation errors","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}
```

## Send OTP for Card Storage

> 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

```json
{"openapi":"3.0.3","info":{"title":"Payments API","version":"1.0.0"},"tags":[{"name":"payments","description":"Payment card and stored card management operations"}],"servers":[{"description":"Server base URL for payment operations","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/payments/stored-cards/phone-number/":{"post":{"summary":"Send OTP for Card Storage","description":"Sends OTP verification code to the provided phone number for secure card storage authorization.\n\nThis 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.\n\n**OTP Flow:**\n- User submits phone number\n- System validates phone format (10-14 digits)\n- Leading 0 removed if present (normalization)\n- OTP code generated and sent via SMS gateway\n- Phone number cached with user identifier\n- Empty 204 response returned on success\n\n**Phone Number Normalization:**\n* Leading 0 automatically removed\n* Example: \"05551234567\" becomes \"5551234567\"\n* Spaces removed during validation\n* Must be 10-14 digits after normalization\n\n**Use Cases:**\n* Initiate card storage verification\n* Send OTP before card save\n* Verify user phone number ownership","operationId":"send_otp_for_card_storage","parameters":[{"$ref":"#/components/parameters/CookieHeaderWithCsrfToken"},{"$ref":"#/components/parameters/CsrfTokenHeader"},{"$ref":"#/components/parameters/AcceptLanguageHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberRequest"}}}},"responses":{"204":{"description":"OTP sent successfully (no content returned)"},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["payments"]}}},"components":{"parameters":{"CookieHeaderWithCsrfToken":{"name":"X-Cookie","in":"header","description":"Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. \nWhen testing via Postman or other external tools, continue using the standard Cookie header. \nSome commerce applications may use 'sessionid' instead of 'osessionid'. \nSet 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. \nThis setting should be applied only for the “TEST IT” button.","required":true,"schema":{"type":"string"}},"CsrfTokenHeader":{"name":"X-Csrftoken","in":"header","description":"CSRF token for state-changing requests","required":true,"schema":{"type":"string"}},"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","description":"Language preference (for multilingual content).\nSupported languages: tr, en, ar, ru, de, fr","required":false,"schema":{"type":"string","enum":["tr","en","ar","ru","de","fr"],"default":"tr"}}},"schemas":{"PhoneNumberRequest":{"type":"object","required":["phone_number"],"properties":{"phone_number":{"type":"string","minLength":10,"maxLength":14,"description":"Phone number for OTP verification (leading 0 removed automatically)"}}},"ErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Field-specific validation errors","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}
```

## Verify OTP and Save Card

> 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

```json
{"openapi":"3.0.3","info":{"title":"Payments API","version":"1.0.0"},"tags":[{"name":"payments","description":"Payment card and stored card management operations"}],"servers":[{"description":"Server base URL for payment operations","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/payments/stored-cards/otp/":{"post":{"summary":"Verify OTP and Save Card","description":"Verifies the OTP code and saves the credit card with secure tokenization.\n\nThis 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.\n\n**Verification Process:**\n- User submits OTP code\n- System validates OTP format (4-8 digits)\n- Phone number retrieved from cache\n- Credit card data retrieved from cache\n- Gateway tokenization request sent\n- Token and masked number returned\n- SavedCard record created with token\n- Empty 200 response on success\n\n**Card Data Flow:**\n* Card number, expiry, CVV cached during earlier step\n* Card data passed to gateway for tokenization\n* **Card number never stored in database**\n* Only token and masked number persisted\n* Original card data deleted from cache\n\n**Tokenization:**\n* Gateway-specific tokenization\n* Token format varies by POS/gateway\n* Masked number format: `123456******1234`\n* Token associated with user and POS\n* Multiple cards per user supported\n\n**Security Features:**\n* OTP verification required\n* Card number never logged or persisted\n* Secure token storage\n* POS isolation (tokens not shared across gateways)\n* Cache timeout prevents replay\n\n**Error Handling:**\n* Invalid OTP: Validation error returned\n* Gateway failure: Error message from gateway\n* Cache miss: Missing phone/card data error\n* Token creation failure: Card not saved\n\n**Use Cases:**\n* Complete card storage after OTP verification\n* Save card for future purchases","operationId":"verify_otp_and_save_card","parameters":[{"$ref":"#/components/parameters/CookieHeaderWithCsrfToken"},{"$ref":"#/components/parameters/CsrfTokenHeader"},{"$ref":"#/components/parameters/AcceptLanguageHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OtpRequest"}}}},"responses":{"200":{"description":"Card successfully saved (no content returned)"},"400":{"description":"Validation error, cache miss, or gateway failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["payments"]}}},"components":{"parameters":{"CookieHeaderWithCsrfToken":{"name":"X-Cookie","in":"header","description":"Use the X-Cookie header instead of the Cookie header in the “TEST IT” section. \nWhen testing via Postman or other external tools, continue using the standard Cookie header. \nSome commerce applications may use 'sessionid' instead of 'osessionid'. \nSet 'ENABLE_X_COOKIE_HEADER = True' in your project environments to enable the “TEST IT” feature. \nThis setting should be applied only for the “TEST IT” button.","required":true,"schema":{"type":"string"}},"CsrfTokenHeader":{"name":"X-Csrftoken","in":"header","description":"CSRF token for state-changing requests","required":true,"schema":{"type":"string"}},"AcceptLanguageHeader":{"name":"Accept-Language","in":"header","description":"Language preference (for multilingual content).\nSupported languages: tr, en, ar, ru, de, fr","required":false,"schema":{"type":"string","enum":["tr","en","ar","ru","de","fr"],"default":"tr"}}},"schemas":{"OtpRequest":{"type":"object","required":["otp"],"properties":{"otp":{"type":"string","minLength":4,"maxLength":8,"description":"OTP verification code received via SMS"}}},"ErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Field-specific validation errors","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}
```

## Get Masterpass JavaScript Configuration

> 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

```json
{"openapi":"3.0.3","info":{"title":"Payments API","version":"1.0.0"},"tags":[{"name":"payments","description":"Payment card and stored card management operations"}],"servers":[{"description":"Server base URL for payment operations","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/masterpass-js/":{"get":{"summary":"Get Masterpass JavaScript Configuration","description":"Retrieves Masterpass JavaScript configuration for client-side integration.\n\nThis 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.\n\n**Configuration Elements:**\n* `js`: Masterpass JavaScript library URL from payment gateway config\n* `client_id`: OAuth client identifier for Masterpass API authentication\n* `merchant_id`: Merchant identifier (empty string for custom merchant type)\n* `s3d_return_url`: Return URL after 3D Secure verification (includes query params)\n\n**Merchant Type Logic:**\n* If `merchant_type == \"custom\"`: merchant_id is empty string\n* Otherwise: merchant_id from gateway configuration\n* Custom merchants use alternative authentication\n\n**Availability:**\n* Requires active Masterpass payment option\n* PaymentOption with `payment_type=PaymentType.masterpass`\n* POS configured for Masterpass gateway\n* Returns 404 if Masterpass not configured\n\n**Frontend Integration:**\n1. Call `/masterpass-js/` to get config\n2. Load JavaScript library from `js` URL\n3. Initialize Masterpass widget with client_id and merchant_id\n4. Set return URL to `s3d_return_url`\n5. User completes Masterpass authentication\n6. 3D Secure verification if enabled\n7. Return to checkout with payment token\n\n**Use Cases:**\n* Initialize Masterpass payment widget\n* Configure 3D Secure authentication\n* Set up OAuth credentials for Masterpass API","operationId":"get_masterpass_js_config","responses":{"200":{"description":"Successfully retrieved Masterpass configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MasterpassJSConfig"}}}},"404":{"description":"Masterpass not configured or unavailable (empty response body)"}},"tags":["payments"]}}},"components":{"schemas":{"MasterpassJSConfig":{"type":"object","properties":{"js":{"type":"string","format":"uri","description":"Masterpass JavaScript library URL"},"client_id":{"type":"string","description":"OAuth client identifier for Masterpass API"},"merchant_id":{"type":"string","description":"Merchant identifier (empty for custom merchant type)"},"s3d_return_url":{"type":"string","format":"uri","description":"Return URL after 3D Secure verification"}}}}}}
```