Checkout API

Getting started

Ottu provides a collection of APIs, which is a quick way to test the payment and enables you to process and manage payments.

Ottu APIs accept and return JSON in the HTTP body, and return standard HTTP response codes. You can create/update/get operations.

Ottu REST-API base URL

REST APIs should be called only from server not from clients, like mobile apps or browser apps.

https://<ottu-url>/b/checkout/v1/pymt-txn/

Create payment transaction

To initiate payment transaction.

Encoding type

JSON and multipart/form-data

Method

POST

Endpoint

https://<ottu-url>/b/checkout/v1/pymt-txn/

Authentication

API supported methods:

Basic authentication

API Private key.

Permission

The applied permissions are only those which are related to PG codes the user is allowed to use.

The payment transaction should be created automatically, when the merchant knows the due amount.

Request parameters

type string required

Defines under which plugin the transaction will be created. Available choices: payment_request, e_commerce.

amount string required

The amount of the transaction. The number of decimals must correlate with the currency. Must be positive.

attachment fileoptional

The attachment file will be stored along with the payment transaction, and the payment transaction supports only one attachment.

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"

shortify_attachment_url bool optional

If true, it generates short URL, which could be embedded in either SMS, Email, or WhatsApp messages.

currency_code string required

The currency code has to be added in Currency > Currencies. More details https://en.wikipedia.org/wiki/ISO_4217 3 letters code.

mode string optional

The default mode is “payment”.

pg_codes list required

The pg code is a list of PG setting's codes. Users provide 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.

webhook_url URL 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. Max length: 200. See Webhook.

redirect_url URL optional

Where the user is being redirected after the payment process gets completed. Redirect URL can be set in the administration panel. Max length: 200.

customer_id string optional

Customer ID is created by a merchant. If the customer ID is presented in the Ottu checkout SDK, regardless of the mobile app being used, the customer will be prompted to save the card. This will be a checkbox for the customer to choose whether to save the card.

customer_first_name string optional

For the customer's first name. Max length 64.

customer_last_name string optional

For the customer's first name. Max length 64.

customer_email string optional

Where to pass the customer’s email address. Have to be a valid email address. Max length 128.

customer_phone string optional

Where to pass the customer’s phone number. Max length 12.

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

billing_address dict optional

The billing address is the customer’s registered address.

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

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

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

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

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

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

order_no string optional

Merchant unique identifier for the transaction. ABC123_1, ABC123_2. Max length: 128.

notifications dict optional

Notification events are triggered by specific states, and it can be sent in various ways, such like SMS and email.

Will be triggered at the following notification events: [“created”, "paid", "canceled", "failed", "expired", "authorized", "voided", "refunded", "captured"] For failed, in case payment transitions to error state and failed state was asked to send an email for, then the customer will get an email.

Will be triggered at the following notification events: [“created”, "paid", "canceled", "failed", "expired", "authorized", "voided", "refunded", "captured"] For failed, in case payment transitions to error state and failed state was asked to send an email for, then the customer will get an SMS.

vendor_name string optional

To pass the vendor’s name.

expiration_time date optional

Expiration time is for the payment cycle. The default value is one hour. Should be In format (HH:MM:SS). Should be consistency with order_no expiration time.

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.

email_recipients list optional

When the merchant wants to email more people.

extra dict optional

The merchant can send anything in key value form. For example, the merchant can define a validation field in extra parameters, then apply the validation rules.

product_type string optional

Product information. Max length: 128.

language string optional

ISO 639-2 language code https://www.loc.gov/standards/iso639-2/php/code_list.php. Default language is en. Max length: 2.

Response parameters

These parameters will be returned for all the response status.

session_id string read only

Ottu unique identifier which gets generated when the transaction is created. It can be used to perform subsequent operations, like retrieve, acknowledge, refund, capture, and cancelation.

operation string

Choice from ("purchase","authorize"). Depending on how the PG is being selected.

attachment URL

amount string

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.

payment_methods list

List of dicts.

dict

Dict generated according to specific pg_code from pg_codes list from request.

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”, ...).

This URL redirects to the payment page.

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

API-Request (default required data)

{
    "type": "payment_request",
    "pg_codes": ["pg code"],
    "amount": "14",
    "currency_code": "KWD",
    "customer_email":"customer email",
    "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",
    "attachment": "",
    "checkout_short_url": "",
    "checkout_url": "<ottu-url>/b/checkout/redirect/start/?session_id=2919a18bb2374b61e6eb58b8bb43e28203a764db",
    "currency_code": "KWD",
    "customer_email": "customer email",
    "customer_first_name": "",
    "customer_id": "",
    "customer_last_name": "",
    "customer_phone": "customer phone",
    "email_recipients": [],
    "expiration_time": "01:00:00",
    "extra": {},
    "initiator_id": null,
    "language": "en",
    "mode": "payment",
    "notifications": {
        "email": [
            "refunded",
            "expired",
            "failed",
            "authorized",
            "paid",
            "created",
            "captured",
            "voided",
            "canceled"
        ],
        "sms": [
            "refunded",
            "expired",
            "failed",
            "authorized",
            "paid",
            "created",
            "captured",
            "voided",
            "canceled"
        ]
    },
    "operation": "authorize",
    "order_no": null,
    "payment_methods": [
        {
            "code": "pg code",
            "name": "pg code",
            "pg": "Ottu PG",
            "type": "sandbox",
            "amount": "14.000",
            "currency_code": "KWD",
            "fee": "0.000",
            "icon": "<ottu-url>/static/images/pg_icons/master_visa_mada.png",
            "flow": "redirect",
            "redirect_url": "<ottu-url>/checkout/2919a18bb2374b61e6eb58b8bb43e28203a764db?chd-only=True"
        }
    ],
    "pg_codes": [
        "pg code"
    ],
    "redirect_url": "",
    "remarks": null,
    "session_id": "2919a18bb2374b61e6eb58b8bb43e28203a764db",
    "state": "created",
    "type": "payment_request",
    "vendor_name": "",
    "webhook_url": ""
}

Update

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.

Encoding type

JSON and multipart/form-data

Method

PATCH

Endpoint

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

Authentication

API supported methods:

Basic authentication.

API Private key.

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

To get information of payment transaction.

Encoding type

JSON and multipart/form-data

Method

GET

Endpoint

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

Authentication

This endpoint is public.

PreviousAuthenticationNextOperations

Last updated