Auto-Debit

Introduction

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 Setup, 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.

Setup

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 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.

6. Optional: Payment Methods API Payment Methods API serves as a preliminary step to gather dynamic parameters, primarily the pg_code, required for the subsequent Checkout API 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.

Authentication

Supported Methods

• Private API Key

• Basic Authentication

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

How It Works

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: First Payment and Subsequent Payments.

• Cardholder Initiated Transactions (CIT)

  These are transactions initiated and authenticated by the cardholder. A typical example is the First Payment where the cardholder is present, providing payment details and authorizing the transaction, commonly seen in e-commerce purchases or at physical point-of-sale.

• Merchant Initiated Transactions (MIT)

  These transactions come into play during Subsequent Payments. Triggered by the merchant based on a prior agreement 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 agreement before initiating the first payment. The Agreement defines the terms for subsequent MITs, clarifying when and how the merchant can carry out these transactions.

What is an Agreement?

An agreement represents a commercial contract you establish with your payer, allowing you to store and utilize their payment details for Subsequent Transactions. This mutual understanding between you (the merchant) and the payer permits processing their payment details under specific conditions.

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.

Please be aware that the availability of specific agreement types is subject to the regulations of individual countries’ central banks. Before setting up a particular agreement, it’s essential to check its applicability in your jurisdiction. If you’re unsure or need clarity regarding the types of agreements available in your country, don’t hesitate to contact our support team at [e-mail]. We’re here to help!

Importance for Merchants:

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 agreement object.

Below table outlines mandatory and optional parameters for two agreement types: recurring and unscheduled, streamlining the agreement creation process.

type	Mandatory
recurring	id frequency amount_variability expiry_date cycle_interval_days total_cycles
unscheduled	id frequency

If you have requirements for an auto-debit type other than recurring/unscheduled or have specific customizations in mind, please don’t hesitate to contact us at [e-mail]. We’re here to support and assist you in tailoring a solution that best fits your business needs

For the First Payment, 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 Subsequent Payments based on the agreement's terms.

It's important to note that:

• Only one card can be linked with an agreement at any given time, and only that card can be charged for Subsequent Payments.

• If there's a need to change the card associated with the agreement, it can only be done through another Cardholder Initiated Transaction (CIT). This means the customer must either enter a new card or select from their saved cards the card they desire for future payments.

• 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 a comprehensive list of agreement parameters and further details, refer to the Checkout API documentation.

1️ First Payment

For the initial payment, which is a Cardholder Initiated Transaction (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 Subsequent Transactions. Here’s the flow:

1. Call Payment Methods API

   Start by fetching the pg_codes (payment gateways) which are enabled for Tokenization. This can be done by calling the Payment Methods API.

2. Call Checkout API

   After obtaining the pg_codes, call the Checkout API to create a payment transaction.

• For auto_debit transactions, it’s essential to:

  • Include the payment_type parameter set to auto_debit.

  • Ensure both the agreement (with its related subfields) and customer_id parameters are supplied, as they are mandatory. For more information about agreement, please check here.

3. 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.

4. Customer Makes Payment and Saves Card

   The customer then proceeds to pay and save their card.

5. Webhook Payemnt Notification

   After the payment is processed, Ottu will notify your webhook_url (which was provided during the Checkout API call).

Here’s what you need to know

• 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 Subsequent Payments. 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 Payment Webhook documentation.

• 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.

• Handling Lost Tokens: In case you don’t save the token or lose it, you can retrieve it using the User Cards API. Further details on this process are provided below.

• 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.

2️ Subsequent Payments

After the initial payment, subsequent payments can be automated using the Auto Debit API.

1. Call Checkout API with Consistent Parameters

   When initiating subsequent payments, call the Checkout API using the pg_code associated with the saved card. It’s crucial to maintain consistency by using the exact same agreement and customer_id as in the First Payment. 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.

2. 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.

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.

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.

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 BasicAuthbasicAuthSSO JWT Auth

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

agreement*all 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.

amount*string

Denotes the total sum of the payment transaction, which encompasses the cost of the procured items or services, excluding any supplementary fees or charges.

amount_details*all of

A comprehensive set of amount details includes: Currency Code, Amount, Total, Fee.

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.

card_acceptance_criteria*all 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.

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.

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.

extraany

The extra information for the payment details, which the merchant has sent it in key value form.

fee*string

The fee denotes the sum the customer pays in their chosen payment currency. This may vary from the transaction's designated currency. The fee is computed once to maintain precision and uniformity throughout the payment procedure.

gateway_account*string

This code corresponds to the payment gateway and plays an essential role in facilitating payment transactions.

gateway_name*string

The name of the payment gateway service being utilized.

gateway_response*object

This field stores the processed response received from the payment gateway and forwarded to Ottu.

initiatorall of

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.

is_sandboxIs Sandbox?

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

message*string

This represents the message, either transmitted by the Payment Gateway (PG) or established by Ottu, that provides a detailed illustration of the payment's current status.

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

The paid amount encompasses fees or captured amounts from authorized transactions. This total is derived from the specified 'amount' field, converting foreign currencies to the default as necessary. This might result in minor variations due to fluctuations in exchange rates.

number (double)string

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.

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.

• one_off - One Off
• auto_debit - Auto Debit

one_offauto_debit

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_amountnumber (double)

The total refunded amount for the payment transaction.

remaining_amount*number (double)

The residual amount due. Together with the editable amount, it indicates the outstanding balance of a transaction awaiting settlement.

result*enum

Indicates the outcome of the operation. success denotes a successful operation.

pendingsuccessfailedcancelederrorcod

session_idstring

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

settled_amount*number (double)

The amount that has been paid or authorized in its original currency, excluding any fees.

signature*string

Signature Field: A cryptographic hash used to guarantee data integrity and authenticity during client-server exchanges. This hash ensures that the API payload has not been tampered with, and can only be verified by authorized parties.

state*string

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

tokenCard (object)

Represents token details, only if the user pays with a tokenized card, Ottu will include the token details in the response.

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.

timestamp_utc*string (date-time)

This field represents the timestamp at which ottu processed the transaction.While this often corresponds to the payment time,it's important to note that it might not always be the case.Payments can be acknowledged at a later time,so this timestamp might not align precisely with the actual payment time.

transactionsarray of ChildPayment (object)

A list of dictionaries is generated, each containing a concise summary of each child payment transaction that has been created.

voided_amountnumber (double)

The total voided amount for the payment transaction.

Request

JavaScriptCurl

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

Response

{
  "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",
  "amount_details": {
    "currency_code": "text",
    "amount": "text",
    "total": "text",
    "fee": "text"
  },
  "capture_delivery_address": false,
  "capture_delivery_location": false,
  "card_acceptance_criteria": {},
  "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",
  "initiator": {
    "first_name": "text",
    "last_name": "text",
    "username": "text",
    "email": "[e-mail]",
    "phone": "text"
  },
  "is_sandbox": false,
  "message": "text",
  "order_no": "text",
  "paid_amount": 0,
  "payment_type": "one_off",
  "reference_number": "text",
  "refunded_amount": 0,
  "remaining_amount": 0,
  "result": "pending",
  "session_id": "text",
  "settled_amount": 0,
  "signature": "text",
  "state": "text",
  "token": {
    "brand": "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"
  },
  "timestamp_utc": "2024-04-27T06:12:00.370Z",
  "transactions": [
    {
      "amount": "text",
      "currency_code": "text",
      "order_no": "text",
      "session_id": "text",
      "state": "paid"
    }
  ],
  "voided_amount": 0
}

Guide: Step By Step

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.

First Payment Process

1. Retrieving pg_codes (Option

Before initiating the first payment, you have the option to call the Payment Methods API to retrieve the necessary pg_codes. This can be done using the following payload:

{
    "plugin": "e_commerce",
    "currencies": ["KWD", "SAR"],
    "operation": "purchase",
    "customer_id": "test",
    "tokenizable": true
}

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.

2. Initiating the Payment via Checkout API

To proceed with the payment, you’ll need to call the Checkout API. Here’s an example of the payload you might use:

{
   "type":"e_commerce",
   "amount":"200.00",
   "payment_type":"auto_debit",
   "currency_code":"KWD",
   "pg_codes":["credit-card"],
   "customer_id":"cust_123",
   "return_url":"https://yourwebsite.com/return",
   "webhook_url":"https://yourwebsite.com/webhook",
   "card_acceptance_criteria":{
      "min_expiry_time":30
   },
   "agreement":{
      "id":"A123456789",
      "amount_variability":"fixed",
      "start_date":"13/12/2023",
      "expiry_date":"01/10/2024",
      "cycle_interval_days":1,
      "total_cycles":1,
      "frequency":"daily",
      "type":"recurring",
      "seller":{
         "name":"Test-auto-debit",
         "short_name":"Test",
         "category_code":"1234"
      }
   }
}

Response:

{
   "agreement":{
      "id":"A123456789",
      "amount_variability":"fixed",
      "start_date":"13/12/2023",
      "expiry_date":"01/10/2024",
      "cycle_interval_days":1,
      "total_cycles":1,
      "frequency":"daily",
      "type":"recurring",
      "seller":{
         "name":"Test-auto-debit",
         "short_name":"Test",
         "category_code":"1234"
      }
   },
   "amount":"200.000",
   "card_acceptance_criteria":{
      "min_expiry_time":30
   },
   "checkout_url":"https://sandbox.ottu.net/b/checkout/redirect/start/?session_id=4a462681df6aab64e27cedc9bbf733cd6442578b",
   "currency_code":"KWD",
   "customer_id":"cust_123",
   "due_datetime":"13/12/2023 12:55:36",
   "expiration_time":"1 00:00:00",
   "language":"en",
   "operation":"purchase",
   "payment_methods":[
      {
         "code":"credit-card",
         "name":"Credit Card",
         "pg":"Ottu PG",
         "type":"sandbox",
         "amount":"200.000",
         "currency_code":"KWD",
         "fee":"0.000",
         "fee_description":"",
         "icon":"https://sandbox.ottu.net/media/gateway/settings/logos/MASTER-.jpeg",
         "flow":"redirect",
         "redirect_url":"https://pg.ottu.dev/checkout/c2FuZGJveC5vdHR1Lm5ldA==/Z0FBQUFBQ"
      }
   ],
   "payment_type":"auto_debit",
   "pg_codes":[
      "credit-card"
   ],
   "session_id":"4a462681df6aab64e27cedc9bbf733cd6442578b",
   "state":"created",
   "type":"e_commerce",
   "webhook_url":"https://yourwebsite.com/webhook"
}

After sending this request, you’ll be provided with a session_id. Additionally, you’ll receive at least two (redirect_url)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 Checkout SDK, utilize the received session_id to initiate the SDK on your page. This will automate the process, presenting any saved cards to the payer, if available.

• Without the Checkout SDK: If you haven’t integrated the SDK, you have the option to redirect the customer to either:

  • checkout_url:

    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 here.

  • payment_methods.redirect_url:

    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 here.

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.

For a seamless experience, we highly recommend using the Checkout SDK, 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 webhook_url. 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 subsequent payments. Since the recurring payment setup is already established with the bank, there’s no need to call the Payment Methods API again in the future. Storing the pg_code ensures you can seamlessly continue with the established payment process.

Card Acceptance Criteria

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 Checkout SDK, 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 Checkout API.

Step Summary

In this pivotal step, several key actions took place:

1. Bank Settlement: An agreement or “settlement” was established with the bank, setting the stage for future transactions.

2. Customer Consent: The customer gave their consent to save their card details, facilitating smoother future payments.

3. 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.

4. 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.

Subsequent Payments

To ensure a smooth subsequent payment process, follow these steps:

1. Pre-Charging Notifications

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.

2. Initiating the Checkout API Using the Prior pg_code

For subsequent payments, generate a new session_id 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 agreement 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.

Request:

{
   "type":"e_commerce",
   "pg_codes":[
      "credit-card"
   ],
   "customer_id":"cust_123",
   "amount":"19",
   "agreement":{
      "id":"A123456789",
      "amount_variability":"fixed",
      "start_date":"13/12/2023",
      "expiry_date":"01/10/2024",
      "cycle_interval_days":1,
      "total_cycles":1,
      "frequency":"daily",
      "type":"recurring",
      "seller":{
         "name":"Test-auto-debit",
         "short_name":"Test",
         "category_code":"1234"
      }
   },
   "payment_type":"auto_debit",
   "currency_code":"KWD"
}

Response:

{
   "agreement":{
      "id":"A123456789",
      "amount_variability":"fixed",
      "start_date":"13/12/2023",
      "expiry_date":"01/10/2024",
      "cycle_interval_days":1,
      "total_cycles":1,
      "frequency":"daily",
      "type":"recurring",
      "seller":{
         "name":"Test-auto-debit",
         "short_name":"Test",
         "category_code":"1234"
      }
   },
   "amount":"19.000",
   "card_acceptance_criteria":{
      "min_expiry_time":30
   },
   "checkout_url":"https://sandbox.ottu.net/b/checkout/redirect/start/?session_id=19aa7cd3cfc43d9d7641f6c433767b25cbcd6c18",
   "currency_code":"KWD",
   "customer_id":"cust_123",
   "due_datetime":"13/12/2023 13:41:29",
   "expiration_time":"1 00:00:00",
   "language":"en",
   "operation":"purchase",
   "payment_methods":[
      {
         "code":"credit-card",
         "name":"Credit Card",
         "pg":"Ottu PG",
         "type":"sandbox",
         "amount":"19.000",
         "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==/Z0FBQUFBQmxlYlNLWDB"
      }
   ],
   "payment_type":"auto_debit",
   "pg_codes":["credit-card"],
   "session_id":"19aa7cd3cfc43d9d7641f6c433767b25cbcd6c18",
   "state":"created",
   "type":"e_commerce"
}

3. Retrieve the session_id

The Checkout API call will return a session_id. This ID is crucial for the next step in the process. session_id: 19aa7cd3cfc43d9d7641f6c433767b25cbcd6c18.

token: 9923965822244314.

4. Initiate the AutoDebit API Call

Use the received session_id and the token from the last payment to charge the payer by calling the AutoDebit API. This call will yield one of two responses: success or failure.

• 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.

• 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 Checkout API again and provide both the expiration_time and due_datetime 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.

Request:

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

Response:

{
   "agreement":{
      "id":"A123456789",
      "amount_variability":"fixed",
      "start_date":"2023-12-13",
      "expiry_date":"2024-10-01",
      "cycle_interval_days":1,
      "total_cycles":1,
      "frequency":"daily",
      "type":"recurring",
      "seller":{
         "name":"Test-auto-debit",
         "short_name":"Test",
         "category_code":"1234"
      }
   },
   "amount":"19.000",
   "amount_details":{
      "currency_code":"KWD",
      "amount":"19.000",
      "total":"19.000",
      "fee":"0.000"
   },
   "card_acceptance_criteria":{
      "min_expiry_time":30
   },
   "currency_code":"KWD",
   "customer_id":"cust_123",
   "fee":"0.000 KWD",
   "gateway_account":"credit-card",
   "gateway_name":"mpgs",
   "gateway_response":{
      "It will contain the raw pg response sent by the pg to Ottu"
   },
   "initiator":{},
   "is_sandbox":true,
   "paid_amount":"19.000",
   "payment_type":"auto_debit",
   "reference_number":"sandboxAQ5UT",
   "result":"success",
   "session_id":"19aa7cd3cfc43d9d7641f6c433767b25cbcd6c18",
   "settled_amount":"19.000",
   "signature":"9a2043*****************",
   "state":"paid",
   "timestamp_utc":"2023-12-13 13:42:35",
   "token":{
      "customer_id":"cust_123",
      "brand":"VISA",
      "name_on_card":"test-card",
      "number":"**** 1019",
      "expiry_month":"01",
      "expiry_year":"39",
      "token":"992*********",
      "pg_code":"credit-card",
      "is_preferred":true,
      "is_expired":false,
      "will_expire_soon":false,
      "cvv_required":true,
      "agreements":[
         "k3",
         "A123456789"
      ]
   }
}

5. Payer's Manual Action

If the auto-debit fails, the payer must be notified that they need to action the payment manually using the provided checkout_url. 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.

Updating Card Information for Auto-Debit Payments

It's essential to remember that any change to the card associated with an auto-debit payment must be Cardholder Initiated Transactions (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:

1. Customer-Initiated Card Change:

• 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.

• Initiating a New Payment Session: Once the customer signals their intent, call the Checkout API to create a new session_id for the specified auto-debit or agreement payment.

• Payment Options: Offer the customer two pathways:

  • Utilize the Checkout SDK to showcase payment choices within your platform.

  • Redirect them to Ottu’s checkout_url, where they can pick an existing card or input new card details.

2. Merchant-Requested Card Change:

• 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.

• 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 Ottu’s checkout_url.

• 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 customer-initiated process—navigating 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 webhook. Make sure your system is primed to record this update.

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

Best Practices

• 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.

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️ I don’t have an agreement ID. What should I do?

If you’re lacking a specific agreement ID with the payer, you have a couple of options:

1. 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.

2. Utilize an identifier you already have in your system, such as the order ID for the Cardholder Initiated Transactions of the series.

4️ 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.

5️ 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.

6️ 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.

7️ I missed saving the card which the customer agreed to be charged. Can I get it back?

Yes, you can. Use the User Cards API and provide the agreement id for which you want to retrieve the card.

8️ Can I update an existing agreement? How?

For the moment, this feature is not live yet. If you require this functionality, please reach out to us at [e-mail].

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.