The smarter way
  • Getting Started
  • USER GUIDE
    • Payment Gateway
    • Currencies
    • Apple Pay
      • Setup MPGS
      • Setup Cybersource
    • Payment Tracking
      • Payment Transactions Insights
      • Payment Transactions States
      • Notifications, URLs & Timing
    • Plugins
      • Payment Request
      • E-Commerce
      • Bulk payment request
    • Features
      • Refund & Void Access Control
      • Two-Step Refund & Void Authorization
    • Integration
    • Configuration
      • Global Configuration
      • Webhooks Configuration
      • Transaction Report Configuration
      • How to Get API Keys
      • URL Shortener Configuration
    • Notification Communication Channels
      • Email Notifications
      • SMS Notifications
      • WhatsApp Notifications
        • Integrated WhatsApp Channel
        • Manual WhatsApp Channel
      • Notification Templates
      • Notification Process: Automatic and Manual
    • Satellite
    • Real Estate
      • Regular Activities
        • Property management
        • Tenant and Contract Management
          • Tenant & Contract Dashboard
          • Tenant Management
          • Contract Management
            • Add New Contract
            • Contract Action
              • Renew Contract
              • Terminate Contract
              • Manual Payment
              • Suspend Contract
              • Resume Contract
              • Advance Payment
        • Generate Invoice
        • Invoices Management
        • Maintenance
        • Transactions
        • Auditing and Rolling Back Activities
      • Merchant First Journey
  • developer
    • Getting Started
    • Tokenization
    • Authentication
    • Payment Methods
    • Checkout API
    • Operations
    • User Cards
    • Payment Status-Inquiry
    • Auto-Debit
    • Invoice API
    • Message Notifications
    • Upload Attachment
    • Checkout SDK
      • Web
      • iOS
      • Android
      • Flutter
    • Webhooks
      • Payment Notification
      • Operation Notification
      • Signing Mechanism
      • Integration Guides
        • Laravel Webhook Receiver Guide
        • .NET Webhook Receiver Guide
    • Test Cards
Powered by GitBook
On this page
  1. developer

Checkout API

PreviousPayment MethodsNextOperations

Last updated 11 days ago

Ottu provides a comprehensive collection of APIs that offer a seamless and efficient way to test payments and enable merchants to accept and process transactions instantly. The Checkout API is the cornerstone of any payment initiation, whether it's or .

In order to ensure optimal transaction success tracking and minimize the number of required payment transactions, merchants should 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 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 are managed using and . Specifically, Basic Authentication is used to grant permissions for creating, updating, and reading data, as well as using allowed when or 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 method being used.

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

For , permissions are granted as follows:

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

    • "Can add payment requests" for the plugin

    • "Can add e-commerce payments" for the plugin

  • Permission to use the payment gateway is also required: "Can use pg_code"

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

  • For more granular control, the following view permissions can be used:

The objective of the POST request is to facilitate the creation of payment transactions and the subsequent generation of payment links, each of which is associated with a unique session ID. These links can be effortlessly shared with customers through a range of communication channels, including email, WhatsApp, and SMS. Additionally, it is possible to incorporate the customer's billing and shipping information into the transaction. Moreover, users of this API have the ability to include diverse forms of data and information within the body request.

agreement object details

It serves as a unique identifier for the agreement established with the payer. It is integral to link to the specific terms and conditions authorized by the payer for processing their stored card details. The Agreement ID plays a crucial role as an identifier for correlated payments associated with a customer order or invoice, highlighting the need for it to vary based on the correlated payments.

It defines if the payment amount can vary with each transaction within the agreement. Enum: fixed, variable

The date on which the agreement with the payer to process payments begins.

The final date until which the agreement remains valid.

The agreed-upon maximum amount for an individual payment within the series.

The number of days between each recurring payment

The total number of payment cycles within the agreement duration.

This pertains to the frequency of payments within the series as agreed upon with the payer. Such as: irregular, daily, ⁣weekly, monthly, quarterly, semi_annually, yearly, and other. When type set as unscheduled, frequency should set as irregular.

The type of commercial agreement that the payer has with the merchant, which can fall into categories such as:

  • recurring (Default value)

  • unscheduled

  • other

  • event_based

  • installment

It details about the retailer, if the agreement is for installment payments. seller child object:

  • category_code string A 4-digit code classifying the retailer's business by the type of goods or services it offers.

  • short_name string Abbreviation of the retailer's trading name, suitable for payer's statement display.

  • names string The retailer's trading name.

Additional parameters related to the agreement. extra_params child object:

  • payment_processing_day int Day of the month on which the payment must be processed. Not required for unscheduled payment agreements. The retailer's trading name.

It is imperative for the merchant to strictly avoid including these parameters when the payment type is labeled as "one-off" The agreement parameter should be sent exclusively when the payment type is designated as "auto-debit".

Attachments can be included as an optional feature in email notifications sent to the customer regarding their payment. These attachments will also be available for download on the checkout page. The primary purpose of this field is to provide the customer with additional information or documentation related to their purchase. However, it's important to note the following:

  • Allowed file extensions for attachments include: PDF, JPEG, PNG, DOC, DOCX, JPG, XLS, XLSX, and TXT.

  • The name of the attached file should not exceed 100 characters.

An object to save customer registered address data into payment transaction.

billing_address object details

One of the billing address parameters and should be filled by street & house data. Max length: 128.

The city where the customer is living and registered. Max length: 40.

Postal code (maybe has different length for different countries). Max length: 12.

This field allows the merchant 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, merchant gains the power to fine-tune his payment processing strategy, tailoring acceptance rules to align with his business needs, security standards, and risk management policies.

Example: If merchant runs an exclusive service that caters predominantly to premium customers, he 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 his services. Merchant should configure these criteria thoughtfully. Striking the right balance between security, risk mitigation, and user experience is paramount.

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

card_acceptance_criteria object details

Specifies the minimum required validity period, in days, for a card to be eligible for payment. If set to 30 days, for example, cards set to expire within the next month would be declined. This ensures short-lived cards nearing their expiration date are filtered out, reducing chances of payment failures. When implementing, balance merchant's operational needs with customer convenience. Setting it too stringent might increase payment declines, while a lenient approach could risk future payment failures.

Additionally, it defaults to 30 days when the payment_type is auto_debit. If any other payment type is selected, no default value is set.

string datetime optional

Specifies the customer's date of birth. This field can be used for various purposes such as identity verification, eligibility checks, or customer profiling. The value must be provided in the YYYY-MM-DD format.

This field specifies the customer's email address and is used to send payment notifications and receipts. Additionally, it is used for fraud prevention and is transmitted to the payment gateway. The email address may also be included on invoices, receipts, and displayed on the payment page. It must be a valid email address. Max length 128

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. Max length 64.

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. Max length: 64.

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. Max length 64.

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. Max length 16.

It becomes a required parameter:

  • If the merchant wants to enable KFAST on KNET. KFAST is a tokenization feature on KPay page, which works with UDF3 mapped with customer_phone.

Otherwise, it remains optional parameter.

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 The default value is UTC. Should be in format (DD/MM/YYYY hh:mm)

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.

If defined, any payment transactions created more than the defined period of time ago will be invalidated or expired if the customer tries to pay them. This field may be used to help ensure that payment transactions are processed in a timely manner. By default, this expiration period is set to 24 hours from the time of transaction creation. Should be In format (DD HH:MM:SS).

In order to automatically change the state to expired, Expire Payment Transactions? Field should be enabled.

From Ottu dashboard > administration panel > config > configuration page, then enable field Expire Payment Transactions? Otherwise, the transaction will be marked as expired when the customer attempts to pay past the expiration time.

An object for extra data aka dynamic fields. Extra data can accept any value by default. However, if the merchant wants to enforce a specific type, they can use the plugins.Field class to do so. All CUSTOM fields are validated inside extra field.

By default, the parameter is set to false, and the sdk_setup_preload_payload is not included in the API response.

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. Available choices: en, ar. Default language is en. Max length: 2.

An object 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.

notifications object details

Will be triggered at the following notification events: [ created, paid, canceled, failed, expired, authorized, voided, refunded, captured]

  • If the payment transaction transitions to an error state and an email notification has been set up for the failed state, then the customer will receive an email.

Will be triggered at the following notification events: [ created, paid, canceled, failed, expired, authorized, voided, refunded, captured]

  • If the payment transaction transitions to an error state and an SMS notification has been set up for the failed state, then the customer will receive an SMS.

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

Enum: one_off, auto_debit, or save_card

  • one_off : For payments that occur only once without future commitments.

If auto_debit is selected:

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

An object to save address data into payment transaction

shipping_address object details

Location details where the shipment should be delivered to. Should be filled by street & house data. Max length 128.

The city where the shipment should be delivered to. Max length 40.

Postal code (maybe has different length for different countries). Max length: 12.

Shipment recipient first name. Max length: 64.

Shipment recipient last name. Max length: 64.

Shipment recipient email address. Max length: 128.

Shipment recipient phone number. Max length: 16.

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

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

These parameters will be returned for all the response status.

Presence condition:

Presence condition:

A short attachment retrieval URL. Max length: 200.

Presence condition:

Presence condition:

Presence condition:

Presence condition:

string datetime optional

Presence condition:

Presence condition:

Presence condition:

Presence condition:

Presence condition:

Presence condition:

Presence condition:

Presence condition:

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 Max length: 11.

Presence condition:

Presence condition:

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 Max length: 16.

Presence condition:

payment_methods object details

Code of the Gateway Settings instance

Name of the Gateway Settings instance.

Name of the gateway, settings are applied to.

It is environment used for this PG settings or not.

URL to default icon of the current gateway.

Choice from (“redirect”, ...).

Presence condition:

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.

Presence condition:

Presence condition:

It must be passed to the Checkout SDK constructor without any modifications.

Presence Conditions:

A unique identifier for each payment transaction, used to maintain the session state during the payment process. It can be used to perform subsequent operations, like retrieve, acknowledge, refund, capture, and cancellation. Max length: 128.

Presence condition:

A field in the response that contains the URL of an attachment that has already been uploaded to the server.

Presence condition:

Presence condition:

Presence condition:

{
    "type": "payment_request",
    "pg_codes": ["pg_codes"],
    "amount": "14",
    "currency_code": "KWD",
    "customer_email":"example@example.com",
    "customer_phone":"customer phone",
    "notifications": {
    "email": ["created", "paid", "canceled", "failed", "expired", "authorized", "voided", "refunded", "captured"],
    "sms": ["created", "paid", "canceled", "failed", "expired", "authorized", "voided", "refunded", "captured"]
        }
}
{
    "amount": "14.000",
    "checkout_url": "https://<ottu-url>/b/checkout/redirect/start/?session_id=5ca114666d472a170d3c4ea6cadbf347679b2532",
    "currency_code": "KWD",
    "customer_email": "example@example.com",
    "customer_phone": "customer phone",
    "due_datetime": "15/01/2023 11:04:55",
    "expiration_time": "1 00:00:00",
    "language": "en",
    "notifications": {
        "email": [
            "authorized",
            "created",
            "canceled",
            "expired",
            "failed",
            "captured",
            "paid",
            "voided",
            "refunded"
        ],
        "sms": [
            "authorized",
            "created",
            "canceled",
            "expired",
            "failed",
            "captured",
            "paid",
            "voided",
            "refunded"
        ]
    },
    "operation": "authorize",
    "payment_methods": [
        {
            "code": "pg_codes",
            "name": "ottu PG",
            "pg": "Ottu PG",
            "type": "sandbox",
            "amount": "14.000",
            "currency_code": "KWD",
            "fee": "0.000",
            "fee_description": "fix fee",
            "icon": "https://<ottu-url>/static/images/pg_icons/master_visa_mada.png",
            "flow": "redirect",
            "redirect_url": "https://<ottu-url>/checkout/5ca114666d472a170d3c4ea6cadbf347?chd-only=True"
        }
    ],
    "pg_codes": [
        "pg_codes"
    ],
    "session_id": "5ca114666d472a170d3c4ea6cadbf347",
    "state": "created",
    "type": "payment_request"
}

Update Payment

PATCH https://<ottu-url>/b/checkout/v1/pymt-txn/{session_id}

Headers

Name
Type
Description

Authorization*

API key

Api-Key {{api_key}}

Using a patch function is a good method of increasing trustability whenever any change gets made to the payment transaction, such as updating the amount on the card or removing items from the cart.

Retrieve Payment

GET https://<ottu-url>/b/checkout/v1/pymt-txn/{session_id}

To get the information of the payment transaction.

Authentication: This endpoint is public

  • amount – Payment amount

  • currency_code – Transaction currency

  • pg_codes – Payment gateways allowed

  • type - e_commerce or payment_request

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:

  • Auto inquiry time:

  • PG auto inquiry time:

Example Calculation:

  • For KNET, the PG auto inquiry time is 8 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.

  • status: success, failed, pending

  • amount and currency_code

  • pg_response: Response from the payment gateway

Ensure your server verifies and processes these webhook notifications.

  • 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).

Both are optional but recommended for a seamless experience.

  1. Pass the session_id to the SDK for UI rendering.

"Can change payment requests" for the plugin

"Can change e-commerce payments" for the plugin

Permission to use the payment gateway 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 on the transaction. For , updates can be performed as long as the payment gateway codes are not updated.

By default, if a user has either the "Can add" or "Can change" permission, they can transactions from the API.

"Can view e-commerce payments" for the plugin

"Can view payment requests" for the plugin

object optional

An established contractual arrangement with the payer, which authorizes the merchant 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. For more information please refer .

string optional

string optional

date optional

date optional

string optional

integer optional

integer optional

string optional

string optional

object optional

object optional

string required

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. The number of decimals must correlate with the . Max length: 24 Min value: 0.01

file optional

Attachments should be sent using the encoding type. Ensure that you change the content type to multipart/form-data when sending attachments. They cannot be sent using encoding.

object optional

string required

string optional

For accuracy purpose, Additional address data for the . Max length: 128.

string required

string optional

State of the customer’s city (sometimes the same as the ). Max length: 40.

string required

Customer’s country, . Will be validated against existing countries. Max length: 2.

string optional

object optional

string optional

string required

The currency in which the transaction is denominated. However, it does not guarantee that the payment must be made in this currency, as there can be currency conversions or resulting in a different currency being charged. See . 3 letters code.

string conditional

If Email are applied, the parameter must be included, making customer_email parameterrequired. else will be optional.

string optional

string optional

string optional

string conditional

If SMS are enabled, the parameter must be included, making the customer_phone parameter required.

string datetime optional

array of strings optional

string optional

If the for a payment has passed, the payment state will be changed and cannot be paid. However, if the payment has passed, the payment can still be paid, but the customer may incur fees or penalties. The state of the payment may not change in this case, but the customer's account may be impacted by the late payment.

object optional

bool optional

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

bool optional

When set to true, the Checkout API will include the in its response. This payload facilitates immediate UI setup without the need for further API calls.

string optional

object optional

list optional

list optional

string optional

array required

The list of payment gateway codes from which a customer can select to perform the payment or authorization. Customer uses only one PG code. For: User can use the PG code that has permission to access to. For : User can use all the PG code.

string optional

save_card : To indicates that the transaction is for the purpose of saving the card information. For additional information, please refer to the document.

auto_debit : For payments that are automatically deducted, such as recurring subscriptions, installments, or unscheduled auto-debits. for more information about auto-debit API, please refer to .

and parameters will also be mandatory.

Only PG codes supporting 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.

string optional

string optional

It is the destination where customers are redirected after the payment stage, only if the webhook_url returns a success status. Query parameters, including , , , and any parameters, will be added to the redirect_url. For more information on how redirection works, please check .

object optional

string required

string optional

For accuracy purpose, Additional address data for the . Max length 128.

string required

string optional

The city where the shipment should be delivered to. (sometimes the same as the ). Max length 40.

string required

Destination country, . Will be validated against existing countries. Max length: 2.

string optional

string required

string required

string required

string required

bool optional

If true, it generates short attachment retrieval URL, which could be embedded in either SMS, Email, or WhatsApp messages, as it uses fewer characters. If an external URL shortening service, such as , is , the will be shorter than attachment response parameter. if not configured, the attachment_short_url will be in the same format with response parameter. Default value is false.

bool optional

If true, it generates short checkout retrieval URL, which could be embedded in either SMS, Email, or WhatsApp messages, as it uses fewer characters. If an external URL shortening service, such as , is , the will be shorter than parameter. If not configured, the checkout_short_url will be in the format of "https://<ottu-url>>/b/abc123". Default value is false.

string required

The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices. Available choices: , . Max length: 24.

string optional

string optional

string optional

In case of a payment event or payment operation, Ottu triggers an HTTP request to this URL, to disclose transactional data. It should be provided by merchant. See Webhook .

object conditional

It denotes a pre-arranged contractual agreement with the paying customer, enabling the secure retention and future use of their payment details for specific purposes. These agreements encompass various payment arrangements, including recurring service payments like mobile subscriptions, installment payments for purchases, one-time charges such as account reloads, or compliance with industry practices like penalty fees for missed appointments. See the request parameter for more information.

This parameter should be included when the is set to auto_debit On the other hand, it must not be sent when the is designated as one_off Importantly, this isn't restricted to just the initial transaction but should be consistently present in all following transactions associated with the "auto_debit" payment type.

In certain agreement types, the condition state becomes a required element. For further details on which parameters are mandatory for recurring agreements, please refer .

string mandatory

Payment transaction total amount. The merchant should always check if the amount he receives from Ottu is the same amount of the order, to avoid user changing the cart amount in between. See the request parameter for more information.

string conditional

Attachment retrieval URL. See the request parameter for more information.

The attachment should be uploaded using request parameter.

string conditional

request parameter should be "true" in order to generate it.

object conditional

Customer’s registered address data. See the request parameter for more information.

Any child parameter provided with the object in the request payload will be populated in the response as child parameter.

object conditional

It outlines the rules for a card's payment eligibility See the request parameter for more information.

Any child parameter provided with the object in the request payload will be populated in the response as child parameter.

string conditional

Short

request parameter should be set to "true" in order to generate it.

string mandatory

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 instead.

string mandatory

The code of the currency used in the transaction. See the request parameter for more information.

Customer's date of birth. For more information, please refer to .

request parameter should be provided.

string conditional

Customer’s email address. See the request parameter for more information.

request parameter should be provided.

string conditional

Customer’s first name. See the request parameter for more information.

request parameter should be provided.

string conditional

It is a unique identifier assigned to a customer. This identifier can be used to distinguish one customer from another and can be utilized for tracking purposes or to retrieve specific customer information from the API. See the request parameter for more information.

request parameter should be provided.

string conditional

Customer’s last name. See the request parameter for more information.

request parameter should be provided.

string conditional

Customer's phone number. See the request parameter for more information.

request parameter should be provided.

string date-time mandatory

It specifies the deadline for payment. It has no effect on changing the transaction state, and the transaction can be paid even after due_datetime. See the request parameter for more information.

array of strings conditional

This is a list of internal email recipients, who will receive notifications sent to the customer about their payment. See the request parameter for more information.

should be provided in the request payload.

string mandatory

It refers to the specific point in time after which the transaction cannot be paid anymore, and its state changes accordingly. See the request parameter for more information.

object conditional

It represents additional data fields that can be dynamically added to the response using the extra request parameter. See the request parameter for more information.

Any child parameter provided with the object in the request payload will be populated in the response as object child parameter.

integer(initiator) conditional

It is present only when is used, because Authentication is not associated with any user.

string mandatory

It represents the language code that is utilized for all communication related to payment transactions with the customer, including payment page, receipt, invoice, email, and SMS For more details check the request parameter

object conditional

It represents the notification settings for this payment transaction which have been received and processed. See the request for more information.

Any child parameter provided with the object in the request payload will be populated in the response as child parameter.

string mandatory

string conditional

It is a unique identifier assigned to the payment transaction, which is primarily used for tracking purposes. The identifier can be set by the merchant or the system. See the request parameter for information.

request parameter should be included in the request payload.

array [object] mandatory

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

string

string

string

bool

string

string

string

This URL redirects to the payment page.See

array mandatory

The options of the payment gateway codes included in the request payload to enable customers to make payments. See the request parameter for more information.

string mandatory

It presents options such as one_off for one-time payments without future obligations and auto_debit for automated deductions, encompassing recurring subscriptions, installment payments, or unscheduled debits. For further details on the Auto Debit API and payment_type please refer to . Default value: "one_off". See the request parameter for more information.

string conditional

The nature of the purchased product or service, which can be employed for the purpose of keeping track and generating reports. See the request parameter for more information.

request parameter should be included in the request payload.

string conditional

The request parameter should be set to true.

string conditional

It represents the URL where the customer will be redirected after the payment stage is complete. See the request parameter more information.

The request parameter should be provided.

object conditional

It is a JSON object containing preloaded data necessary for initializing the . This data encompasses vital details such as customer information, available payment methods, and specific transaction details, all formatted according to the Checkout SDK's initialization specifications. By offering essential information upfront, this feature streamlines the , contributing to an improved user experience and increased efficiency.

It will be included in the response solely when the parameter is set to true.

string mandatory

object conditional

Shipping location data of the customer. See the request parameter for more information.

The child objects of the parameter provided in the request object will be populated as child objects of the parameter in the response object.

string mandatory

The current state of the payment transaction, it helps to understand the progress of the payment. Enum: created , pending , attempted , authorized , paid , failed , canceled , expired , invalided ,refunded , cod. See for more information.

string mandatory

The type of the payment transaction. See the request parameter for more information.

string conditional

The request parameter should be included in the request payload.

string conditional

It represents the name of the merchant or vendor associated with a payment transaction. For more information see .

The request parameter should be included in the request payload.

URL conditional

It contains the 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. See Webhook .

The request parameter should be provided.

"", "", "", and "" are required parameters. When we add we should add: "" for email notification. "" for SMS notification.

All the same fields from can be used. The type of update is partial. But some fields can be cross-validated and require other fields to be provided.

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

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

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

= + max{}

This is the time Ottu waits before automatically checking the transaction status with the payment gateway. for more information, please refer .

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

For MPGS (Mastercard Payment Gateway Services), the is 11 minutes.

If your system sets an of 5 minutes, then:

For MPGS: = 5 + 11 = 16 minutes

For KNET: = 5 + 8 = 13 minutes

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

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

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

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

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

Yes! Use with a set to auto_debit to create for recurring transactions. Learn more in the .

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

Call the to create a transaction.

Handle for transaction updates.

multipart/form-data
JSON
ISO 3166-1 Alpha-2 code
Auto-Debit API documentation
tokenization
ISO 3166-1 Alpha-2 code
Payment Notification
Payment Notification
Checkout API
webhooks
Update
code
code
PATCH
View
fetch
Create Payment Transaction
Request Parameters
agreement
id
amount_variability
start_date
expiry_date
max_amount_per_cycle
cycle_interval_days
total_cycles
frequency
type
seller
extra_params
amount
currency_code
attachment
billing_address
1️
line1
2️
line2
line1
3️
city
4️
state
city
5️
country
6️
postal_code
card_acceptance_criteria
min_expiry_time
currency_code
customer_birthdate
customer_email
notifications
notification.email
customer_first_name
customer_id
customer_last_name
customer_phone
notifications
notification.sms
due_datetime
email_recipients
expiration_time
expiration _time
due_datetime
extra
generate_qr_code
qr_code_url
checkout_url,
include_sdk_setup_preload
sdk_setup_preload_payload
language
notifications
1️
email
2️
sms
order_no
pg_codes
payment_type
agreement
customer_id
product_type
redirect_url
shipping_address
1️
line1
2️
line2
line1
3️
city
4️
state
city
5️
country
6️
postal_code
7️
first_name
8️
last_name
9️
email
1️
0️
phone
shortify_attachment_url
Bitly
configured
attachment_short_url
attachment
shortify_checkout_url
Bitly
configured
checkout_short_url
checkout_url
type
attachment_upload_url
vendor_name
webhook_url
Response Parameters
agreement
agreement
payment_type
payment_type
amount
amount
attachment
attachment
attachment
attachment_short_url
shortify_attachment_url
billing_address
billing_address
billing_address
billing_address
card_acceptance_criteria
card_acceptance_criteria
card_acceptance_criteria
card_acceptance_criteria
checkout_short_url
checkout url.
shortify_checkout_url
checkout_url
checkout_short_url
currency_code
currency_code
customer_birthdate
customer_birthdate
customer_birthdate
customer_email
customer_email
customer_email
customer_first_name
customer_first_name
customer_first_name
customer_id
customer_id
customer_id
customer_last_name
customer_last_name
customer_last_name
custome_phone
customer_phone
customer_phone
due_datetime
due_datetime
email_recipients
email_recipients
email_recipients
expiration_time
expiration_time
extra
extra
extra
extra
initiator_id
language
language
notifications
notifications
notifications
notifications
operation
order_no
order_no
order_no
payment_methods
pg_codes
redirect_url
1️
code
2️
name
3️
pg
4️
is_sandbox
5️
icon
6️
flow
7️
redirect_url
redirect_url
pg_codes
pg_codes
payment_type
Auto-Debit API
payment_type
product_type
product_type
product_type
qr_code_url
generate_qr_code
redirect_url
redirect_url
redirect_url
sdk_setup_preload_payload
include_sdk_setup_preload
session_id
shipping_address
shipping_address
shipping_address
shipping_address
state
type
type
attachment_upload_url
attachment_upload_url
vendor_name
vendor_name
vendor_name
webhook_url
webhook_url
API Schema Reference
Example: Checkout API - create payment transaction (request-response)
API-Request (default required data)
type
pg_codes
amount
currency_code
notification
customer_email
customer_phone
Response
Update Payment Transaction
Parameters
create request
Retrieve Payment Transaction
FAQ
1️
What is the Ottu Checkout API used for?
webhooks
session_id
2️
How do I create a payment transaction?
POST request
session_id
3️
How can I ensure that the payer cannot make a payment after a certain amount of time since redirection?
expiration_time
auto inquiry time
PG auto inquiry time
PG auto inquiry time
auto inquiry time
expiration_time
expiration_time
4️
Can I update an existing transaction?
PUT request
5️
What happens if a customer abandons the payment?
automatic inquiry
6️
How do I get notified when a payment is completed?
payment notification
webhook_url
7️
What is the difference between webhook_url and redirect_url?
8️
Can I retry a failed payment?
9️
Can I set up recurring payments using the Checkout API?
Auto-Debit
Auto-Debit
payment_type
agreements
1️
0️
How do I integrate the Checkout API with the SDK?
Web
Android
iOS
session_id
here
here
currencies
exchanges
Payment Request
E-Commerce
E-Commerce
Payment Request
payment_request
e_commerce
API-based
SDK-based
authentication
How to Generate API Keys
plugin
Best Practices and Guidelines
create
Checkout API PATCH
Permissions
PG codes
creating
updating
API Key
Basic Authentication
Create
code
Payment Request
E-Commerce
Checkout SDK
order_no
session_id
extra
session_id
reference_number
here
section.
Basic Authentication
API-Key
API-Key
Basic Authentication
Basic authentication
API Private key
Basic Authentication
API-Key
Tokenization without Payment
checkout process
here
here
payment transaction state
here
  • Best Practices and Guidelines
  • Permissions
  • API Key
  • Basic Authentication
  • Create Payment Transaction
  • Request Parameters
  • Response Parameters
  • API Schema Reference
  • POSTCreate a new Payment Transaction
  • Example: Checkout API - create payment transaction (request-response)
  • Update Payment
  • Parameters
  • Retrieve Payment
  • FAQ

Create a new Payment Transaction

post

Create a new Payment Transaction

Authorizations
Header parameters
AuthorizationstringRequired

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

Default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo
Body

Serializer to work with PaymentTransaction instances.

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

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

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.

pg_codesstring[]Required

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

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:
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.

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.

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.

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:
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: 200Optional

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:
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 · uriOptional

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
POST /b/checkout/v1/pymt-txn/ HTTP/1.1
Host: sandbox.ottu.net
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 1609

{
  "amount": "text",
  "currency_code": "text",
  "pg_codes": [
    "text"
  ],
  "type": "e_commerce",
  "billing_address": {
    "line1": "text",
    "line2": "text",
    "city": "text",
    "state": "text",
    "country": "AW",
    "postal_code": "text"
  },
  "shipping_address": {
    "line1": "text",
    "line2": "text",
    "city": "text",
    "state": "text",
    "country": "AW",
    "postal_code": "text",
    "first_name": "text",
    "last_name": "text",
    "email": "name@gmail.com",
    "phone": "text"
  },
  "agreement": {
    "id": "text",
    "amount_variability": "fixed",
    "start_date": "2025-05-09",
    "expiry_date": "2025-05-09",
    "max_amount_per_cycle": "text",
    "cycle_interval_days": 1,
    "total_cycles": 1,
    "frequency": "irregular",
    "type": "event_based",
    "seller": {
      "name": "text",
      "short_name": "text",
      "category_code": "text"
    },
    "extra_params": {
      "payment_processing_day": 1
    }
  },
  "attachment": "https://example.com",
  "attachment_upload_url": "text",
  "card_acceptance_criteria": {
    "min_expiry_time": 1
  },
  "customer_email": "name@gmail.com",
  "customer_first_name": "text",
  "customer_id": "text",
  "customer_last_name": "text",
  "customer_phone": "text",
  "due_datetime": "2025-05-09T04:24:05.909Z",
  "email_recipients": [
    "name@gmail.com"
  ],
  "expiration_time": "text",
  "extra": {
    "student_id_number": "text",
    "parent_email_address": "text",
    "fee_category": "text",
    "amount": "text",
    "grade": "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",
  "product_type": "text",
  "redirect_url": "https://example.com",
  "shortify_attachment_url": true,
  "shortify_checkout_url": true,
  "unit_code": "text",
  "vendor_name": "text",
  "webhook_url": "https://example.com"
}
{
  "amount": "text",
  "currency_code": "text",
  "pg_codes": [
    "text"
  ],
  "type": "e_commerce",
  "billing_address": {
    "line1": "text",
    "line2": "text",
    "city": "text",
    "state": "text",
    "country": "AW",
    "postal_code": "text"
  },
  "shipping_address": {
    "line1": "text",
    "line2": "text",
    "city": "text",
    "state": "text",
    "country": "AW",
    "postal_code": "text",
    "first_name": "text",
    "last_name": "text",
    "email": "name@gmail.com",
    "phone": "text"
  },
  "agreement": {
    "id": "text",
    "amount_variability": "fixed",
    "start_date": "2025-05-09",
    "expiry_date": "2025-05-09",
    "max_amount_per_cycle": "text",
    "cycle_interval_days": 1,
    "total_cycles": 1,
    "frequency": "irregular",
    "type": "event_based",
    "seller": {
      "name": "text",
      "short_name": "text",
      "category_code": "text"
    },
    "extra_params": {
      "payment_processing_day": 1
    }
  },
  "attachment": "https://example.com",
  "attachment_short_url": "https://example.com",
  "attachment_upload_url": "text",
  "card_acceptance_criteria": {
    "min_expiry_time": 1
  },
  "checkout_short_url": "https://example.com",
  "checkout_url": "https://example.com",
  "customer_email": "name@gmail.com",
  "customer_first_name": "text",
  "customer_id": "text",
  "customer_last_name": "text",
  "customer_phone": "text",
  "due_datetime": "2025-05-09T04:24:05.909Z",
  "email_recipients": [
    "name@gmail.com"
  ],
  "expiration_time": "text",
  "extra": {
    "student_id_number": "text",
    "parent_email_address": "text",
    "fee_category": "text",
    "amount": "text",
    "grade": "text"
  },
  "initiator_id": 1,
  "language": "en",
  "notifications": {
    "email": [
      "created"
    ],
    "sms": [
      "created"
    ],
    "whatsapp": [
      "created"
    ]
  },
  "operation": "text",
  "order_no": "text",
  "payment_methods": {
    "code": "text",
    "name": "text",
    "pg": "text",
    "type": "e_commerce",
    "amount": "text",
    "currency_code": "text",
    "fee": "text",
    "fee_description": "text",
    "icon": "https://example.com",
    "flow": "text",
    "redirect_url": "https://example.com"
  },
  "payment_type": "one_off",
  "product_type": "text",
  "qr_code_url": "https://example.com",
  "redirect_url": "https://example.com",
  "sdk_setup_preload_payload": {
    "amount": "text",
    "cards": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "customer_id": "text",
    "customer_phone": "text",
    "currency_code": "text",
    "language": "en",
    "operation": "text",
    "payment_methods": [],
    "payment_services": [],
    "flex_methods": [],
    "response": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "state": "created",
    "type": "e_commerce",
    "is_amount_editable": true,
    "session_id": "text"
  },
  "session_id": "text",
  "settled_pg_code": "text",
  "state": "created",
  "vendor_name": "text",
  "webhook_url": "https://example.com"
}