Ayoconnect's Direct Debit API provides a seamless way to accept payments by binding your customer's bank account (enabling recurring payments). ## Product Features

Securely link your customer's bank account
Supports both one-time checkout and recurring payments
Pull funds directly from your customer's bank account with their consent
Unlink your customer's bank account directly from the application
Robust Alert systems to detect anomalies
Automated Reconciliation
Dashboard for transaction visibility

You can download the full Product Guide from here. ## Supported Banks | Bank Name | Bank Code | Support Split Settlement | Support Payment With OTP (API Based) | Support Payment Without OTP (API Based) | Payment Only Using UI | Support Unbinding Without OTP (API Based) | |--------------|-----------|--------------------------------------|--------------------------------------|-----------------------------------------|-----------------------|-------------------------------------------| | Bank BRI | 002 |

| | Bank Mandiri | 008 |

| | Bank BNI | 009 |

| | Bank Danamon | 011 |

| | Bank CIMB | 022 |

| ## Credentials Before starting Direct Debit SNAP APIs integration, partners must ensure that they have all the required credentials. Every partner will receive a unique set of credentials from Ayoconnect during their onboarding process. | Credential | Description | Source | |---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------| | merchantId | This field is a 6-character merchant identifier that is unique per each merchant. The exact value is disclosed to each merchant separately. | Provided by Ayoconnect. | | client_id | Unique 32-character string used to generate B2B and B2B2C Tokens. | Provided by Ayoconnect. | | client_secret | Unique 32-character string used to generate a signature. | Provided by Ayoconnect. | | Public Key | RSA Public key. The method to generate a valid key pair is mentioned below. The public key needs to be shared by the partner during their onboarding process. | Generated by the partner. | | Private Key | RSA Private key. The method to generate a valid key pair is mentioned below. | Generated by the partner. |

RSA Key Pair Generation

Generate a private key with the correct length.
- openssl genrsa -out private-key.pem 3072
Generate the corresponding public key.
- openssl rsa -in private-key.pem -pubout -out public-key.pem

Authentication

All API requests must contain the Authorization Token in the header, which is used to authenticate the merchant.
There are two types of Authorization Tokens:

B2B Token

Generated Using Generate B2B Access Token /api/v3.0/access-token/b2b and passed in headers as Bearer Token. The B2B Token is mandatory in all API requests.
```
Authorization: Bearer <b2b_token>
```

B2B2C Token

Generated Using Generate B2B2C Access Token /api/v3.0/access-token/b2b2c and passed in headers as Bearer Token.

API Name	Endpoint
API Direct Debit Payment	`/dd/api/v3.0/debit/payment-host-to-host`
API Verify OTP	`/dd/api/v3.0/otp-verification`

Authorization-Customer: Bearer <b2b2c_token>

Authentication Tokens (B2B or B2B2C) generated once are only valid for 3600 seconds, after that a new token must be generated.

Signature Generation

All API requests must contain a valid signature header. The signature is passed in the X-Signature header of the HTTP Request.
The signature generation algorithm and contents to sign depend on the API being called. The table below mentions the APIs, signature algorithm, and content to sign.

Signature Algorithm	Content to Sign	Key to Sign	API Name
SHA256withRSA	`client_ID + "\|" + X-TIMESTAMP`	privateKey	Generate B2B Access Token
			Generate B2B2C Access Token
HMAC_SHA512	`HTTPMethod +":"+ URLPath +":"+ AccessToken +":"+ Lowercase(HexEncode(SHA-256(minify(RequestBody))))+":" + TimeStamp`	clientSecret	Get OAuth Code API
			API Account Binding
			API Account Unbinding
			API Direct Debit
			API Verify OTP

Signature Generation Example

Credential	Value
client_id	`fceda4da-ae95-4d14-8cb6-eef392139a1b`
client_secret	`fceda4da-ae95-4d14-8cb6-eef392139a2c`
private_key	`----BEGIN RSA PRIVATE KEY----- MIIBOgIBAAJBAJ9wKHG/JDCr+6eZ6as5hHspDhZEUkveTF9GnCcDqRVmS/E4rhYw niRfSSf2hfp516cYpC7zJ2AFB4id63T3lxECAwEAAQJALk7qQFdvEH/zYPOwTd4v 34HGKKuBZ63Sat3cXuyOQLt3OSj/lgRx/XELRjdLMADQrxTI0ijUvr9jqLB0I6O1 DQIhAMo3voVyYA0dmZvNWPRf6JzkFeexsXKmsrpNij9pwvPHAiEAyde1FPNTAeQn e0DW+gtE5dHg/omiZDYBKLBj4jb4bmcCIDhvSjqP6wJ+CkqTCopY4eA3P23EB5PJ tgOMdFKyP3gtAiEAgC0db2p94guTDvBEFJGndRJtAPdCSsUIw2AQbg1egi0CIH+a Z4Mar+3f+SFIElF+M+aD4AzzibGUJghJ03cbR6Pt ----END RSA PRIVATE KEY-----`
public_key	`----BEGIN PUBLIC KEY----- MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAJ9wKHG/JDCr+6eZ6as5hHspDhZEUkve TF9GnCcDqRVmS/E4rhYwniRfSSf2hfp516cYpC7zJ2AFB4id63T3lxECAwEAAQ== ----END PUBLIC KEY-----`

Below are the examples for Signature Generation which are generated using the above dummy credentials. Please do not try to use the above credentials; they are just for reference.

SHA256WithRSA

String Format	`client_ID + "\|" + X-TIMESTAMP`
client_id	`fceda4da-ae95-4d14-8cb6-eef392139a1b`
X-TIMESTAMP	`2023-03-28T22:13:27+07:00`
String to Sign	`fceda4da-ae95-4d14-8cb6-eef392139a1b\|2023-03-28T22:13:27+07:00`
Hex Encoded Generated Signature	`2729b693fb377029422605c74a7f8d7c0769c6f733450ed9602b8152104328d47010bb88bb46a1e72b23ca2946c1807f753b60a38a53a6fd4e8e4cea8d26d6c8`

HMAC_SHA512

String Format	`http_method + ":" + url_path + ":" + access_token + ":" + Lowercase(HexEncode(SHA256(minify(RequestBody))))+ ":" + timestamp`
http_method	`POST`
url_path	`/dd/api/v3.0/registration-account-binding`
access_token	`ed8f7f42a6d741fbb891bae654e81678`
JSON Body	`{ "partnerReferenceNo": "qic5taezfgta7yhn74u7cppr47wan027", "lang": "ID", "merchantId": "AYOTON", "phoneNo":"6281981282990" }`
Minified JSON Body	`{"partnerReferenceNo":"qic5taezfgta7yhn74u7cppr47wan027","lang":"ID","merchantId":"AYOTON","phoneNo":"6281981282990"}`
timestamp	`2023-03-28T22:13:27+07:00`
String to Sign	`POST:/dd/api/v3.0/registration-account-binding:ed8f7f42a6d741fbb891bae654e81678:626c42bf3d17e3a02bcabd6d265103135b6dd70e7af6341e87c56ad3650015ee:2023-03-28T22:13:27+07:00`
client_secret	`fceda4da-ae95-4d14-8cb6-eef392139a2c`
Encryption With client_secret	`2e955289baf7f297dda75b830c00f15b81a71710c2d0a0bbdf5884ae15bf47bb46e627a0b25cff1c1da16c42682ec69945950a1b120b6be490a53b7d613cf7e4`

Direct Debit Flows

A Direct Debit Flow is a set of API calls that are executed one after another. Please follow the guidelines below for all the flows.

All API calls that are part of the same flow must have the same X-External-ID header. Failing to do so will result in a broken flow, and it may not be possible to resolve any issues raised for that flow.
Do not attempt to open Ayoconnect's UI in an IFrame.

Below is a list of all the Direct Debit flows:

Account Binding
1. Registration Account Binding API
Account Binding is the first process of the Direct Debit Journey of a user. Account Binding means registering the user's Debit Card/Account in Ayoconnect's Direct Debit system so that payment can be done using that Card. It is a one-time process, and after successful Account Binding, the user can make payments as many times as they want as long as the card is not unbound. In that case, the user has to rebind the card again.

Account Binding is done through Ayoconnect's UI, and after successful Account Binding, the user can be redirected to a partner-specific URL, which must be provided in the account binding API request.

Follow the below steps to perform a Account Binding:
1. Generate a unique `referenceNo` by calling the Registration Account Binding API.
2. Open the binding URL, and the Bank selection screen will open. Follow the steps mentioned in the UI and complete Account Binding. After successful Account Binding, a callback with the status will be sent to the registered callback URL, must be provided during onboarding.
3. The callback is the main source for retrieving the bankCardToken, which is required to perform payments.
Payment

A callback will also be sent to the partner's callback URL with the status of payment. Structures of the callback are mentioned below in the Callback Specification section.
1. Direct Debit Payment API
2. Verify OTP API ( Only for Payment with OTP )
Card Unbinding
1. Account Unbinding API
2. Verify OTP API ( For some banks)

Callback Specification

Callbacks are HTTP API requests sent from Ayoconnect’s server to the partner’s server to notify the partner about the status of specific operations. All callbacks follow a fixed format. During the onboarding process, the partner must provide two callback URLs — one for Account Binding status and another for Charge Payment status. The API service codes for the Binding and Unbinding callback APIs are 07 and 09, respectively, while the service code for the Payment callback API is 55.

Success/Failure callbacks are sent in the following Direct Debit Flows:

Account Binding

Successful account binding:

```json { "additionalInfo": { "accountBindedTime": "2025-10-31T14:06:54", "bankCardToken": "2e270f75fc43a3e28715a98c981dbf32", "bankCode": "009", "bindingStatusDesc": "SUCCESS", "externalId": "gfhmY7W7HTW8vanwYDBOmc32fVJ1UZRR", "latestBindingStatus": "04", "maskedCard": "************3214", "merchantId": "AYOTON", "publicUserId": "AYOTON-11B932PJ", "paymentOTPMode":"WITH_OTP", "additionalInfo1":"Example", "additionalInfo2":"User1", "additionalInfo3":"Test" }, "originalPartnerReferenceNo": "K0riumwMg7R4jaSvY2gojQshE5trMhNU", "originalReferenceNo": "b163411c53f440e8a2d97a3deaeb41f9", "responseCode": "2000700", "responseMessage": "Successful" } ````

Failed account binding:

```json { "additionalInfo": { "bankCode": "002", "bindingStatusDesc": "FAIL", "externalId": "sqhUnfiMLLAUmxFuptQ5lXlufIOTSdM8", "latestBindingStatus": "05", "merchantId": "AYOTON", "publicUserId": "AYOTON-11BDYUSQ" "paymentOTPMode":"WITH_OTP", "additionalInfo1":"Example", "additionalInfo2":"User1", "additionalInfo3":"Test" }, "originalPartnerReferenceNo": "Tn0ittP85H3Dz0til4fsdN6nG2l5pk6f", "originalReferenceNo": "1aff5e8de8f540c5a2477608cbfd8661" "responseCode": "5000701", "responseMessage": "Invalid Card" } ```` #Field Description | Field | Description | |-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| | responseCode | Response Code | | responseMessage | Response Message | | originalPartnerReferenceNo | Partner ReferenceNo is the unique Id per API shared by clients | originalReferenceNo | Reference number is 32 char reference number on Ayoconnect system. | | additionalInfo | Additional info required regarding account binding flow. | | latestBindingStatus | Binding Status, possible values: 00 - INITIATED, 01 - INPROGRESS, 02 - VERIFICATION_PENDING, 04 - SUCCESS, 05 - FAIL, 06 - UNBINDED |

Charge Payment

Successful Charge Payment:

```json { "responseCode": "2005400", "responseMessage": "Request has been processed successfully", "serviceCode": "54", "originalPartnerReferenceNo": "QyhqfjvSAu9dfqugSPr27OtqoLf0pXpg", "originalReferenceNo": "77f431e011d648a0ac38e565ce009382", "latestTransactionStatus": "00", "transactionStatusDesc": "Success", "paidTime": "2025-09-18T21:35:03+07:00", "transAmount": { "value": "20000.00", "currency": "IDR" }, "additionalInfo": { "merchantId": "AYOTON", "publicUserId":"AYOTON-H173bGA", "latestSettlementStatus":"SETTLED", "additionalInfo1":"Example" "additionalInfo2":"User1" "additionalInfo3":"Test" "splitSettlement": [ { "subCompanyCode": "12345", "amount": { "value": "10000.00", "currency": "IDR" } }, { "subCompanyCode": "67892", "amount": { "value": "10000.00", "currency": "IDR" } } ] } } ```

Failed Charge Payment:

```json { "responseCode": "5005401", "responseMessage": "Payment Failed", "serviceCode": "54", "originalPartnerReferenceNo": "qugSPdfqoLf0pX27OtQypgrhqfjvSAu9", "originalReferenceNo": "009381e011d64877f438e565cea0ac32", "latestTransactionStatus": "06", "transactionStatusDesc": "FAILED", "transAmount": { "value": "20000.00", "currency": "IDR" }, "additionalInfo": { "merchantId": "AYOTON", "publicUserId":"AYOTON-H173bGA", "additionalInfo1":"Example" "additionalInfo2":"User1" "additionalInfo3":"Test" "splitSettlement": [ { "subCompanyCode": "12345", "amount": { "value": "10000.00", "currency": "IDR" } }, { "subCompanyCode": "67892", "amount": { "value": "10000.00", "currency": "IDR" } } ] } } ```

Processing Charge Payment:

```json { "responseCode": "2025400", "responseMessage": "Request In Progress", "serviceCode": "54", "originalPartnerReferenceNo": "qugSPdfqoLf0pX27OtQypgrhqfjvSAu9", "originalReferenceNo": "009381e011d64877f438e565cea0ac32", "latestTransactionStatus": "03", "transactionStatusDesc": "Pending", "transAmount": { "value": "20000.00", "currency": "IDR" }, "additionalInfo": { "merchantId": "AYOTON", "publicUserId":"AYOTON-H173bGA", "additionalInfo1":"Example" "additionalInfo2":"User1" "additionalInfo3":"Test" "splitSettlement": [ { "subCompanyCode": "12345", "amount": { "value": "10000.00", "currency": "IDR" } }, { "subCompanyCode": "67892", "amount": { "value": "10000.00", "currency": "IDR" } } ] } } ```

Refund Charge Payment:

```json { "responseCode": "2005800", "responseMessage": "Successful", "serviceCode": "58", "originalPartnerReferenceNo": "QyhqfjvSAu9dfqugSPr27OtqoLf0pXpg", "originalReferenceNo": "77f431e011d648a0ac38e565ce009382", "latestTransactionStatus": "00", "transactionStatusDesc": "SUCCESS", "paidTime": "2025-09-18T21:35:03+07:00", "transAmount": { "value": "20000.00", "currency": "IDR" }, "refundAmount": { "value": "20000.00", "currency": "IDR" }, "refundTime": "2025-09-20T21:35:03+07:00", "additionalInfo": { "merchantId": "AYOTON", "publicUserId":"AYOTON-H173bGA", "latestSettlementStatus":"REFUNDED", "isChargeback": "N", "bankCardToken": "c31343c801184f9cae465c1b17d58be9", "bankCode": "009", "additionalInfo1": "Example", "additionalInfo2": "User1", "additionalInfo3": "Test", "splitSettlement": [ { "subCompanyCode": "12345", "subSplitAmount": { "value": "10000.00", "currency": "IDR" } }, { "subCompanyCode": "67892", "subSplitAmount": { "value": "10000.00", "currency": "IDR" } } ] } } ``` #Field Description | Field | Description | |-----------------------------|------------------------------------------------------------------------------------------------------------------------| | responseCode | Unique code. responseCode = HTTP Code + Service Code + Case Code. | | responseMessage | Response Message | | originalPartnerReferenceNo | Partner Reference number received in the initial (OTP Creation API) response. | | originalReferenceNo | Original Partner Reference number is a 32-character reference number in the Ayoconnect system. | | originalExternalId | Alphanumeric String. Reference number that should be unique in the same flow. | | latestTransactionStatus | Status of the payment. Possible Values are: 00 - Success, 03 - Pending, 04 - Refunded, 06- Failed, 07- Not Found . | | | additionalInfo | Additional information required regarding the payment flow. |

All callbacks, whether indicating success or failure, must be acknowledged by the partner in a fixed response format. Ayoconnect will retry the callback up to three times using exponential backoff.

Callback Acknowledgement Format

```json { "responseCode": "2005600", "approvalCode": "201039000200", "responseMessage": "Request has been processed successfully" } ``` #Field Description | Field | Description | |---------------------|------------------------------------------------------------------------------------------------------------------------| | responseCode | Unique code for each error: `responseCode = HTTP Code + Service Code of API + Case Code` . If Ayoconnect receives any HTTP Status other than 200, Ayoconnect will consider the callback as failed and the system will retry to send the callback. | | approvalCode | Approval Code for future use. | | responseDescription | Description of the error. Errors with the same responseCode and responseMessage can have different error descriptions. |

Note: In the event of an incorrect OTP verification, merchants may receive multiple callbacks if they retry OTP verification during the binding or payment flow.

Refer to the [Direct Debit Response Codes](#/components/schemas/x-tables) section for the full list of possible response codes.

RSA Key Pair Generation

Authentication

B2B Token

B2B2C Token

Signature Generation

Signature Generation Example

SHA256WithRSA

HMAC_SHA512

Direct Debit Flows

Account Binding

Payment

Card Unbinding

Callback Specification

Account Binding

Charge Payment

Callback Acknowledgement Format