Checkout Provider

External checkout provider integration endpoints

Process Checkout Provider Step

post

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

Query parameters

pagestring · enumOptional

The checkout page/step to process.

Possible values:

Header parameters

X-CSRFTokenstringRequired

CSRF token for write operations (POST, PUT, PATCH, DELETE). Required for security when using session authentication. Obtain token from cookie 'csrftoken' or meta tag in HTML.

Example: abc123def456ghi789

CookiestringRequired

Session ID and CSRF token cookies. Format: sessionid=<id>; osessionid=<id>; csrftoken=<token>

Example: sessionid=abc123def456; osessionid=abc123def456; csrftoken=xyz789

Body

application/json

or

or

or

or

or

Responses

200

Checkout step processed successfully.

Important: On success, the response contains the next page's data, not the current page's. This allows the client to proceed to the next step with the required data.

Request Page	Response Contains
CheckoutProviderIndexPage	CheckoutProviderSelectionPage context
CheckoutProviderSelectionPage	CheckoutProviderAddressSelectionPage context
CheckoutProviderAddressSelectionPage	CheckoutProviderShippingOptionPage context
CheckoutProviderShippingOptionPage	CheckoutProviderAgreementListPage context
CheckoutProviderAgreementListPage	CheckoutProviderNotificationPage context
CheckoutProviderNotificationPage	CheckoutProviderThankYouPage context (order completion)

application/json

Page context data returned from checkout provider endpoint. The response structure varies depending on which page was processed:

Page	Response Fields
CheckoutProviderIndexPage	Empty object {}
CheckoutProviderSelectionPage	checkout_providers[], redirect_url (remote payment page)
CheckoutProviderAddressSelectionPage	redirect_url (to continue on provider)
CheckoutProviderShippingOptionPage	shipping_options[]
CheckoutProviderAgreementListPage	agreements[]
CheckoutProviderNotificationPage	return_url, merchant_customer_id, merchant_customer_date_joined, merchant_customer_akifast_date_joined

All fields are optional since different pages return different subsets.

redirect_urlstring · uriOptional

URL to redirect the user to.

• SelectionPage: Remote payment page URL (e.g., Akifast hosted page).
• AddressSelectionPage: URL to continue checkout on provider page.

return_urlstring · uriOptional

NotificationPage only. URL to redirect after order completion. Points to the order success page.

merchant_customer_idintegerOptional

NotificationPage only. Customer's unique ID in the merchant system.

merchant_customer_date_joinedstring · date-timeOptional

NotificationPage only. Customer's registration date in the merchant system.

merchant_customer_akifast_date_joinedstring · date-timeOptional

NotificationPage only. Date when customer linked their Akifast account.

codestringOptional

NotificationPage context only. The selected agreement code.

textstringOptional

NotificationPage context only. Human-readable name of the selected agreement.

agreement_bodystringOptional

NotificationPage context only. Rendered HTML content of the selected agreement document.

Other propertiesanyOptional

400

Validation error, basket changed, or processing error. The response contains error details in a field-keyed format.

application/json

post

/orders/checkout-provider/

HTTPcURLJavaScriptPython

POST /orders/checkout-provider/ HTTP/1.1
Host: sandbox.akinon.com
X-CSRFToken: abc123def456ghi789
Cookie: sessionid=abc123def456; osessionid=abc123def456; csrftoken=xyz789
Content-Type: application/json
Accept: */*
Content-Length: 19

{
  "basket_id": 12345
}

CheckoutProviderIndexPage (Akifast Example)CheckoutProviderSelectionPage (Akifast Example)CheckoutProviderAddressSelectionPage (Akifast Example)CheckoutProviderShippingOptionPage (Akifast Example)CheckoutProviderAgreementListPage (Akifast Example)CheckoutProviderNotificationPage (Akifast Example)

{
  "checkout_providers": [
    {
      "pk": 1,
      "name": "Akifast",
      "slug": "akifast"
    },
    {
      "pk": 2,
      "name": "PayPal Express",
      "slug": "paypal"
    }
  ]
}

List Available Checkout Providers

get

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.

Responses

200

List of checkout providers

application/json

pkintegerOptional

Provider ID.

namestringOptional

Provider display name.

slugstringOptional

Provider slug identifier.

logostring · nullableOptional

URL to the provider's logo image.

is_activebooleanOptional

Whether the provider is currently active.

get

/orders/checkout-provider-list/

HTTPcURLJavaScriptPython

GET /orders/checkout-provider-list/ HTTP/1.1
Host: sandbox.akinon.com
Accept: */*

200

List of checkout providers

[
  {
    "pk": 1,
    "name": "Akifast",
    "slug": "akifast",
    "logo": "https://cdn.example.com/akifast-logo.png",
    "is_active": true
  },
  {
    "pk": 2,
    "name": "PayPal Express",
    "slug": "paypal",
    "logo": "https://cdn.example.com/paypal-logo.png",
    "is_active": true
  }
]

Get Completed Order Details

get

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.

Path parameters

order_numberstringRequired

Signed order number (time-limited signature for security).

Query parameters

formatstring · enumOptional

Response format. Use json for JSON response.

Possible values:

Responses

200

Order details

text/htmlapplication/json

stringOptional

HTML page with order confirmation.

404

Order not found or signature expired/invalid

application/json

get

/orders/checkout-provider-completed/{order_number}/

HTTPcURLJavaScriptPython

GET /orders/checkout-provider-completed/{order_number}/ HTTP/1.1
Host: sandbox.akinon.com
Accept: */*

text

Cancel Checkout Provider Flow

get

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.

Responses

302

Redirects to the basket page

get

/orders/checkout-provider-cancel/

HTTPcURLJavaScriptPython

GET /orders/checkout-provider-cancel/ HTTP/1.1
Host: sandbox.akinon.com
Accept: */*

302

Redirects to the basket page

No content