Recurring Payments & Auto-Debit

Auto-debit is a financial arrangement where a customer authorizes a merchant to automatically deduct money from their saved card. This covers subscriptions, installments, recurring billing, and event-based charges — all processed without the customer needing to be present after the initial setup.

Boost Your Integration

Ottu offers SDKs and tools to speed up your integration. See Getting Started for all available options.

When to Use

• Subscriptions — monthly or annual recurring charges for SaaS, memberships, or content
• Installment payments — split a single purchase into multiple scheduled charges
• On-demand billing — charge customers when events occur (e.g., account top-ups, usage-based billing)
• Recurring invoices — automatically collect payment on invoice due dates

Setup

Before implementing auto-debit, ensure you have:

• A Payment Gateway with auto-debit capability enabled
• The Checkout API for creating payment sessions
• Tokenization set up — cards must be tokenized before they can be auto-debited
• A webhook endpoint configured to receive payment notifications
• Familiarity with the User Cards API for card management

Guide

Key Concepts

Auto-debit payments involve two types of transactions:

• CIT (Cardholder Initiated Transaction) — The first payment where the customer is present, enters their card details, and authorizes future charges. This establishes the agreement and saves the card token.
• MIT (Merchant Initiated Transaction) — Subsequent automatic charges triggered by the merchant using the saved token. The customer is not present during these transactions.

Agreement

An agreement is a commercial contract between you and your customer that authorizes you to store and use their payment details for subsequent transactions. Each agreement has:

• A unique id that you define
• A type (recurring, unscheduled, or installment)
• Scheduling parameters (frequency, cycle_interval_days, total_cycles, expiry_date)
• Amount rules (amount_variability: fixed or variable)

warning

Only one card can be linked to an agreement at any time. To change the card, a new CIT (customer-present) transaction is required.

Agreement Types

Type	Use Case	Required Fields
Recurring	Subscriptions, regular billing	id, frequency, amount_variability, expiry_date, cycle_interval_days, total_cycles
Unscheduled	On-demand charges (e.g., account top-ups)	id, frequency
Installment	Split payments for a single purchase	id, frequency, amount_variability, expiry_date, cycle_interval_days, total_cycles, seller

Workflow

1. CIT — Merchant creates a session with payment_type: auto_debit and an agreement object.
2. Payment — Customer enters their card via the Checkout SDK or hosted page and completes 3DS authentication.
3. Webhook — Ottu delivers the token. Save token.token and token.pg_code for future charges.
4. MIT — Merchant charges the token by creating a new session, then calling the Native Payments API (or using One-Step Checkout).
5. Result — The Native Payments API (or One-Step Checkout) returns the payment result directly in the API response — there is no webhook for MIT charges. No customer interaction needed.

Live Demo

Experience the complete recurring payment lifecycle. Save a test card, watch the webhook deliver the token in real time, then charge the card automatically — choose between Two-Step or One-Step checkout.

Test Card

Use card number 5123 4500 0000 0008 with expiry 01/39 and CVV 100.

Try Recurring Payments

Experience the full CIT/MIT flow: save a card with a test payment, then charge it automatically — all in sandbox mode.

Step-by-Step

First Payment (CIT)

Step 1 of 4

Step 1 of 4

Discover Payment Methods

Create Payment Session

Collect Card Details

Receive Webhook with Token

Before creating a session, call the Payment Methods API with auto_debit: true to discover which gateways support tokenization and auto-debit.

POST /b/pbl/v2/payment-methods/

{
"plugin": "payment_request",
"operation": "purchase",
"currencies": ["KWD"],
"auto_debit": true
}

Use the returned pg_codes in the next step.

Create a session with payment_type: auto_debit and the agreement object. Use a unique customer_id per customer — all future MIT charges and saved cards are associated with this ID.

POST /b/checkout/v1/pymt-txn/

{
"type": "e_commerce",
"amount": "200.00",
"payment_type": "auto_debit",
"currency_code": "KWD",
"pg_codes": ["credit-card"],
"customer_id": "cust_123",
"webhook_url": "https://yourwebsite.com/webhook",
"agreement": {
  "id": "A123456789",
  "type": "recurring",
  "amount_variability": "fixed",
  "start_date": "01/04/2026",
  "expiry_date": "01/04/2027",
  "cycle_interval_days": 30,
  "total_cycles": 12,
  "frequency": "monthly",
  "seller": {
    "name": "Your-Business-Name",
    "short_name": "YBN",
    "category_code": "1234"
  }
}
}

Collect the customer's card using one of these options:

• Checkout SDK (recommended) — initialize with the session_id
• Redirect to checkout_url — sends the customer to Ottu's hosted checkout page
• Redirect to payment_methods.redirect_url — sends the customer directly to a specific gateway's card entry page

After the customer completes the payment, Ottu sends a webhook notification with the token:

{
"session_id": "4a462681df6aab64e27cedc9bbf733cd6442578b",
"result": "success",
"state": "paid",
"payment_type": "auto_debit",
"customer_id": "cust_123",
"agreement": {
  "id": "A123456789",
  "type": "recurring"
},
"token": {
  "token": "9923965822244314",
  "customer_id": "cust_123",
  "brand": "VISA",
  "number": "**** 1019",
  "pg_code": "credit-card",
  "agreements": ["A123456789"]
}
}

Save the token.token and token.pg_code — you'll need them for subsequent charges.

Subsequent Payments (MIT)

Once you have the token, you can charge the customer automatically using either of the following approaches.

Two-Step (Checkout API + Native Payments API):

1. Create a new session via the Checkout API with the same pg_code, agreement.id, and customer_id
2. Call the Native Payments API with the session_id and token:

POST /b/pbl/v2/auto-debit/ — Charge Saved Card

{
  "session_id": "19aa7cd3cfc43d9d7641f6c433767b25cbcd6c18",
  "token": "9923965822244314"
}

info

Use the same pg_code, agreement.id, and customer_id as the first payment. The amount may vary if the agreement's amount_variability is set to "variable".

One-Step (Checkout API with payment_instrument):

Combine session creation and payment in a single call using payment_instrument. To see this in action, try the Live Demo above.

POST /b/checkout/v1/pymt-txn/ — One-Step Checkout

{
  "type": "e_commerce",
  "amount": "19.000",
  "payment_type": "auto_debit",
  "currency_code": "KWD",
  "pg_codes": ["credit-card"],
  "customer_id": "cust_123",
  "webhook_url": "https://yourwebsite.com/webhook",
  "agreement": { "id": "A123456789", "type": "recurring" },
  "payment_instrument": {
    "instrument_type": "token",
    "payload": { "token": "9923965822244314" }
  }
}

Use Cases

Updating Card Information

Card changes for auto-debit always require a CIT (the customer must be present):

Customer-Initiated Update:

1. Customer visits your card management section
2. Your backend creates a new Checkout session with the same agreement.id
3. Present the Checkout SDK or redirect to checkout_url
4. Customer selects or enters a new card
5. After successful payment, the new card is associated with the agreement
6. You receive the updated token via webhook

Merchant-Requested Update:

When a card is about to expire or a payment fails, notify the customer via email/SMS with a direct link to a checkout page where they can enter a new card.

tip

Set up notifications for upcoming card expirations to avoid disruptions. Prompt customers to update their card details before expiry.

Error Handling

When an MIT payment fails:

1. Notify the customer — send an email/SMS explaining the failure reason
2. Provide a payment link — include a checkout_url so the customer can pay manually
3. Retry after 24 hours — create a new session with appropriate grace period parameters
4. Allow card update — the customer may need to update their saved card

Common failure reasons:

• Insufficient funds — retry after a delay
• Expired card — request card update from customer
• Gateway decline — check with payment gateway for details
• Token invalidated — requires new CIT to re-establish

Pre-Charge Notifications

For recurring billing, notify customers before each charge:

• 1 week before — upcoming charge notification
• 1 day before — final reminder with option to modify
• Include a link to update card or cancel subscription

API Reference

Native Payment API(Auto Debit)

Native Payment API(Auto Debit)

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

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.

Permissions

Auth Method	Required Permissions
API Key	All permissions (admin access)
Basic Auth	Can add payment requests or Can add e-commerce payments

Idempotency. Pass an Idempotency-Key request header to make this charge safe to retry. If the same key was already recorded on the transaction by a previous successful charge, the request is rejected with 409 Conflict before any charge is attempted — so a network retry can never double-charge the customer. The key is stored only after a successful charge, so retrying a failed charge with the same key is still allowed. Omitting the header preserves the original, non-idempotent behavior. See Native Payments → Idempotency for the full contract.

curl --location 'https://sandbox.ottu.net/b/pbl/v2/auto-debit/' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Api-Key YOUR_API_KEY' \
--data '{
  "session_id": "string",
  "token": "string"
}'

Request

Responses

200

400

401

Last updated on Jun 26, 2026

Best Practices

• Track schedules — maintain a scheduling system for recurring payment dates
• Keep records — store detailed transaction records for reconciliation and dispute handling
• Communicate — send clear pre-charge and post-charge notifications to customers
• Include links — always provide direct checkout links in notifications for easy card updates
• Handle failures gracefully — implement retry logic with increasing intervals
• Monitor token health — track card expirations and proactively request updates

FAQ

What's Next?

• Operations — Refund, capture, or void auto-debit transactions
• Webhooks — Handle payment notifications for recurring charges
• User Cards — Manage saved cards and retrieve tokens
• One-Step Checkout — Combine session creation and payment in a single call