📝Request Params

agreement

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.

agreement object details

id `string` `optional`

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.

amount_variability `string` `optional`

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

start_date `date` `optional`

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

expiry_date `date` `optional`

The final date until which the agreement remains valid.

max_amount_per_cycle `string` `optional`

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

cycle_interval_days `integer` `optional`

The number of days between each recurring payment

total_cycles `integer` `optional`

The total number of payment cycles within the agreement duration.

frequency `string` `optional`

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

type `string` `optional`

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

seller `object` `optional`

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.

extra_params `object` `optional`

Additional parameters related to the agreement.

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

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

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.

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.

card_acceptance_criteria

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.

card_acceptance_criteria object details

min_expiry_time `string` `optional`

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.

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_birthdate

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.

customer_email

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.

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

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.

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.
If SMS notifications are enabled, the notification.sms parameter must be included, making the customer_phone parameter required.

Otherwise, it remains optional parameter.

due_datetime

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)

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

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.

include_sdk_setup_preload

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.

Here’s the fully simplified and organized version, combining everything into a clean reference-style format for documentation:

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.

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.

For MPGS transactions, the order_no value must not exceed 37 characters.

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.

payment_type

string optional

Enum: one_off, auto_debit, save_card

one_off: For payments that occur only once without future commitments.
save_card: Indicates that the transaction is for the purpose of saving the card information.
When payment_type is set to save_card, the checkout preload response will not include the list of previously saved cards for the customer. This is because no actual payment is being processed—only a new card is being saved—so returning previously saved cards would not provide any benefit to the user.
For additional information, please refer to the Tokenization without Payment documentation.
auto_debit: For payments that are automatically deducted, such as recurring subscriptions, installments, or unscheduled auto-debits.
If auto_debit is selected:
- agreement and customer_id parameters become mandatory.
- Only PG codes supporting tokenization can be selected.
- The card used for the transaction will be associated with the supplied agreement.id. This card will be locked, preventing the customer from deleting it unless another card is chosen as the replacement for auto-debit.
For more information, refer to the Auto-Debit API documentation.

payment_instrument

object optional

It provides the essential values required for direct payment processing, including details about the selected payment instrument, the credentials used to authorize the transaction, and the rules that define the payment processing flow.

Do not call this API from the browser. When using the payment_instrument parameter in the Checkout API, this endpoint must be called server-to-server to prevent exposure of sensitive payment data and credentials.

In payment_instrument, only one pg_code is allowed. The selected gateway must support the chosen payment method (Apple Pay, Google Pay, or Auto Debit).

payment_instrument object details

1️instrument_type `string` `required`

It specifies the payment method being used. This determines how the payload is interpreted and how the payment flow proceeds.

Enum:
apple_pay → Apple Pay (digital wallet)
google_pay → Google Pay (digital wallet)
token → Token-based recurring or stored payment

2️payload object required

It contains the payment credentials or token received from the provider. Must be passed exactly as received, with no modifications.

Example:

"instrument_type": "apple_pay" The payload must be a dictionary object containing the complete Apple Pay token from Apple’s Payment Sheet. Always pass it exactly as received, without any modification.

{
  "payment_instrument": {
    "instrument_type": "apple_pay",
    "payload": {
      "version": "EC_v1",
      "data": "encrypted_payment_data_base64",
      "signature": "signature_base64",
      "header": {
        "ephemeralPublicKey": "key_base64",
        "publicKeyHash": "hash_base64",
        "transactionId": "transaction_id"
      }
    }
  }
}

"instrument_type": "google_pay" The payload must be a dictionary object containing the complete Google Pay payment data, including encrypted payment information and signatures.

{
  "payment_instrument": {
    "instrument_type": "google_pay",
    "payload": {
      "signature": "MEUCIQCbtFh7UIe1Bpi7...",
      "intermediateSigningKey": {
        "signedKey": "{\"keyValue\":\"MFkwEw...\"}",
        "signatures": ["MEQCIH0G6CYKU..."]
      },
      "protocolVersion": "ECv2",
      "signedMessage": "{\"encryptedMessage\":\"...\"}"
    }
  }
}

"instrument_type": "token" The payload must be a dictionary. It contains the saved card toke.

{
    "payment_instrument": {
        "instrument_type": "token"
        "payload": {
            "token": "*********"
        },

    }
}

preload_checkout_page

boolean optional

When set to true during transaction creation (POST only), Ottu preloads and caches the checkout page to make it load faster when the customer is redirected or when your system polls the checkout URL right after creation.

This caching is ignored on updates (PATCH/PUT) because any update automatically clears the cache.
The cache stays valid until the transaction expires, with a maximum TTL of 1 hour (whichever is shorter).
If the transaction state changes, the cache is invalidated immediately.
If the cache is missed, Ottu falls back to normal checkout_url logic (e.g., webhook checks, redirect decisions, and other validations).

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

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.

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

PreviousCheckout API Next📬Response Params

Last updated 8 days ago

id string optional

amount_variability string optional

start_date date optional

expiry_date date optional

max_amount_per_cycle string optional

cycle_interval_days integer optional

total_cycles integer optional

frequency string optional

type string optional

seller object optional

extra_params object optional

1️ line1 string required

2️ line2 string optional

3️city string required

4️ state string optional

5️ country string required

6️ postal_code string required

min_expiry_time string optional

1️ email list optional

2️ SMS list optional

1️instrument_type string required

1️ line1 string required

2️ line2 string optional

3️city string required

4️ state string optional

5️ country string required

6️ postal_code string required

7️ first_name string required

8️ last_name string required

9️ email string required

1️0️ phone string required

id `string` `optional`

amount_variability `string` `optional`

start_date `date` `optional`

expiry_date `date` `optional`

max_amount_per_cycle `string` `optional`

cycle_interval_days `integer` `optional`

total_cycles `integer` `optional`

frequency `string` `optional`

type `string` `optional`

seller `object` `optional`

extra_params `object` `optional`

1️ line1 `string` `required`

2️ line2 `string` `optional`

3️city `string` `required`

4️ state `string` `optional`

5️ country `string` `required`

6️ postal_code `string` `required`

min_expiry_time `string` `optional`

1️ email `list` `optional`

2️ SMS `list` `optional`

1️instrument_type `string` `required`

1️ line1 `string` `required`

2️ line2 `string` `optional`

3️city `string` `required`

4️ state `string` `optional`

5️ country `string` `required`

6️ postal_code `string` `required`

7️ first_name `string` `required`

8️ last_name `string` `required`

9️ email `string` `required`

1️0️ phone `string` `required`