Checkout API
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.
REST APIs should be called only from server not from clients, like mobile apps or browser apps.
To initiate payment transaction.
POST
https://<ottu-url>/b/checkout/v1/pymt-txn/
API supported methods:
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.
Defines under which plugin the transaction will be created.
Available choices: payment_request, e_commerce.
The amount of the transaction.
The number of decimals must correlate with the currency.
Must be positive.
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"
If true, it generates short URL, which could be embedded in either SMS, Email, or WhatsApp messages.
The currency code has to be added in Currency > Currencies.
More details https://en.wikipedia.org/wiki/ISO_4217
3 letters code.
The default mode is “payment”.
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.
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.
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 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.
For the customer's first name.
Max length 64.
For the customer's first name.
Max length 64.
Where to pass the customer’s email address.
Have to be a valid email address.
Max length 128.
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.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.
The city where the customer is living and registered.
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.
Merchant unique identifier for the transaction. ABC123_1, ABC123_2.
Max length: 128.
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.
To pass the vendor’s name.
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.
When the merchant wants to email more people.
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 information.
Max length: 128.
ISO 639-2 language code
https://www.loc.gov/standards/iso639-2/php/code_list.php.
Default language is en.
Max length: 2.
These parameters will be returned for all the response status.
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.
Choice from ("purchase","authorize"). Depending on how the PG is being selected.
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.
List of dicts.
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.
{
"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.
{
"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": ""
}
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.
PATCH
API supported methods:
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.
To get information of payment transaction.
GET
This endpoint is public.
Last modified 2mo ago