Interactive API test
Last updated
Last updated
Create a new Payment Transaction example
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
^-?\d{0,7}(?:\.\d{0,3})?$
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.
The list of payment gateway codes from which a customer can select to perform the payment or authorization.
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
- Ecommercepayment_request
- Payment RequestNested serializer to save Address data into PaymentTransaction
Nested serializer to save Address data into PaymentTransaction
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.
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.
A writable field that accepts an attachment that has already been uploaded to the server.
(?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$
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.
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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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
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
- Englishar
- ArabicA 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.
The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system.
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:
agreement
and customer_id
parameters will also be mandatory.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:
one_off
- One Offauto_debit
- Auto Debitsave_card
- Save CardThe type of product or service being purchased. This field may be used for tracking and reporting purposes.
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.
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.
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.
The slug of the unit to be used for the transaction.
The name of the vendor or merchant associated with this payment. This field may be used for accounting and reporting purposes.
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.
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
^-?\d{0,7}(?:\.\d{0,3})?$
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.
The list of payment gateway codes from which a customer can select to perform the payment or authorization.
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
- Ecommercepayment_request
- Payment RequestNested serializer to save Address data into PaymentTransaction
Nested serializer to save Address data into PaymentTransaction
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.
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.
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.
A writable field that accepts an attachment that has already been uploaded to the server.
(?:pdf|jpeg|png|doc|docx|jpg|xls|xlsx|txt)$
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.
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.
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.
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.
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.
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.
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 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.
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.
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.
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.
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
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
- Englishar
- ArabicA 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.
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.
The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system.
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.
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:
agreement
and customer_id
parameters will also be mandatory.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:
one_off
- One Offauto_debit
- Auto Debitsave_card
- Save CardThe type of product or service being purchased. This field may be used for tracking and reporting purposes.
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.
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.
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.
A unique identifier for each payment transaction, used to maintain the session state during the payment process.
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.
The current state of the payment transaction, it helps to understand the progress of the payment.
created
- Createdpending
- Pendingattempted
- Attemptedauthorized
- Authorizedpaid
- Paidfailed
- Failedcanceled
- Canceledexpired
- Expiredinvalided
- Invalidedrefunded
- Refundedcod
- Cash on DeliveryThe name of the vendor or merchant associated with this payment. This field may be used for accounting and reporting purposes.
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.