Invoice API
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.
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.
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 theInvoice 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.Optional:
round
function When offering customer-facing invoice generation, it's essential to display precise figures supported by clear formulas. Theround
function is pivotal in achieving this accuracy.
How round
funtion works?
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:
Establish Precision: Begin by determining the number of decimal digits permitted for the currency involved, according to ISO 4217 Currency Codes.
Identify the Rounding Digit: Locate the digit immediately to the right of the desired precision. This digit is pivotal in determining the rounding outcome.
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:
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 specificpg_code
you plan to use consistently, you have the option to skip this step by directly storing thatpg_code
in your system. However, utilizing thePayment 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.
Boost Your Integration
Optimize your integration with the Invoice API
using our official packages, designed to significantly simplify the process. These packages efficiently handle the complexities of API integration, allowing you to focus on the critical elements of your project.
Available Packages:
Python SDK: Enhances access to invoice functionalities through a Pythonic interface, effectively abstracting the intricacies of API interactions to boost developer efficiency. Learn more
Django SDK: Seamlessly integrates invoice features into Django-based applications, providing Django-specific enhancements that streamline invoice transactions. Continue exploring
While these packages enhance speed and convenience, understanding the foundational concepts detailed in the documentation is essential for robust and sustainable integration.
Supported Methods
For detailed information on authentication procedures, please refer to the Authentication documentation.
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
.
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:
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.
Integration with Ottu Checkout API:
Invoice API
seamlessly integrates with the Ottu Checkout API to generate a checkout_url.
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.
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.
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.
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.
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.
- 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.
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.
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 thePATCH
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.
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:
Prior to initiating the initial payment, you can choose to invoke the Payment Methods API to obtain the required pg_codes.
Using a payload as minimal as the one below, you can obtain an invoice.
Request
Response
The URL for the invoice PDF in the above response is:
Applying a discount percentage of 12 to the invoice_items
object within the Invoice API
request payload:
Invoice:
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.
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.
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:
Calculate
quantity_price
: round(quantity
*unit_price
)Calculate the discount on the item:
If both
discount_percentage
anddiscount_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 thanquantity_price
and store it intotal_discount
.total_discount
= round(total_discount
) for proper number handling.
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
Store results for use on the Invoice level.
Invoice Level:
Calculate subtotal by:
subtotal = 0
Loop over items:
subtotal
= round(subtotal
+item.total_incl_tax
)subtotal
:VAL CALC
Calculate the discount on the invoice:
If both
discount_percentage
anddiscount_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 thesubtotal
and store it intotal_discount
.total_discount
= round(total_discount
) for proper number handling.
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
: Theamount
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.
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.
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.
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.
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.
Authentication can be done using Private API Key or Basic Authentication. For more information please refer to Permissions section.
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.
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.
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.
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.
Last updated