# Checkout Provider

External checkout provider integration endpoints

## Process Checkout Provider Step

> Processes a checkout step using an external checkout provider (e.g., Akifast).\
> \
> \*\*How It Works:\*\*\
> \- Send \`basket\_id\` in request body and specify the page via \`?page=\` query parameter.\
> \- Each page performs specific operations and returns context data for the next step.\
> \- The checkout flow is stateful - each step builds on the previous one.\
> \- On the final step, the order is created.\
> \
> \## Checkout Flow Pages\
> \
> \### 1. CheckoutProviderIndexPage\
> Initializes the checkout flow. Call this first to start the process.\
> \
> \---\
> \
> \### 2. CheckoutProviderSelectionPage\
> User selects which checkout provider to use (e.g., Akifast).\
> \
> \*\*What happens on this step:\*\*\
> 1\. The selected checkout provider is validated and saved to the order.\
> 2\. Delivery option is set to "customer" (home delivery).\
> 3\. Any loyalty points usage is reset to zero.\
> 4\. A payment session is started with the external provider.\
> 5\. Callback URLs are registered for the provider to send data back.\
> 6\. A \`redirect\_url\` is generated for the provider's hosted checkout page.\
> 7\. A \`conversation\_id\` is stored for security verification in subsequent steps.\
> \
> \*\*On success:\*\* User should be redirected to the \`redirect\_url\` to continue checkout on the provider's page.\
> \
> \---\
> \
> \### 3. CheckoutProviderAddressSelectionPage\
> Receives address data from the checkout provider's callback.\
> The provider sends shipping and billing address information which gets saved to the order.\
> \
> \---\
> \
> \### 4. CheckoutProviderShippingOptionPage\
> Returns available shipping options for the delivery address.\
> The \`conversation\_id\` must match the one from the payment session for security.\
> \
> \---\
> \
> \### 5. CheckoutProviderAgreementListPage\
> User selects a shipping option and views the terms & conditions.\
> The shipping cost is calculated based on the selected option.\
> \
> \---\
> \
> \### 6. CheckoutProviderNotificationPage\
> Receives payment confirmation from the provider and creates the order.\
> \
> \*\*Important:\*\* The basket is validated to ensure it hasn't changed during checkout.\
> If items were added, removed, or quantities changed, the order creation fails.\
> \
> \---\
> \
> \### 7. CheckoutProviderThankYouPage (Final Response)\
> After successful order creation, this page's context is returned.\
> \
> \*\*Response contains:\*\*\
> \- \`return\_url\`: Signed URL to the order completion page\
> \- \`merchant\_customer\_id\`: Customer's unique ID\
> \- \`merchant\_customer\_date\_joined\`: Customer's registration date\
> \- \`merchant\_customer\_akifast\_date\_joined\`: Date when customer linked their account with the provider\
> \
> \---\
> \
> \*\*Error Handling:\*\*\
> \- If basket changes during checkout → 400 error\
> \- If order creation fails → System attempts fallback order creation

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"tags":[{"name":"Checkout Provider","description":"External checkout provider integration endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[],"paths":{"/orders/checkout-provider/":{"post":{"tags":["Checkout Provider"],"summary":"Process Checkout Provider Step","description":"Processes a checkout step using an external checkout provider (e.g., Akifast).\n\n**How It Works:**\n- Send `basket_id` in request body and specify the page via `?page=` query parameter.\n- Each page performs specific operations and returns context data for the next step.\n- The checkout flow is stateful - each step builds on the previous one.\n- On the final step, the order is created.\n\n## Checkout Flow Pages\n\n### 1. CheckoutProviderIndexPage\nInitializes the checkout flow. Call this first to start the process.\n\n---\n\n### 2. CheckoutProviderSelectionPage\nUser selects which checkout provider to use (e.g., Akifast).\n\n**What happens on this step:**\n1. The selected checkout provider is validated and saved to the order.\n2. Delivery option is set to \"customer\" (home delivery).\n3. Any loyalty points usage is reset to zero.\n4. A payment session is started with the external provider.\n5. Callback URLs are registered for the provider to send data back.\n6. A `redirect_url` is generated for the provider's hosted checkout page.\n7. A `conversation_id` is stored for security verification in subsequent steps.\n\n**On success:** User should be redirected to the `redirect_url` to continue checkout on the provider's page.\n\n---\n\n### 3. CheckoutProviderAddressSelectionPage\nReceives address data from the checkout provider's callback.\nThe provider sends shipping and billing address information which gets saved to the order.\n\n---\n\n### 4. CheckoutProviderShippingOptionPage\nReturns available shipping options for the delivery address.\nThe `conversation_id` must match the one from the payment session for security.\n\n---\n\n### 5. CheckoutProviderAgreementListPage\nUser selects a shipping option and views the terms & conditions.\nThe shipping cost is calculated based on the selected option.\n\n---\n\n### 6. CheckoutProviderNotificationPage\nReceives payment confirmation from the provider and creates the order.\n\n**Important:** The basket is validated to ensure it hasn't changed during checkout.\nIf items were added, removed, or quantities changed, the order creation fails.\n\n---\n\n### 7. CheckoutProviderThankYouPage (Final Response)\nAfter successful order creation, this page's context is returned.\n\n**Response contains:**\n- `return_url`: Signed URL to the order completion page\n- `merchant_customer_id`: Customer's unique ID\n- `merchant_customer_date_joined`: Customer's registration date\n- `merchant_customer_akifast_date_joined`: Date when customer linked their account with the provider\n\n---\n\n**Error Handling:**\n- If basket changes during checkout → 400 error\n- If order creation fails → System attempts fallback order creation","operationId":"processCheckoutProvider","parameters":[{"$ref":"#/components/parameters/CSRFTokenHeader"},{"$ref":"#/components/parameters/CookieHeader"},{"name":"page","in":"query","required":false,"schema":{"type":"string","enum":["CheckoutProviderIndexPage","CheckoutProviderSelectionPage","CheckoutProviderAddressSelectionPage","CheckoutProviderShippingOptionPage","CheckoutProviderAgreementListPage","CheckoutProviderNotificationPage"]},"description":"The checkout page/step to process."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CheckoutProviderIndexPageRequest"},{"$ref":"#/components/schemas/CheckoutProviderSelectionPageRequest"},{"$ref":"#/components/schemas/CheckoutProviderAddressSelectionPageRequest"},{"$ref":"#/components/schemas/CheckoutProviderShippingOptionPageRequest"},{"$ref":"#/components/schemas/CheckoutProviderAgreementListPageRequest"},{"$ref":"#/components/schemas/CheckoutProviderNotificationPageRequest"}],"discriminator":{"propertyName":"_page","mapping":{"index":"#/components/schemas/CheckoutProviderIndexPageRequest","selection":"#/components/schemas/CheckoutProviderSelectionPageRequest","address":"#/components/schemas/CheckoutProviderAddressSelectionPageRequest","shipping":"#/components/schemas/CheckoutProviderShippingOptionPageRequest","agreement":"#/components/schemas/CheckoutProviderAgreementListPageRequest","notification":"#/components/schemas/CheckoutProviderNotificationPageRequest"}}}}}},"responses":{"200":{"description":"Checkout step processed successfully.\n\n**Important:** On success, the response contains the **next page's** data, not the current page's.\nThis allows the client to proceed to the next step with the required data.\n\n| Request Page | Response Contains |\n|--------------|-------------------|\n| `CheckoutProviderIndexPage` | `CheckoutProviderSelectionPage` context |\n| `CheckoutProviderSelectionPage` | `CheckoutProviderAddressSelectionPage` context |\n| `CheckoutProviderAddressSelectionPage` | `CheckoutProviderShippingOptionPage` context |\n| `CheckoutProviderShippingOptionPage` | `CheckoutProviderAgreementListPage` context |\n| `CheckoutProviderAgreementListPage` | `CheckoutProviderNotificationPage` context |\n| `CheckoutProviderNotificationPage` | `CheckoutProviderThankYouPage` context (order completion) |","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutProviderPageResponse"}}}},"400":{"description":"Validation error, basket changed, or processing error.\nThe response contains error details in a field-keyed format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutProviderErrorResponse"}}}}}}}},"components":{"parameters":{"CSRFTokenHeader":{"name":"X-CSRFToken","in":"header","description":"CSRF token for write operations (POST, PUT, PATCH, DELETE).\nRequired for security when using session authentication.\nObtain token from cookie 'csrftoken' or meta tag in HTML.","required":true,"schema":{"type":"string"}},"CookieHeader":{"name":"Cookie","in":"header","description":"Session ID and CSRF token cookies.\nFormat: `sessionid=<id>; osessionid=<id>; csrftoken=<token>`","required":true,"schema":{"type":"string"}}},"schemas":{"CheckoutProviderIndexPageRequest":{"type":"object","description":"Request for `CheckoutProviderIndexPage` - Initializes the checkout provider flow.\nThis is the first page in the checkout flow. Only `basket_id` is required.","required":["basket_id"],"properties":{"basket_id":{"type":"integer","description":"The ID of the active basket to checkout.\nMust be an existing basket with `status=active`."}}},"CheckoutProviderSelectionPageRequest":{"type":"object","description":"Request for `CheckoutProviderSelectionPage` - User selects a checkout provider.\nAfter this step, user is redirected to the external payment provider's page.","required":["basket_id","checkout_provider"],"properties":{"basket_id":{"type":"integer","description":"The ID of the active basket to checkout.\nMust be an existing basket with `status=active`."},"checkout_provider":{"type":"integer","description":"The ID of the selected checkout provider (e.g., Akifast).\nMust be one of the available providers returned by `/checkout-provider-list/`.\nThe system validates that this provider is available for the current basket."}}},"CheckoutProviderAddressSelectionPageRequest":{"type":"object","description":"Request for `CheckoutProviderAddressSelectionPage` - Receives address data from checkout provider callback.\nThis data is sent by the external checkout provider after user enters their address.\n\n**Note:** The address format shown here is Akifast-specific. Other checkout providers may use different formats.","required":["basket_id","session_token","shipping_address","billing_address"],"properties":{"basket_id":{"type":"integer","description":"The ID of the active basket.\nMust match the basket in the checkout session."},"session_token":{"type":"string","format":"uuid","description":"Session token from the checkout provider callback.\nUsed to verify the callback authenticity."},"shipping_address":{"$ref":"#/components/schemas/AkifastAddressInput"},"billing_address":{"$ref":"#/components/schemas/AkifastAddressInput"}}},"AkifastAddressInput":{"type":"object","description":"**Akifast-specific** address input format.\nThis schema is used when Akifast is the checkout provider.\nOther checkout providers may have different address formats.","required":["name","surname","phone_number","address_title","line","hash_data","country","city","town","district"],"properties":{"name":{"type":"string","description":"First name of the address holder."},"surname":{"type":"string","description":"Last name of the address holder."},"phone_number":{"type":"string","description":"Contact phone number.\nShould include country code for international format."},"postal_code":{"type":["string","null"],"description":"Postal/ZIP code (optional).\nNot all regions require postal codes."},"address_title":{"type":"string","description":"User-defined title for the address.\nExamples: \"Home\", \"Office\", \"Work\""},"line":{"type":"string","description":"Full street address line.\nShould include street name, building number, apartment, etc."},"address_type":{"type":["string","null"],"enum":["CUSTOMER","RETAIL_STORE","PICKUP_LOCATION","CHECKOUT_PROVIDER",null],"description":"Address type indicator (case-insensitive, converted to lowercase internally).\n- `CUSTOMER`: Standard customer delivery address\n- `RETAIL_STORE`: Retail store address for in-store pickup\n- `PICKUP_LOCATION`: Designated pickup point\n- `CHECKOUT_PROVIDER`: Address provided by checkout provider"},"tax_no":{"type":["string","null"],"description":"Tax identification number for invoice purposes.\nOptional field for corporate/business customers."},"tax_office":{"type":["string","null"],"description":"Tax office name for invoice purposes.\nCommonly used for corporate customers in Turkey (Vergi Dairesi)."},"company_name":{"type":["string","null"],"description":"Company name for corporate customers.\nUsed for invoice generation."},"notes":{"type":["string","null"],"description":"Additional delivery notes.\nExamples: \"Leave at door\", \"Call before delivery\""},"hash_data":{"type":"string","description":"Address verification hash from the checkout provider.\nUsed to verify address data integrity."},"country":{"$ref":"#/components/schemas/AddressLocationField"},"city":{"$ref":"#/components/schemas/AddressLocationField"},"town":{"$ref":"#/components/schemas/AddressLocationField"},"district":{"$ref":"#/components/schemas/AddressLocationField"}}},"AddressLocationField":{"type":"object","description":"Geographic location field (country/city/town/district).\nThe `code` is used to identify the location in the system.","required":["name","code"],"properties":{"name":{"type":"string","description":"Display name of the location."},"code":{"type":"string","description":"Location code provided by the checkout provider.\nUsed to match with the corresponding location in the system."}}},"CheckoutProviderShippingOptionPageRequest":{"type":"object","description":"Request for `CheckoutProviderShippingOptionPage` - Retrieves available shipping options.\nThe `conversation_id` must match the stored value from the payment session for security.","required":["basket_id","conversation_id"],"properties":{"basket_id":{"type":"integer","description":"The ID of the active basket.\nMust match the basket in the checkout session."},"conversation_id":{"type":"string","description":"Conversation ID from the checkout provider.\nMust match the conversation ID from the payment session initialization.\nValidation error if mismatch: \"Verification failed, please try again\""},"language":{"type":["string","null"],"description":"Language code for localized content (optional).\nExamples: \"tr\" (Turkish), \"en\" (English)."}}},"CheckoutProviderAgreementListPageRequest":{"type":"object","description":"Request for `CheckoutProviderAgreementListPage` - Shows agreements and sets shipping option.\nUser must select a shipping option and an agreement code.","required":["basket_id","session_token","shipping_option_key","user","code"],"properties":{"basket_id":{"type":"integer","description":"The ID of the active basket.\nMust match the basket in the checkout session."},"session_token":{"type":"string","format":"uuid","description":"Session token from the checkout provider callback."},"shipping_option_key":{"type":"integer","description":"The ID of the selected shipping option.\nMust be one of the available shipping options returned in the previous step."},"code":{"type":"string","enum":["info","sales"],"description":"The agreement code to display.\n- `info`: Preliminary information form (ön bilgilendirme formu)\n- `sales`: Distance selling agreement (mesafeli satış sözleşmesi)"},"user":{"type":"object","description":"User information from the checkout provider.\nEmail is used to update the shipping address contact info.","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"User's email address from checkout provider."}}},"shipping_address":{"$ref":"#/components/schemas/AkifastAddressInput","description":"Optional shipping address update.\nIf provided, updates the shipping address in pre-order."},"billing_address":{"$ref":"#/components/schemas/AkifastAddressInput","description":"Optional billing address update.\nIf provided, updates the billing address in pre-order."}}},"CheckoutProviderNotificationPageRequest":{"type":"object","description":"Request for `CheckoutProviderNotificationPage` - Final step that creates the order.\nThis is sent by the checkout provider after successful payment.\nContains complete transaction, user, address, and payment information.\n\n**Note:** The schema shown here (akifast_user, transaction, etc.) is Akifast-specific.\nOther checkout providers may use different field names and formats.","required":["basket_id","basket","agreements","conversation_id","is_successful","akifast_user","transaction","payment_info","card_info"],"properties":{"basket_id":{"type":"integer","description":"The ID of the active basket.\nMust match the basket in the checkout session."},"basket":{"type":"object","description":"Basket snapshot for validation.\nThe system compares this with the current basket to detect changes.\nIf items were added/removed/modified during checkout, order creation fails.","required":["basket_items"],"properties":{"basket_items":{"type":"array","description":"List of basket items for validation.\nEach item's SKU, quantity, and basket_item_id are compared.","items":{"type":"object","required":["sku","quantity","basket_item_id"],"properties":{"sku":{"type":"string","description":"Product SKU code."},"quantity":{"type":"integer","description":"Item quantity in the basket."},"basket_item_id":{"type":"string","description":"Basket item identifier.\nFormat: \"item-{id}\" where id is the basket item ID."}}}}}},"agreements":{"type":"boolean","description":"User's acceptance of terms and conditions.\nMust be `true` to proceed with order creation.\nValidation error if false: \"You must accept agreement to continue.\""},"conversation_id":{"type":"string","description":"Conversation ID for security verification.\nMust match the stored value from payment session initialization.\nValidation error if mismatch: \"Verification failed, please try again\""},"is_successful":{"type":"boolean","description":"Payment success indicator from the checkout provider.\nMust be `true` to create the order.\nValidation error if false: \"Transaction failed. Please try again.\""},"akifast_user":{"$ref":"#/components/schemas/AkifastUserInput"},"transaction":{"$ref":"#/components/schemas/AkifastTransactionInput"},"payment_info":{"type":"object","description":"Payment system information.","required":["payment_system_code"],"properties":{"payment_system_code":{"type":"string","description":"Payment system code.\nExamples: \"akbank\", \"garanti\", \"isbank\", \"yapikredi\""}}},"card_info":{"type":"array","description":"Card information array.\nContains the BIN number for card identification.","minItems":1,"items":{"type":"object","required":["bin"],"properties":{"bin":{"type":"string","minLength":6,"maxLength":8,"pattern":"^[0-9]{6,8}$","description":"Card BIN number (first 6 or 8 digits of card number).\nUsed to identify the card type and issuing bank.\nMust be numeric and 6-8 characters."}}}},"shipping_address":{"$ref":"#/components/schemas/AkifastAddressInput","description":"Final shipping address.\nIf provided, updates the shipping address before order creation."},"billing_address":{"$ref":"#/components/schemas/AkifastAddressInput","description":"Final billing address.\nIf provided, updates the billing address before order creation."}}},"AkifastUserInput":{"type":"object","description":"**Akifast-specific** user information format.\nThis schema is used when Akifast is the checkout provider.\nOther checkout providers may have different user data formats.","required":["akinon_user_id","name","surname","email"],"properties":{"akinon_user_id":{"type":"string","maxLength":255,"description":"Unique user identifier from Akifast/Akinon system.\nUsed to link or create social account."},"name":{"type":"string","maxLength":255,"description":"User's first name."},"surname":{"type":"string","maxLength":255,"description":"User's last name."},"email":{"type":"string","format":"email","description":"User's email address.\nAutomatically converted to lowercase during validation."},"phone_number":{"type":["string","null"],"maxLength":255,"description":"User's phone number."},"identity_number":{"type":["string","null"],"maxLength":255,"description":"National identity number (T.C. Kimlik No in Turkey).\nOptional field for compliance requirements."},"status":{"type":["string","null"],"maxLength":255,"description":"User account status in Akifast system."},"verification_status":{"type":["string","null"],"maxLength":255,"description":"User verification status."},"verification_date":{"type":["string","null"],"maxLength":255,"description":"Date when user was verified."},"gender":{"type":["string","null"],"maxLength":255,"description":"User's gender."},"email_verified":{"type":["string","null"],"maxLength":255,"description":"Email verification status."},"birth_date":{"type":["string","null"],"maxLength":255,"description":"User's birth date."}}},"AkifastTransactionInput":{"type":"object","description":"**Akifast-specific** transaction data format.\nThis schema is used when Akifast is the checkout provider.\nOther checkout providers may have different transaction data formats.\nContains installment, shipping, and raw payment response data.","required":["installment_count","interest_amount","total_paid_amount","payment_system_raw_response","shipping_option_key","is_threed"],"properties":{"shipping_option_key":{"type":"integer","description":"Selected shipping option ID.\nMust be available for the delivery address.\nValidated against available shipping options."},"installment_count":{"type":"integer","minimum":1,"maximum":12,"description":"Number of installments for the payment.\n1 = single payment (no installment)\n2-12 = installment payment"},"interest_rate":{"type":"number","format":"float","minimum":0,"maximum":100,"description":"Interest rate percentage (optional).\n0 = no interest"},"interest_amount":{"type":"number","format":"float","description":"Total interest amount added to the order.\n0 for interest-free installments."},"total_paid_amount":{"type":"number","format":"float","description":"Total amount paid by the customer.\nIncludes order amount + shipping + interest."},"is_threed":{"type":"boolean","description":"Whether 3D Secure authentication was used.\ntrue = 3DS verified transaction\nfalse = non-3DS transaction"},"payment_system_raw_response":{"type":"string","description":"Raw response from the payment system.\nStored for audit and debugging purposes.\nMay be JSON string or other format."}}},"CheckoutProviderPageResponse":{"type":"object","description":"Page context data returned from checkout provider endpoint.\nThe response structure varies depending on which page was processed:\n\n| Page | Response Fields |\n|------|-----------------|\n| `CheckoutProviderIndexPage` | Empty object `{}` |\n| `CheckoutProviderSelectionPage` | `checkout_providers[]`, `redirect_url` (remote payment page) |\n| `CheckoutProviderAddressSelectionPage` | `redirect_url` (to continue on provider) |\n| `CheckoutProviderShippingOptionPage` | `shipping_options[]` |\n| `CheckoutProviderAgreementListPage` | `agreements[]` |\n| `CheckoutProviderNotificationPage` | `return_url`, `merchant_customer_id`, `merchant_customer_date_joined`, `merchant_customer_akifast_date_joined` |\n\nAll fields are optional since different pages return different subsets.","additionalProperties":true,"properties":{"redirect_url":{"type":"string","format":"uri","description":"URL to redirect the user to.\n- **SelectionPage**: Remote payment page URL (e.g., Akifast hosted page).\n- **AddressSelectionPage**: URL to continue checkout on provider page."},"return_url":{"type":"string","format":"uri","description":"**NotificationPage only.**\nURL to redirect after order completion. Points to the order success page."},"merchant_customer_id":{"type":"integer","description":"**NotificationPage only.**\nCustomer's unique ID in the merchant system."},"merchant_customer_date_joined":{"type":"string","format":"date-time","description":"**NotificationPage only.**\nCustomer's registration date in the merchant system."},"merchant_customer_akifast_date_joined":{"type":"string","format":"date-time","description":"**NotificationPage only.**\nDate when customer linked their Akifast account."},"checkout_providers":{"type":"array","description":"**SelectionPage only.**\nList of available checkout providers for this basket.","items":{"type":"object","properties":{"pk":{"type":"integer","description":"Provider ID."},"name":{"type":"string","description":"Provider display name."},"slug":{"type":"string","description":"Provider slug identifier."}}}},"shipping_options":{"type":"array","description":"**ShippingOptionPage only.**\nAvailable shipping options for the delivery address.","items":{"type":"object","properties":{"key":{"type":"integer","description":"Shipping option ID (use this for `shipping_option_key`)."},"name":{"type":"string","description":"Shipping option display name."},"slug":{"type":"string","description":"Shipping option slug."},"logo_url":{"type":"string","format":"uri","description":"URL to the shipping provider's logo."},"shipping_amount":{"type":"string","format":"decimal","description":"Calculated shipping cost for this option."},"description":{"type":"string","description":"Shipping option description (e.g., delivery time)."}}}},"agreements":{"type":"array","description":"**AgreementListPage only.**\nAvailable agreements for user acceptance.","items":{"type":"object","properties":{"code":{"type":"string","description":"Agreement code. Use this in subsequent requests.\nExamples: \"info\", \"sales\""},"text":{"type":"string","description":"Human-readable agreement name."}}}},"code":{"type":"string","description":"**NotificationPage context only.**\nThe selected agreement code."},"text":{"type":"string","description":"**NotificationPage context only.**\nHuman-readable name of the selected agreement."},"agreement_body":{"type":"string","description":"**NotificationPage context only.**\nRendered HTML content of the selected agreement document."}}},"CheckoutProviderErrorResponse":{"type":"object","description":"Error response from checkout provider endpoint.\nErrors are returned as field-keyed arrays of error messages.\n\nCommon error keys:\n- `basket`: Basket-related errors (empty, changed, not found)\n- `error`: General processing errors\n- `non_field_errors`: Validation errors not tied to a specific field\n- `conversation_id`: Conversation ID verification failed\n- `agreements`: Agreement acceptance required\n- `is_successful`: Payment success validation\n- `card_info`: Card BIN validation\n- `shipping_option_key`: Shipping option validation","additionalProperties":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"object"}}]}}}}}
```

## List Available Checkout Providers

> Returns a list of available external checkout providers.\
> \
> \*\*Business Logic:\*\*\
> \- Returns cached provider configurations for performance.\
> \- Cache is refreshed every few minutes (L0: 1min, L1: 2min, L2: 4min).\
> \- Providers include payment gateways and wallet services.\
> \- Only active providers are returned.

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"tags":[{"name":"Checkout Provider","description":"External checkout provider integration endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[],"paths":{"/orders/checkout-provider-list/":{"get":{"tags":["Checkout Provider"],"summary":"List Available Checkout Providers","description":"Returns a list of available external checkout providers.\n\n**Business Logic:**\n- Returns cached provider configurations for performance.\n- Cache is refreshed every few minutes (L0: 1min, L1: 2min, L2: 4min).\n- Providers include payment gateways and wallet services.\n- Only active providers are returned.","operationId":"listCheckoutProviders","responses":{"200":{"description":"List of checkout providers","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutProvider"}}}}}}}}},"components":{"schemas":{"CheckoutProvider":{"type":"object","properties":{"pk":{"type":"integer","description":"Provider ID."},"name":{"type":"string","description":"Provider display name."},"slug":{"type":"string","description":"Provider slug identifier."},"logo":{"type":["string","null"],"format":"uri","description":"URL to the provider's logo image."},"is_active":{"type":"boolean","description":"Whether the provider is currently active."}}}}}}
```

## Get Completed Order Details

> Retrieves the details of a completed order after checkout provider flow.\
> \
> \*\*Business Logic:\*\*\
> \- Validates the signed order number to prevent unauthorized access.\
> \- The signature is time-limited for security.\
> \- Returns order details including items, campaigns, and rewards.\
> \
> \*\*Response Format:\*\*\
> \- Default: HTML page rendering order confirmation.\
> \- JSON: Add \`?format=json\` query parameter.

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"tags":[{"name":"Checkout Provider","description":"External checkout provider integration endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[],"paths":{"/orders/checkout-provider-completed/{order_number}/":{"get":{"tags":["Checkout Provider"],"summary":"Get Completed Order Details","description":"Retrieves the details of a completed order after checkout provider flow.\n\n**Business Logic:**\n- Validates the signed order number to prevent unauthorized access.\n- The signature is time-limited for security.\n- Returns order details including items, campaigns, and rewards.\n\n**Response Format:**\n- Default: HTML page rendering order confirmation.\n- JSON: Add `?format=json` query parameter.","operationId":"getCheckoutProviderCompletedOrder","parameters":[{"name":"order_number","in":"path","required":true,"schema":{"type":"string"},"description":"Signed order number (time-limited signature for security)."},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json"]},"description":"Response format. Use `json` for JSON response."}],"responses":{"200":{"description":"Order details","content":{"text/html":{"schema":{"type":"string","description":"HTML page with order confirmation."}},"application/json":{"schema":{"$ref":"#/components/schemas/CompletedOrderResponse"}}}},"404":{"description":"Order not found or signature expired/invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}}}},"components":{"schemas":{"CompletedOrderResponse":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/OrderDetail"},"campaigns":{"type":"array","items":{"type":"object"},"description":"Applied campaigns on the order."}}},"OrderDetail":{"type":"object","properties":{"pk":{"type":"integer"},"number":{"type":"string","description":"Order number."},"status":{"$ref":"#/components/schemas/EnumValue"},"currency":{"$ref":"#/components/schemas/EnumValue"},"amount":{"type":"string","format":"decimal"},"discount_amount":{"type":"string","format":"decimal"},"shipping_amount":{"type":"string","format":"decimal"},"shipping_tax_rate":{"type":"string","format":"decimal"},"created_date":{"type":"string","format":"date-time"},"orderitem_set":{"type":"array","items":{"$ref":"#/components/schemas/OrderItemSummary"}},"shipping_address":{"$ref":"#/components/schemas/AddressSummary"},"billing_address":{"$ref":"#/components/schemas/AddressSummary"}}},"EnumValue":{"type":"object","properties":{"value":{"type":"string","description":"The internal value of the enum choice."},"label":{"type":"string","description":"The human-readable label of the enum choice."}}},"OrderItemSummary":{"type":"object","properties":{"pk":{"type":"integer"},"product":{"$ref":"#/components/schemas/ProductSummary"},"status":{"$ref":"#/components/schemas/EnumValue"},"price":{"type":"string","format":"decimal"},"quantity":{"type":"integer","default":1},"discount_amount":{"type":"string","format":"decimal"},"tracking_number":{"type":["string","null"]},"shipping_company":{"$ref":"#/components/schemas/EnumValue"}}},"ProductSummary":{"type":"object","properties":{"pk":{"type":"integer"},"sku":{"type":"string"},"name":{"type":"string"},"image":{"type":["string","null"],"format":"uri"}}},"AddressSummary":{"type":"object","properties":{"pk":{"type":"integer"},"title":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"line":{"type":"string"},"city":{"type":"object","properties":{"pk":{"type":"integer"},"name":{"type":"string"}}},"country":{"type":"object","properties":{"pk":{"type":"integer"},"name":{"type":"string"}}}}},"ValidationErrorResponse":{"type":"object","description":"Standard DRF validation error response","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}
```

## Cancel Checkout Provider Flow

> Cancels the current checkout provider flow and returns to the basket page.\
> \
> \*\*Business Logic:\*\*\
> \- Destroys the pre-order data from the session.\
> \- Redirects the user to the basket page.\
> \- Used when the user abandons the checkout process or payment fails.\
> \
> \*\*Trigger Scenarios:\*\*\
> \- User clicks "Cancel" on external payment page.\
> \- Payment fails at the provider.\
> \- User closes the payment window.

```json
{"openapi":"3.1.0","info":{"title":"Orders API","version":"1.0.0"},"tags":[{"name":"Checkout Provider","description":"External checkout provider integration endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[],"paths":{"/orders/checkout-provider-cancel/":{"get":{"tags":["Checkout Provider"],"summary":"Cancel Checkout Provider Flow","description":"Cancels the current checkout provider flow and returns to the basket page.\n\n**Business Logic:**\n- Destroys the pre-order data from the session.\n- Redirects the user to the basket page.\n- Used when the user abandons the checkout process or payment fails.\n\n**Trigger Scenarios:**\n- User clicks \"Cancel\" on external payment page.\n- Payment fails at the provider.\n- User closes the payment window.","operationId":"cancelCheckoutProvider","responses":{"302":{"description":"Redirects to the basket page","headers":{"Location":{"schema":{"type":"string"},"description":"Redirect URL to basket page (e.g., `/basket/`)"}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.akinon.com/commerce-openapis/orders/checkout-provider.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.