> For the complete documentation index, see [llms.txt](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/developer/checkout-api.md).
# Checkout API
Ottu's `Checkout API` collection offers a robust suite of tools designed to streamline the payment processing experience for merchants and developers alike. This comprehensive API collection facilitates seamless payment initiation and management, ensuring efficient and secure transactions. Whether through API-based or SDK-based implementations, the Checkout APIs provide critical functionalities required for modern e-commerce environments.
* **Create Payment Transaction**: This API is pivotal for initiating payment transactions. It enables the creation of a payment transaction and generates a `session_id`, which is crucial for further transaction processing. For an in-depth understanding of this API, please refer to the [Create Payment Transaction](/ottu-team-sandbox-doc/developer/checkout-api/create-payment.md) section.
* **Update Payment Transaction**: Essential for modifying existing payment transactions, this API uses the `session_id` to identify and update transactions accordingly. Detailed information is available in the [Update Payment Transaction](/ottu-team-sandbox-doc/developer/checkout-api/update-payment.md) section.
* **Retrieve Payment Transaction**: This API is designed to fetch details of existing payment transactions using the `session_id`. It ensures that merchants can access transaction details as needed. Further exploration can be done in the [Retrieve Payment Transaction](/ottu-team-sandbox-doc/developer/checkout-api/retrieve-payment.md) section.
* **Upload Attachment API**: Allows merchants to attach files to a transaction, enhancing the flexibility and documentation capabilities of the payment processing system. For more details on how to use this API, visit the [Upload Attachment](/ottu-team-sandbox-doc/developer/checkout-api/upload-attachment.md) section.
## [Quick Start](#quick-start)
Merchants can effortlessly create payment links using the Checkout API. To experience this functionality firsthand, simply click the **"Test it"** button below and explore the full potential of the Checkout API.
## [Setup](#setup)
To enhance your integration process, consider leveraging our official packages designed specifically for the Checkout API. These packages reduce the complexity of API integration by encapsulating the necessary logic, allowing you to focus on core business functionalities.
**Available Packages:**
* **Python SDK:** Facilitates access to checkout functions with a Pythonic interface, streamlining developer tasks by abstracting complex API interactions.[ Learn more](https://github.com/ottuco/ottu-py?tab=readme-ov-file#checkout-aka-session-create)
* **Django SDK:** Seamlessly integrates checkout functionalities into Django projects, equipped with Django-specific tools and utilities that simplify payment processes. [Explore details](https://github.com/ottuco/ottu-py?tab=readme-ov-file#checkout)
Understanding the key concepts and structures documented is vital for robust and maintainable integration of these packages, ensuring both speed and convenience.
## [Best Practices and Guidelines](#best-practices-and-guidelines)
In order to ensure optimal transaction success tracking and minimize the number of required payment transactions, merchants should [create](#create-payment-transaction) 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](#update) 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)
Permissions are managed using [Basic Authentication](/ottu-team-sandbox-doc/developer/authentication.md#basic-authentication) and [API-Key](/ottu-team-sandbox-doc/developer/authentication.md#private-key-api-key). \
Specifically, Basic Authentication is used to grant permissions for creating, updating, and reading data, as well as using allowed [PG codes](#pg_codes-list-required) when [creating ](#create-payment-transaction)or [updating](#update) 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 ](/ottu-team-sandbox-doc/developer/authentication.md)method being used.
### [API Key](#api-key)
When using the [API-Key](/ottu-team-sandbox-doc/developer/authentication.md#private-key-api-key), all permissions are granted by default, as the API-Key is considered to have admin permissions. See [How to Generate API Keys](/ottu-team-sandbox-doc/user-guide/configuration/how-to-get-api-keys.md)
### [Basic Authentication](#basic-authentication)
For [Basic Authentication](/ottu-team-sandbox-doc/developer/authentication.md#basic-authentication), permissions are granted as follows:
#### [Create](#create)
* To create a transaction, the user needs specific permission depending on the [plugin](/ottu-team-sandbox-doc/user-guide/plugins.md) being used:
* "**Can add payment requests**" for the [Payment Request](/ottu-team-sandbox-doc/user-guide/plugins.md#payment-request) plugin
* "**Can add e-commerce payments**" for the [E-Commerce](/ottu-team-sandbox-doc/user-guide/plugins.md#e-commerce) plugin
* Permission to use the payment gateway [code](#pg_codes-array-required) is also required: "**Can use `pg_code`**"
#### [Update](#update)
* To update a transaction, the user needs specific permission depending on the plugin being used:
* "**Can change payment requests**" for the [Payment Request](/ottu-team-sandbox-doc/user-guide/plugins.md#payment-request) plugin
* "**Can change e-commerce payments**" for the [E-Commerce](/ottu-team-sandbox-doc/user-guide/plugins.md#e-commerce) plugin
* Permission to use the payment gateway [code](#pg_codes-array-required) is also required: **"Can use `pg_code`**"
{% hint style="info" %}
The PUT operation cannot be used if the user does not have permission to use the previously defined payment gateway [code](#pg_codes-array-required) on the transaction. For [PATCH](#update-payment-transaction), updates can be performed as long as the payment gateway codes are not updated.
{% endhint %}
#### [View](#view)
* By default, if a user has either the "**Can add**" or "**Can change**" permission, they can [fetch](#retrieve) transactions from the API.
* For more granular control, the following view permissions can be used:
* "**Can view e-commerce payments**" for the [E-Commerce](/ottu-team-sandbox-doc/user-guide/plugins.md#e-commerce) plugin
* "**Can view payment requests**" for the [Payment Request](/ottu-team-sandbox-doc/user-guide/plugins.md#payment-request) plugin
Thank you for exploring the `Checkout API` documentation. Ottu's `Checkout APIs` are designed to provide a robust, secure, and efficient toolset for the seamless handling of payment transactions. Whether payment transactions are being [created](/ottu-team-sandbox-doc/developer/checkout-api/create-payment.md), [updated](/ottu-team-sandbox-doc/developer/checkout-api/update-payment.md), or [retrieved](/ottu-team-sandbox-doc/developer/checkout-api/retrieve-payment.md), the `Checkout APIs` are tailored to enhance operational capabilities and ensure a superior payment experience for customers.
Detailed guidance on each `Checkout API`, including setup instructions, [request](/ottu-team-sandbox-doc/developer/checkout-api/request-params.md) and [response](/ottu-team-sandbox-doc/developer/checkout-api/response-params.md) parameters, and practical examples, can be found in the specific sections outlined in this documentation.
Ottu is committed to supporting the integration journey every step of the way, ensuring that the benefits of the Ottu payment platform are leveraged efficiently and securely.
## Create a new Payment Transaction
> Create a new Payment Transaction
```json
{"openapi":"3.0.0","info":{"title":"Checkout APIs","version":"1.0.0"},"security":[{"SSO BasicAuth":[]},{"basicAuth":[]},{"SSO JWT Auth":[]},{"jwtAuth":[]}],"components":{"securitySchemes":{"SSO BasicAuth":{"scheme":"basic","type":"http"},"basicAuth":{"scheme":"basic","type":"http"},"SSO JWT Auth":{"bearerFormat":"JWT","scheme":"bearer","type":"http"},"jwtAuth":{"bearerFormat":"JWT","scheme":"bearer","type":"http"}},"schemas":{"CheckoutPOSTRequest":{"description":"Serializer to work with PaymentTransaction instances.\n\nAlso uses request data from other serializers to save into PaymentTransaction db table:","properties":{"agreement":{"allOf":[{"$ref":"#/components/schemas/Agreement"}],"description":"An established contractual arrangement with the payer, which authorizes you 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. \n\nNote: If your intention is solely to store payment details for transactions initiated by the payer in the future, then this parameter group should not be used."},"amount":{"description":"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","format":"decimal","type":"string"},"attachment":{"description":"A writable field that accepts an attachment file to 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. The value of this field should be a file object. Upon successful submission, the API will return the URL for downloading the attached file. ","format":"uri","type":"string"},"attachment_short_url":{"description":"A short URL that links to the attachment associated with this payment. This URL may be included in email/sms notifications sent to the customer regarding their payment or displayed on the checkout page to allow the customer to easily access the attachment.","format":"uri","readOnly":true,"type":"string"},"attachment_upload_url":{"description":"A writable field that accepts an attachment that has already been uploaded to the server.","pattern":"(?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$","type":"string"},"billing_address":{"$ref":"#/components/schemas/Address"},"card_acceptance_criteria":{"allOf":[{"$ref":"#/components/schemas/CardAcceptanceCriteria"}],"description":"This field allows you 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`, you gain the power to fine-tune your payment processing strategy, tailoring acceptance rules to align with your business needs, security standards, and risk management policies.\n\n**Example**: If you run an exclusive service that caters predominantly to premium customers, you 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 your services. Remember to configure these criteria thoughtfully. Striking the right balance between security, risk mitigation, and user experience is paramount.\n\n**Note**: The `card_acceptance_criteria` field is applicable only for direct payments and not for hosted session payments."},"checkout_short_url":{"description":"A short URL link that, when opened, redirects to the checkout page for this payment. This URL may be shared with the customer to allow them to easily access and complete the payment. This field is only available if the `shortify_checkout_url` field is set to True.","format":"uri","readOnly":true,"type":"string"},"checkout_url":{"description":"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.","format":"uri","readOnly":true,"type":"string"},"currency_code":{"description":"The specified currency represents the denomination of the transaction.Nevertheless, it doesn't necessarily mandate payment in this exact currency.Due to potential currency conversions or exchanges, the final charge may be in a different currency.","type":"string"},"customer_birthdate":{"description":"Customer's date of birth in YYYY-MM-DD format.This field can be used for age verification or compliance purposes during payment processing.","format":"date","title":"Customer Date of Birth","type":"string"},"customer_email":{"description":"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.","format":"email","maxLength":128,"type":"string"},"customer_first_name":{"description":"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.","maxLength":64,"type":"string"},"customer_id":{"description":"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.","maxLength":64,"type":"string"},"customer_last_name":{"description":"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.","maxLength":64,"type":"string"},"customer_phone":{"description":"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.","maxLength":16,"type":"string"},"customer_phone_2":{"description":"The customer's additional phone number, if any. This field can be updated by the customer on the payment page or in the Checkout SDK.","maxLength":16,"title":"Customer additional phone","type":"string"},"due_datetime":{"description":"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.","format":"date-time","title":"Due date and time","type":"string"},"email_recipients":{"description":"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.","items":{"format":"email","type":"string"},"type":"array"},"expiration_time":{"description":"If defined, any payment transactions created more than the specified period of time ago will be invalidated or expired if the customer attempts to complete them. By default, this expiration period is set to 24 hours from the time of transaction creation. This feature helps ensure that payment transactions are processed promptly.","type":"string"},"extra":{"allOf":[{"$ref":"#/components/schemas/ExtraInner"}],"description":"The extra information for the payment details, which the merchant has sent it in key value form."},"generate_qr_code":{"default":false,"description":"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.","type":"boolean","writeOnly":true},"include_sdk_setup_preload":{"default":false,"description":"Set this to true to include the 'sdk_setup_preload_payload' payload in the API response. This payload is only generated and added when this parameter is explicitly set to true. By default, it is false and the 'sdk_setup_preload_payload' payload will not be included.","type":"boolean","writeOnly":true},"initiator_id":{"description":"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. Note that if the payment transaction was using API Key auth initiator_id can be set to any value that corresponds to an existing ACTIVE user in the system","title":"initiator","type":"integer"},"language":{"default":"en","description":"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.\n\n* `en` - English\n* `ar` - Arabic","enum":["en","ar"],"type":"string"},"notifications":{"allOf":[{"$ref":"#/components/schemas/Notifications"}],"description":"A JSON field 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.","title":"Notification settings"},"operation":{"description":"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.","readOnly":true,"type":"string"},"order_no":{"description":"The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system.","maxLength":128,"type":"string"},"payment_methods":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodsForRedirect"}],"description":"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.","readOnly":true},"payment_type":{"default":"one_off","description":"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. \n\nChoose `save_card` if you want to perform a card tokenization operation.\n\nNOTE: If `auto_debit` is selected: \n1. `agreement` and `customer_id` parameters will also be mandatory. \n2. Only PG codes supporting tokenization can be selected. \nAs a side effect, the card used for the payment will be associated with the supplied `agreement.id`. This card will be locked, preventing the customer from deleting it from the system until an alternate card is chosen for auto-debit payments.\n\nNOTE: If `save_card` is selected: \n1. The amount must be zero for the save card operation. \n2. The selected MID(pg_code) must support tokenization to enable the save card operation. \n3. Please note that the save card operation is considered successful without any funds being charged.\n4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL.\n\n\n* `one_off` - One Off\n* `auto_debit` - Auto Debit\n* `save_card` - Save Card","enum":["one_off","auto_debit","save_card"],"type":"string"},"pg_codes":{"description":"The list of payment gateway codes from which a customer can select to perform the payment or authorization.","items":{"type":"string"},"title":"Gateway","type":"array"},"product_type":{"description":"The type of product or service being purchased. This field may be used for tracking and reporting purposes.","maxLength":128,"type":"string"},"qr_code_url":{"description":"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. This parameter is only present when `generate_qr_code` is set to true.","format":"uri","readOnly":true,"type":"string"},"redirect_url":{"description":"The URL where the customer will be redirected after the payment stage only if the webhook URL returns a success status. `order_no`, `reference_number` and `session_id` will be appended to the redirect URL as query parameters.","format":"uri","maxLength":2000,"type":"string"},"sdk_setup_preload_payload":{"allOf":[{"$ref":"#/components/schemas/CheckoutSDK"}],"default":false,"description":"A JSON object containing preloaded data required to initialize the checkout interface.This includes essential details such as customer information, available payment methods.and specific transaction details, all formatted according to the Checkout SDK's initialization specifications.This field streamlines the checkout process by providing necessary information upfront.enhancing user experience and efficiency.","readOnly":true},"session_id":{"description":"A unique identifier for each payment transaction, used to maintain the session state during the payment process.","readOnly":true,"type":"string"},"settled_pg_code":{"description":"The code of the payment gateway used for completing the transaction. This field indicates the specific gateway that processed and settled the payment, providing clarity on which payment service was ultimately utilized for this transaction.","readOnly":true,"title":"Final Payment Gateway","type":"string"},"shipping_address":{"$ref":"#/components/schemas/ShippingAddress"},"shortify_attachment_url":{"default":false,"description":"If set to True, the URL of the uploaded attachment will be shortened using a URL shortener service. This should be used when sharing the attachment URL via SMS or WhatsApp.","type":"boolean","writeOnly":true},"shortify_checkout_url":{"default":false,"description":"If set to True, the checkout URL will be shortened using a URL shortener service. This should be used when sharing the payment URL via SMS or WhatsApp.","type":"boolean","writeOnly":true},"state":{"description":"The current state of the payment transaction, it helps to understand the progress of the payment.\n\n* `created` - Created\n* `pending` - Pending\n* `attempted` - Attempted\n* `authorized` - Authorized\n* `paid` - Paid\n* `failed` - Failed\n* `canceled` - Canceled\n* `expired` - Expired\n* `invalided` - Invalided\n* `refunded` - Refunded\n* `cod` - Cash on Delivery","enum":["created","pending","attempted","authorized","paid","failed","canceled","expired","invalided","refunded","cod"],"readOnly":true,"type":"string"},"type":{"description":"The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices.\n\n* `e_commerce` - Ecommerce\n* `payment_request` - Payment Request","enum":["e_commerce","payment_request"],"type":"string"},"unit_code":{"description":"The slug of the unit to be used for the transaction.","title":"Unit","type":"string","writeOnly":true},"vendor_name":{"description":"The name of the vendor or merchant associated with this payment. This field may be used for accounting and reporting purposes.","maxLength":64,"type":"string"},"webhook_url":{"description":"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. ","format":"uri","maxLength":2000,"type":"string"}},"required":["amount","attachment_short_url","checkout_short_url","checkout_url","currency_code","operation","payment_methods","pg_codes","qr_code_url","sdk_setup_preload_payload","session_id","settled_pg_code","state","type"],"type":"object"},"Agreement":{"description":"Serializer to hold the recurring data information.\nThis is required for being able to create recurring payments and the PGs\nrequire this information.","properties":{"amount_variability":{"description":"Indicates if all payments within the agreement use the same amount or if the amount differs between the payments.\n\n* `fixed` - Fixed\n* `variable` - Variable","enum":["fixed","variable"],"type":"string"},"cycle_interval_days":{"description":"The minimum number of days between payments agreed with the payer.","maximum":366,"minimum":1,"type":"integer"},"expiry_date":{"description":"Date on which your agreement with the payer to process payments expires.","format":"date","type":"string"},"extra_params":{"allOf":[{"$ref":"#/components/schemas/AgreementExtraParams"}],"description":"Additional parameters related to the agreement."},"frequency":{"description":"The frequency of the payments within the series as agreed with the payer.\n\n* `irregular` - Irregular\n* `daily` - Daily\n* `weekly` - Weekly\n* `semi_monthly` - Semi Monthly\n* `monthly` - Monthly\n* `quarterly` - Quarterly\n* `semi_annually` - Semi Annually\n* `yearly` - Yearly\n* `other` - Other","enum":["irregular","daily","weekly","semi_monthly","monthly","quarterly","semi_annually","yearly","other"],"type":"string"},"id":{"description":"A unique identifier for the agreement established with the payer. This ID links to the specific terms and conditions the payer has authorized for processing their stored card details. Use cases include: \n1. Recurring Payments: Periodic debits, e.g., gym memberships. \n2. Installment Payments: Multiple charges for a single purchase over time. \n3. Unscheduled: Future payments as required, e.g., account top-ups. \n4. Industry Practice: Standard business practices related to an original payment, e.g., hotel charges after checkout.","maxLength":128,"type":"string"},"max_amount_per_cycle":{"description":"The maximum amount for a single payment in the series as agreed with the payer.","format":"decimal","type":"string"},"seller":{"allOf":[{"$ref":"#/components/schemas/AgreementSeller"}],"description":"Details about the retailer, if the agreement is for installment payments."},"start_date":{"description":"Date on which the agreement with the payer to process payments starts.","format":"date","type":"string"},"total_cycles":{"description":"The number of merchant-initiated payments within the recurring payment agreement.","maximum":999,"minimum":1,"type":"integer"},"type":{"default":"recurring","description":"The type of commercial agreement that the payer has with the merchant.\n\n *Note*: For `unscheduled` agreements, the allowed values should be configured as follows: \n\n `id` - Accepts any value. \n\n `frequency`. \n\n `type`.\n\n This configuration ensures that only specific values are permitted for each field when the `type` is `Unscheduled`.\n\n *Note*: For `recurring` agreements, the following fields are mandatory as follows: \n\n `amount_variability` \n\n `cycle_interval_days` \n\n `expiry_date` \n\n ` `requency` \n\n `id` \n\n `total_cycles` \n\n This configuration ensures that the required values are mandatory for each field when the `type` is `Recurring`.\n\n* `event_based` - Event Based\n* `installment` - Installment\n* `recurring` - Recurring\n* `unscheduled` - Unscheduled\n* `other` - Other","enum":["event_based","installment","recurring","unscheduled","other"],"type":"string"}},"type":"object"},"AgreementExtraParams":{"properties":{"payment_processing_day":{"description":"Day of the month on which the payment must be processed. Not required for unscheduled payment agreements.","maximum":31,"minimum":1,"type":"integer"}},"type":"object"},"AgreementSeller":{"properties":{"category_code":{"description":"A 4-digit code classifying the retailer's business by the type of goods or services it offers.","maxLength":64,"type":"string"},"name":{"description":"The retailer's trading name.","maxLength":128,"type":"string"},"short_name":{"description":"Abbreviation of the retailer's trading name, suitable for payer's statement display.","maxLength":64,"type":"string"}},"type":"object"},"Address":{"description":"Nested serializer to save Address data into PaymentTransaction","properties":{"city":{"maxLength":40,"type":"string"},"country":{"description":"* `AW` - Aruba\n* `AF` - Afghanistan\n* `AO` - Angola\n* `AI` - Anguilla\n* `AX` - Åland Islands\n* `AL` - Albania\n* `AD` - Andorra\n* `AE` - United Arab Emirates\n* `AR` - Argentina\n* `AM` - Armenia\n* `AS` - American Samoa\n* `AQ` - Antarctica\n* `TF` - French Southern Territories\n* `AG` - Antigua and Barbuda\n* `AU` - Australia\n* `AT` - Austria\n* `AZ` - Azerbaijan\n* `BI` - Burundi\n* `BE` - Belgium\n* `BJ` - Benin\n* `BQ` - Bonaire, Sint Eustatius and Saba\n* `BF` - Burkina Faso\n* `BD` - Bangladesh\n* `BG` - Bulgaria\n* `BH` - Bahrain\n* `BS` - Bahamas\n* `BA` - Bosnia and Herzegovina\n* `BL` - Saint Barthélemy\n* `BY` - Belarus\n* `BZ` - Belize\n* `BM` - Bermuda\n* `BO` - Bolivia, Plurinational State of\n* `BR` - Brazil\n* `BB` - Barbados\n* `BN` - Brunei Darussalam\n* `BT` - Bhutan\n* `BV` - Bouvet Island\n* `BW` - Botswana\n* `CF` - Central African Republic\n* `CA` - Canada\n* `CC` - Cocos (Keeling) Islands\n* `CH` - Switzerland\n* `CL` - Chile\n* `CN` - China\n* `CI` - Côte d'Ivoire\n* `CM` - Cameroon\n* `CD` - Congo, The Democratic Republic of the\n* `CG` - Congo\n* `CK` - Cook Islands\n* `CO` - Colombia\n* `KM` - Comoros\n* `CV` - Cabo Verde\n* `CR` - Costa Rica\n* `CU` - Cuba\n* `CW` - Curaçao\n* `CX` - Christmas Island\n* `KY` - Cayman Islands\n* `CY` - Cyprus\n* `CZ` - Czechia\n* `DE` - Germany\n* `DJ` - Djibouti\n* `DM` - Dominica\n* `DK` - Denmark\n* `DO` - Dominican Republic\n* `DZ` - Algeria\n* `EC` - Ecuador\n* `EG` - Egypt\n* `ER` - Eritrea\n* `EH` - Western Sahara\n* `ES` - Spain\n* `EE` - Estonia\n* `ET` - Ethiopia\n* `FI` - Finland\n* `FJ` - Fiji\n* `FK` - Falkland Islands (Malvinas)\n* `FR` - France\n* `FO` - Faroe Islands\n* `FM` - Micronesia, Federated States of\n* `GA` - Gabon\n* `GB` - United Kingdom\n* `GE` - Georgia\n* `GG` - Guernsey\n* `GH` - Ghana\n* `GI` - Gibraltar\n* `GN` - Guinea\n* `GP` - Guadeloupe\n* `GM` - Gambia\n* `GW` - Guinea-Bissau\n* `GQ` - Equatorial Guinea\n* `GR` - Greece\n* `GD` - Grenada\n* `GL` - Greenland\n* `GT` - Guatemala\n* `GF` - French Guiana\n* `GU` - Guam\n* `GY` - Guyana\n* `HK` - Hong Kong\n* `HM` - Heard Island and McDonald Islands\n* `HN` - Honduras\n* `HR` - Croatia\n* `HT` - Haiti\n* `HU` - Hungary\n* `ID` - Indonesia\n* `IM` - Isle of Man\n* `IN` - India\n* `IO` - British Indian Ocean Territory\n* `IE` - Ireland\n* `IR` - Iran, Islamic Republic of\n* `IQ` - Iraq\n* `IS` - Iceland\n* `IL` - Israel\n* `IT` - Italy\n* `JM` - Jamaica\n* `JE` - Jersey\n* `JO` - Jordan\n* `JP` - Japan\n* `KZ` - Kazakhstan\n* `KE` - Kenya\n* `KG` - Kyrgyzstan\n* `KH` - Cambodia\n* `KI` - Kiribati\n* `KN` - Saint Kitts and Nevis\n* `KR` - Korea, Republic of\n* `KW` - Kuwait\n* `LA` - Lao People's Democratic Republic\n* `LB` - Lebanon\n* `LR` - Liberia\n* `LY` - Libya\n* `LC` - Saint Lucia\n* `LI` - Liechtenstein\n* `LK` - Sri Lanka\n* `LS` - Lesotho\n* `LT` - Lithuania\n* `LU` - Luxembourg\n* `LV` - Latvia\n* `MO` - Macao\n* `MF` - Saint Martin (French part)\n* `MA` - Morocco\n* `MC` - Monaco\n* `MD` - Moldova, Republic of\n* `MG` - Madagascar\n* `MV` - Maldives\n* `MX` - Mexico\n* `MH` - Marshall Islands\n* `MK` - North Macedonia\n* `ML` - Mali\n* `MT` - Malta\n* `MM` - Myanmar\n* `ME` - Montenegro\n* `MN` - Mongolia\n* `MP` - Northern Mariana Islands\n* `MZ` - Mozambique\n* `MR` - Mauritania\n* `MS` - Montserrat\n* `MQ` - Martinique\n* `MU` - Mauritius\n* `MW` - Malawi\n* `MY` - Malaysia\n* `YT` - Mayotte\n* `NA` - Namibia\n* `NC` - New Caledonia\n* `NE` - Niger\n* `NF` - Norfolk Island\n* `NG` - Nigeria\n* `NI` - Nicaragua\n* `NU` - Niue\n* `NL` - Netherlands\n* `NO` - Norway\n* `NP` - Nepal\n* `NR` - Nauru\n* `NZ` - New Zealand\n* `OM` - Oman\n* `PK` - Pakistan\n* `PA` - Panama\n* `PN` - Pitcairn\n* `PE` - Peru\n* `PH` - Philippines\n* `PW` - Palau\n* `PG` - Papua New Guinea\n* `PL` - Poland\n* `PR` - Puerto Rico\n* `KP` - Korea, Democratic People's Republic of\n* `PT` - Portugal\n* `PY` - Paraguay\n* `PS` - Palestine, State of\n* `PF` - French Polynesia\n* `QA` - Qatar\n* `RE` - Réunion\n* `RO` - Romania\n* `RU` - Russian Federation\n* `RW` - Rwanda\n* `SA` - Saudi Arabia\n* `SD` - Sudan\n* `SN` - Senegal\n* `SG` - Singapore\n* `GS` - South Georgia and the South Sandwich Islands\n* `SH` - Saint Helena, Ascension and Tristan da Cunha\n* `SJ` - Svalbard and Jan Mayen\n* `SB` - Solomon Islands\n* `SL` - Sierra Leone\n* `SV` - El Salvador\n* `SM` - San Marino\n* `SO` - Somalia\n* `PM` - Saint Pierre and Miquelon\n* `RS` - Serbia\n* `SS` - South Sudan\n* `ST` - Sao Tome and Principe\n* `SR` - Suriname\n* `SK` - Slovakia\n* `SI` - Slovenia\n* `SE` - Sweden\n* `SZ` - Eswatini\n* `SX` - Sint Maarten (Dutch part)\n* `SC` - Seychelles\n* `SY` - Syrian Arab Republic\n* `TC` - Turks and Caicos Islands\n* `TD` - Chad\n* `TG` - Togo\n* `TH` - Thailand\n* `TJ` - Tajikistan\n* `TK` - Tokelau\n* `TM` - Turkmenistan\n* `TL` - Timor-Leste\n* `TO` - Tonga\n* `TT` - Trinidad and Tobago\n* `TN` - Tunisia\n* `TR` - Turkey\n* `TV` - Tuvalu\n* `TW` - Taiwan, Province of China\n* `TZ` - Tanzania, United Republic of\n* `UG` - Uganda\n* `UA` - Ukraine\n* `UM` - United States Minor Outlying Islands\n* `UY` - Uruguay\n* `US` - United States\n* `UZ` - Uzbekistan\n* `VA` - Holy See (Vatican City State)\n* `VC` - Saint Vincent and the Grenadines\n* `VE` - Venezuela, Bolivarian Republic of\n* `VG` - Virgin Islands, British\n* `VI` - Virgin Islands, U.S.\n* `VN` - Viet Nam\n* `VU` - Vanuatu\n* `WF` - Wallis and Futuna\n* `WS` - Samoa\n* `YE` - Yemen\n* `ZA` - South Africa\n* `ZM` - Zambia\n* `ZW` - Zimbabwe","enum":["AW","AF","AO","AI","AX","AL","AD","AE","AR","AM","AS","AQ","TF","AG","AU","AT","AZ","BI","BE","BJ","BQ","BF","BD","BG","BH","BS","BA","BL","BY","BZ","BM","BO","BR","BB","BN","BT","BV","BW","CF","CA","CC","CH","CL","CN","CI","CM","CD","CG","CK","CO","KM","CV","CR","CU","CW","CX","KY","CY","CZ","DE","DJ","DM","DK","DO","DZ","EC","EG","ER","EH","ES","EE","ET","FI","FJ","FK","FR","FO","FM","GA","GB","GE","GG","GH","GI","GN","GP","GM","GW","GQ","GR","GD","GL","GT","GF","GU","GY","HK","HM","HN","HR","HT","HU","ID","IM","IN","IO","IE","IR","IQ","IS","IL","IT","JM","JE","JO","JP","KZ","KE","KG","KH","KI","KN","KR","KW","LA","LB","LR","LY","LC","LI","LK","LS","LT","LU","LV","MO","MF","MA","MC","MD","MG","MV","MX","MH","MK","ML","MT","MM","ME","MN","MP","MZ","MR","MS","MQ","MU","MW","MY","YT","NA","NC","NE","NF","NG","NI","NU","NL","NO","NP","NR","NZ","OM","PK","PA","PN","PE","PH","PW","PG","PL","PR","KP","PT","PY","PS","PF","QA","RE","RO","RU","RW","SA","SD","SN","SG","GS","SH","SJ","SB","SL","SV","SM","SO","PM","RS","SS","ST","SR","SK","SI","SE","SZ","SX","SC","SY","TC","TD","TG","TH","TJ","TK","TM","TL","TO","TT","TN","TR","TV","TW","TZ","UG","UA","UM","UY","US","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","YE","ZA","ZM","ZW"],"type":"string"},"line1":{"maxLength":128,"type":"string"},"line2":{"maxLength":128,"type":"string"},"postal_code":{"maxLength":12,"type":"string"},"state":{"maxLength":40,"type":"string"}},"required":["city","country","line1"],"type":"object"},"CardAcceptanceCriteria":{"properties":{"min_expiry_time":{"description":"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 your operational needs with customer convenience. Setting it too stringent might increase payment declines, while a lenient approach could risk future payment failures.\n\nAdditionally, it defaults to 30 days when the `payment_type` is `auto_debit`. If any other payment type is selected, no default value is set.","maximum":365,"minimum":1,"type":"integer"}},"type":"object"},"ExtraInner":{"description":"Serializer for extra data aka dynamic fields.\nExtra data can accept any value by default. However,\nif the merchant wants to enforce a specific type, they can\nuse the plugins.Field class to do so. All CUSTOM fields are\nvalidated inside extra field.\n\nImplementation:\n - requires to have a config property in the parent\n serializer which has to return a PluginConfig instance,\n to which fields are attached.","properties":{"payment_category_amount":{"type":"string"},"payment_category_name":{"type":"string"}},"type":"object"},"Notifications":{"properties":{"email":{"items":{"description":"* `created` - Created\n* `paid` - Paid\n* `canceled` - Canceled\n* `failed` - Failed\n* `expired` - Expired\n* `authorized` - Authorized\n* `voided` - Voided\n* `refunded` - Refunded\n* `captured` - Captured","enum":["created","paid","canceled","failed","expired","authorized","voided","refunded","captured"],"type":"string"},"type":"array"},"sms":{"items":{"description":"* `created` - Created\n* `paid` - Paid\n* `canceled` - Canceled\n* `failed` - Failed\n* `expired` - Expired\n* `authorized` - Authorized\n* `voided` - Voided\n* `refunded` - Refunded\n* `captured` - Captured","enum":["created","paid","canceled","failed","expired","authorized","voided","refunded","captured"],"type":"string"},"type":"array"},"whatsapp":{"items":{"description":"* `created` - Created\n* `paid` - Paid\n* `canceled` - Canceled\n* `failed` - Failed\n* `expired` - Expired\n* `authorized` - Authorized","enum":["created","paid","canceled","failed","expired","authorized"],"type":"string"},"type":"array"}},"type":"object"},"PaymentMethodsForRedirect":{"properties":{"amount":{"description":"The total amount to be charged, including fees.","type":"string"},"code":{"description":"The slug code of the payment method.","pattern":"^[-a-zA-Z0-9_]+$","type":"string"},"currency_code":{"description":"The currency code for the payment method represented as an ISO 4217 code.","maxLength":3,"type":"string"},"fee":{"description":"The fee charged by the payment gateway.","type":"string"},"fee_description":{"description":"This field provides the label for any additional transaction fee. In the SDK, this label will be displayed prominently during the checkout process to inform the payer about the nature of the fee. Ensure to incorporate this field in a clear and visible manner within the checkout UI to maintain transparency with the end-users.","type":"string"},"flow":{"default":"redirect","description":"The flow type of the payment method.","type":"string"},"icon":{"description":"The URL of the icon for the payment method.","format":"uri","type":"string"},"name":{"description":"The name of the payment method.","type":"string"},"pg":{"description":"The payment gateway of the payment.","type":"string"},"redirect_url":{"description":"The URL where the customer should be redirected to perform the payment.","format":"uri","nullable":true,"type":"string"},"type":{"description":"The type of the payment transaction.\n\n* `e_commerce` - Ecommerce\n* `payment_request` - Payment Request","enum":["e_commerce","payment_request"],"type":"string"}},"required":["amount","code","currency_code","fee","fee_description","icon","name","pg","type"],"type":"object"},"CheckoutSDK":{"description":"Serialize data for SDK init.\nThe SDK will use this data to initialize the payment process and\nto display the payment methods.","properties":{"amount":{"description":"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","format":"decimal","type":"string"},"cancel_url":{"description":"This endpoint used to cancel the transaction using the merchant cancellation flow, \nto ensure the transaction cannot be paid again \nand trigger the webhook notification \n","readOnly":true,"type":"string"},"cards":{"description":"List of saved tokenized cards for customer payments, which can be used for transactions. Render alongside `payment_methods` for customers to choose from.","items":{"additionalProperties":{},"type":"object"},"readOnly":true,"type":"array"},"currency_code":{"description":"The specified currency represents the denomination of the transaction.Nevertheless, it doesn't necessarily mandate payment in this exact currency.Due to potential currency conversions or exchanges, the final charge may be in a different currency.","type":"string"},"customer_id":{"description":"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.","maxLength":64,"type":"string"},"customer_phone":{"description":"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.","maxLength":16,"type":"string"},"flex_methods":{"description":"The `flex_methods` field encompasses a comprehensive array\nof payment options available to customers,\nexplicitly excluding device-specific methods such as `apple_pay`\n`google_pay`, redirect flow `payment_methods` and tokenized card solutions\notherwise it represents the flexible payment methods ie:(`tamara`, `tabby`)\npayment options that necessitate dynamic flows\nwhere SDK might need to fetch some `pre-payment-check` API calls then\nusers are guided to an external webpage to finalize their payment transactions.\n\nIt's important to note that the flex_methods array is dynamic\nand can accommodate an unlimited array of payment methods.\neach method listed should be individually rendered within the user interface with a separated flow.\n","items":{},"readOnly":true,"type":"array"},"is_amount_editable":{"description":"This field specifies whether the customer can modify the payment amount and choose the amount he wishes to pay.","readOnly":true,"title":"Editable amount","type":"boolean"},"language":{"default":"en","description":"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.\n\n* `en` - English\n* `ar` - Arabic","enum":["en","ar"],"type":"string"},"operation":{"description":"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.","readOnly":true,"type":"string"},"payment_methods":{"description":"The provided documentation describes the `payment_methods` field.\n\n Detailing the types of payment methods included and their functionality \nas well as backward compatibility considerations for removed methods. \n\nThe `payment_methods` field includes various payment options available to customers\nexcluding device-specific methods like `apple_pay`, `google_pay`and `flex_methods` represented in flex methods section\nit primarily supports methods requiring a redirect flow\nwhere users complete transactions on an external webpage.\n\n`Functionality`: users are redirected to an external \nsite mostly to gateway payment page \nusing `redirect_url` where they can complete the payment flow\n\n**The dynamic nature of the payment_methods**:`payment_methods` type is an array of objects \nand it's type allows it to accommodate an unlimited variety of payment options\nas each object represents a gateway payment option but strictly associated to redirect payment flow\n\n**Backward Compatibility Notice:**\n\n`stc_pay`: \nprevious Inclusion, `stc_pay` was formerly listed within the `payment_methods` array\nit has been removed in favor of a more streamlined integration within the SDK\nsimilar to the approach for `payment_services`.\n\n**Backward Compatibility:** \n\nThe SDK must still support STC Pay for applications relying on older API versions.\nAlthough it will not appear in current and future versions\nthe SDK will manage its inclusion internally\n\nto ensure a seamless transition and consistent user experience\nacross different API versions, without disrupting existing integrations.\n","items":{},"readOnly":true,"type":"array"},"payment_services":{"description":"Dedicated to singular, prominently featured payment options\n\nsuch as `apple_pay`, `google_pay`, `samsung_pay`, `stc_pay`, etc.,\nthe `payment_services` field presents these methods in a distinctive manner.\n\nUnlike `payment_methods`, payment services are intended to be displayed uniquely,\nTypically represented by dedicated buttons or interfaces within the payment page.\n\nThis ensures that each payment service,\nidentifiable by its unique flow ie: (`apple_pay`, `stc_pay`)\nis presented no more than once to the user\nmaintaining clarity and simplicity in the payment selection process.\n\n**Backward Compatibility Notice**:\nhistorically, the availability of (`apple_pay`, `google_pay`) \nwas indicated through the `apple_pay_available` and `google_pay_available` flags\nat the root level of the API response.\n\nWith the evolution of the API, these flags have been deprecated, \nand the respective payment methods have been integrated into the `payment_services` array.\n\nDespite this restructuring, backward compatibility for these payment methods\nis preserved in the SDK to accommodate previous API versions,\nensuring a seamless transition for existing implementations.\n","items":{},"readOnly":true,"type":"array"},"payment_type":{"default":"one_off","description":"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. \n\nChoose `save_card` if you want to perform a card tokenization operation.\n\nNOTE: If `auto_debit` is selected: \n1. `agreement` and `customer_id` parameters will also be mandatory. \n2. Only PG codes supporting tokenization can be selected. \nAs a side effect, the card used for the payment will be associated with the supplied `agreement.id`. This card will be locked, preventing the customer from deleting it from the system until an alternate card is chosen for auto-debit payments.\n\nNOTE: If `save_card` is selected: \n1. The amount must be zero for the save card operation. \n2. The selected MID(pg_code) must support tokenization to enable the save card operation. \n3. Please note that the save card operation is considered successful without any funds being charged.\n4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL.\n\n\n* `one_off` - One Off\n* `auto_debit` - Auto Debit\n* `save_card` - Save Card","enum":["one_off","auto_debit","save_card"],"type":"string"},"response":{"additionalProperties":{},"description":"**What is a payment gateway response?**\n\nA payment gateway response is the feedback received\nfrom payment gateway after a user has completed a payment\nthis response provides information on whether the payment was successful or if it was canceled or failed.\n\n**When do we receive the response?**\n\nWe receive the payment gateway response immediately after the user has made a payment\nor after n of minutes defined for a gateway inquiry request initiated by ottu core\nto fetch the transaction status after the defined time for each gateway.\n\n**Which attempt do we get the response for?**\n\nthe response we provide is from the most recent payment attempt.\nthis ensures that the information reflects the latest status of the transaction.\n\n**Structure of the response**: \n\nThe response structure is managed by our SDK,\nwhich updates the payment details and triggers one of three callbacks\nbased on the status provided in the response:\n\n`successCallback`: Triggered if the response.status indicates a successful payment.\n\n`cancelCallback`: Triggered if the response.status indicates a canceled payment.\n\n`errorCallback`: Triggered if the response.status indicates a error payment.\n\n","readOnly":true,"type":"object"},"session_id":{"description":"A unique identifier for each payment transaction, used to maintain the session state during the payment process.","readOnly":true,"type":"string"},"state":{"description":"The current state of the payment transaction, it helps to understand the progress of the payment.\n\n* `created` - Created\n* `pending` - Pending\n* `attempted` - Attempted\n* `authorized` - Authorized\n* `paid` - Paid\n* `failed` - Failed\n* `canceled` - Canceled\n* `expired` - Expired\n* `invalided` - Invalided\n* `refunded` - Refunded\n* `cod` - Cash on Delivery","enum":["created","pending","attempted","authorized","paid","failed","canceled","expired","invalided","refunded","cod"],"readOnly":true,"type":"string"},"type":{"description":"The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices.\n\n* `e_commerce` - Ecommerce\n* `payment_request` - Payment Request","enum":["e_commerce","payment_request"],"type":"string"}},"required":["amount","cancel_url","cards","currency_code","flex_methods","is_amount_editable","operation","payment_methods","payment_services","response","session_id","state","type"],"type":"object"},"ShippingAddress":{"description":"Nested serializer to save Address data into PaymentTransaction","properties":{"city":{"maxLength":40,"type":"string"},"country":{"description":"* `AW` - Aruba\n* `AF` - Afghanistan\n* `AO` - Angola\n* `AI` - Anguilla\n* `AX` - Åland Islands\n* `AL` - Albania\n* `AD` - Andorra\n* `AE` - United Arab Emirates\n* `AR` - Argentina\n* `AM` - Armenia\n* `AS` - American Samoa\n* `AQ` - Antarctica\n* `TF` - French Southern Territories\n* `AG` - Antigua and Barbuda\n* `AU` - Australia\n* `AT` - Austria\n* `AZ` - Azerbaijan\n* `BI` - Burundi\n* `BE` - Belgium\n* `BJ` - Benin\n* `BQ` - Bonaire, Sint Eustatius and Saba\n* `BF` - Burkina Faso\n* `BD` - Bangladesh\n* `BG` - Bulgaria\n* `BH` - Bahrain\n* `BS` - Bahamas\n* `BA` - Bosnia and Herzegovina\n* `BL` - Saint Barthélemy\n* `BY` - Belarus\n* `BZ` - Belize\n* `BM` - Bermuda\n* `BO` - Bolivia, Plurinational State of\n* `BR` - Brazil\n* `BB` - Barbados\n* `BN` - Brunei Darussalam\n* `BT` - Bhutan\n* `BV` - Bouvet Island\n* `BW` - Botswana\n* `CF` - Central African Republic\n* `CA` - Canada\n* `CC` - Cocos (Keeling) Islands\n* `CH` - Switzerland\n* `CL` - Chile\n* `CN` - China\n* `CI` - Côte d'Ivoire\n* `CM` - Cameroon\n* `CD` - Congo, The Democratic Republic of the\n* `CG` - Congo\n* `CK` - Cook Islands\n* `CO` - Colombia\n* `KM` - Comoros\n* `CV` - Cabo Verde\n* `CR` - Costa Rica\n* `CU` - Cuba\n* `CW` - Curaçao\n* `CX` - Christmas Island\n* `KY` - Cayman Islands\n* `CY` - Cyprus\n* `CZ` - Czechia\n* `DE` - Germany\n* `DJ` - Djibouti\n* `DM` - Dominica\n* `DK` - Denmark\n* `DO` - Dominican Republic\n* `DZ` - Algeria\n* `EC` - Ecuador\n* `EG` - Egypt\n* `ER` - Eritrea\n* `EH` - Western Sahara\n* `ES` - Spain\n* `EE` - Estonia\n* `ET` - Ethiopia\n* `FI` - Finland\n* `FJ` - Fiji\n* `FK` - Falkland Islands (Malvinas)\n* `FR` - France\n* `FO` - Faroe Islands\n* `FM` - Micronesia, Federated States of\n* `GA` - Gabon\n* `GB` - United Kingdom\n* `GE` - Georgia\n* `GG` - Guernsey\n* `GH` - Ghana\n* `GI` - Gibraltar\n* `GN` - Guinea\n* `GP` - Guadeloupe\n* `GM` - Gambia\n* `GW` - Guinea-Bissau\n* `GQ` - Equatorial Guinea\n* `GR` - Greece\n* `GD` - Grenada\n* `GL` - Greenland\n* `GT` - Guatemala\n* `GF` - French Guiana\n* `GU` - Guam\n* `GY` - Guyana\n* `HK` - Hong Kong\n* `HM` - Heard Island and McDonald Islands\n* `HN` - Honduras\n* `HR` - Croatia\n* `HT` - Haiti\n* `HU` - Hungary\n* `ID` - Indonesia\n* `IM` - Isle of Man\n* `IN` - India\n* `IO` - British Indian Ocean Territory\n* `IE` - Ireland\n* `IR` - Iran, Islamic Republic of\n* `IQ` - Iraq\n* `IS` - Iceland\n* `IL` - Israel\n* `IT` - Italy\n* `JM` - Jamaica\n* `JE` - Jersey\n* `JO` - Jordan\n* `JP` - Japan\n* `KZ` - Kazakhstan\n* `KE` - Kenya\n* `KG` - Kyrgyzstan\n* `KH` - Cambodia\n* `KI` - Kiribati\n* `KN` - Saint Kitts and Nevis\n* `KR` - Korea, Republic of\n* `KW` - Kuwait\n* `LA` - Lao People's Democratic Republic\n* `LB` - Lebanon\n* `LR` - Liberia\n* `LY` - Libya\n* `LC` - Saint Lucia\n* `LI` - Liechtenstein\n* `LK` - Sri Lanka\n* `LS` - Lesotho\n* `LT` - Lithuania\n* `LU` - Luxembourg\n* `LV` - Latvia\n* `MO` - Macao\n* `MF` - Saint Martin (French part)\n* `MA` - Morocco\n* `MC` - Monaco\n* `MD` - Moldova, Republic of\n* `MG` - Madagascar\n* `MV` - Maldives\n* `MX` - Mexico\n* `MH` - Marshall Islands\n* `MK` - North Macedonia\n* `ML` - Mali\n* `MT` - Malta\n* `MM` - Myanmar\n* `ME` - Montenegro\n* `MN` - Mongolia\n* `MP` - Northern Mariana Islands\n* `MZ` - Mozambique\n* `MR` - Mauritania\n* `MS` - Montserrat\n* `MQ` - Martinique\n* `MU` - Mauritius\n* `MW` - Malawi\n* `MY` - Malaysia\n* `YT` - Mayotte\n* `NA` - Namibia\n* `NC` - New Caledonia\n* `NE` - Niger\n* `NF` - Norfolk Island\n* `NG` - Nigeria\n* `NI` - Nicaragua\n* `NU` - Niue\n* `NL` - Netherlands\n* `NO` - Norway\n* `NP` - Nepal\n* `NR` - Nauru\n* `NZ` - New Zealand\n* `OM` - Oman\n* `PK` - Pakistan\n* `PA` - Panama\n* `PN` - Pitcairn\n* `PE` - Peru\n* `PH` - Philippines\n* `PW` - Palau\n* `PG` - Papua New Guinea\n* `PL` - Poland\n* `PR` - Puerto Rico\n* `KP` - Korea, Democratic People's Republic of\n* `PT` - Portugal\n* `PY` - Paraguay\n* `PS` - Palestine, State of\n* `PF` - French Polynesia\n* `QA` - Qatar\n* `RE` - Réunion\n* `RO` - Romania\n* `RU` - Russian Federation\n* `RW` - Rwanda\n* `SA` - Saudi Arabia\n* `SD` - Sudan\n* `SN` - Senegal\n* `SG` - Singapore\n* `GS` - South Georgia and the South Sandwich Islands\n* `SH` - Saint Helena, Ascension and Tristan da Cunha\n* `SJ` - Svalbard and Jan Mayen\n* `SB` - Solomon Islands\n* `SL` - Sierra Leone\n* `SV` - El Salvador\n* `SM` - San Marino\n* `SO` - Somalia\n* `PM` - Saint Pierre and Miquelon\n* `RS` - Serbia\n* `SS` - South Sudan\n* `ST` - Sao Tome and Principe\n* `SR` - Suriname\n* `SK` - Slovakia\n* `SI` - Slovenia\n* `SE` - Sweden\n* `SZ` - Eswatini\n* `SX` - Sint Maarten (Dutch part)\n* `SC` - Seychelles\n* `SY` - Syrian Arab Republic\n* `TC` - Turks and Caicos Islands\n* `TD` - Chad\n* `TG` - Togo\n* `TH` - Thailand\n* `TJ` - Tajikistan\n* `TK` - Tokelau\n* `TM` - Turkmenistan\n* `TL` - Timor-Leste\n* `TO` - Tonga\n* `TT` - Trinidad and Tobago\n* `TN` - Tunisia\n* `TR` - Turkey\n* `TV` - Tuvalu\n* `TW` - Taiwan, Province of China\n* `TZ` - Tanzania, United Republic of\n* `UG` - Uganda\n* `UA` - Ukraine\n* `UM` - United States Minor Outlying Islands\n* `UY` - Uruguay\n* `US` - United States\n* `UZ` - Uzbekistan\n* `VA` - Holy See (Vatican City State)\n* `VC` - Saint Vincent and the Grenadines\n* `VE` - Venezuela, Bolivarian Republic of\n* `VG` - Virgin Islands, British\n* `VI` - Virgin Islands, U.S.\n* `VN` - Viet Nam\n* `VU` - Vanuatu\n* `WF` - Wallis and Futuna\n* `WS` - Samoa\n* `YE` - Yemen\n* `ZA` - South Africa\n* `ZM` - Zambia\n* `ZW` - Zimbabwe","enum":["AW","AF","AO","AI","AX","AL","AD","AE","AR","AM","AS","AQ","TF","AG","AU","AT","AZ","BI","BE","BJ","BQ","BF","BD","BG","BH","BS","BA","BL","BY","BZ","BM","BO","BR","BB","BN","BT","BV","BW","CF","CA","CC","CH","CL","CN","CI","CM","CD","CG","CK","CO","KM","CV","CR","CU","CW","CX","KY","CY","CZ","DE","DJ","DM","DK","DO","DZ","EC","EG","ER","EH","ES","EE","ET","FI","FJ","FK","FR","FO","FM","GA","GB","GE","GG","GH","GI","GN","GP","GM","GW","GQ","GR","GD","GL","GT","GF","GU","GY","HK","HM","HN","HR","HT","HU","ID","IM","IN","IO","IE","IR","IQ","IS","IL","IT","JM","JE","JO","JP","KZ","KE","KG","KH","KI","KN","KR","KW","LA","LB","LR","LY","LC","LI","LK","LS","LT","LU","LV","MO","MF","MA","MC","MD","MG","MV","MX","MH","MK","ML","MT","MM","ME","MN","MP","MZ","MR","MS","MQ","MU","MW","MY","YT","NA","NC","NE","NF","NG","NI","NU","NL","NO","NP","NR","NZ","OM","PK","PA","PN","PE","PH","PW","PG","PL","PR","KP","PT","PY","PS","PF","QA","RE","RO","RU","RW","SA","SD","SN","SG","GS","SH","SJ","SB","SL","SV","SM","SO","PM","RS","SS","ST","SR","SK","SI","SE","SZ","SX","SC","SY","TC","TD","TG","TH","TJ","TK","TM","TL","TO","TT","TN","TR","TV","TW","TZ","UG","UA","UM","UY","US","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","YE","ZA","ZM","ZW"],"type":"string"},"email":{"format":"email","maxLength":128,"type":"string"},"first_name":{"maxLength":64,"type":"string"},"last_name":{"maxLength":64,"type":"string"},"line1":{"maxLength":128,"type":"string"},"line2":{"maxLength":128,"type":"string"},"phone":{"maxLength":16,"type":"string"},"postal_code":{"maxLength":12,"type":"string"},"state":{"maxLength":40,"type":"string"}},"required":["city","country","email","first_name","last_name","line1","phone"],"type":"object"},"CheckoutPOSTResponse":{"description":"Serializer to work with PaymentTransaction instances.\n\nAlso uses request data from other serializers to save into PaymentTransaction db table:","properties":{"agreement":{"allOf":[{"$ref":"#/components/schemas/Agreement"}],"description":"An established contractual arrangement with the payer, which authorizes you 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. \n\nNote: If your intention is solely to store payment details for transactions initiated by the payer in the future, then this parameter group should not be used."},"amount":{"description":"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","format":"decimal","type":"string"},"attachment":{"description":"A writable field that accepts an attachment file to 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. The value of this field should be a file object. Upon successful submission, the API will return the URL for downloading the attached file. ","format":"uri","type":"string"},"attachment_short_url":{"description":"A short URL that links to the attachment associated with this payment. This URL may be included in email/sms notifications sent to the customer regarding their payment or displayed on the checkout page to allow the customer to easily access the attachment.","format":"uri","readOnly":true,"type":"string"},"attachment_upload_url":{"description":"A writable field that accepts an attachment that has already been uploaded to the server.","pattern":"(?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$","type":"string"},"billing_address":{"$ref":"#/components/schemas/Address"},"card_acceptance_criteria":{"allOf":[{"$ref":"#/components/schemas/CardAcceptanceCriteria"}],"description":"This field allows you 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`, you gain the power to fine-tune your payment processing strategy, tailoring acceptance rules to align with your business needs, security standards, and risk management policies.\n\n**Example**: If you run an exclusive service that caters predominantly to premium customers, you 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 your services. Remember to configure these criteria thoughtfully. Striking the right balance between security, risk mitigation, and user experience is paramount.\n\n**Note**: The `card_acceptance_criteria` field is applicable only for direct payments and not for hosted session payments."},"checkout_short_url":{"description":"A short URL link that, when opened, redirects to the checkout page for this payment. This URL may be shared with the customer to allow them to easily access and complete the payment. This field is only available if the `shortify_checkout_url` field is set to True.","format":"uri","readOnly":true,"type":"string"},"checkout_url":{"description":"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.","format":"uri","readOnly":true,"type":"string"},"currency_code":{"description":"The specified currency represents the denomination of the transaction.Nevertheless, it doesn't necessarily mandate payment in this exact currency.Due to potential currency conversions or exchanges, the final charge may be in a different currency.","type":"string"},"customer_birthdate":{"description":"Customer's date of birth in YYYY-MM-DD format.This field can be used for age verification or compliance purposes during payment processing.","format":"date","title":"Customer Date of Birth","type":"string"},"customer_email":{"description":"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.","format":"email","maxLength":128,"type":"string"},"customer_first_name":{"description":"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.","maxLength":64,"type":"string"},"customer_id":{"description":"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.","maxLength":64,"type":"string"},"customer_last_name":{"description":"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.","maxLength":64,"type":"string"},"customer_phone":{"description":"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.","maxLength":16,"type":"string"},"customer_phone_2":{"description":"The customer's additional phone number, if any. This field can be updated by the customer on the payment page or in the Checkout SDK.","maxLength":16,"title":"Customer additional phone","type":"string"},"due_datetime":{"description":"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.","format":"date-time","title":"Due date and time","type":"string"},"email_recipients":{"description":"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.","items":{"format":"email","type":"string"},"type":"array"},"expiration_time":{"description":"If defined, any payment transactions created more than the specified period of time ago will be invalidated or expired if the customer attempts to complete them. By default, this expiration period is set to 24 hours from the time of transaction creation. This feature helps ensure that payment transactions are processed promptly.","type":"string"},"extra":{"allOf":[{"$ref":"#/components/schemas/ExtraInner"}],"description":"The extra information for the payment details, which the merchant has sent it in key value form."},"generate_qr_code":{"default":false,"description":"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.","type":"boolean","writeOnly":true},"include_sdk_setup_preload":{"default":false,"description":"Set this to true to include the 'sdk_setup_preload_payload' payload in the API response. This payload is only generated and added when this parameter is explicitly set to true. By default, it is false and the 'sdk_setup_preload_payload' payload will not be included.","type":"boolean","writeOnly":true},"initiator_id":{"description":"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. Note that if the payment transaction was using API Key auth initiator_id can be set to any value that corresponds to an existing ACTIVE user in the system","title":"initiator","type":"integer"},"language":{"default":"en","description":"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.\n\n* `en` - English\n* `ar` - Arabic","enum":["en","ar"],"type":"string"},"notifications":{"allOf":[{"$ref":"#/components/schemas/Notifications"}],"description":"A JSON field 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.","title":"Notification settings"},"operation":{"description":"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.","readOnly":true,"type":"string"},"order_no":{"description":"The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system.","maxLength":128,"type":"string"},"payment_methods":{"allOf":[{"$ref":"#/components/schemas/PaymentMethodsForRedirect"}],"description":"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.","readOnly":true},"payment_type":{"default":"one_off","description":"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. \n\nChoose `save_card` if you want to perform a card tokenization operation.\n\nNOTE: If `auto_debit` is selected: \n1. `agreement` and `customer_id` parameters will also be mandatory. \n2. Only PG codes supporting tokenization can be selected. \nAs a side effect, the card used for the payment will be associated with the supplied `agreement.id`. This card will be locked, preventing the customer from deleting it from the system until an alternate card is chosen for auto-debit payments.\n\nNOTE: If `save_card` is selected: \n1. The amount must be zero for the save card operation. \n2. The selected MID(pg_code) must support tokenization to enable the save card operation. \n3. Please note that the save card operation is considered successful without any funds being charged.\n4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL.\n\n\n* `one_off` - One Off\n* `auto_debit` - Auto Debit\n* `save_card` - Save Card","enum":["one_off","auto_debit","save_card"],"type":"string"},"pg_codes":{"description":"The list of payment gateway codes from which a customer can select to perform the payment or authorization.","items":{"type":"string"},"title":"Gateway","type":"array"},"product_type":{"description":"The type of product or service being purchased. This field may be used for tracking and reporting purposes.","maxLength":128,"type":"string"},"qr_code_url":{"description":"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. This parameter is only present when `generate_qr_code` is set to true.","format":"uri","readOnly":true,"type":"string"},"redirect_url":{"description":"The URL where the customer will be redirected after the payment stage only if the webhook URL returns a success status. `order_no`, `reference_number` and `session_id` will be appended to the redirect URL as query parameters.","format":"uri","maxLength":2000,"type":"string"},"sdk_setup_preload_payload":{"allOf":[{"$ref":"#/components/schemas/CheckoutSDK"}],"default":false,"description":"A JSON object containing preloaded data required to initialize the checkout interface.This includes essential details such as customer information, available payment methods.and specific transaction details, all formatted according to the Checkout SDK's initialization specifications.This field streamlines the checkout process by providing necessary information upfront.enhancing user experience and efficiency.","readOnly":true},"session_id":{"description":"A unique identifier for each payment transaction, used to maintain the session state during the payment process.","readOnly":true,"type":"string"},"settled_pg_code":{"description":"The code of the payment gateway used for completing the transaction. This field indicates the specific gateway that processed and settled the payment, providing clarity on which payment service was ultimately utilized for this transaction.","readOnly":true,"title":"Final Payment Gateway","type":"string"},"shipping_address":{"$ref":"#/components/schemas/ShippingAddress"},"shortify_attachment_url":{"default":false,"description":"If set to True, the URL of the uploaded attachment will be shortened using a URL shortener service. This should be used when sharing the attachment URL via SMS or WhatsApp.","type":"boolean","writeOnly":true},"shortify_checkout_url":{"default":false,"description":"If set to True, the checkout URL will be shortened using a URL shortener service. This should be used when sharing the payment URL via SMS or WhatsApp.","type":"boolean","writeOnly":true},"state":{"description":"The current state of the payment transaction, it helps to understand the progress of the payment.\n\n* `created` - Created\n* `pending` - Pending\n* `attempted` - Attempted\n* `authorized` - Authorized\n* `paid` - Paid\n* `failed` - Failed\n* `canceled` - Canceled\n* `expired` - Expired\n* `invalided` - Invalided\n* `refunded` - Refunded\n* `cod` - Cash on Delivery","enum":["created","pending","attempted","authorized","paid","failed","canceled","expired","invalided","refunded","cod"],"readOnly":true,"type":"string"},"type":{"description":"The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices.\n\n* `e_commerce` - Ecommerce\n* `payment_request` - Payment Request","enum":["e_commerce","payment_request"],"type":"string"},"unit_code":{"description":"The slug of the unit to be used for the transaction.","title":"Unit","type":"string","writeOnly":true},"vendor_name":{"description":"The name of the vendor or merchant associated with this payment. This field may be used for accounting and reporting purposes.","maxLength":64,"type":"string"},"webhook_url":{"description":"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. ","format":"uri","maxLength":2000,"type":"string"}},"required":["amount","attachment_short_url","checkout_short_url","checkout_url","currency_code","operation","payment_methods","pg_codes","qr_code_url","sdk_setup_preload_payload","session_id","settled_pg_code","state","type"],"type":"object"},"ClientErrors":{"oneOf":[{"$ref":"#/components/schemas/FieldErrors"},{"$ref":"#/components/schemas/NestedFieldErrors"},{"$ref":"#/components/schemas/GenericErrorMessage"}]},"FieldErrors":{"properties":{"field_name":{"items":{"default":"This field is required.","type":"string"},"type":"array"}},"type":"object"},"NestedFieldErrors":{"properties":{"field_name":{"$ref":"#/components/schemas/Nested"}},"required":["field_name"],"type":"object"},"Nested":{"properties":{"field_name":{"items":{"default":"To use sms notifications provide the `customer_phone` field.","type":"string"},"type":"array"}},"required":["field_name"],"type":"object"},"GenericErrorMessage":{"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}}},"paths":{"/b/checkout/v1/pymt-txn/":{"post":{"description":"Create a new Payment Transaction","operationId":"create_payment_transaction_checkout","parameters":[{"description":"Private API key to be provided in the format `Api-Key `.","in":"header","name":"Authorization","required":true,"schema":{"default":"Api-Key n44ZGdxa.kk4sm3CE3LEumjn8vYEGSwBP10xdY8Rl","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutPOSTRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/CheckoutPOSTRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/CheckoutPOSTRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutPOSTResponse"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientErrors"}}},"description":""},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericErrorMessage"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericErrorMessage"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericErrorMessage"}}},"description":""},"415":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericErrorMessage"}}},"description":""},"423":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericErrorMessage"}}},"description":""}},"summary":"Create a new Payment Transaction","tags":["Checkout API"]}}}}
```
## [**FAQ**](#faq)
#### :digit\_one: [**What is the Ottu Checkout API used for?**](#what-is-the-ottu-checkout-api-used-for)
The **Checkout API** is used to create and manage payment transactions. It enables merchants to generate a **payment session (**[session\_id](/ottu-team-sandbox-doc/developer/checkout-api/response-params.md#session_id)**)**, redirect users to a payment gateway, and receive payment updates via [webhooks](/ottu-team-sandbox-doc/developer/webhooks.md).
#### :digit\_two:[**How do I create a payment transaction?**](#how-do-i-create-a-payment-transaction)
To create a payment transaction, send a [POST request](/ottu-team-sandbox-doc/developer/checkout-api/create-payment.md) to the Checkout API with the required parameters:
* `amount` – Payment amount
* `currency_code` – Transaction currency
* `pg_codes` – Payment gateways allowed
* `type` - `e_commerce` or `payment_request`
After submission, the API returns a [session\_id](/ottu-team-sandbox-doc/developer/checkout-api/response-params.md#session_id), which is required for processing the transaction.
#### :digit\_three: [**How can I ensure that the payer cannot make a payment after a certain amount of time since redirection?**](#how-can-i-ensure-that-the-payer-cannot-make-a-payment-after-a-certain-amount-of-time-since-redirecti)
To prevent a payer from completing a payment after a specific period, you need to configure the expiration\_time parameter based on the payment gateway (PG) auto inquiry time. This ensures that even if the user remains on the payment page, they won’t be able to proceed once the expiration time has passed.
The expiration time should be set as:
[expiration\_time](/ottu-team-sandbox-doc/developer/checkout-api/request-params.md#expiration_time) = [auto inquiry time](#auto-inquiry-time) + max{[PG auto inquiry time](#pg-auto-inquiry-time)}
* #### **Auto inquiry time:**
This is the time Ottu waits before automatically checking the transaction status with the payment gateway. for more information, please refer [here](/ottu-team-sandbox-doc/developer/payment-status-inquiry.md#automatic-inquiry).
* #### **PG auto inquiry time:**
This is the maximum duration the payment gateway allows before timing out a payment session. More information about PG auto inquiry time is accessible [here](/ottu-team-sandbox-doc/user-guide/payment-gateway.md#payment-gateway-features-summary).
#### **Example Calculation:**
* For **MPGS (Mastercard Payment Gateway Services)**, the [PG auto inquiry time](#pg-auto-inquiry-time) is **11 minutes**.
* For **KNET**, the PG auto inquiry time is **8 minutes**.
If your system sets an [auto inquiry time](#auto-inquiry-time) **of 5 minutes**, then:
* For MPGS: [expiration\_time](/ottu-team-sandbox-doc/developer/checkout-api/request-params.md#expiration_time) = 5 + 11 = 16 minutes
* For KNET: [expiration\_time](/ottu-team-sandbox-doc/developer/checkout-api/request-params.md#expiration_time) = 5 + 8 = 13 minutes
This means that after 16 minutes (for MPGS) or 13 minutes (for KNET), the payer will not be able to complete the transaction, even if they are still on the payment page.
#### :digit\_four: [**Can I update an existing transaction?**](#can-i-update-an-existing-transaction)
Yes! You can update a transaction **before** it is completed by sending a [PUT request](/ottu-team-sandbox-doc/developer/checkout-api/update-payment.md) to the Checkout API, referencing the `session_id`. Updates might include modifying the `amount`, `currency_code`, or allowed `pg_codes`.
#### :digit\_five: [**What happens if a customer abandons the payment?**](#what-happens-if-a-customer-abandons-the-payment)
If a customer does not complete the payment, the transaction remains in a `pending` state until it expires. Ottu's [automatic inquiry](#auto-inquiry-time) will check the status based on the configured timing and update the state accordingly.
#### :digit\_six: [**How do I get notified when a payment is completed?**](#how-do-i-get-notified-when-a-payment-is-completed)
Ottu **sends a** [payment notification ](/ottu-team-sandbox-doc/developer/webhooks/payment-notification.md)webhook to the [webhook\_url](/ottu-team-sandbox-doc/developer/checkout-api/request-params.md#webhook_url) you provided in the API request. The webhook contains details like:
* `status`: `success`, `failed`, `pending`
* `amount` and `currency_code`
* `pg_response`: Response from the payment gateway
Ensure your server verifies and processes these webhook notifications.
#### :digit\_seven: [**What is the difference between `webhook_url` and `redirect_url`?**](#what-is-the-difference-between-webhook_url-and-redirect_url)
* **`webhook_url`** – The API sends real-time payment updates it (for backend processing).
* **`redirect_url`** – After payment, the customer is sent to it (for UI redirection).
For more details on redirection behavior related to `webhook_url`, please refer to this [section.](/ottu-team-sandbox-doc/developer/webhooks/payment-notification.md#redirectional-diagram)
Both are optional but recommended for a seamless experience.
#### :digit\_eight: [**Can I retry a failed payment?**](#can-i-retry-a-failed-payment)
Yes, if a transaction fails, you can **reuse the same** [session\_id](/ottu-team-sandbox-doc/developer/checkout-api/response-params.md#session_id). the payment state will be `attempt`. for more information about , please refer [here](/ottu-team-sandbox-doc/user-guide/payment-tracking/payment-transactions-states.md#payment-attempt).
#### :digit\_nine: [**Can I set up recurring payments using the Checkout API?**](#can-i-set-up-recurring-payments-using-the-checkout-api)
Yes! Use [Auto-Debit](/ottu-team-sandbox-doc/developer/native-payment-api.md#auto-debit-tokenized-payments) with a [payment\_type](/ottu-team-sandbox-doc/developer/checkout-api/request-params.md#payment_type) set to `auto_debit` to create [agreements](/ottu-team-sandbox-doc/developer/checkout-api/request-params.md#agreement) for recurring transactions. Learn more in the [Auto-Debit](/ottu-team-sandbox-doc/developer/native-payment-api.md#auto-debit-tokenized-payments).
#### :digit\_one::digit\_zero: [**How do I integrate the Checkout API with the SDK?**](#how-do-i-integrate-the-checkout-api-with-the-sdk)
The Checkout SDK ([Web](/ottu-team-sandbox-doc/developer/checkout-sdk/web.md), [Android](/ottu-team-sandbox-doc/developer/checkout-sdk/android.md), [iOS](/ottu-team-sandbox-doc/developer/checkout-sdk/ios.md)) requires a [session\_id](/ottu-team-sandbox-doc/developer/checkout-api/response-params.md#session_id) from the Checkout API. Your backend should:
1. Call the [Checkout API](/ottu-team-sandbox-doc/developer/checkout-api.md) to create a transaction.
2. Pass the `session_id` to the SDK for UI rendering.
3. Handle [webhooks](/ottu-team-sandbox-doc/developer/webhooks.md) for transaction updates.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/developer/checkout-api.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.