Auto-Debit
Last updated
Last updated
Welcome to the Ottu Auto Debit API documentation. Our API provides businesses and developers with the ability to incorporate Ottu's auto-debit functionality into their existing systems, allowing for seamless and automated payment processing.
But what is auto debit? Auto debit is a financial arrangement wherein a customer authorizes a company to deduct money from their account, whether on a recurring basis, an unscheduled basis, or potentially in the future, the deduction could occur on an event-based, installment, or other specified terms. The frequency and amount of these deductions are determined in advance and can vary depending on the type of agreement, be it a subscription, a loan repayment, or any other kind of periodic payment.
Imagine you are a merchant providing a monthly subscription service to your customers. Each month, you need to charge your customers, but the process becomes tedious when you have to remind them to make the payment or when they have to manually make the payment each time. This is where the auto debit functionality shines. With Ottu's Auto Debit API, you can schedule these charges automatically, ensuring seamless business operations and improving customer experience, all while saving valuable time and effort.
In the following sections, we will guide you through the steps of , , and how to use the various endpoints available. This will give you the tools and knowledge needed to fully leverage the capabilities of the Ottu Auto Debit API.
Before you can integrate with Ottu's Auto Debit API, there are several prerequisites that need to be fulfilled. These prerequisites are essential to ensure that the API functions correctly and securely.
Payment Gateway: A Payment Gateway with auto debit enabled is required for the API to work. The Payment Gateway is a tool that authorizes and processes transactions between you and your customers. For a detailed understanding of what a Payment Gateway is and how it functions, please refer to our User Guide.
Checkout API:
Before you call the Auto Debit API, the must be used to create a payment transaction. This is where important details such as the , customer data, and more are added. Once the payment has been created via the Checkout API, a will be generated. This session_id is a key parameter for the Auto Debit API.
Tokenization and User Cards API:
Understanding and utilizing the and API is an essential step in the process. In order to handle transactions securely and keep sensitive data such as card information safe, Ottu uses a process called tokenization. When a user saves a card, the sensitive card data is replaced with a unique token generated by the PG.
In the context of the Auto Debit API, you will need to these tokens (i.e., the saved card details of the customer) by calling the User Cards API. The tokens received from this API call are used to identify which card will be used for the auto debit process, ensuring a secure transaction without exposing sensitive customer information. Thus, getting familiar with the and the concept of is crucial to the successful implementation of the Auto Debit API.
Payment Webhook Response:
Lastly, you need to be familiar with the . This response is returned by the Auto Debit API, providing important information about the transaction status.
Optional: Checkout SDK
As an optional but highly recommended step, you can utilize our Checkout SDK. This software development kit does the heavy lifting for you by handling tasks such as rendering all the payment methods, showing saved cards, and giving payers the option to save their card for future transactions.
Optional: Payment Methods API
The serves as a preliminary step to gather dynamic parameters, primarily the , required for the subsequent call. Think of it as a preparatory API call that equips you with the necessary “ammunition” for the main transactional API.
Why is it optional?
If you’re already aware of the specific pg_code you intend to use consistently, you can bypass this step by storing that pg_code directly in your system. However, invoking the Payment Methods API ensures that you’re always updated with the latest available payment gateways or any changes in the configuration. This dynamic approach ensures a more resilient and adaptable integration with Ottu.
Once you've fulfilled these prerequisites, you're ready to integrate the Auto Debit API. The following sections of this document will guide you through the authentication process and the usage of various API endpoints.
To optimize the integration of your Auto-Debit API, our official packages are designed to simplify the process significantly. These packages efficiently manage the complexities of API integration, enabling you to concentrate on the essential aspects of your project.
Here are the currently available packages:
To fully leverage these packages, a thorough understanding of the foundational concepts and structures detailed in the documentation is essential for effective and sustainable integration.
Supported Methods
Examples include:
Recurring Payments: Regular payments, like a mobile phone subscription, where the payer authorizes billing at intervals (e.g., monthly). The amount can be fixed or variable.
Installment Payments: An arrangement to split a single purchase into multiple payments at defined intervals, like six monthly installments.
Unscheduled Payments: Where the payer authorizes automatic deductions for a payment when required, such as auto top-ups when an account balance is low.
Other: Agreements that don’t fit the recurring, installment, or unscheduled categories, like split tender payments.
Below table outlines mandatory and optional parameters for two agreement types: recurring and unscheduled, streamlining the agreement creation process.
recurring
id
frequency
amount_variability
expiry_date
cycle_interval_days
total_cycles
unscheduled
id
frequency
It's important to note that:
Even if a customer has multiple saved cards in their account, only the card specifically selected for the auto-debit payment can be charged. Other cards in the customer's account cannot be used for this agreement.
For auto_debit transactions, it’s essential to:
Include the payment_type parameter set to auto_debit.
The customer then proceeds to pay and save their card.
Multiple Tokens: The merchant should pass the Agreement ID as a parameter to distinguish between a customer's tokens, especially when the customer possesses multiple tokens.
Card and Agreement Association: When a payment is made via auto-debit, the agreement.id value will be linked with the saved card. Ottu manages this association automatically. This means that if a payer decides to use a different card for subsequent payments, Ottu will handle the transition by disassociating the agreement.id from the previous card and linking it to the new one. It’s important to note that an agreement.id can only be associated with one card at a time. This automated management ensures that you always have the correct card details associated with the agreement, simplifying the process for subsequent payments.
The automated debit process is now initiated, and the payment will be processed automatically without the need for the payer to be online.
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.
Navigating the world of digital payments can be intricate. Whether you’re processing an initial payment or managing subsequent transactions, each step is crucial to ensure a seamless experience for both merchants and payers. This guide provides a detailed walkthrough, from the moment a customer decides to save their card details to the intricacies of handling recurring charges.
Why Consider This Step? While this step is optional, it offers several advantages:
Flexibility: If you’re uncertain about the pg_code or anticipate it might change in the future, this step ensures you always have the most up-to-date code.
End-to-End Integration: By retrieving the pg_codesdynamically, you ensure a seamless integration with Ottu. This means that any changes in the configuration, such as a code alteration or the addition of a new payment gateway, will be automatically reflected in your system.
Hardcoding Alternative: If you’re confident that the pg_code will remain consistent and won’t change, you can opt to hardcode it directly into your system. This approach might simplify the process but could require updates if there are changes on Ottu end.
If the payer has previously saved cards associated with the pg_code used to create the payment, it’s advisable to redirect them to the checkout_url. Otherwise, use the payment_methods.redirect_url.
In this pivotal step, several key actions took place:
Bank Settlement: An agreement or “settlement” was established with the bank, setting the stage for future transactions.
Customer Consent: The customer gave their consent to save their card details, facilitating smoother future payments.
Card Tokenization: The customer’s card was tokenized, converting sensitive card details into a secure token. If the customer already had a tokenized card, they could use it to authorize the payments.
Ready for Future Charges: With these foundational steps completed, everything is now in place! All that remains is to initiate charges as and when they’re due.
Wohoo! The groundwork is laid, and you’re all set to process subsequent payments effortlessly.
To ensure a smooth subsequent payment process, follow these steps:
Before the charging day, it’s recommended to send the payer 1-2 email notifications, ideally one week before and then one day before the scheduled charge. This serves as a reminder to ensure they have the necessary funds available or to go online and modify the card they wish to use for the payment.
token: 9923965822244314.
Success: If you receive a success response, it indicates that the payment was processed successfully. You can then notify the payer about the successful payment.
Navigation: The customer visits your website and heads to the auto-debit payment management section with the intent to modify the card linked to their ongoing auto-debit payment.
Payment Options: Offer the customer two pathways:
Utilize the Checkout SDK to showcase payment choices within your platform.
Reason for Change: There may be scenarios where you, as a merchant, need the customer to switch their card. Common reasons include impending card expiration or failed payment attempts.
Recurring Payment Schedule: It’s essential to be aware of the frequency of these subsequent payments, whether they’re set to be weekly, monthly, or based on another schedule. This helps in anticipating the transaction and ensuring everything runs smoothly.
Record Keeping: For every transaction made, maintain a detailed record. This aids in account reconciliation, handling customer queries, and staying compliant with any financial regulations.
Regular Customer Communication: Apart from the essential notifications, keep your customers in the loop with regular updates about their subscription or payment plan. This can foster trust and ensure they see the value in the service they’re paying for.
Instant Payment Access: In all your notifications, include a direct link—either to the Ottu checkout_url or to the auto-debit payment management section on your platform. This simplifies the process for customers who might want to immediately settle due payments or change their associated card details.
Stay Updated: Periodically review your Ottu integration. With the ever-evolving digital landscape, it’s crucial to ensure you’re leveraging the latest features and adhering to the most recent security protocols.
Absolutely. With Ottu, you don't have to worry about PCI DSS compliance. Our platform securely handles all the sensitive data and never exposes this information to the merchant. This means you can safely implement the auto-debit feature just like any other Rest API
Create a new agreement ID specifically for interacting with the gateway. Remember to save this id and present it to the gateway for all related payments, encompassing the cardholder initiated transaction.
Currently, the only way to save a new card is by having the customer successfully complete a payment with it. At the moment, it's not possible to just save new card details directly.
For the moment, this feature is not live yet. If you require this functionality, please reach out to us at support@ottu.com.
As we come to the end of this guide to Ottu's Auto Debit API, we hope you found it comprehensive and instructive. This document has aimed to demystify the process of integrating our API into your system, equipping you with the necessary insights to employ auto-debit payments effectively.
Should you have more specific queries or require further guidance, we urge you to reach out to our dedicated support team. Their expertise is available to help you navigate any complexities you encounter during integration.
At Ottu, we believe in simplifying payments and enhancing user experience. We're confident that with the Auto Debit API, you'll have the tools at your disposal to achieve seamless, automated transactions. Thank you for choosing Ottu, and we look forward to powering your business's payment solutions.
Python SDK: Enhances access to auto-debit functionalities through a Pythonic interface, effectively abstracting the intricacies of API calls to boost developer efficiency.
Django SDK: Integrates auto-debit features smoothly into Django-based applications, providing Django-specific enhancements that streamline auto-debit transactions.
For detailed information on authentication procedures, please refer to the .
Ottu’s Auto Debit API process is intricately designed to navigate the nuances of both cardholder and merchant initiated transactions. This process revolves around two primary phases: and .
These are transactions initiated and authenticated by the cardholder. A typical example is the where the cardholder is present, providing payment details and authorizing the transaction, commonly seen in e-commerce purchases or at physical point-of-sale.
These transactions come into play during . Triggered by the merchant based on a prior with the cardholder, they are frequently observed in scenarios like monthly subscriptions or certain installment payments.
For a smooth transaction process, it’s important to understand the role of an before initiating the first payment. The Agreement defines the terms for subsequent MITs, clarifying when and how the merchant can carry out these transactions.
An agreement represents a commercial contract you establish with your payer, allowing you to store and utilize their payment details for . This mutual understanding between you (the merchant) and the payer permits processing their payment details under specific conditions.
Before utilizing Ottu's auto-debit feature, it is crucial to confirm the existence of the necessary agreement. For more information about the agreement parameters, please refer to the details in the .
For the , the agreement lays the foundation by defining the terms under which the initial transaction takes place. During this step, the customer selects the specific card they wish to associate with the auto-debit payment. This chosen card will be the only one charged for all based on the agreement's terms.
Only one card can be linked with an at any given time, and only that card can be charged for .
If there's a need to change the card associated with the agreement, it can only be done through another (CIT). This means the customer must either enter a new card or select from their saved cards the card they desire for future payments.
For a comprehensive list of agreement parameters and further details, refer to the .
For the initial payment, which is a (CIT), the payer must be online to initiate and perform the transaction. With the auto_debit for payment_type parameter, the payer’s card will be automatically saved for . Here’s the flow:
Start by fetching the (payment gateways) which are enabled for . This can be done by calling the Payment Methods API.
After obtaining the pg_codes, call the to create a payment transaction.
Ensure both the (with its related subfields) and parameters are supplied, as they are mandatory. For more information about agreement, please check .
Now, present the payment options to the payer. You can either use the response from the or use the . The SDK does the heavy lifting by rendering all payment options and capturing the payment.
After the payment is processed, Ottu will notify your (which was provided during the Checkout API call).
Token Retrieval: The notification to your webhook_url will contain the saved card details in the token field. It’s crucial to always save this token, even for . This is because the payer might choose a different card for future auto-debit payments. For a detailed schema of the notification, refer to the .
Handling Lost Tokens: In case you don’t save the token or lose it, you can retrieve it using the . Further details on this process are provided below.
After the , subsequent payments can be automated using the Auto Debit API.
When initiating subsequent payments, call the using the associated with the saved card. It’s crucial to maintain consistency by using the exact same and as in the . Ottu will handle the task of sending the required parameters to the bank, ensuring a seamless transaction process. For Parameter Updates: Avoid sending updated parameters for subsequent payments, as they will have no effect. The method to update the agreement will be discussed in a later section.
Now, call the Auto Debit API using the from the and the card/token you wish to use to charge the customer.
This diagram visually represents the steps needed to set up subsequent payments. After calling the , you then call the Auto Debit API using the and card/token. The payment is then processed automatically, eliminating the need for the payer to manually authorize each transaction.
Before initiating the first payment, you have the option to call the to retrieve the necessary . This can be done using the following payload:
To proceed with the payment, you’ll need to call the . Here’s an example of the payload you might use:
After sending this request, you’ll be provided with a . Additionally, you’ll receive at least two ()s. These URLs are essential as they guide the customer through the subsequent stages of the payment process.
Using the Checkout SDK: If you’ve integrated the , utilize the received to initiate the SDK on your page. This will automate the process, presenting any saved cards to the payer, if available.
This URL leads the payer to an Ottu page where any saved cards are displayed, and they also have the option to save a new card. for more information about redirect_url, check .
This URL takes the payer directly to the payment page where they can input their card details. More information about payment_methods objects could be found .
For a seamless experience, we highly recommend using the , which handles these decisions and processes automatically.
Once the customer completes the payment, the card will be saved and associated with the agreement.id that was provided earlier. A notification will then be sent to your . Within this notification, the saved card will be represented by a parameter named token. It’s crucial to securely save both the token and the pg_code used for this payment. The pg_code is especially important for . Since the recurring payment setup is already established with the bank, there’s no need to call the again in the future. Storing the pg_code ensures you can seamlessly continue with the established payment process.
It’s noteworthy that the payload includes card_acceptance_criteria.min_expiry_time = 30. This parameter ensures that for this specific payment, any attempt by the customer to add a new card or select a card via the , which has an expiration time not exceeding the current date plus 30 days, will be declined. Tailoring this field according to your operational requirements is crucial to prevent the acceptance of cards nearing their expiration. Ideally, a validity buffer of at least one month should be considered.
Furthermore, parameters under card_acceptance_criteria, like exclude_bins (allowing only specific BINs to pay), are applicable only for pg_codes that are on direct payment integration and not for hosted sessions. For a comprehensive list of card_acceptance_criteria, refer to the .
For subsequent payments, generate a new by initiating a new payment transaction using the Checkout API, and this transaction should incorporate the pg_code from the previous successful transaction. This is either associated with the current or derived from the initial payment. While supplying other parameters, ensure consistency with the initial payment setup. Remember, the amount might differ if your agreement allows for variable amounts.
The call will return a . This ID is crucial for the next step in the process.
session_id: 19aa7cd3cfc43d9d7641f6c433767b25cbcd6c18.
Use the received session_id and the token from the last payment to charge the payer by calling the . This call will yield one of two responses: success or failure.
Failure: In the event of a failed payment, notify the payer about the payment failure and provide the reason, which will be sent to you by Ottu. At this stage, update the payment session_id by calling the again and provide both the and parameters to set a grace period for the customer, for example, 3 days. While waiting for the customer to attempt a manual payment, it’s recommended to try charging again after 24 hours, in case the customer has added funds or resolved the issue with their card.
If the auto-debit fails, the payer must be notified that they need to action the payment manually using the provided . When they access the link, they will be directed to make the payment, which can be done using an existing card or by entering a new card’s details.
It's essential to remember that any change to the card associated with an auto-debit payment must be (CIT). The customer must be actively involved and give consent when updating or selecting a different card for existing auto-debit payments. Here’s how this process can be facilitated:
Initiating a New Payment Session: Once the customer signals their intent, call the to create a new for the specified auto-debit or agreement payment.
Redirect them to, where they can pick an existing card or input new card details.
Communication: When such a situation arises, notify the customer via email or SMS. The communication should include a link to either your platform’s auto-debit payment management or .
Customer Action: The email/SMS serves as an invitation for the customer to make necessary card changes. They’ll need to follow the same steps as in the to the designated link, initiating a new session, and completing a payment.
Completion: Like in the previous scenario, any new card details are shared with your system through a . Make sure your system is primed to record this update.
Yes, you certainly can. Ottu uses to ensure that your customer's Primary Account Number (PAN) is never exposed. What you receive and can safely store is a token, not an actual card number. It's structured like a card number but doesn't carry the same security risks. If you're curious about how tokenization works, you can check out for a deeper dive.
If you’re lacking a specific agreement with the payer, you have a couple of options:
Utilize an identifier you already have in your system, such as the order ID for the of the series.
The optimal time to save the card token in your database is immediately after the against the subscription that you plan to auto-debit. While it's not strictly necessary—you can always this information through the and Payment Methods APIs—it does streamline your processes and reduce development complexity.
No, it's not mandatory to use the . You can control the payment process using the responses from the . However, it's worth noting that the Checkout SDK simplifies the UI implementation and is necessary for certain payment methods such as , Google Pay, STC Pay, and others. While it's recommended to use the Checkout SDK for its simplicity and comprehensive features, the choice ultimately lies in your hands based on your specific needs.
Yes, you can. Use the and provide the agreement id for which you want to retrieve the card.
This endpoint will take a session id and check for it's related payment if it's possible to be auto charged or not. if possible it will charge the payment and return the operation response. 📝 NOTE Optional fields may not be represented in response body.
Auto debit serializer should take session_id and consumer payment token then validate if session id is valid if session id is valid then validate if payment gateway supports auto debit if payment gateway supports auto debit then validate if payment gateway has implemented auto debit if payment gateway has implemented auto debit then charge the token and return charge response from client auto_debit method which should be implemented in client
A unique identifier for each payment transaction, used to maintain the session state during the payment process.
Use this field to provide the unique identifier of a saved customer card for processing a payment in the API request.