Invoice API

Introduction

Ottu provides businesses and developers with the capability to incorporate its Invoice functionality into their existing systems, streamlining the process of invoice generation for both online and walk-in customers.

But what exactly is an Invoice? An invoice is a document dispatched by a seller to a buyer, itemizing not only the quantity and cost of products or services rendered by the seller but also detailing any applicable taxes, discounts, and shipping costs. Whether issued for a traditional walk-in customer at a brick-and-mortar establishment or an online purchaser, the invoice stands as both a record of the sale and a call for payment.

Imagine you're a business owner selling a range of products online. As orders pour in, you're faced with the arduous task of creating, sending, and tracking invoices manually. This not only consumes precious time but can also lead to errors, missed payments, and dissatisfied customers.

With Ottu's advanced Invoice API, these challenges become a thing of the past. This robust system automates invoicing, ensuring timely dispatch, clear communication, and streamlined payment collection. Whether you're billing for a one-time purchase, tracking bulk orders, or managing advance payments, the Invoice API has got you covered. Through its intuitive integration, you can elevate the efficiency of your business operations and enhance the overall customer experience.

Additionally, it's worth noting that this API bears significant similarities to Ottu's Checkout API, offering seamless integration and familiarity for businesses already leveraging Ottu's suite of tools.

Setup

Before you can integrate with Ottu's Invoice API, several prerequisites need to be fulfilled. These prerequisites are essential to ensure that the Invoice API functions correctly and securely.

1. Payment Gateway: The Invoice API operates seamlessly with a Payment Gateway. Think of this gateway as the essential bridge that authorizes and facilitates transactions between your establishment and your customers. However, it's crucial to know that the Invoice API is explicitly tailored for a Purchase Payment Gateway and does not support the Authorize type. For a comprehensive understanding of Payment Gateways and their inner workings, do give our Payment Gateway User Guide a read. It provides valuable insights and clarifications.

2. Optional: round function When offering customer-facing invoice generation, it's essential to display precise figures supported by clear formulas. The round function is pivotal in achieving this accuracy.

How round funtion works?

In order to ensure the precision and consistency of the financial calculations across various international transactions, Ottu relies on a standardized rounding method known as ROUND_HALF_UP from Python. This method adheres to specific standards established by reputable international organizations:

• SIX Financial Information: Ottu relies on currency decimal specifications provided by the SIX Group through SIX Financial Information.

• ISO 4217 Currency Codes: ISO 4217 provides currency codes and their corresponding minor units, indicating the decimal precision.

The ROUND_HALF_UP method follows a careful procedure to ensure precision:

1. Establish Precision: Begin by determining the number of decimal digits permitted for the currency involved, according to ISO 4217 Currency Codes.

2. Identify the Rounding Digit: Locate the digit immediately to the right of the desired precision. This digit is pivotal in determining the rounding outcome.

3. Apply Rounding Criteria:

   • If the digit to the right of the rounding digit is 5 or greater, the rounding digit is increased by one to ensure rounding up.

   • Conversely, if the digit to the right of the rounding digit is less than 5, the rounding digit remains unchanged, maintaining the current value.

Why round Matters for Your Interface: Ottu's backend utilizes round for precise financial workings. For merchants building a frontend for this Endpoint, it's vital to mirror round in real-time calculations. This ensures users will avoid discrepancy errors when interfacing with Ottu's backend. Certain optional fields in the API are designed to maintain this alignment between frontend input and backend processing, streamlining user experience and bolstering trust. Sources of Decimal Standards:

3. Optional: Payment Methods API The Payment Methods API serves as an initial phase aimed at collecting dynamic parameters, particularly the pg_codes, essential for subsequent calls to the Checkout API. Consider it a preparatory API call that furnishes you with the necessary information for the primary transactional API. Why is it considered optional? If you are already familiar with the specific pg_code you plan to use consistently, you have the option to skip this step by directly storing that pg_code in your system. However, utilizing the Payment Methods API guarantees that you stay informed about the most recent payment gateways available or any modifications in the configuration. This dynamic approach ensures a more robust and adaptable integration with Ottu.

Once you've fulfilled these prerequisites, you're ready to integrate the Invoice API. The following sections of this document will guide you through the authentication process and the usage of various API endpoints.

Authentication

Supported Methods

• Private API Key

• Basic Authentication

For detailed information on authentication procedures, please refer to the Authentication documentation.

Permissions

Below, we are explaining how permissions are managed using Basic Authentication and Private API Key.

When using Basic Authentication, 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 to sensitive data.

Ottu Invoice API supports different levels of permissions for the Payment Request and E-Commerce plugins.

To create a transaction, user requires specific permissions that vary depending on the plugin in use:

• “Can add payment requests” for the Payment Request plugin

• “Can add e-commerce payments” for the E-Commerce plugin

And also needs permission to use the required Payment Gateway

• "Can use pg_code”

To add invoice, user needs to have below permission:

• “Can add Invoice”

When using the Private API Key, all permissions are granted by default, as the private API-Key is considered to have admin permissions. It is recommended to regularly rotate API keys and follow secure password storage practices when using Basic Authentication.

How it Works

The Ottu Invoice API serves as a robust mechanism for merchants to seamlessly issue invoices and manage transactions on the Ottu platform. Here's a detailed breakdown of how the Ottu Invoice API functions:

1. Initiating the Invoice:

   • Merchants utilize the Invoice API, passing the necessary parameters to initiate the creation of an invoice. Please check Invoice API Parameters Specifications.

2. Integration with Ottu Checkout API:

   • Invoice API seamlessly integrates with the Ottu Checkout API to generate a checkout_url.

3. Communication to Customers:

   • Merchants can choose to send the checkout_url to customers via Email or SMS using Ottu's communication channels.

   • Alternatively, merchants have the flexibility to handle the communication from their internal systems.

4. Customer Interaction:

   • Customers receive the checkout_url and, upon clicking, are redirected to Ottu's Checkout Page.

   • Here, customers can conveniently view and download the detailed invoice and proceed to make a direct payment.

5. Transaction Completion:

   • After completing the transaction, Ottu posts a response to the designated webhook_url, providing real-time updates on the transaction status. Please refer to Payment Webhooks.

6. Post-Transaction Customer Experience:

   • Following transaction completion, customers are redirected either to Ottu's Response Page or a specified redirect_url. Please refer to Redirectional Diagram.

   • Ottu's Response Page offers customers the option to download the invoice along with the payment receipt for their records.

This end-to-end process ensures a seamless and secure transaction experience for both merchants and customers, integrating Ottu's Invoice API with Ottu Checkout API for efficient invoice generation, and payment processing.

Invoice Information

In this section, we delve into the comprehensive details encompassing the creation of an invoice through Ottu's robust system. The invoicing process involves multiple layers, each designed to provide flexibility and customization to the merchant. Here's a breakdown of the key components:

Header/Seller Information: Merchants have the opportunity to tailor the invoice header, adding a distinctive touch to their brand. This customization includes the provision of a logo of their choice, seamlessly incorporated into the invoice.

Invoice Information: The essence of the invoice lies in the information provided by the merchant, encompassing Mandatory, Optional, or Calculated values.This information is systematically organized at two distinct levels—the Item level and the Invoice level.

What do the Calculated values encompass?

These values, referred as VAL CALC, serve as validators to ensure that the real-time calculations, typically conducted by the client-side system or application, align with the values computed by Ottu's backend system. Validating these fields at both the item and invoice levels helps identify any disparities between the two, thereby ensuring accuracy and reliability throughout the invoicing process.

• Item Level:

  • Mandatory: Stock Keeping Unit (SKU), Description, Quantity, Unit Price.

  • Optional: Tax Rate, Discount Amount, Discount Percentage.

  • VAL CALC: Total Excluding Tax, Total Including Tax, Tax Amount.

• Invoice Level:

  • Mandatory: Type, Currency Code, PG Codes, Invoice Number, Due Date.

  • Optional: Tax Rate, Discount Amount, Discount Percentage, Shipping Excluding Tax, Shipping Method, Shipping Tax Rate.

  • VAL CALC: Total Excluding Tax, Total Including Tax, Tax Amount, Shipping Including Tax, Subtotal, Amount.

Address Information: Similar to the Checkout API, Ottu's invoicing system supports both Billing and Shipping addresses, providing a seamless and unified experience for users.

Buyer Information: Tailored to accommodate diverse business needs, the Buyer Information section allows for custom fields configured based on the type of the invoice payment_request, e_commerce. This flexibility ensures that merchants can capture essential buyer details relevant to their specific invoicing context.

Invoice API Parameters Specification

In the previous section, we discussed the different sections and levels of invoice information, where details are sourced either from the merchant's input in the Invoice API request or calculated automatically. Below table categorizes the parameters in the Invoice API based on whether they are mandatory, optional, or calculated automatically (VAL CALC), at both the item and invoice levels.

Details at the item level are encapsulated within the invoice_items object. The merchant can append as many items to this object as there are distinct products or items that the customer purchases.

Level	Mandatory Fields	VAL CALC	Optional
Invoice	type currency_code pg_codes invoice_number due_date	tax_amount shipping_inc_tax total_excl_tax total_incl_tax subtotal amount	company_name tax_rate discount_amount discount_percentage shipping_excl_tax shipping_tax_rate shipping_method
Item	sku description quantity unit_price	tax_amount total_excl_tax total_incl_tax	tax_rate discount_amount discount_percentage

It's important to note that:

• For optional properties, if they are not relevant, exclude them entirely from the payload. Avoid sending null or zero values; it's better to omit the property altogether if unnecessary.

• All rate or percentage-related fields are limited to two decimal places. For other monetary fields, the number of decimal places is determined by the currency of the invoice, generally according to ISO 4217.

• The Invoice API differs from the Checkout API in that it does not support the PATCH method. Once an invoice is created, it is immutable and cannot be modified. Should any updates be necessary, a new invoice must be created in place of the original.

For a more detailed technical understanding and the implementation specifics of these operations, please refer to the OpenAPI schema in the API Schema Reference section below.

Create a new Invoice

Create a new Invoice

POSThttps://deltabulk2.ottu.net/b/invoice/v1/invoice/

Authorization

SSO BasicAuthbasicAuthSSO JWT AuthjwtAuth

Body

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

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.

due_date*string (date)

The date by which the customer is expected to make payment for the invoice.

invoice_items*array of InvoiceItem (object)

The list of items for the invoice.

invoice_number*string

A unique identifier for the invoice, typically used for tracking and referencing purposes.

pg_codes*Gateway

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

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.

amountstring (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

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.

company_namestring

The company name is used for invoice API.

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.

discount_amountstring (decimal)

The fixed amount discount applied to the full invoice amount, including taxes. If set, the discount_percentage field will be set to null. Both discount_amount and discount_percentage cannot be set simultaneously. The discount cannot be higher than the total_excl_tax field.

discount_percentagestring (decimal)

The percentage-based discount applied to the full invoice amount, including taxes. If set, the discount_amount field will be automatically calculated. Both discount_amount and discount_percentage cannot be set simultaneously. The discount cannot be higher than the total_excl_tax field.

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.

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.

invoice_id*integer

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.

shipping_excl_taxShipping Excl. Tax

The cost of shipping for the invoice, excluding taxes.

shipping_incl_taxShipping Incl. Tax

The cost of shipping for the invoice, including all applicable taxes.

shipping_methodstring

The method or service used for shipping the items associated with the invoice.

shipping_tax_ratestring (decimal)

The tax rate applied to the shipping cost, expressed as a percentage.

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

status*enum

Current status of the invoice. Can be one of the following: sent, paid, overdue, canceled.

• sent - Sent
• paid - Paid
• overdue - Overdue
• canceled - Canceled

sentpaidoverduecanceled

subtotalstring (decimal)

Sum of total_incl_tax's of all invoice items.

tax_amountstring (decimal)

The total amount of tax applied to the invoice.

tax_rateTax

The tax rate applied to the invoice, expressed as a percentage.

total_excl_taxTotal Excl. Tax

The total amount of the invoice, excluding taxes.

total_incl_taxTotal Incl. Tax

The total amount of the invoice, including all applicable taxes.

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

201400

Body

application/json

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.

due_date*string (date)

The date by which the customer is expected to make payment for the invoice.

invoice_items*array of InvoiceItem (object)

The list of items for the invoice.

invoice_number*string

A unique identifier for the invoice, typically used for tracking and referencing purposes.

pg_codes*Gateway

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

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.

amountstring (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

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.

company_namestring

The company name is used for invoice API.

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.

discount_amountstring (decimal)

The fixed amount discount applied to the full invoice amount, including taxes. If set, the discount_percentage field will be set to null. Both discount_amount and discount_percentage cannot be set simultaneously. The discount cannot be higher than the total_excl_tax field.

discount_percentagestring (decimal)

The percentage-based discount applied to the full invoice amount, including taxes. If set, the discount_amount field will be automatically calculated. Both discount_amount and discount_percentage cannot be set simultaneously. The discount cannot be higher than the total_excl_tax field.

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.

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.

invoice_id*integer

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.

shipping_excl_taxShipping Excl. Tax

The cost of shipping for the invoice, excluding taxes.

shipping_incl_taxShipping Incl. Tax

The cost of shipping for the invoice, including all applicable taxes.

shipping_methodstring

The method or service used for shipping the items associated with the invoice.

shipping_tax_ratestring (decimal)

The tax rate applied to the shipping cost, expressed as a percentage.

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

status*enum

Current status of the invoice. Can be one of the following: sent, paid, overdue, canceled.

• sent - Sent
• paid - Paid
• overdue - Overdue
• canceled - Canceled

sentpaidoverduecanceled

subtotalstring (decimal)

Sum of total_incl_tax's of all invoice items.

tax_amountstring (decimal)

The total amount of tax applied to the invoice.

tax_rateTax

The tax rate applied to the invoice, expressed as a percentage.

total_excl_taxTotal Excl. Tax

The total amount of the invoice, excluding taxes.

total_incl_taxTotal Incl. Tax

The total amount of the invoice, including all applicable taxes.

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://deltabulk2.ottu.net/b/invoice/v1/invoice/', {
    method: 'POST',
    headers: {
      "Authorization": "basic <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "attachment_short_url": "https://example.com",
      "checkout_short_url": "https://example.com",
      "checkout_url": "https://example.com",
      "currency_code": "text",
      "due_date": "2024-04-27",
      "invoice_items": [
        {
          "currency_code": "text",
          "description": "text",
          "quantity": "text",
          "sku": "text",
          "unit_price": "text"
        }
      ],
      "invoice_number": "text",
      "operation": "text",
      "payment_methods": {
        "amount": "text",
        "code": "text",
        "currency_code": "text",
        "fee": "text",
        "fee_description": "text",
        "icon": "https://example.com",
        "name": "text",
        "pg": "text",
        "type": "e_commerce"
      },
      "pg_codes": [
        "text"
      ],
      "qr_code_url": "https://example.com",
      "sdk_setup_preload_payload": {
        "amount": "text",
        "cards": [],
        "currency_code": "text",
        "is_amount_editable": false,
        "operation": "text",
        "payment_methods": "text",
        "payment_services": [],
        "session_id": "text",
        "state": "created",
        "type": "e_commerce"
      },
      "session_id": "text",
      "settled_pg_code": "text",
      "state": "created",
      "status": "sent",
      "type": "e_commerce"
    }),
});
const data = await response.json();

Response

{
  "currency_code": "text",
  "due_date": "2024-04-27",
  "invoice_items": [
    {
      "sku": "text",
      "description": "text",
      "quantity": "text",
      "unit_price": "text",
      "tax_rate": "text",
      "tax_amount": "text",
      "discount_percentage": "text",
      "discount_amount": "text",
      "total_excl_tax": "text",
      "total_incl_tax": "text",
      "currency_code": "text"
    }
  ],
  "invoice_number": "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-04-27",
    "expiry_date": "2024-04-27",
    "max_amount_per_cycle": "text",
    "frequency": "irregular",
    "type": "event_based",
    "seller": {
      "name": "text",
      "short_name": "text",
      "category_code": "text"
    },
    "extra_params": {}
  },
  "amount": "text",
  "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",
  "company_name": "text",
  "customer_email": "[e-mail]",
  "customer_first_name": "text",
  "customer_id": "text",
  "customer_last_name": "text",
  "customer_phone": "text",
  "discount_amount": "text",
  "discount_percentage": "text",
  "due_datetime": "2024-04-27T10:04:59.976Z",
  "email_recipients": [
    "[e-mail]"
  ],
  "expiration_time": "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",
  "shipping_excl_tax": "text",
  "shipping_incl_tax": "text",
  "shipping_method": "text",
  "shipping_tax_rate": "text",
  "shortify_attachment_url": false,
  "shortify_checkout_url": false,
  "state": "created",
  "status": "sent",
  "subtotal": "text",
  "tax_amount": "text",
  "tax_rate": "text",
  "total_excl_tax": "text",
  "total_incl_tax": "text",
  "unit_code": "text",
  "vendor_name": "text",
  "webhook_url": "https://example.com"
}

Guide: Step by Step

Dive into integrating the Invoice API with our concise, step-by-step guide. Designed for seamless adoption into your existing systems, this guide will take you through the essentials of setup and utilization. It's tailored to enhance your invoicing process, ensuring accuracy and efficiency in your financial transactions. Get ready to transform and streamline your billing operations with ease.

The objective of the POST request is to facilitate the creation of payment transactions and the subsequent generation of payment links, each of which is associated with a unique session_id. These links can be effortlessly shared with customers through various communication channels, including email, WhatsApp, and SMS. Additionally, it is possible to incorporate the customer's billing and shipping information into the transaction. Moreover, users of this API can include diverse forms of data and information within the body request.

Creating the Invoice:

1. Retrieving pg_codes (optional)

Prior to initiating the initial payment, you can choose to invoke the Payment Methods API to obtain the required pg_codes.

2. Initiating the Payment via Invoice API

Using a payload as minimal as the one below, you can obtain an invoice.

Request

{
   "type":"e_commerce",
   "due_date":"2025-12-29",
   "currency_code":"KWD",
   "pg_codes":[
      "credit-card"
   ],
   "invoice_number":"A00001",
   "invoice_items":[
      {
         "sku":"ABC111",
         "description":"Test",
         "quantity":1.111,
         "unit_price":5.234
      }
   ]
}

Response

{
   "amount":5.815,
   "checkout_url":"https://sandbox.ottu.net/b/checkout/redirect/start/?session_id=9ba4c834f55f1e5476b9d9ea47ec7b12f61f9511",
   "currency_code":"KWD",
   "due_datetime":"29/12/2025 00:00:00",
   "invoice_id":3,
   "language":"en",
   "operation":"purchase",
   "payment_methods":[
      {
         "code":"credit-card",
         "name":"Credit Card",
         "pg":"Ottu PG",
         "type":"sandbox",
         "amount":"5.815",
         "currency_code":"KWD",
         "fee":"0.000",
         "fee_description":"",
         "icon":"https://sandbox.ottu.net/media/gateway/settings/logos/MASTER_q6sxwtA_md4lBKv.jpeg",
         "flow":"redirect",
         "redirect_url":"https://pg.ottu.dev/checkout/c2FuZGJveC5vdHR1Lm5ldA==/Z0F"
      }
   ],
   "payment_type":"one_off",
   "pg_codes":[
      "credit-card"
   ],
   "session_id":"9ba4c834f55f1e5476b9d9ea47ec7b12f61f9511",
   "state":"created",
   "type":"e_commerce",
   "invoice_number":"A00001",
   "due_date":"2025-12-29",
   "invoice_items":[
      {
         "sku":"ABC111",
         "description":"Test",
         "quantity":1.111,
         "unit_price":5.234,
         "total_excl_tax":5.815,
         "tax_amount":0.0,
         "total_incl_tax":5.815
      }
   ],
   "shortify_checkout_url":false,
   "expiration_time":null,
   "shortify_attachment_url":false,
   "generate_qr_code":false,
   "include_sdk_setup_preload":false,
   "data":{
      "fields":[
         
      ],
      "api_version":"invoice_v1"
   },
   "subtotal":5.815,
   "total_excl_tax":5.815,
   "tax_amount":0.0,
   "shipping_incl_tax":0.0,
   "total_incl_tax":5.815,
   "invoice_pdf_url":"https://e.pay.kn/HWiDBBAQ8WBn"
}

The URL for the invoice PDF in the above response is:

"invoice_pdf_url":"https://e.pay.kn/HWiDBBAQ8WBn"

Applying a discount percentage of 12 to the invoice_items object within the Invoice API request payload:

{
   "type":"e_commerce",
   "due_date":"2025-12-29",
   "currency_code":"KWD",
   "pg_codes":[
      "credit-card"
   ],
   "invoice_number":"A00002",
   "invoice_items":[
      {
         "sku":"ABC111",
         "description":"Test",
         "quantity":1.111,
         "unit_price":5.234,
         "discount_percentage":12
      }
   ]
}

Invoice:

Best Practices

Understanding Ottu's Invoice API: Ottu's Invoice API automates invoice generation, saving time and reducing errors for both online and walk-in customers. Please check Invoice Generation Logic.

Prerequisites for Integration: Ensure a Purchase Payment Gateway and understand Ottu's rounding function. Optionally explore the Payment Methods API for dynamic updates.

Authentication Best Practices: Use Private API Key or Basic Authentication. Regularly rotate API keys for security.

Updating Invoice: Invoice is immutable; create a new one for updates.

VAL CALC Fields: VAL CALC fields ensure accurate figures, like Tax Amount and Shipping Including Tax.

Documentation References: Refer to Ottu's OpenAPI schema for technical details.

Technical Implementation Guide: Follow Ottu's step-by-step guide for a seamless integration.

Invoice Generation Logic

The Invoice Generation Logic is a critical component of Ottu's invoicing system, designed to ensure precision, accuracy, and consistency in financial transactions. At the core of this logic is the utilization of the round function. For more information about round function, please check here.

Key Steps in Invoice Generation

The invoice generation process involves two levels: the invoice items level and the invoice level. The logic begins at the invoice items level and progresses through a series of calculations, incorporating discounts, taxes, and total values. The results are then aggregated at the invoice level to derive a comprehensive view of the entire transaction

Invoice Items Level:

1. Calculate quantity_price: round(quantity * unit_price)

2. Calculate the discount on the item:

   • If both discount_percentage and discount_amount are present, throw an error message.

   • If only discount_percentage is present, calculate the total discount for this item: total_discount = (quantity_price * discount_percentage/100).

   • If only discount_amount is present, ensure it is not more than quantity_price and store it in total_discount.

   • total_discount = round(total_discount) for proper number handling.

3. Calculate total values:

   • total_excl_tax = round(quantity_price - total_discount)

   • total_excl_tax: VAL CALC: If provided in the payload, check for discrepancies.

   • tax_amount = round(total_excl_tax * tax_rate / 100)

   • tax_amount: VAL CALC

   • total_incl_tax = round(total_excl_tax + tax_amount)

   • total_incl_tax: VAL CALC

4. Store results for use on the Invoice level.

Invoice Level:

1. Calculate subtotal by:

   • subtotal = 0

   • Loop over items: subtotal = round(subtotal + item.total_incl_tax)

   • subtotal: VAL CALC

2. Calculate the discount on the invoice:

   • If both discount_percentage and discount_amount are present, throw an error message.

   • If only discount_percentage is present, calculate the total discount for the invoice: total_discount = (subtotal * discount_percentage/100).

   • If only discount_amount is present, ensure it is not more than the subtotal and store it in total_discount.

   • total_discount = round(total_discount) for proper number handling.

3. Calculate total values:

   • total_excl_tax = round(subtotal - total_discount)

   • total_excl_tax: VAL CALC: If provided in the payload, check for discrepancies.

   • tax_amount = round(total_excl_tax * tax_rate / 100)

   • tax_amount: VAL CALC

   • shipping_tax = round(shipping_excl_tax * shipping_tax_rate / 100)

   • shipping_incl_tax = round(shipping_excl_tax + shipping_tax)

   • shipping_incl_tax: VAL CALC

   • total_incl_tax = round(total_excl_tax + tax_amount + shipping_incl_tax)

   • total_incl_tax: VAL CALC

   • amount = total_incl_tax

   • amount: VAL CALC: The amount field is not mandatory, but if included, it serves as a verification measure. It acts as a final check to ensure that the total amount calculated on the frontend aligns with the amount the endpoint will use for the invoice creation. Any mismatch halts the process to prevent inconsistencies.

FAQ

1️ What is Ottu's Invoice API?

Ottu's Invoice API is a tool provided by Ottu for businesses and developers to integrate invoice functionality into their systems. It automates the process of invoice generation, making it efficient for both online and walk-in customers.

2️ Why should I use Ottu's Invoice API?

Ottu's Invoice API automates the invoicing process, saving time and reducing errors associated with manual creation. It provides a seamless experience for customers and merchants, ensuring timely communication and streamlined payment collection.

3️ What are the prerequisites for integrating with Ottu's Invoice API?

Before integration, ensure you have a Purchase Payment Gateway, understand the round function, and optionally explore the Payment Methods API. For more information, please refer to Setup.

4️ Can I skip using the Payment Methods API?

Yes, if you are familiar with a specific pg_code, you can skip using the Payment Methods API. However, using it ensures you stay informed about recent payment gateways and configurations, enhancing adaptability.

5️ How do I handle authentication and permissions for Ottu's Invoice API?

Authentication can be done using Private API Key or Basic Authentication. For more information please refer to Permissions section.

6️ What are VAL CALC fields in the Invoice API?

They are optional and fields associated with the calculation of prices in an invoice. They play a crucial role in displaying accurate figures during the invoice creation process, such as Tax Amount and Shipping Including Tax. For more information, please check here.

7️ Can I modify an invoice after creation?

No, Ottu's Invoice API does not support the PATCH method. Once an invoice is created, it is immutable and cannot be modified. Any updates require creating a new invoice.

8️ How does Ottu calculate totals and taxes in the invoice?

Ottu uses a specific logic for calculating totals and taxes at both the item and invoice levels. Details are provided in the Invoice Generation Logic section of the documentation.

9️ Where can I find more technical details and implementation specifics?

For detailed technical understanding and implementation specifics, refer to Ottu's OpenAPI schema in the API Schema Reference section of the documentation.

To conclude, Ottu's Invoice API presents a powerful tool for businesses and developers, offering a seamless and automated solution for invoice generation. With a focus on user-friendly integration, the API streamlines the invoicing process, providing flexibility and customization for merchants. The comprehensive features, including detailed invoice information and generation logic, ensure accuracy and efficiency. Ottu's Invoice API stands as a valuable asset for those seeking to enhance their invoicing workflows, providing a reliable and advanced solution for a diverse range of businesses.