Checkout API

Getting Started

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 API-based or SDK-based.

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

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:

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

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

Create Payment Transaction

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.

Request Parameters

amount 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 currency_code. Max length: 24 Min value: 0.01

attachment string optional

An optional attachment that will 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 It works only with multipart/form-data encoding type Attachment could not be sent using JSON encoding type Allowed extensions:"pdf", "jpeg", "png", "doc", "docx", "jpg", "xls", "xlsx" The name of the attached file should be no more than 100.

billing_address object optional

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

billing_address object details

1️ line1 string required

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

2️ line2 string optional

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

3️city string required

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

4️ state string optional

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

5️ country string required

Customer’s country, ISO 3166-1 Alpha-2 code. Will be validated against existing countries. Max length: 2.

6️ postal_code string required

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

  • billing_address object details

    • line1 string required

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

    • line2 string optional

      For accuracy purpose, Additional address data for the line1.

Child ParameterTypeRequired / OptionalDescription

line1

string

Required

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

line2

string

Optional

For accuracy purpose, Additional address data for the

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

line1

string required

One of the billing address parameters and should be filled by street & house data

line2

string optional

For accuracy purpose, Additional address data for the

currency_code 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 exchanges resulting in a different currency being charged. See currencies. 3 letters code.

customer_email string optional

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. Have to be a valid email address. Max length 128.

customer_first_name string optional

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.

customer_id string optional

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.

customer_last_name string optional

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 string optional

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.

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

due_datetime string date-time optional

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)

email_recipients array of strings 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_time string optional

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. The default value is one hour. Should be In format (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.

If the expiration _time for a payment has passed, the payment state will be changed and cannot be paid. However, if the payment due_datetime 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.

extra object optional

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.

generate_qr_code bool optional

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 value is false.

language string optional

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.

mode string optional

Default: “payment”. Value: “payment”.

notifications object optional

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

1️ email list optional

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.

2️ SMS list optional

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.

order_no string optional

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.

pg_codes 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 Basic authentication: User can use the PG code that has permission to access to. For API Private key: User can use all the PG code.

product_type string optional

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

redirect_url string optional

The URL where the customer will be redirected after the payment stage only if the webhook_url returns a success status. Redirect URL can be set in the administration panel. Max length: 200.

shipping_address object optional

An object to save address data into payment transaction

shipping_address object details

1️ line1 string required

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

2️ line2 string optional

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

3️city string required

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

4️ state string optional

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

5️ country string required

Destination country, ISO 3166-1 Alpha-2 code. Will be validated against existing countries. Max length: 2.

6️ postal_code string required

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

7️ first_name string required

Shipment recipient first name. Max length: 64.

8️ last_name string required

Shipment recipient last name. Max length: 64.

9️ email string required

Shipment recipient email address. Max length: 128.

1️0️ phone string required

Shipment recipient phone number. Max length: 16.

shortify_attachment_url 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 Bitly, is configured, the attachment_short_url will be shorter than attachment response parameter. if not configured, the attachment_short_url will be in the same format with attachment response parameter. Default value is false.

shortify_checkout_url 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 Bitly, is configured, the checkout_short_url will be shorter than checkout url response parameter. If not configured, the checkout_short_url will be in the format of "https://<ottu-url>>/b/abc123". Default value is false.

type 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: payment_request, e_commerce. Max length: 24.

vendor_name string optional

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

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

Response Parameters

These parameters will be returned for all the response status.

amount 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 amount for more information.

attachment string conditional

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

Presence condition:

  • The attachment should be uploaded using attachment request parameter.

attachment_short_url string conditional

A short attachment retrieval URL. Max length: 200.

Presence condition:

billing_address object conditional

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

Presence condition:

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

checkout_short_url string conditional

Short checkout url.

Presence condition:

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

currency_code string mandatory

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

customer_email string conditional

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

Presence condition:

customer_first_name string conditional

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

Presence condition:

customer_id 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 customer_id for more information.

Presence condition:

customer_last_name string conditional

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

Presence condition:

custome_phone string conditional

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

Presence condition:

due_datetime 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 due_datetime for more information.

email_recipients 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 email_recipients for more information.

Presence condition:

  • Email recipient should be provided in the request payload.

expiration_time 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 expiration_time for more information.

extra object conditional

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

Presence condition:

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

initiator_id integer(initiator) conditional

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:

language 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 language

mode string mandatory

Default: “payment”. Value: “payment”.

notifications object conditional

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

Presence condition:

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

operation string mandatory

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.

order_no 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 order_no for information.

Presence condition:

  • order_no request parameter should be included in the request payload.

payment_methods array [object] mandatory

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

object details

1️ code string

Code of the Gateway Settings instance

2️ name string

Name of the Gateway Settings instance.

3️ pg string

Name of the gateway, settings are applied to.

4️ is_sandbox bool

It is environment used for this PG settings or not.

5️ icon string:URL

URL to default icon of the current gateway.

6️ flow string

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

7️ payment_url string:URL

This URL redirects to the payment page.

pg_codes array mandatory

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

product_type 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 product_type for information.

Presence condition:

  • product_type request parameter should be included in the request payload.

qr_code_url string conditional

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:

redirect_url string conditional

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

Presence condition:

session_id string mandatory

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.

shipping_address object conditional

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

Presence condition:

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

state 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 payment transaction state for more information.

type string mandatory

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

vendor_name string conditional

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

Presence condition:

  • The request parameter vendor_name should be included in the request payload.

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

Example: Checkout API - create payment transaction (request-response)

API-Request (default required data)

{
    "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"]
        }
}

"type", "pg_codes", "amount", and "currency_code" are required parameters. When we add notification we should add: "customer_email" for email notification. "customer_phone" for SMS notification.

Response 

{
    "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": "02:00:00",
    "language": "en",
    "mode": "payment",
    "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/5ca114666d472a170d3c4ea6cadbf347679b2532?chd-only=True"
        }
    ],
    "pg_codes": [
        "pg_codes"
    ],
    "session_id": "5ca114666d472a170d3c4ea6cadbf347679b2532",
    "state": "created",
    "type": "payment_request"
}

Update Payment

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

Headers

NameTypeDescription

Authorization*

API key

Api-Key {{api_key}}

Update Payment Transaction

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.

Parameters

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

Retrieve Payment

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

Retrieve Payment Transaction

To get the information of the payment transaction.

Authentication: This endpoint is public

PreviousAuthenticationNextOperations

Last updated