Checkout API

Ottu's Checkout API collection offers a robust suite of tools designed to streamline the payment processing experience for merchants and developers alike. This comprehensive API collection facilitates seamless payment initiation and management, ensuring efficient and secure transactions. Whether through API-based or SDK-based implementations, the Checkout APIs provide critical functionalities required for modern e-commerce environments.

• Create Payment Transaction: This API is pivotal for initiating payment transactions. It enables the creation of a payment transaction and generates a session_id, which is crucial for further transaction processing. For an in-depth understanding of this API, please refer to the Create Payment Transaction section.

• Update Payment Transaction: Essential for modifying existing payment transactions, this API uses the session_id to identify and update transactions accordingly. Detailed information is available in the Update Payment Transaction section.

• Retrieve Payment Transaction: This API is designed to fetch details of existing payment transactions using the session_id. It ensures that merchants can access transaction details as needed. Further exploration can be done in the Retrieve Payment Transaction section.

• Upload Attachment API: Allows merchants to attach files to a transaction, enhancing the flexibility and documentation capabilities of the payment processing system. For more details on how to use this API, visit the Upload Attachment section.

Quick Start

Merchants can effortlessly create payment links using the Checkout API. To experience this functionality firsthand, simply click the "Test it" button below and explore the full potential of the Checkout API.

Test it

Setup

To enhance your integration process, consider leveraging our official packages designed specifically for the Checkout API. These packages reduce the complexity of API integration by encapsulating the necessary logic, allowing you to focus on core business functionalities.

Available Packages:

• Python SDK: Facilitates access to checkout functions with a Pythonic interface, streamlining developer tasks by abstracting complex API interactions. Learn more

• Django SDK: Seamlessly integrates checkout functionalities into Django projects, equipped with Django-specific tools and utilities that simplify payment processes. Explore details

Understanding the key concepts and structures documented is vital for robust and maintainable integration of these packages, ensuring both speed and convenience.

Best Practices and Guidelines

In order to ensure optimal transaction success tracking and minimize the number of required payment transactions, merchants should create a Payment Transaction as soon as the amount is known. This typically occurs when a customer adds their first item to their cart. Following this, any changes to the total amount should be updated using the Checkout API PATCH method.

By updating the same payment transaction, rather than creating a new one for each payment attempt, merchants can more effectively trace customer interactions with their cart. This is particularly useful for events such as insufficient funds, where a customer may remove an item from their cart and successfully complete a transaction on their next attempt. Tracking and analyzing such events can help merchants make data-driven decisions for future improvements.

Permissions

Permissions are managed using Basic Authentication and API-Key. Specifically, Basic Authentication is used to grant permissions for creating, updating, and reading data, as well as using allowed PG codes when creating or updating payment transactions.

It is important to ensure that the appropriate level of permissions is assigned to each user or application using the APIs. This can help to prevent unauthorized access or modification of sensitive data. Additionally, it is recommended to rotate API-Keys on a regular basis and to use secure password storage practices when using Basic Authentication.

Ottu Checkout API supports different levels of permissions for the Payment Request and E-Commerce plugins. The permissions depend on the authentication method being used.

API Key

When using the API-Key, all permissions are granted by default, as the API-Key is considered to have admin permissions. See How to Generate API Keys

Basic Authentication

For Basic Authentication, permissions are granted as follows:

Create

• To create a transaction, the user needs specific permission depending on the plugin being used:

  • "Can add payment requests" for the Payment Request plugin
  • "Can add e-commerce payments" for the E-Commerce plugin
• Permission to use the payment gateway code is also required: "Can use pg_code"

Update

• To update a transaction, the user needs specific permission depending on the plugin being used:

  • "Can change payment requests" for the Payment Request plugin
  • "Can change e-commerce payments" for the E-Commerce plugin
• Permission to use the payment gateway code is also required: "Can use pg_code"

The PUT operation cannot be used if the user does not have permission to use the previously defined payment gateway code on the transaction. For PATCH, updates can be performed as long as the payment gateway codes are not updated.

View

• By default, if a user has either the "Can add" or "Can change" permission, they can fetch transactions from the API.
• For more granular control, the following view permissions can be used:

  • "Can view e-commerce payments" for the E-Commerce plugin
  • "Can view payment requests" for the Payment Request plugin

Thank you for exploring the Checkout API documentation. Ottu's Checkout APIs are designed to provide a robust, secure, and efficient toolset for the seamless handling of payment transactions. Whether payment transactions are being created, updated, or retrieved, the Checkout APIs are tailored to enhance operational capabilities and ensure a superior payment experience for customers.

Detailed guidance on each Checkout API, including setup instructions, request and response parameters, and practical examples, can be found in the specific sections outlined in this documentation.

Ottu is committed to supporting the integration journey every step of the way, ensuring that the benefits of the Ottu payment platform are leveraged efficiently and securely.

Create a new Payment Transaction

post

Create a new Payment Transaction

Authorizations

SSO BasicAuthbasicAuthSSO JWT AuthjwtAuth

Header parameters

AuthorizationstringRequired

Private API key to be provided in the format Api-Key <key>.

Default: Api-Key n44ZGdxa.kk4sm3CE3LEumjn8vYEGSwBP10xdY8Rl

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

Serializer to work with PaymentTransaction instances.

Also uses request data from other serializers to save into PaymentTransaction db table:

agreementall ofOptional

An established contractual arrangement with the payer, which authorizes you to securely store and subsequently utilize their payment information for specific purposes. This could encompass arrangements like recurring payments for services such as mobile subscriptions, installment-based payments for purchases, arrangements for ad-hoc charges like account top-ups, or for standard industry practices like penalty charges for missed appointments.

Note: If your intention is solely to store payment details for transactions initiated by the payer in the future, then this parameter group should not be used.

amountstring · decimalRequired

Represents the total amount of the payment transaction, which includes the cost of the purchased items or services but excludes any additional fees or charges

attachmentstring · uriOptional

A writable field that accepts an attachment file to be included in email notifications sent to the customer regarding their payment, and also be available for download on the checkout page. This field may be used to provide the customer with additional information or documentation related to their purchase. The value of this field should be a file object. Upon successful submission, the API will return the URL for downloading the attached file.

attachment_short_urlstring · uriRead-onlyRequired

A short URL that links to the attachment associated with this payment. This URL may be included in email/sms notifications sent to the customer regarding their payment or displayed on the checkout page to allow the customer to easily access the attachment.

attachment_upload_urlstringOptional

A writable field that accepts an attachment that has already been uploaded to the server.

Pattern: (?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$

card_acceptance_criteriaall ofOptional

This field allows you to define specific rules and conditions that a card must meet to be eligible for payment. These stipulations apply regardless of whether a customer chooses to pay using a saved card or opts to add a new card for the transaction. By leveraging the card_acceptance_criteria, you gain the power to fine-tune your payment processing strategy, tailoring acceptance rules to align with your business needs, security standards, and risk management policies.

Example: If you run an exclusive service that caters predominantly to premium customers, you might set criteria that only allow transactions from high-tier credit cards like VISA Platinum. This ensures that payments align with the exclusivity and branding of your services. Remember to configure these criteria thoughtfully. Striking the right balance between security, risk mitigation, and user experience is paramount.

Note: The card_acceptance_criteria field is applicable only for direct payments and not for hosted session payments.

checkout_short_urlstring · uriRead-onlyRequired

A short URL link that, when opened, redirects to the checkout page for this payment. This URL may be shared with the customer to allow them to easily access and complete the payment. This field is only available if the shortify_checkout_url field is set to True.

checkout_urlstring · uriRead-onlyRequired

URL that directs the customer to the Ottu Checkout Page where they can see the payment details and available payment methods for the transaction. If you need to share the payment link over SMS or WhatsApp, use checkout_short_url instead.

currency_codestringRequired

The specified currency represents the denomination of the transaction.Nevertheless, it doesn't necessarily mandate payment in this exact currency.Due to potential currency conversions or exchanges, the final charge may be in a different currency.

customer_birthdatestring · dateOptional

Customer's date of birth in YYYY-MM-DD format.This field can be used for age verification or compliance purposes during payment processing.

customer_emailstring · email · max: 128Optional

The email address of the customer that is used to send payment notifications and receipts, and can be used for fraud prevention. This field is mandatory and is always sent to the payment gateway. It may also be included in the invoice, receipt, email, and displayed on the payment page.

customer_first_namestring · max: 64Optional

The first name of the recipient of the payment. This field is used for various communications such as the invoice, receipt, email, SMS, or displayed on the payment page. It may also be sent to the payment gateway if necessary.

customer_idstring · max: 64Optional

The customer ID is a unique identifier for the customer within the merchant's system. It is also used as a merchant identifier for the customer and plays a critical role in tokenization. All the customer's cards will be associated with this ID.

customer_last_namestring · max: 64Optional

The last name of the recipient of the payment. This field is used for various communications such as the invoice, receipt, email, SMS, or displayed on the payment page. It may also be sent to the payment gateway if necessary.

customer_phonestring · max: 16Optional

Customer phone number associated with the payment. This might be sent to the payment gateway and depending on the gateway, it may trigger a click to pay process on the payment page. The phone number will also be included in the invoice, receipt, email, and displayed on the payment page.

customer_phone_2string · max: 16Optional

The customer's additional phone number, if any. This field can be updated by the customer on the payment page or in the Checkout SDK.

due_datetimestring · date-timeOptional

The date and time by which the payment is due. This field may be used to help remind the customer to complete the payment before the due date.

email_recipientsstring · email[]Optional

A comma-separated list of email addresses for internal recipients who will receive customer emails. These recipients will be included in email notifications sent to the customer regarding their payment.

expiration_timestringOptional

If defined, any payment transactions created more than the specified period of time ago will be invalidated or expired if the customer attempts to complete them. By default, this expiration period is set to 24 hours from the time of transaction creation. This feature helps ensure that payment transactions are processed promptly.

extraall ofOptional

The extra information for the payment details, which the merchant has sent it in key value form.

generate_qr_codebooleanWrite-onlyOptional

If set to true, the qr_code_url field will be present in the response. Upon scanning it, the customer will be redirected to the checkout_url, which is the Ottu Checkout page.

Default: false

include_sdk_setup_preloadbooleanWrite-onlyOptional

Set this to true to include the 'sdk_setup_preload_payload' payload in the API response. This payload is only generated and added when this parameter is explicitly set to true. By default, it is false and the 'sdk_setup_preload_payload' payload will not be included.

Default: false

initiator_idintegerOptional

The user who initiated the creation of this payment transaction, if available. This field is optional and may be used to track who created the payment transaction. Note that if the payment transaction was using API Key auth initiator_id can be set to any value that corresponds to an existing ACTIVE user in the system

languagestring · enumOptional

This field specifies the language to be used for communication with the customer, including the payment page, receipt, invoice, email, SMS, and any other communications related to the payment transaction.

• en - English
• ar - Arabic

Default: enPossible values:

notificationsall ofOptional

A JSON field that contains the notification settings for this payment transaction, including SMS and email notifications, as well as the events for which they will be sent (e.g., 'created', 'paid', 'refund', 'canceled', etc.). This field may be used to configure and customize the notifications sent to customers and internal recipients throughout the payment process.

operationstringRead-onlyRequired

Specifies the type of operation to be performed by the payment gateway. If set to purchase, the payment source will be directly charged. If set to authorize, the payment source will only be authorized and the actual charge will be made at a later time.

order_nostring · max: 128Optional

The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system.

payment_methodsall ofRead-onlyRequired

An array containing all the payment methods derived from the pg_codes input. Each object in the array contains information about a single payment gateway, including its icon and the redirect_url that will redirect the customer to the payment gateway's payment page.

payment_typestring · enumOptional

Type of payment. Choose one_off for payments that occur only once without future commitments. Choose auto_debit for payments that are automatically deducted, such as recurring subscriptions, installments, or unscheduled auto-debits.

Choose save_card if you want to perform a card tokenization operation.

NOTE: If auto_debit is selected:

1. agreement and customer_id parameters will also be mandatory.
2. Only PG codes supporting tokenization can be selected. As a side effect, the card used for the payment will be associated with the supplied agreement.id. This card will be locked, preventing the customer from deleting it from the system until an alternate card is chosen for auto-debit payments.

NOTE: If save_card is selected:

1. The amount must be zero for the save card operation.
2. The selected MID(pg_code) must support tokenization to enable the save card operation.
3. Please note that the save card operation is considered successful without any funds being charged.
4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL.

• one_off - One Off
• auto_debit - Auto Debit
• save_card - Save Card

Default: one_offPossible values:

pg_codesstring[]Required

The list of payment gateway codes from which a customer can select to perform the payment or authorization.

product_typestring · max: 128Optional

The type of product or service being purchased. This field may be used for tracking and reporting purposes.

qr_code_urlstring · uriRead-onlyRequired

A QR code that, when scanned, redirects to the checkout page for this payment. This QR code may be displayed on invoices, receipts, or other documents to allow customers to easily access the checkout page and make a payment. This parameter is only present when generate_qr_code is set to true.

redirect_urlstring · uri · max: 2000Optional

The URL where the customer will be redirected after the payment stage only if the webhook URL returns a success status. order_no, reference_number and session_id will be appended to the redirect URL as query parameters.

sdk_setup_preload_payloadall ofRead-onlyRequired

A JSON object containing preloaded data required to initialize the checkout interface.This includes essential details such as customer information, available payment methods.and specific transaction details, all formatted according to the Checkout SDK's initialization specifications.This field streamlines the checkout process by providing necessary information upfront.enhancing user experience and efficiency.

Default: false

session_idstringRead-onlyRequired

A unique identifier for each payment transaction, used to maintain the session state during the payment process.

settled_pg_codestringRead-onlyRequired

The code of the payment gateway used for completing the transaction. This field indicates the specific gateway that processed and settled the payment, providing clarity on which payment service was ultimately utilized for this transaction.

shortify_attachment_urlbooleanWrite-onlyOptional

If set to True, the URL of the uploaded attachment will be shortened using a URL shortener service. This should be used when sharing the attachment URL via SMS or WhatsApp.

Default: false

shortify_checkout_urlbooleanWrite-onlyOptional

If set to True, the checkout URL will be shortened using a URL shortener service. This should be used when sharing the payment URL via SMS or WhatsApp.

Default: false

statestring · enumRead-onlyRequired

The current state of the payment transaction, it helps to understand the progress of the payment.

• created - Created
• pending - Pending
• attempted - Attempted
• authorized - Authorized
• paid - Paid
• failed - Failed
• canceled - Canceled
• expired - Expired
• invalided - Invalided
• refunded - Refunded
• cod - Cash on Delivery

Possible values:

typestring · enumRequired

The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices.

• e_commerce - Ecommerce
• payment_request - Payment Request

Possible values:

unit_codestringWrite-onlyOptional

The slug of the unit to be used for the transaction.

vendor_namestring · max: 64Optional

The name of the vendor or merchant associated with this payment. This field may be used for accounting and reporting purposes.

webhook_urlstring · uri · max: 2000Optional

URL where the payment result will be sent via a POST request after the customer has completed the payment session. The payment result will be included in the request body.

Responses

201Success

application/json

400Error

application/json

401Error

application/json

403Error

application/json

404Error

application/json

415Error

application/json

423Error

application/json

post

HTTPcURLJavaScriptPython

POST /b/checkout/v1/pymt-txn/ HTTP/1.1
Host: 
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 1623

{
  "agreement": {
    "amount_variability": "fixed",
    "cycle_interval_days": 1,
    "expiry_date": "2025-05-06",
    "extra_params": {
      "payment_processing_day": 1
    },
    "frequency": "irregular",
    "id": "text",
    "max_amount_per_cycle": "text",
    "seller": {
      "category_code": "text",
      "name": "text",
      "short_name": "text"
    },
    "start_date": "2025-05-06",
    "total_cycles": 1,
    "type": "event_based"
  },
  "amount": "text",
  "attachment": "https://example.com",
  "attachment_upload_url": "text",
  "billing_address": {
    "city": "text",
    "country": "AW",
    "line1": "text",
    "line2": "text",
    "postal_code": "text",
    "state": "text"
  },
  "card_acceptance_criteria": {
    "min_expiry_time": 1
  },
  "currency_code": "text",
  "customer_birthdate": "2025-05-06",
  "customer_email": "[e-mail]",
  "customer_first_name": "text",
  "customer_id": "text",
  "customer_last_name": "text",
  "customer_phone": "text",
  "customer_phone_2": "text",
  "due_datetime": "2025-05-06T03:14:17.281Z",
  "email_recipients": [
    "[e-mail]"
  ],
  "expiration_time": "text",
  "extra": {
    "payment_category_amount": "text",
    "payment_category_name": "text"
  },
  "generate_qr_code": true,
  "include_sdk_setup_preload": true,
  "initiator_id": 1,
  "language": "en",
  "notifications": {
    "email": [
      "created"
    ],
    "sms": [
      "created"
    ],
    "whatsapp": [
      "created"
    ]
  },
  "order_no": "text",
  "payment_type": "one_off",
  "pg_codes": [
    "text"
  ],
  "product_type": "text",
  "redirect_url": "https://example.com",
  "shipping_address": {
    "city": "text",
    "country": "AW",
    "email": "[e-mail]",
    "first_name": "text",
    "last_name": "text",
    "line1": "text",
    "line2": "text",
    "phone": "text",
    "postal_code": "text",
    "state": "text"
  },
  "shortify_attachment_url": true,
  "shortify_checkout_url": true,
  "type": "e_commerce",
  "unit_code": "text",
  "vendor_name": "text",
  "webhook_url": "https://example.com"
}

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

{
  "agreement": {
    "amount_variability": "fixed",
    "cycle_interval_days": 1,
    "expiry_date": "2025-05-06",
    "extra_params": {
      "payment_processing_day": 1
    },
    "frequency": "irregular",
    "id": "text",
    "max_amount_per_cycle": "text",
    "seller": {
      "category_code": "text",
      "name": "text",
      "short_name": "text"
    },
    "start_date": "2025-05-06",
    "total_cycles": 1,
    "type": "event_based"
  },
  "amount": "text",
  "attachment": "https://example.com",
  "attachment_short_url": "https://example.com",
  "attachment_upload_url": "text",
  "billing_address": {
    "city": "text",
    "country": "AW",
    "line1": "text",
    "line2": "text",
    "postal_code": "text",
    "state": "text"
  },
  "card_acceptance_criteria": {
    "min_expiry_time": 1
  },
  "checkout_short_url": "https://example.com",
  "checkout_url": "https://example.com",
  "currency_code": "text",
  "customer_birthdate": "2025-05-06",
  "customer_email": "[e-mail]",
  "customer_first_name": "text",
  "customer_id": "text",
  "customer_last_name": "text",
  "customer_phone": "text",
  "customer_phone_2": "text",
  "due_datetime": "2025-05-06T03:14:17.281Z",
  "email_recipients": [
    "[e-mail]"
  ],
  "expiration_time": "text",
  "extra": {
    "payment_category_amount": "text",
    "payment_category_name": "text"
  },
  "initiator_id": 1,
  "language": "en",
  "notifications": {
    "email": [
      "created"
    ],
    "sms": [
      "created"
    ],
    "whatsapp": [
      "created"
    ]
  },
  "operation": "text",
  "order_no": "text",
  "payment_methods": {
    "amount": "text",
    "code": "text",
    "currency_code": "text",
    "fee": "text",
    "fee_description": "text",
    "flow": "text",
    "icon": "https://example.com",
    "name": "text",
    "pg": "text",
    "redirect_url": "https://example.com",
    "type": "e_commerce"
  },
  "payment_type": "one_off",
  "pg_codes": [
    "text"
  ],
  "product_type": "text",
  "qr_code_url": "https://example.com",
  "redirect_url": "https://example.com",
  "sdk_setup_preload_payload": {
    "amount": "text",
    "cancel_url": "text",
    "cards": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "currency_code": "text",
    "customer_id": "text",
    "customer_phone": "text",
    "flex_methods": [],
    "is_amount_editable": true,
    "language": "en",
    "operation": "text",
    "payment_methods": [],
    "payment_services": [],
    "payment_type": "one_off",
    "response": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "session_id": "text",
    "state": "created",
    "type": "e_commerce"
  },
  "session_id": "text",
  "settled_pg_code": "text",
  "shipping_address": {
    "city": "text",
    "country": "AW",
    "email": "[e-mail]",
    "first_name": "text",
    "last_name": "text",
    "line1": "text",
    "line2": "text",
    "phone": "text",
    "postal_code": "text",
    "state": "text"
  },
  "state": "created",
  "type": "e_commerce",
  "vendor_name": "text",
  "webhook_url": "https://example.com"
}

FAQ

1️ What is the Ottu Checkout API used for?

The Checkout API is used to create and manage payment transactions. It enables merchants to generate a payment session (session_id), redirect users to a payment gateway, and receive payment updates via webhooks.

2️How do I create a payment transaction?

To create a payment transaction, send a POST request to the Checkout API with the required parameters:

• amount – Payment amount

• currency_code – Transaction currency

• pg_codes – Payment gateways allowed

• type - e_commerce or payment_request

After submission, the API returns a session_id, which is required for processing the transaction.

3️ How can I ensure that the payer cannot make a payment after a certain amount of time since redirection?

To prevent a payer from completing a payment after a specific period, you need to configure the expiration_time parameter based on the payment gateway (PG) auto inquiry time. This ensures that even if the user remains on the payment page, they won’t be able to proceed once the expiration time has passed.

The expiration time should be set as:

expiration_time = auto inquiry time + max{PG auto inquiry time}

• Auto inquiry time:

  This is the time Ottu waits before automatically checking the transaction status with the payment gateway. for more information, please refer here.
• PG auto inquiry time:

  This is the maximum duration the payment gateway allows before timing out a payment session. More information about PG auto inquiry time is accessible here.

Example Calculation:

• For MPGS (Mastercard Payment Gateway Services), the PG auto inquiry time is 11 minutes.
• For KNET, the PG auto inquiry time is 8 minutes.

If your system sets an auto inquiry time of 5 minutes, then:

• For MPGS: expiration_time = 5 + 11 = 16 minutes
• For KNET: expiration_time = 5 + 8 = 13 minutes

This means that after 16 minutes (for MPGS) or 13 minutes (for KNET), the payer will not be able to complete the transaction, even if they are still on the payment page.

4️ Can I update an existing transaction?

Yes! You can update a transaction before it is completed by sending a PUT request to the Checkout API, referencing the session_id. Updates might include modifying the amount, currency_code, or allowed pg_codes.

5️ What happens if a customer abandons the payment?

If a customer does not complete the payment, the transaction remains in a pending state until it expires. Ottu's automatic inquiry will check the status based on the configured timing and update the state accordingly.

6️ How do I get notified when a payment is completed?

Ottu sends a payment notification webhook to the webhook_url you provided in the API request. The webhook contains details like:

• status: success, failed, pending

• amount and currency_code

• pg_response: Response from the payment gateway

Ensure your server verifies and processes these webhook notifications.

7️ What is the difference between webhook_url and redirect_url?

• webhook_url – The API sends real-time payment updates it (for backend processing).

• redirect_url – After payment, the customer is sent to it (for UI redirection).

For more details on redirection behavior related to webhook_url, please refer to this section.

Both are optional but recommended for a seamless experience.

8️ Can I retry a failed payment?

Yes, if a transaction fails, you can reuse the same session_id. the payment state will be attempt. for more information about , please refer here.

9️ Can I set up recurring payments using the Checkout API?

Yes! Use Auto-Debit with a payment_type set to auto_debit to create agreements for recurring transactions. Learn more in the Auto-Debit.

1️0️ How do I integrate the Checkout API with the SDK?

The Checkout SDK (Web, Android, iOS) requires a session_id from the Checkout API. Your backend should:

1. Call the Checkout API to create a transaction.
2. Pass the session_id to the SDK for UI rendering.

3. Handle webhooks for transaction updates.