Interactive API test

Create a new Payment Transaction

Create a new Payment Transaction

POSThttps://ksa.ottu.dev/b/checkout/v1/pymt-txn/

Authorization

SSO BasicAuthSSO JWT AuthApiKeyAuth

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

amount*string (decimal)

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

currency_code*string

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.

pg_codes*Gateway

The list of payment gateway codes from which a customer can select to perform the payment or authorization.

type*enum

The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices.

• e_commerce - Ecommerce
• payment_request - Payment Request

e_commercepayment_request

billing_addressAddress (object)

Nested serializer to save Address data into PaymentTransaction

shipping_addressShippingAddress (object)

Nested serializer to save Address data into PaymentTransaction

agreementall of

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.

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

attachmentstring (uri)

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.

attachment_short_url*string (uri)

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.

attachment_upload_urlstring

A writable field that accepts an attachment that has already been uploaded to the server.

card_acceptance_criteriaall of

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.

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.

Note: The card_acceptance_criteria field is applicable only for direct payments and not for hosted session payments.

checkout_short_url*string (uri)

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.

checkout_url*string (uri)

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.

customer_emailstring (email)

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.

customer_first_namestring

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.

customer_idstring

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.

customer_last_namestring

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.

customer_phonestring

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.

due_datetimeDue date and time

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.

email_recipientsarray of string (email)

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_timestring

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.

extraall of

The extra information for the payment details, which the merchant has sent it in key value form.

generate_qr_codeboolean

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.

include_sdk_setup_preloadboolean

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.

initiator_id*initiator

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 created via the Checkout API using an API-Key, no initiator will be associated with the payment.

languageenum

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.

• en - English
• ar - Arabic

enar

notificationsNotification settings

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.

operation*string

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.

order_nostring

The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system.

payment_methods*all of

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.

payment_typeenum

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.

Choose save_card if you want to perform a card tokenization operation.

NOTE: If auto_debit is selected:

1. agreement and customer_id parameters will also be mandatory.
2. Only PG codes supporting tokenization can be selected. As 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.

NOTE: If save_card is selected:

1. The amount must be zero for the save card operation.
2. The selected MID(pg_code) must support tokenization to enable the save card operation.
3. Please note that the save card operation is considered successful without any funds being charged.
4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL.

• one_off - One Off
• auto_debit - Auto Debit
• save_card - Save Card

one_offauto_debitsave_card

product_typestring

The type of product or service being purchased. This field may be used for tracking and reporting purposes.

qr_code_url*string (uri)

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.

redirect_urlstring (uri)

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.

sdk_setup_preload_payload*all of

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.

session_id*string

A unique identifier for each payment transaction, used to maintain the session state during the payment process.

settled_pg_code*Final Payment Gateway

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.

shortify_attachment_urlboolean

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.

shortify_checkout_urlboolean

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.

state*enum

The current state of the payment transaction, it helps to understand the progress of the payment.

• created - Created
• pending - Pending
• attempted - Attempted
• authorized - Authorized
• paid - Paid
• failed - Failed
• canceled - Canceled
• expired - Expired
• invalided - Invalided
• refunded - Refunded
• cod - Cash on Delivery

createdpendingattemptedauthorizedpaidfailedcanceledexpiredinvalidedrefundedcod

unit_codeUnit

The slug of the unit to be used for the transaction.

vendor_namestring

The name of the vendor or merchant associated with this payment. This field may be used for accounting and reporting purposes.

webhook_urlstring (uri)

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.

Response

201400401403404415423

Body

application/json

amount*string (decimal)

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

currency_code*string

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.

pg_codes*Gateway

The list of payment gateway codes from which a customer can select to perform the payment or authorization.

type*enum

The type of the payment transaction. This field represents the purpose of the payment and can be one of several pre-defined choices.

• e_commerce - Ecommerce
• payment_request - Payment Request

e_commercepayment_request

billing_addressAddress (object)

Nested serializer to save Address data into PaymentTransaction

shipping_addressShippingAddress (object)

Nested serializer to save Address data into PaymentTransaction

agreementall of

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.

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

attachmentstring (uri)

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.

attachment_short_url*string (uri)

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.

attachment_upload_urlstring

A writable field that accepts an attachment that has already been uploaded to the server.

card_acceptance_criteriaall of

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.

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.

Note: The card_acceptance_criteria field is applicable only for direct payments and not for hosted session payments.

checkout_short_url*string (uri)

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.

checkout_url*string (uri)

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.

customer_emailstring (email)

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.

customer_first_namestring

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.

customer_idstring

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.

customer_last_namestring

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.

customer_phonestring

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.

due_datetimeDue date and time

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.

email_recipientsarray of string (email)

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_timestring

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.

extraall of

The extra information for the payment details, which the merchant has sent it in key value form.

generate_qr_codeboolean

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.

include_sdk_setup_preloadboolean

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.

initiator_id*initiator

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 created via the Checkout API using an API-Key, no initiator will be associated with the payment.

languageenum

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.

• en - English
• ar - Arabic

enar

notificationsNotification settings

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.

operation*string

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.

order_nostring

The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system.

payment_methods*all of

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.

payment_typeenum

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.

Choose save_card if you want to perform a card tokenization operation.

NOTE: If auto_debit is selected:

1. agreement and customer_id parameters will also be mandatory.
2. Only PG codes supporting tokenization can be selected. As 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.

NOTE: If save_card is selected:

1. The amount must be zero for the save card operation.
2. The selected MID(pg_code) must support tokenization to enable the save card operation.
3. Please note that the save card operation is considered successful without any funds being charged.
4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL.

• one_off - One Off
• auto_debit - Auto Debit
• save_card - Save Card

one_offauto_debitsave_card

product_typestring

The type of product or service being purchased. This field may be used for tracking and reporting purposes.

qr_code_url*string (uri)

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.

redirect_urlstring (uri)

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.

sdk_setup_preload_payload*all of

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.

session_id*string

A unique identifier for each payment transaction, used to maintain the session state during the payment process.

settled_pg_code*Final Payment Gateway

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.

shortify_attachment_urlboolean

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.

shortify_checkout_urlboolean

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.

state*enum

The current state of the payment transaction, it helps to understand the progress of the payment.

• created - Created
• pending - Pending
• attempted - Attempted
• authorized - Authorized
• paid - Paid
• failed - Failed
• canceled - Canceled
• expired - Expired
• invalided - Invalided
• refunded - Refunded
• cod - Cash on Delivery

createdpendingattemptedauthorizedpaidfailedcanceledexpiredinvalidedrefundedcod

unit_codeUnit

The slug of the unit to be used for the transaction.

vendor_namestring

The name of the vendor or merchant associated with this payment. This field may be used for accounting and reporting purposes.

webhook_urlstring (uri)

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.

Request

JavaScriptCurl

const response = await fetch('https://ksa.ottu.dev/b/checkout/v1/pymt-txn/', {
    method: 'POST',
    headers: {
      "Authorization": "basic <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "amount": "0.01",
      "currency_code": "KWD",
      "pg_codes": [
        "alghanim",
        "authcap",
        "blank-kwd",
        "cash",
        "cb-nbk-ap",
        "credimax-test",
        "cs-sabb",
        "dcc-mpgs-test-bh",
        "google-pay",
        "google-pay-nbk",
        "gpay-gbk",
        "kfh_ottu_pg",
        "kfh-mpgs",
        "kfh-mpgs-test",
        "knet",
        "knet-apple-best",
        "knet-apple-kddc",
        "kpay-raja",
        "kpay-rajaa",
        "live-token",
        "master-visa-card",
        "migs-test",
        "mpgs-ap",
        "mpgs-client",
        "mpgs-production",
        "mpgs-sar",
        "nbk-apple-pay",
        "ottu_pg_kwd",
        "ottu_pg_kwd_tkn",
        "ottu_pg_prod",
        "ottu-pg",
        "pl-cred",
        "seazen",
        "stc_pay",
        "test-rajaa",
        "testing-n-genius",
        "tokenmpgs",
        "vptest"
      ],
      "type": "payment_request"
    }),
});
const data = await response.json();

Response

{
  "amount": "text",
  "currency_code": "text",
  "pg_codes": [
    "text"
  ],
  "type": "e_commerce",
  "billing_address": {
    "line1": "text",
    "line2": "text",
    "city": "text",
    "state": "text",
    "country": "AW",
    "postal_code": "text"
  },
  "shipping_address": {
    "line1": "text",
    "line2": "text",
    "city": "text",
    "state": "text",
    "country": "AW",
    "postal_code": "text",
    "first_name": "text",
    "last_name": "text",
    "email": "[e-mail]",
    "phone": "text"
  },
  "agreement": {
    "id": "text",
    "amount_variability": "fixed",
    "start_date": "2024-05-20",
    "expiry_date": "2024-05-20",
    "max_amount_per_cycle": "text",
    "frequency": "irregular",
    "type": "event_based",
    "seller": {
      "name": "text",
      "short_name": "text",
      "category_code": "text"
    },
    "extra_params": {}
  },
  "attachment": "https://example.com",
  "attachment_short_url": "https://example.com",
  "attachment_upload_url": "text",
  "card_acceptance_criteria": {},
  "checkout_short_url": "https://example.com",
  "checkout_url": "https://example.com",
  "customer_email": "[e-mail]",
  "customer_first_name": "text",
  "customer_id": "text",
  "customer_last_name": "text",
  "customer_phone": "text",
  "due_datetime": "2024-05-20T08:56:27.939Z",
  "email_recipients": [
    "[e-mail]"
  ],
  "expiration_time": "text",
  "extra": {
    "remarks": "text"
  },
  "generate_qr_code": false,
  "include_sdk_setup_preload": false,
  "language": "en",
  "notifications": {
    "email": [
      "created"
    ],
    "sms": [
      "created"
    ]
  },
  "operation": "text",
  "order_no": "text",
  "payment_methods": {
    "code": "text",
    "name": "text",
    "pg": "text",
    "type": "e_commerce",
    "amount": "text",
    "currency_code": "text",
    "fee": "text",
    "fee_description": "text",
    "icon": "https://example.com",
    "flow": "redirect",
    "redirect_url": "https://example.com"
  },
  "payment_type": "one_off",
  "product_type": "text",
  "qr_code_url": "https://example.com",
  "redirect_url": "https://example.com",
  "sdk_setup_preload_payload": {
    "amount": "text",
    "cards": [],
    "customer_id": "text",
    "customer_phone": "text",
    "currency_code": "text",
    "language": "en",
    "operation": "text",
    "payment_methods": "text",
    "payment_services": [],
    "state": "created",
    "type": "e_commerce",
    "is_amount_editable": false,
    "session_id": "text"
  },
  "session_id": "text",
  "settled_pg_code": "text",
  "shortify_attachment_url": false,
  "shortify_checkout_url": false,
  "state": "created",
  "unit_code": "text",
  "vendor_name": "text",
  "webhook_url": "https://example.com"
}