📝Request Params
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 here.
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
".
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
file
optional
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:
Attachments should be sent using the multipart/form-data encoding type. Ensure that you change the content type to
multipart/form-data
when sending attachments. They cannot be sent using JSON encoding.Allowed file extensions for attachments are: "pdf", "jpeg", "png", "doc", "docx", "jpg", "xls", "xlsx", and "txt".
The name of the attached file should not exceed 100 characters.
object
optional
An object to save customer registered address data into payment transaction.
object
optional
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.
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.
string
optional
This field specifies the customer's email address, used for sending payment notifications and receipts. It is also utilized for fraud prevention purposes. When provided, this email address is transmitted to the payment gateway and may appear on invoices, receipts, and the payment page. It must be a valid email address. Max length 128.
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.
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.
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.
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.
string datetime
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)
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.
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. 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.
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.
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.
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.
bool
optional
When set to true, the Checkout API will include the sdk_setup_preload_payload in its response. This payload facilitates immediate UI setup without the need for further API calls.
By default, the parameter is set to false
, and the sdk_setup_preload_payload
is not included in the API response.
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.
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.
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.
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.
string
optional
Enum: "one_off
" , "auto_debit
"
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. for more information about auto-debit API, please refer to Auto-Debit API documentation.
If auto_debit
is selected:
agreement and customer_id parameters will also be mandatory.
Only
PG codes
supporting tokenization can be selected. As a side effect, the card used for the payment will be associated with the suppliedagreement.id
. This card will be locked, preventing the customer from deleting it from the system until an alternate card is chosen forauto-debit
payments
string
optional
The type of product or service being purchased. This field may be used for tracking and reporting purposes Max length: 128.
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 order_no, reference_number, session_id, and any extra parameters, will be added to the redirect_url
.
For more information on how redirection works, please check here.
object
optional
An object to save address data into payment transaction
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.
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 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: payment_request, e_commerce. Max length: 24.
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.
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 Payment Notification.
Last updated