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 CIMB | 022 |

| | Bank Mandiri | 008 |

| | Bank BNI | 009 |

| | Bank BNC | 490 |

| | Bank Danamon | 011 |

| | Bank BCA | 014 |

| ## 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/v1.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/v1.0/access-token/b2b2c and passed in headers as Bearer Token.

API Name	Endpoint
API Account Unbinding	`/api/v1.0/registration-account-unbinding`
API Direct Debit Payment	`/api/v1.0/debit/payment-host-to-host`
API Verify OTP	`/api/v1.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	`/api/v1.0/registration-account-binding`
access_token	`ed8f7f42a6d741fbb891bae654e81678`
JSON Body	`{ "partnerReferenceNo": "qic5taezfgta7yhn74u7cppr47wan027", "authCode": "8ecx3bnfk9bu2o4y0z8ur8pfhH12eltF", "merchantId": "AYOPOP" }`
Minified JSON Body	`{"partnerReferenceNo":"qic5taezfgta7yhn74u7cppr47wan027","authCode":"8ecx3bnfk9bu2o4y0z8ur8pfhH12eltF","merchantId":"AYOPOP"}`
timestamp	`2023-03-28T22:13:27+07:00`
String to Sign	`POST:/api/v1.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:

Card Binding
1. Get OAuth Code API
2. Account Binding API
Card Binding is the first process of the Direct Debit Journey of a user. Card Binding means registering the user's Debit Card in Ayoconnect's Direct Debit system so that payment can be done using that Card. It is a one-time process, and after successful Card 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.

Card Binding is done through Ayoconnect's UI, and after successful Card Binding, the user can be redirected to a partner-specific URL, which must be provided during partner onboarding time.

Follow the below steps to perform a Card Binding:
1. Generate a unique `authCode` by calling the Get OAuth Code API.
2. Replace the `auth_code` in the below URL with the value of the `authCode` key received in the Get OAuth Code API response:
  `https://sandbox.api.of.ayoconnect.id/dd-card-binding?authCode=auth_code`
3. Open the URL, and the Bank selection screen will open. Follow the steps mentioned in the UI and complete Card Binding. After successful Card Binding, a callback with the status will be sent to the registered callback URL.
4. For the final step in Card Binding, call the API Account Binding `api/v1.0/registration-account-binding` with the `authCode` received in step 1 to get the `accountToken` and other details of the card, which can be directly used for payments.
Charge Payment

A callback will also be sent to the partner's CHARGE_PAYMENT 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
Card Unbinding
1. Account Unbinding API
2. Verify OTP API

Callback Specification

Callbacks are essentially HTTP API requests made from Ayoconnect's side to the partner's server to inform the partner about the status of a particular operation. All callbacks follow a fixed format. During the onboarding process, the partner must provide two callback URLs, one for Card Binding status and another for Charge Payment status. The API service code for the callback API is '00'.

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

Card Binding

Successful card binding:

Failed card binding:

```json { "originalPartnerReferenceNo": "acmhfgdqpugctpu9m2qwh57b4bcawrc8", "originalReferenceNo": "j7w23ydbgymw2nq7mhjny8vew7k23xjr", "latestTransactionStatus": "FAILED", "transactionStatusDesc": "Server timeout", "additionalInfo": { "X-External-ID": "62564110041605628746333468617711", "responseCode": "5000000", "flow": "CARD_BINDING" "additionalInfo1": "test@test.com", "additionalInfo2": "Ahd.j5dnks", "additionalInfo3": "1234567890ABC" } } ```` #Field Description | Field | Description | |-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| | originalPartnerReferenceNo | Original Partner Reference number is the state parameter send in the get authcode API. This is considered as a transaction id for reference on merchants system. | | originalReferenceNo | Original Partner Reference number is 32 char reference number on Ayoconnect system. | | latestTransactionStatus | Status of the card binding. For example SUCCESS, FAILED or PROCESSING | | additionalInfo | Additional info required regarding card binding flow. | | X-External-ID | Alphanumeric String. Reference number that should be unique in the same flow. | | responseCode | Unique code. responseCode = HTTP Code + Service Code + Case Code | | flow | Operation flow for which this callback applicable for. For card binding flow will always be "CARD_BINDING" |

Charge Payment

Successful Charge Payment:

Failed Charge Payment:

Processing Charge Payment:

```json { "originalPartnerReferenceNo": "c39893bd596b4305b22edab2173c07c7", "originalReferenceNo": "df3532214f0f408da5df9ed9bc735df5", "latestTransactionStatus": "PROCESSING", "additionalInfo": { "X-External-ID": "1f6aa8e0312643b29a4b347dcebca7ef", "responseCode": "2000000", "flow": "CHARGE_PAYMENT", "splitSettlement": [ { "subCompanyCode": "00000", "amount": { "value": "12345678.00", "currency": "IDR", } } } ], "additionalInfo1": "test@test.com", "additionalInfo2": "Ahd.j5dnks", "additionalInfo3": "1234567890ABC" } } ``` #Field Description | Field | Description | |-----------------------------|------------------------------------------------------------------------------------------------------------------------| | 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. | | latestTransactionStatus | Status of the payment. For example, SUCCESS or FAILED. | | additionalInfo | Additional information required regarding the payment flow. | | X-External-ID | Alphanumeric String. Reference number that should be unique in the same flow. | | responseCode | Unique code. responseCode = HTTP Code + Service Code + Case Code. | | flow | Operation flow for which this callback is applicable. For payment flow, it will always be "CHARGE_PAYMENT". |

All callbacks, whether representing success or failure, must be acknowledged by the partner with a fixed response format so that Ayoconnect's system doesn't keep retrying the callbacks.

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 attempt to retry OTP verification for the same transaction.

Error Specification

All Direct Debit APIs have a fixed standard way of returning errors when a particular operation fails. Below are a few example errors returned in the API response:

```json { "responseCode": "5001002", "responseMessage": "General Error", "responseDescription": "Card binding process has failed." } ``` ```json { "responseCode": "5001002", "responseMessage": "General Error", "responseDescription": "Unable to unbind the card as it is linked to an active product." } ``` ```json { "responseCode": "5001002", "responseMessage": "General Error", "responseDescription": "Limit configuration not found for merchant." } ``` ```json { "responseCode": "4043011", "responseMessage": "Invalid Card", "responseDescription": "Card was not found." } ``` ```json { "responseCode": "4033005", "responseMessage": "Do Not Honor", "responseDescription": "The customer is blocked. Please reach out to Ayoconnect for resolution." } ``` #Field Description | Field | Description | |---------------------|------------------------------------------------------------------------------------------------------------------------| | responseCode | Unique code for each error: `responseCode = HTTP Code + Service Code of API + Case Code` | | responseMessage | Error message | | responseDescription | Description of the error. Errors with the same responseCode and responseMessage can have different error descriptions. |

RSA Key Pair Generation

Authentication

B2B Token

B2B2C Token

Signature Generation

Signature Generation Example

SHA256WithRSA

HMAC_SHA512

Direct Debit Flows

Card Binding

Charge Payment

Card Unbinding

Callback Specification

Card Binding

Charge Payment

Callback Acknowledgement Format

Error Specification