Test Auto-Debit

Auto debit endpoint for auto debit payment flow

post

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.

Authentication Notes

The Api-Key is already automatically added to the headers, so no authentication type required.

If you want to choose your preferred authentication type, follow these steps:

Deselect the Api-Key header and choose one of the following:
- For ApiKeyAuth, use: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo.
- For BasicAuth, provide your valid username and password.
- For JWT Auth, include your token in the format: Bearer <your_token>.

Authorizations

AuthorizationstringRequired

HTTP API Key Authentication

API-Key authentication for private use only.

Example API-Key

vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo

Example Header:

Authorization: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo

Header parameters

AuthorizationstringRequired

Private API key to be provided in the format Api-Key <key>.

Default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo

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

session_idstring · min: 1 · max: 128Required

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

tokenstring · min: 1Required

Responses

200Success

application/json

pg_paramsstringRead-onlyRequired

The pg_params field contains the details received from the payment gateway callback these details are provided to us by the gateway after a user has completed a payment transaction additionally, pg_params can include information obtained from an inquiry request made to the payment gateway status check API.

amountstringRead-onlyRequired

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

capture_delivery_addressbooleanOptional

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

capture_delivery_locationbooleanOptional

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

currency_codestring · min: 3 · max: 3Required

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 · max: 40Optional

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

customer_address_countrystring · min: 2 · max: 2Required

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_line1stringOptional

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_line2stringOptional

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 · max: 12Optional

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 · max: 40Optional

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 · max: 128Optional

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 · max: 64Optional

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 · max: 64Optional

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 · max: 64Optional

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 · max: 32Optional

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.

extraanyOptional

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

feestringRead-onlyRequired

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_accountstringRead-onlyRequired

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

gateway_namestringRead-onlyRequired

The name of the payment gateway service being utilized.

is_sandboxbooleanOptional

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

messagestringRead-onlyRequired

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_nostring · max: 128 · nullableOptional

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

paid_amountone ofRead-onlyRequired

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 · doubleOptional

stringOptional

payment_typestring · enumOptional

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.

Choose save_card if you want to perform a card tokenization operation.

NOTE: If auto_debit is selected:

agreement and customer_id parameters will also be mandatory.
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.

NOTE: If save_card is selected:

The amount must be zero for the save card operation.
The selected MID(pg_code) must support tokenization to enable the save card operation.
Please note that the save card operation is considered successful without any funds being charged.
Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL.

one_off - One Off
auto_debit - Auto Debit
save_card - Save Card

Possible values:

reference_numberstringRead-onlyRequired

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 · doubleOptional

The total refunded amount for the payment transaction.

remaining_amountnumber · doubleRead-onlyRequired

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

resultstring · enumRead-onlyRequired

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

Possible values:

session_idstring · max: 128Optional

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

settled_amountnumber · doubleRead-onlyRequired

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

signaturestringRead-onlyRequired

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.

statestringRead-onlyRequired

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

transaction_log_idinteger · int64 · max: 4294967295 · nullableOptional

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_utcstring · date-timeRead-onlyRequired

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.

voided_amountnumber · doubleOptional

The total voided amount for the payment transaction.

400Error

application/json

401Error

application/json

post

/b/pbl/v2/auto-debit/

POST /b/pbl/v2/auto-debit/ HTTP/1.1
Host: betabulk.ottu.net
Authorization: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo
Content-Type: application/json
Accept: */*
Content-Length: 84

{
  "session_id": "5e4788a84a9ce8a6bc1a83dcac11a1ff2822be82",
  "token": "9261815648110746"
}

{
  "pg_params": "text",
  "agreement": {
    "id": "text",
    "amount_variability": "fixed",
    "start_date": "2026-03-19",
    "expiry_date": "2026-03-19",
    "max_amount_per_cycle": "text",
    "cycle_interval_days": 1,
    "total_cycles": 1,
    "frequency": "irregular",
    "type": "recurring",
    "seller": {
      "name": "text",
      "short_name": "text",
      "category_code": "text"
    },
    "extra_params": {
      "payment_processing_day": 1
    }
  },
  "amount": "text",
  "amount_details": {
    "currency_code": "text",
    "amount": "text",
    "total": "text",
    "fee": "text",
    "exchange_rate": "text"
  },
  "capture_delivery_address": true,
  "capture_delivery_location": true,
  "card_acceptance_criteria": {
    "min_expiry_time": 1
  },
  "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",
  "extra": null,
  "fee": "text",
  "gateway_account": "text",
  "gateway_name": "text",
  "gateway_response": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "initiator": {
    "id": 1,
    "first_name": "text",
    "last_name": "text",
    "username": "text",
    "email": "name@gmail.com",
    "phone": "text"
  },
  "is_sandbox": true,
  "message": "text",
  "order_no": "text",
  "paid_amount": 1,
  "payment_type": "one_off",
  "reference_number": "text",
  "refunded_amount": 1,
  "remaining_amount": 1,
  "result": "pending",
  "session_id": "text",
  "settled_amount": 1,
  "signature": "text",
  "state": "text",
  "token": {
    "brand": "text",
    "customer_id": "text",
    "cvv_required": true,
    "expiry_month": "text",
    "expiry_year": "text",
    "is_expired": true,
    "is_preferred": true,
    "name_on_card": "text",
    "number": "text",
    "pg_code": "text",
    "pg": "knet",
    "token": "text",
    "agreements": null
  },
  "transaction_log_id": 1,
  "timestamp_utc": "2026-03-19T21:01:02.110Z",
  "transactions": [
    {
      "amount": "text",
      "currency_code": "text",
      "order_no": "text",
      "session_id": "text",
      "state": "paid"
    }
  ],
  "voided_amount": 1
}

Back

Last updated 1 year ago

hashtagAuto debit endpoint for auto debit payment flow

HTTP API Key Authentication

Example API-Key

Example Header:

Auto debit endpoint for auto debit payment flow