Native Payment API

Use the Native Payment API when you want full control of the client experience (web or mobile) and prefer not to use the Checkout SDK. Your client or backend collects a payment payload and sends it to Ottu to process the payment for a given session_id.

A payment payload can be:

• Wallet payment data (e.g., Apple Pay paymentData, Google Pay paymentMethodData) — typically encrypted by the wallet.

• Gateway token / network token (card-on-file or one-click use cases) — not necessarily encrypted.

Ottu processes the payload with the configured gateway and returns a normalized callback result.

When to Use

• Apple Pay or Google Pay buttons are rendered and managed by you.

• Existing tokenization has already been implemented and needs to be used to charge with a gateway token.

• Granular, SDK-less control of the UX is required, while Ottu’s orchestration and gateway integrations are still leveraged.

Quick Start

Send a post request to the payment service endpoint with payment session_id, then the payment service collected token to perform the payment process.

Quick Apple Pay Example (cURL)

curl -X POST "https://sandbox.ottu.net/b/pbl/v2/payment/apple-pay/" \
  -H "Authorization: Api-Key GYj5Na8H.29g9hqNjm11nORQMa2WiZwIBQQ49MdAL" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "pg_code": "apple-pay", 
      "session_id": "str",
      "payload": {
        "paymentData": {
          ...
        }
      } // the apple payment token without modifications
    }
  }'

Ottu securely processes the Apple Pay request and returns a unified success response once the payment is completed.

{
  "result": "success",
  "message": "successful payment",
  "pg_response": {}
}

Use the response values to reconcile the payment in your backend and update your order state.

Continue with the sections below to learn more about response fields, error handling, and webhook integration.

Authentication

Supported Methods

• Private API Key (Server-Only)

• Public API Key (Client-Safe)

• Basic Authentication (Server-Only)

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

The Private API Key must never be exposed in any client-side application.

Integration Flows

1. Client → Ottu (Public API Key )

   1. The client collects the wallet or tokenized payment payload and calls the Native Payment API directly using the Public API Key.

   2. The client receives the API callback response.

If the call is made from the client side, the backend must be synchronized with the payment result by ensuring that one of the following actions is performed:

• The API response is forwarded to the backend, or

• The Payment Status (Inquiry) API is called by the backend after the client confirms that the payment has been completed.

1. Client → Backend → Ottu (Private API Key– Recommended)

   1. The client sends the payment payload to Backend

   2. Backend calls Ottu native payment API

   3. Backend receive payment response callback

   4. Backend process callback response and notify client side with payment status

Setup

• A valid session_id obtained from the Checkout API.

• A Merchant Gateway ID (MID) with the payment service activated and properly configured in Ottu.

To complete the setup, the Service Setup section for the specific payment service being implemented must be followed, such as:

• Apple Pay

• Google Pay

• Auto-Debit (Tokenized Payments)

If multiple gateways are configured, always include the pg_code corresponding to the MID that has the target payment service enabled. Example: If a transaction has knet and mpgs pg_code but only knet supports Apple Pay, you must send pg_code: knet when calling the Apple Pay API.

Checklist

• Created a valid session_id.

• Completed Apple Pay / Google Pay setup (if applicable).

• Selected the correct invocation model (client or backend).

• Used the appropriate API key type (Public API Key vs. Private API Key).

• Sent wallet payment payload or gateway token (no raw card data).

• Implemented backend sync logic.

Apple Pay

The prerequisites and checklist mentioned in the general Setup section should be applied. They can be accessed here.

Setup

1. Apple Pay is configured on the client side (iOS / web).

2. The encrypted paymentData object is collected from Apple Pay.

3. The payload, along with the session_id, is sent to the Ottu Payment API.

4. Ottu processes via the configured Apple Pay gateway and returns a unified result (succeeded, failed).

• Do not modify the Apple Pay payload. Any change invalidates token decryption.

• Include pg_code if multiple gateways are configured.

API Schema Reference

Native Payment API(Apple Pay)

post

Allows merchants to submit an Apple Pay payment directly via server-to-server integration. This endpoint requires private key authentication and expects a valid Apple Pay token structure in the request payload under payload.

Typical use case: The merchant collects the Apple Pay token on their frontend and sends it to this endpoint along with session and amount information.

Authorizations

basicAuthSSO_BasicAuth

AuthorizationstringRequired

Body

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

pg_codestring · nullableOptional

The unique pg_code used for this payment instrument.

session_idstringRequired

A unique identifier for the payment transaction (session).

Responses

200Success

application/json

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_birthdatestring · nullableOptional

The customer's date of birth in ISO format (YYYY-MM-DD).

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

or

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:

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.

NOTE: If save_card is selected:

1. The amount must be zero for the save card operation.
2. The selected MID(pg_code) must support tokenization to enable the save card operation.
3. Please note that the save card operation is considered successful without any funds being charged.
4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL.
5. When the transaction type is save_card, all previously saved cards returned in the sdk_preload_payload should be hidden since the user is saving a new card and does not need to select from existing ones.

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

Possible values:

reference_numberstringRead-onlyRequired

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

transaction_log_idinteger · max: 2147483647 · 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/payment/apple-pay/

HTTPcURLJavaScriptPython

POST /b/pbl/v2/payment/apple-pay/ HTTP/1.1
Host: sandbox.ottu.net
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 320

{
  "payload": {
    "paymentData": {
      "version": "text",
      "data": "text",
      "signature": "text",
      "header": {
        "ephemeralPublicKey": "text",
        "wrappedKey": "text",
        "publicKeyHash": "text",
        "transactionId": "text"
      }
    },
    "paymentMethod": {
      "displayName": "text",
      "network": "text",
      "type": "text"
    },
    "transactionIdentifier": "text"
  },
  "pg_code": null,
  "session_id": "text"
}

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

{
  "pg_params": {
    "auth_code": null,
    "card_type": null,
    "card_holder": null,
    "cardholder_email": null,
    "card_expiry_month": null,
    "card_expiry_year": null,
    "full_card_expiry": null,
    "card_number": null,
    "card_issuer": null,
    "ref": null,
    "result": null,
    "track_id": null,
    "post_date": null,
    "transaction_id": null,
    "payment_id": null,
    "pg_message": null,
    "receipt_no": null,
    "transaction_no": null,
    "decision": null,
    "card_expiry": null,
    "card_details": null,
    "dcc_payer_amount": null,
    "dcc_payer_currency": null,
    "dcc_payer_exchange_rate": null,
    "rrn": null
  },
  "agreement": {
    "id": "text",
    "amount_variability": "fixed",
    "start_date": "2026-03-06",
    "expiry_date": "2026-03-06",
    "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"
    }
  },
  "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_birthdate": null,
  "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": "[email protected]",
    "phone": "text"
  },
  "is_sandbox": true,
  "message": "text",
  "order_no": null,
  "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": null,
    "customer_id": "text",
    "cvv_required": true,
    "expiry_month": "text",
    "expiry_year": "text",
    "is_expired": true,
    "is_preferred": true,
    "name_on_card": null,
    "number": null,
    "pg_code": "text",
    "pg_name": "knet",
    "token": "text",
    "agreements": null
  },
  "transaction_log_id": null,
  "timestamp_utc": "2026-03-06T18:42:01.025Z",
  "transactions": [
    {
      "amount": "text",
      "currency_code": "text",
      "order_no": null,
      "session_id": "text",
      "state": "paid"
    }
  ],
  "voided_amount": 1
}

Google Pay

The prerequisites and checklist mentioned in the general Setup section should be applied. They can be accessed here.

Setup

1. Google Pay is configured on the client side (Android / web).

2. The wallet payment payload (paymentMethodData, email, addresses, etc.) is collected.

3. The payload, along with the session_id is sent to the Ottu Native Payment API.

4. Ottu processes through the configured gateway and returns a normalized response.

• Do not modify the Google Pay payload. Any change invalidates token decryption.

• Include pg_code if multiple gateways are configured.

• If the response contains type: "iframe", render it for 3D Secure authentication.Important:

API Schema Reference

Native Payment API(Google Pay)

post

Allows merchants to submit an Google Pay payment directly via server-to-server integration. This endpoint requires private key authentication and expects a valid Google Pay token structure in the request payload under payload.

Typical use case: The merchant collects the Google Pay token on their frontend and sends it to this endpoint along with session and amount information.

Authorizations

basicAuthSSO_BasicAuth

AuthorizationstringRequired

Body

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

pg_codestring · nullableOptional

The unique pg_code used for this payment instrument.

session_idstringRequired

A unique identifier for the payment transaction (session).

Responses

200Success

application/json

or

or

400Error

application/json

401Error

application/json

post

/b/pbl/v2/payment/google-pay/

HTTPcURLJavaScriptPython

POST /b/pbl/v2/payment/google-pay/ HTTP/1.1
Host: sandbox.ottu.net
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 326

{
  "payload": {
    "apiVersion": 1,
    "apiVersionMinor": 1,
    "paymentMethodData": {
      "type": "text",
      "description": "text",
      "info": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "tokenizationData": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    },
    "email": "[email protected]",
    "shippingAddress": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  },
  "pg_code": null,
  "session_id": "text"
}

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

{
  "pg_params": {
    "auth_code": null,
    "card_type": null,
    "card_holder": null,
    "cardholder_email": null,
    "card_expiry_month": null,
    "card_expiry_year": null,
    "full_card_expiry": null,
    "card_number": null,
    "card_issuer": null,
    "ref": null,
    "result": null,
    "track_id": null,
    "post_date": null,
    "transaction_id": null,
    "payment_id": null,
    "pg_message": null,
    "receipt_no": null,
    "transaction_no": null,
    "decision": null,
    "card_expiry": null,
    "card_details": null,
    "dcc_payer_amount": null,
    "dcc_payer_currency": null,
    "dcc_payer_exchange_rate": null,
    "rrn": null
  },
  "agreement": {
    "id": "text",
    "amount_variability": "fixed",
    "start_date": "2026-03-06",
    "expiry_date": "2026-03-06",
    "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"
    }
  },
  "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_birthdate": null,
  "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": "[email protected]",
    "phone": "text"
  },
  "is_sandbox": true,
  "message": "text",
  "order_no": null,
  "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": null,
    "customer_id": "text",
    "cvv_required": true,
    "expiry_month": "text",
    "expiry_year": "text",
    "is_expired": true,
    "is_preferred": true,
    "name_on_card": null,
    "number": null,
    "pg_code": "text",
    "pg_name": "knet",
    "token": "text",
    "agreements": null
  },
  "transaction_log_id": null,
  "timestamp_utc": "2026-03-06T18:42:01.025Z",
  "transactions": [
    {
      "amount": "text",
      "currency_code": "text",
      "order_no": null,
      "session_id": "text",
      "state": "paid"
    }
  ],
  "voided_amount": 1
}

Auto-Debit (Tokenized Payments)

The prerequisites and checklist mentioned in the general Setup section should be applied. They can be accessed here.

Setup

1. Ensure the token is active and usable for the merchant.

2. Use an existing session_id created via the Checkout API.

3. Send the token in the token field to Ottu.

4. Ottu processes the payment with the configured gateway and returns the callback result.

Supports CIT (Cardholder Initiated) and MIT (Merchant Initiated) transactions.

API Schema Reference

Native Payment API(Auto Debit)

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.

Authorizations

SSO_BasicAuthbasicAuthSSO_JWT_Auth

AuthorizationstringRequired

Header parameters

AuthorizationstringRequired

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

Default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo

Body

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

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

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

tokenstringRequired

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

Responses

200Success

application/json

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_birthdatestring · nullableOptional

The customer's date of birth in ISO format (YYYY-MM-DD).

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

or

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:

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.

NOTE: If save_card is selected:

1. The amount must be zero for the save card operation.
2. The selected MID(pg_code) must support tokenization to enable the save card operation.
3. Please note that the save card operation is considered successful without any funds being charged.
4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL.
5. When the transaction type is save_card, all previously saved cards returned in the sdk_preload_payload should be hidden since the user is saving a new card and does not need to select from existing ones.

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

Possible values:

reference_numberstringRead-onlyRequired

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

transaction_log_idinteger · max: 2147483647 · 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/

HTTPcURLJavaScriptPython

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

{
  "session_id": "text",
  "token": "text"
}

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

{
  "pg_params": {
    "auth_code": null,
    "card_type": null,
    "card_holder": null,
    "cardholder_email": null,
    "card_expiry_month": null,
    "card_expiry_year": null,
    "full_card_expiry": null,
    "card_number": null,
    "card_issuer": null,
    "ref": null,
    "result": null,
    "track_id": null,
    "post_date": null,
    "transaction_id": null,
    "payment_id": null,
    "pg_message": null,
    "receipt_no": null,
    "transaction_no": null,
    "decision": null,
    "card_expiry": null,
    "card_details": null,
    "dcc_payer_amount": null,
    "dcc_payer_currency": null,
    "dcc_payer_exchange_rate": null,
    "rrn": null
  },
  "agreement": {
    "id": "text",
    "amount_variability": "fixed",
    "start_date": "2026-03-06",
    "expiry_date": "2026-03-06",
    "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"
    }
  },
  "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_birthdate": null,
  "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": "[email protected]",
    "phone": "text"
  },
  "is_sandbox": true,
  "message": "text",
  "order_no": null,
  "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": null,
    "customer_id": "text",
    "cvv_required": true,
    "expiry_month": "text",
    "expiry_year": "text",
    "is_expired": true,
    "is_preferred": true,
    "name_on_card": null,
    "number": null,
    "pg_code": "text",
    "pg_name": "knet",
    "token": "text",
    "agreements": null
  },
  "transaction_log_id": null,
  "timestamp_utc": "2026-03-06T18:42:01.025Z",
  "transactions": [
    {
      "amount": "text",
      "currency_code": "text",
      "order_no": null,
      "session_id": "text",
      "state": "paid"
    }
  ],
  "voided_amount": 1
}

FAQ

1️ Can I call the Native Payment API directly from the client?

Yes, but only with the Public Key, and your backend must remain synchronized.

2️ Which model should I use in production?

Always prefer Client → Backend → Ottu using the Private Key.

3️How do I verify the payment result?

Use the Payment Status (Inquiry) API.

4️What if my transaction has multiple gateway codes?

Include the pg_code for the MID that has the corresponding payment service enabled (e.g., Apple Pay, Google Pay).

5️What happens if I modify wallet data?

The payment will fail — wallet tokens must be sent unmodified.

6️Can I charge saved tokens automatically?

Yes, use the Native Payment API for tokenized or recurring payments.