Auto-Debit

Introduction

Ottu 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 where a customer authorizes a company to deduct money from their account on a recurring basis. 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. With the power of Ottu's Auto Debit API at your fingertips, setting up recurring payments, processing one-time payments, and managing transaction records becomes a breeze. All it takes to get started is a simple integration.

In the following sections , we will guide you through the steps of installation, authentication, 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.

Installation

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.

1. 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 Payment Gateway User Guide.

2. Checkout API: Before you call the Auto Debit API, the Checkout API must be used to create a payment transaction. This is where important details such as the amount, customer data, and more are added. Once the payment has been created via the Checkout API, a session_id will be generated. This session_id is a key parameter for the Auto Debit API.

3. Tokenization and User Cards API: Understanding and utilizing the Tokenization and User Cards 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 retrieve 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 User Cards API and the concept of tokenization is crucial to the successful implementation of the Auto Debit API.

4. Payment Webhook Response: Lastly, you need to be familiar with the Payment Webhook response. This response is returned by the Auto Debit API, providing important information about the transaction status.

5. 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. By integrating the Checkout SDK into your system, you can significantly streamline the payment process, enhance user experience, and ensure secure transactions. Although it's not a strict prerequisite, using the Checkout SDK can simplify your work and make the process of integrating the Auto Debit API much smoother.

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.

How It Works

Ottu's Auto Debit API process involves two primary phases - The First Payment and Subsequent Payments. Let's dive into each step:

1️ First Payment

For the initial payment, the payer must be online to initiate and perform the transaction. During this process, the payer can opt to save their card for future automatic payments. Here's the flow:

• Call Payment Methods API: Start by fetching the pg_codes (payment gateways) which are enabled for auto-debit. This can be done by calling the Payment Methods API.

• Call Checkout API: Once you have the pg_codes, call the Checkout API to create a payment transaction. In order to provide the option for the payer to save their card for future payments, it is mandatory to include the customer_id parameter.

• Present Payment Options to Payer: Now, present the payment options to the payer. You can either use the payment_methods response from the Checkout API or use the Checkout SDK. The SDK does the heavy lifting by rendering all payment options and capturing the payment.

• Customer Makes Payment and Saves Card: The customer then proceeds to pay and save their card.

• Merchant Receives Notification: Once the payment is made, your webhook_url gets notified about the payment. You can then save the card details in your database for future transactions.

2️ Subsequent Payments

After the initial payment, you can automate subsequent payments using the Auto Debit API.

• Call Checkout API: Start by calling the Checkout API to create a payment transaction. Remember to use the pg_code associated with the saved card, and the customer_id value that was used for the initial payment.

• Call Auto Debit API: Now, call the Auto Debit API using the session_id from the Checkout API and the card/token you wish to use to charge the customer.

• The automated debit process is now initiated, and the payment will be processed automatically without the need for the payer to be online.

• Keep in mind that this process assumes that the payer has agreed to have their card saved and enabled for auto-debit during the first payment.

This diagram visually represents the steps needed to set up subsequent payments. After calling the Checkout API, you then call the Auto Debit API using the session_id and card/token. The payment is then processed automatically, eliminating the need for the payer to manually authorize each transaction.

3️ Updating Card Information

There might be instances where the card linked to automatic payments might expire or the customer may want to change the card being used. Here's how you can handle such scenarios:

• Customer Has Other Saved Cards If the customer has other saved cards, you can fetch these by calling the User Cards API. Present the available cards to the customer and let them select the one they wish to use for ongoing payments. Save the chosen card details and use it for future transactions.

• Customer Does Not Have Saved Cards If the customer does not have any other saved cards, you will need to repeat the process used for the first payment. The customer will need to complete a payment and save a new card.

In both cases, always remember to update the saved card information in your database for future automatic payments.

Authentication

The Auto Debit API utilizes API Key Authentication to ensure secure communication and prevent unauthorized access. Before making requests to the API, you need to generate an API Key from your Ottu account. Once you have the API Key, it needs to be included in the header of each API request. To understand in detail how API Key authentication works and how you can generate your API Key, please refer to Authentication User Guide. Always ensure to keep your API Key secret. If you believe your API Key has been compromised, regenerate it immediately from your Ottu account.

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

API Schema Reference

Auto debit endpoint for auto debit payment flow

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.

POST/b/pbl/v2/auto-debit/

Authorization

SSO JWT AuthjwtAuthtokenAuthbasicAuthSSO BasicAuth

Body

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

session_id*string

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

token*string

Use this field to provide the unique identifier of a saved customer card for processing a payment in the API request.

Response

200400401

Body

application/json

amount*string

Amount of the transaction

amount_details*all of

Details of the transaction amount.

capture_delivery_addressboolean

By enabling this, you will ask for user's address. If enabled, capture delivery coordinates should also be active.

capture_delivery_locationCapture delivery coordinates

By enabling this, you will ask for user's delivery location on a map.

currency_code*string

The currency in which the transaction is denominated. However, it does not guarantee that the payment must be made in this currency, as there can be currency conversions or exchanges resulting in a different currency being charged.

customer_address_citystring

The city of the customer's billing address. This field may be used to send the billing address to the payment gateway.

customer_address_country*string

The country of the customer's billing address, formatted as a two-letter ISO country code (e.g., 'US' for United States, 'CA' for Canada). This field may be used to send the billing address to the payment gateway.

customer_address_line1Customer address line 1

The first line of the customer's billing street address. This field may be used to send the billing address to the payment gateway.

customer_address_line2Customer address line 2

The second line of the customer's billing street address, if available. This field may be used to provide additional address information, such as an apartment or suite number.

customer_address_postal_codestring

The postal code of the customer's billing address. This field may be used to send the billing address to the payment gateway.

customer_address_statestring

The state or region of the customer's billing address. This field may be used to send the billing address to the payment gateway.

customer_emailstring

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.

extraobject

fee*string

fee paid by the customer in the currency he made the payment, can be different from the currency of the transaction Fee must be calculated only once

gateway_account*string

The payment gateway code, which is utilized to proceed the payment.

gateway_name*string

The payment gateway name.

gateway_response*object

The response from the payment gateway.

is_sandboxIs Sandbox?

Indicates whether the operation was performed in a test environment or not.

message*string

Message sent by PG or set by Ottu to illustrate the status of the payment.

token*all of

order_nonullable string

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

paid_amount*one of

paid amount included fee or captured amount for authorized transaction.

Calculate the amount of the transaction based on the amount field If the transaction is paid in the same currency, simply return the amount from the payment attempt else try to convert from foreign currency to default. This might cause discrepancy in the amount if the exchange rate has changed

number (double)string

reference_number*string

An auto-generated internal identifier for this payment transaction. While this field may be used for tracking and reporting purposes, it is recommended to use the session_id field instead, as it provides the same functionality and more.

refunded_amount*number (double)

remaining_amount*number (double)

remaining amount to be paid, plays together only with editable amount

result*all of

session_idstring

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

settled_amount*number (double)

paid or authorized amount in the original currency without fee

state*string

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

transaction_log_idnullable integer (int64)

Identifies the transaction log associated with the payment transaction. A transaction log is created for each record that is dispatched during a bulk dispatch process.

transactions*array of ChildPayment (object)

voided_amount*number (double)

initiator*all of

Transaction initiator details.

Request

JavaScriptCurl

const response = await fetch('/b/pbl/v2/auto-debit/', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "session_id": "text",
      "token": "text"
    }),
});
const data = await response.json();

Response

{
  "amount": "text",
  "amount_details": {
    "currency_code": "text",
    "amount": "text",
    "total": "text",
    "fee": "text"
  },
  "capture_delivery_address": false,
  "capture_delivery_location": false,
  "currency_code": "text",
  "customer_address_city": "text",
  "customer_address_country": "text",
  "customer_address_line1": "text",
  "customer_address_line2": "text",
  "customer_address_postal_code": "text",
  "customer_address_state": "text",
  "customer_email": "text",
  "customer_first_name": "text",
  "customer_id": "text",
  "customer_last_name": "text",
  "customer_phone": "text",
  "fee": "text",
  "gateway_account": "text",
  "gateway_name": "text",
  "is_sandbox": false,
  "message": "text",
  "token": {
    "brand": "text",
    "auto_debit_enabled": "text",
    "customer_id": "text",
    "cvv_required": false,
    "expiry_month": "text",
    "expiry_year": "text",
    "is_expired": false,
    "is_preferred": false,
    "name_on_card": "text",
    "number": "text",
    "pg_code": "text",
    "token": "text"
  },
  "order_no": "text",
  "paid_amount": 0,
  "reference_number": "text",
  "refunded_amount": 0,
  "remaining_amount": 0,
  "result": {},
  "session_id": "text",
  "settled_amount": 0,
  "state": "text",
  "transactions": [
    {
      "amount": "text",
      "currency_code": "text",
      "order_no": "text",
      "session_id": "text",
      "state": {}
    }
  ],
  "voided_amount": 0,
  "initiator": {
    "first_name": "text",
    "last_name": "text",
    "username": "text",
    "email": "[e-mail]",
    "phone": "text"
  }
}

Examples

First Payment

Suppose the initial payment is being made and the payer has opted to save their card details. Here's an example of a request to the Checkout API:

POST: https://<ottu-url>/b/checkout/v1/pymt-txn/
{
  "amount": "2000",
  "type": "type", // Available choices are `payment_request` or `e_commerce`.
  "currency": "USD",
  "pg_code": "PG001",
  "customer_id": "CustomerID",
  "redirect_url": "https://yourwebsite.com/return",
  "webhook_url": "https://yourwebsite.com/webhook"
}

This request will return a session_id which you need to save and use for the subsequent payments.

Subsequent Payments

When making subsequent payments, the Auto Debit API will be used. Here's an example:

POST: https://<ottu-url>/b/pbl/v2/auto-debit/
{
  "session_id": "sess_123",
  "token": "token_123"
}

This request will return a response indicating whether the transaction was successful.

Updating Card

If the card has expired or the customer wants to switch the card, you can fetch the saved cards of the customer by calling the User Cards API. Here's an example:

GET: https:<ottu-url>/b/pbl/v2/card?type=sandbox&pg_codes=PG001&customer_id=CustomerID

This will return a list of saved cards for that customer. You can present these options to the customer and let them select the card they want to use for future payments.

For a scenario where the customer does not have other saved cards, the first payment process needs to be repeated.

Please note that the above examples are illustrative and the actual API calls would depend on the specific configuration of your Ottu setup.

FAQ

1️ Can I use the Auto-Debit feature even if I'm not PCI DSS compliant?

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

2️ Can I store card tokens in my database if I'm not PCI DSS compliant?

Yes, you certainly can. Ottu uses tokenization 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 this for a deeper dive.

3️ When should I save the card token in my database?

The optimal time to save the card token in your database is immediately after the first payment against the subscription that you plan to auto-debit. While it's not strictly necessary—you can always fetch this information through the User Cards API and Payment Methods APIs—it does streamline your processes and reduce development complexity.

4️ How can I add a new card for a customer?

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.

5️ Do I need to use the Checkout SDK to display payment options to the customer?

No, it's not mandatory to use the Checkout SDK. You can control the payment process using the responses from the Checkout API. However, it's worth noting that the Checkout SDK simplifies the UI implementation and is necessary for certain payment methods such as Apple Pay, 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.

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.