Ayoconnect's Instant Transfer API provides a seamless way to manage and transfer funds to customer account of 130+ banks across Indonesia. The Instant Transfer API seamless integration process and secure transfer infrastructure allows our partners to transfer funds to millions of Indonesians via a single API. ## Product Features

Add and manage beneficiary(ies)
Disburse to any valid retail account across 130+ banks in Indonesia realtime
Monitor and maintain disbursement and balance
Robust Alert systems to detect anomalies
Automated Reconciliation

## Credentials Before starting Instant Transfer 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 Disbursement	`/it/api/v2.0/transfer-interbank`

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	API Account Validation
			API Disbursement
			API Status Inquiry
			API Balance Inquiry

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	`/it/api/v2.0/account-inquiry-external`
access_token	`ed8f7f42a6d741fbb891bae654e81678`
JSON Body	`{"beneficiaryBankCode": "002", "beneficiaryAccountNo": "7332127799", "partnerReferenceNo": "675dfga23Smjauslznjs78aa56gbv512"}`
Minified JSON Body	`{"beneficiaryBankCode":"002","beneficiaryAccountNo":"7332127799","partnerReferenceNo":"675dfga23Smjauslznjs78aa56gbv512"}`
timestamp	`2023-03-28T22:13:27+07:00`
String to Sign	`POST:/it/api/v2.0/account-inquiry-external:ed8f7f42a6d741fbb891bae654e81678:626c42bf3d17e3a02bcabd6d265103135b6dd70e7af6341e87c56ad3650015ee:2023-03-28T22:13:27+07:00`
client_secret	`fceda4da-ae95-4d14-8cb6-eef392139a2c`
Encryption With client_secret	`2e955289baf7f297dda75b830c00f15b81a71710c2d0a0bbdf5884ae15bf47bb46e627a0b25cff1c1da16c42682ec69945950a1b120b6be490a53b7d613cf7e4`

Instant Transfer Flows

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

## Flows Ayoconnect defines the flows as the 'customer journeys'. For example, if a merchant wants to track the flow of one customer through the APIs, the 'X-EXTERNAL-ID' header can be used for that porpose. A flow can consists of, for example: - one call to the 'Account Validation' API, one call to the 'Disbursement' API and one call to the 'Check Status' API So, the same value of the 'X-EXTERNAL-ID' header can be used in the different APIs calls. No 'idempotency check' is implemented on this field to identify the transaction. ## Idempotency check to indentify the transaction To clearly identify duplicated transactions, the 'Disbursement' API uses the 'X-EXTERNAL-ID' field to identify the transaction. Once the 'X-EXTERNAL-ID' field has been processed, it can't be used again. If another request uses the 'X-EXTERNAL-ID' field, it will be automatically rejected by the 'Disbursement' API. ## Callbacks The merchant will receive a callback after every successful or failed 'Account Validation' and/or 'Disbursement' request. If the callback isn't successfully received by the merchant, Ayoconnect will retry to send it 3 more times. After the fourth attempt, the callback won't be retried anymore and only can be delivered again by creating a [support ticket](openfinance_eng@ayoconnect.id). NOTE: The 'Account Validation' and 'Disbursement' APIs behave in an asynchronous way, while the 'Check Status' API behaves in a synchronous way. As a merchant, you need to provide the callback URL to the Ayoconnect team during the onboarding process. Some times, merchants can receive duplicated callbacks from Ayoconnect either automatically or manually so, they need to ensure there are no side effects from their side when receiving duplicated callbacks. ## 1. Account Validation As a merchant, you can enable your customers to validate/verify a beneficiary for disbursement with the Ayoconnect's Instant Transfer service. ### 1.1. Callback URL for the 'Account Validation' process The callback URL is used to notify the merchant about the status of the 'Account Validation' process. The merchant will be notified whether the beneficiary was added to a customer or not. #### 1.1.1. 'Account Validation' callback headers The following headers are included in all the callbacks received from Ayoconnect: | Header | Value | Description | |-------------------------|-------------------------------------|-----------------------------------| | Accept | application/json | Accept type | | Content-Type | application/json | Content type of the request body | | X-EXTERNAL-ID | Same value provided in the request | Unique ID for the flow | #### 1.1.2. 'Account Validation' callback fields The following parameters are included in the callbacks received from Ayoconnect: | Name | Type | Required | Example | Description | |------------------------|-------------|----------|----------------------------------|---------------------------------------------------------------------------| | responseCode | string | Y | 2001600 | Product response code | | responseMessage | string | Y | Successful | Response message | | referenceNo | string | Y | d46aff7cff1445a2b4dcc60425d87985 | Unique Id generated for each API request | | partnerReferenceNo | string | Y | IhrrgCy4So4JqAP4g4NWzmOVieSxoF21 | 'partnerReferenceNo' value received in the request | | beneficiaryAccountName | string | Y | Cassandra Henry | Beneficiary name | | beneficiaryAccountNo | string | Y | 5552096217 | Beneficiary account number | | beneficiaryBankCode | string | Y | 002 | Beneficiary bank code | | beneficiaryBankName | string | Y | PT. BANK CENTRAL ASIA Tbk. | Beneficiary name | | additionalInfo | object | Y | | Additional Info | Contents of the 'additionalInfo' fields: | Name | Type | Required | Value | Description | |--------------------------|--------|----------|----------------------------------|-------------------------------------------------------| | beneficiaryId | string | Y | BE_46fba92630 | Beneficiary Id. Unique identifier for the beneficiary | | customerReference | string | O | 4019dbfb8a074b4bbe8eac22089d | Unique reference number used for Disbursement | | publicUserId | string | Y | AYOCON-ZG3D62R5R | Unique Customer Id | ##### Successful 'Account Validation' process (callback URL sample request) ```json { "responseCode": "2021600", "responseMessage": "Successful", "referenceNo": "e0beb9a246fb482e97d8c3c15d6460cb", "partnerReferenceNo": "vKhSjSISVC9K1nmiA5RPRyvYc38ulxXv", "beneficiaryAccountName": "Anna Simmmons", "beneficiaryAccountNo": "202655579", "beneficiaryBankCode": "002", "beneficiaryBankName": "PT. BANK RAKYAT INDONESIA (PERSERO), TBK", "additionalInfo": { "customerReference": "3c5a788ad3d74373abc9aaf3ab74", "publicUserId": "AYOPOP-ZG3D62R5R", "beneficiaryId": "BE_e9ff09eddf" } } ``` ##### Unsuccessful 'Account Validation' process (callback URL sample request) ```json { "responseCode": "4031618", "responseMessage": "Inactive Account", "referenceNo": "7fcb59e099d94fb4a17f1718647bf37f", "partnerReferenceNo": "4p299b55wh222R12kv889999eyT2O190", "beneficiaryAccountName": "N/A", "beneficiaryAccountNo": "5552096215", "beneficiaryBankCode": "002", "beneficiaryBankName": "PT. BANK CENTRAL ASIA Tbk.", "additionalInfo": { "publicUserId": "AYOPOP-ZG3D62R5R", "beneficiaryId": "BE_1623428ad2" } } ``` ## 2. Disbursement As a merchant, you can enable your customers to disburse via Ayoconnect Disbursement API. Once the account is Inquired, your customers can use it to transfer funds to them. Merchants will be notified of the final status of the Disbursement in the callbacks whenever it is updated, or they can check the status of the Disbursement by calling the 'check status' API. As getting the final status from the banks can take some time, there can be some delay when receiving the callback but, it will be delivered. ### 2.1. Callback URL for the Disbursement process The callback URL is used to notify the merchant about the status of the disbursement process. The merchant will be notified whether the disbursement process was successful or not. #### 2.1.1. Disbursement callback headers The following headers are included in all the callbacks received from Ayoconnect: | Header | Value | Description | |-------------------------|-------------------------------------|----------------------------------| | Accept | application/json | Accept type | | Content-Type | application/json | Content type of the request body | | X-EXTERNAL-ID | Same value provided in the request | Unique ID for the flow | #### 2.1.2. Disbursement callback fields The following parameters are included in the callbacks received from Ayoconnect: | Name | Type | Required | Example | Description | |------------------------|-------------|----------|----------------------------------|---------------------------------------------------------------------------| | responseCode | string | Y | 2003600 | Product response code | | responseMessage | string | Y | Successful | Response message | | referenceNo | string | Y | 3aa7a027417b401fbd40fa77b02a256f | Unique Id generated for each API request | | partnerReferenceNo | string | Y | aa226aa10bb11R6789u99ox4F11r9811 | 'partnerReferenceNo' value received in the request | | amount | object | Y | | Amount object | | beneficiaryAccountNo | string | Y | 5552096217 | Beneficiary account number | | beneficiaryBankCode | string | Y | 002 | Beneficiary bank code | | additionalInfo | object | Y | | Additional Info | Contents of 'amount' fields: | Name | Type | Required | Value | Description | |------------------|-------------|----------|----------------------------------|--------------------------------------------------------------| | value | string | Y | 2000.00 | The amount of the transaction | | currency | string | Y | IDR | The currency of the transaction (3-letter currency ISO code) | Possible Disbursement statuses: | Status | Description | |--------|-------------------------| | 00 | Success | | 03 | Pending | | 04 | Refunded | | 06 | Failed | | 07 | Not found | ##### Successful Disbursement process (callback URL sample request) ```json { "responseCode": "2003600", "responseMessage": "Successful", "referenceNo": "203b4431392c4a1b92c59229a79f9965", "partnerReferenceNo": "aa226aa10bb11R6789u99ox4F11r9811", "amount": { "value": "10000.00", "currency": "IDR" }, "beneficiaryAccountNo": "355655569", "beneficiaryBankCode": "002", "additionalInfo": { "responseDescription": "SUCCESS", "notes": "testvalue" } } ``` ##### Processing Disbursement process (callback URL sample request) ```json { "responseCode": "2021800", "responseMessage": "Request In Progress", "referenceNo": "d7ae025fac65493da57f8d3781e1ea19", "partnerReferenceNo": "9966de1f263c4c1d9391f7527006cb36", "amount": { "value": "10000.00", "currency": "IDR" }, "beneficiaryAccountNo": "5552697224", "additionalInfo": { "responseDescription": "Transaction still on process", "notes": "Test", "additionalInfo2": "TestingProduction", "additionalInfo3": "Test" } } ``` ##### Insufficient balance Disbursement process (callback URL sample request) ```json { "responseCode": "4031814", "responseMessage": "Insufficient Funds", "referenceNo": "7f2e08964c73466fb8cddec87f7a5218", "partnerReferenceNo": "aa226aa10bb11R6789u99ox4F11r9811", "amount": { "value": "10000.00", "currency": "IDR" }, "beneficiaryAccountNo": "355655569", "beneficiaryBankCode": "002", "additionalInfo": { "responseDescription": "FAILED", "notes": "aa226aa10bb11R6789u99ox4F11r9811" } } ``` ##### Unsuccessful Disbursement process (callback URL sample request) ```json { "responseCode": "4031816", "responseMessage": "Suspend Transaction", "referenceNo": "7d35d0cb159e408d8d30bf674a1d5505", "partnerReferenceNo": "aa226aa10bb11R6789u99ox4F11r9811", "amount": { "value": "15000.00", "currency": "IDR" }, "beneficiaryAccountNo": "5552096217", "beneficiaryBankCode": "002", "additionalInfo": { "responseDescription": "FAILED", "notes": "Transfer" } } ```