# Kenya Payments API Documentation
# 1. How to get API Key
The user logs in to the cash register -> Developer Center -> API Key -> Create API key. API Key has a separate configuration page and is bound to a fixed IP address ("0.0.0.0" means no IP interception and filtering, and any IP can be accessed), and different API Keys can be configured to meet different needs. Please do not disclose your Access Key and Secret Key to avoid asset loss. After the Secret Key is generated, it cannot be viewed again. Please save it in time. If you forget the Secret Key, please recycle the key pair in the backstage of the merchant and apply for a new key pair.
# 1.1 How to create an API KEY
• Click Developer Center - API Key
• 1 Choose whether to enable the debug mode (after enabling the debug mode, if you have any errors, there will be a standard prompt message and log viewing address)
• 2Select API Key permissions
• 3Enter the whitelist address (0.0.0.0 means that any IP address can be accessed)
Note: (When entering the whitelist domain name, you should pay attention to using "," to isolate multiple IPs.)
• 4 click create to generate API KEY
(After the API KEY is generated, you can copy, view, edit, and delete it in the My API KEY list below. Note that the Secret key only appears once when it is generated. Please save it properly. If you forget the Secret Key, please recycle it key pair and apply for a new key pair.)
• Click Edit to close or open [Start Debugging] and modify API Key permissions and whitelist addresses. After modification, click Save
Note: Please wait patiently for 90 seconds for the API Key to take effect after creating or editing the API Key
# 2. How to use API Key
The current API Key is to add a parameter list in the header of the request
| parameter name | Parameter Description | type | Is it necessary |
|---|---|---|---|
| access_key | Api Key access key (eg: TPhoa7ZQ) | String | yes |
| timestamp | Millisecond time stamp (13 digits such as: 1679669488472) | String | yes |
| nonce | UUID (36 bits such as: 02f7a04f-53cc-47d4-bb3f-fae69dab49ac) The five parts are 8 characters, 4 characters, 4 characters, 4 characters, and 12 characters, separated by "-" | String | yes |
| sign | Parameter signature (eg: GXx2wYUD6UVr+zcmeCSFFPzcBLA=) | String | yes |
# 3. Technical side parameter access process
# 4. How to sign the interface
# Signature instructions
API requests are very likely to be tampered with during transmission over the internet. In order to ensure that the request has not been changed, all private interfaces except the public interface (basic information, market data, etc.) must use your API Key for signature authentication to verify Check whether the parameter or parameter value has changed in transit.
A legitimate request consists of the following parts:
- access_key: API access key;
- secret_key: the key used for signature encryption (only visible once when applying for an API Key in the background, please copy and save it in a safe place, and cannot disclose it);
- timestamp: The time (UTC time) when you made the request. Such as: 1632811287325 (13 digits). Including this value in a query request helps prevent third parties from intercepting your request;
- nonce: random UUID string. Such as: 053a1b81-48a0-4bb1-96b2-60f6e509d911 (36 bits);
- sign: The value calculated by the signature, which is used to ensure that the signature is valid and has not been tampered with;
- All interfaces need to pass the above public parameters except secret_key in the http request header (header) . The public parameters include (access_key, timestamp, nonce, sign) and other signature parameters are subject to the API interface description.
# Signature steps
1. Define a Map dictionary type object, and put the parameters in the request into it in the form of key-value
2. Put access_key, timestamp, and nonce into the Map defined in the first step
3. Sort the attributes in the Map in ascending order (lexicographic order) according to the ASCII code and convert the Map to a string in the form of "key1=value1&key2=value2"
4. Encrypt the character string converted in the previous step with secret_key by HMAC_SHA1 and perform Base64 transcoding to obtain the value of the sign parameter. secret_key is the information in the apikey created on the cashier platform
5. Add the sign value and other required parameters to the request header, and send the request to the target interface
# Signature Debugging Tool
SignUtil: The user logs in to the cash register -> Developer Center -> API Documentation -> Signature Tool to open the signature tool page (the access_key in the tool must use a valid access_key and please set the IP whitelist that allows this access_key access to 0.0.0.0, we It is strongly recommended to discard the used access_key after debugging)
# 5. Interface list
# 5.1 Test interface connectivity
request method
Get
Request URL
/ping
response data
{ "version" : "1.0.1" , "timestamp" : 1688116827306 }
Response parameter description
| Param | type | Desc |
|---|---|---|
| version | String | If this parameter is returned, all interfaces in this document can be requested normally |
| timestamp | int64 | Unix timestamp |
# 5.2 Create a new Virtual Accounts type collection order
request method
post
Request URL
/api/v3/ken/createCollectingOrder
request type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
request header
| Param | Desc | Sample |
|---|---|---|
| access_key | Merchant background acquisition | pFqV75X3 |
| timestamp | Unix timestamp 13 digit milliseconds | 1679724896223 |
| nonce | UUID V4 | 794c26b0-d33c-4394-b2bb-c485eca16d9e |
| sign | computed signature | kAXyh+eerqrefyaF8dyFB0M4FVo= |
request parameters
Description of request parameters
| Param | Desc | Sample | require |
|---|---|---|---|
| amount | Receipt amount, the decimal point cannot exceed 2 digits (String) | 10000 | required |
| channelType | Payment type (String) oneof=VIRTUA | VIRTUA | required |
| externalOrderId | Merchant order number max=64 (String) | 555555555555555433 | required |
| accountName | Bank Name oneof =BRI BNI MANDIRI PERMATA BSS BSI CIMB BCA BNC B1 BT M1 RI （String） | BRI | optional |
| notifyUrl | Notification URL (String, URL) | http://192.168.1.135:30001 | optional |
| returnUrl | returnAddress(String, URL) | http://192.168.1.135:30001 | optional |
response type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
response data
{
"code": "200",
"success": true,
"msg": "成功",
"msgEn": "SUCCESS",
"data": {
"cashierUrl": "http://192.168.1.200:1084/OCURRPAID202311010213331698804813742DEV001OO0000000200000877?data=eyJjYXNoaWVyQ3VycmVuY3lBbW91bnQiOjEwMDAwLjAwLCJjYXNoaWVyRXhwaXJlVGltZSI6MTY5\nODgwNjYxMzc1NiwiY2FzaGllcklkIjoiT0NVUlJQQUlEMjAyMzExMDEwMjEzMzMxNjk4ODA0ODEz\nNzQyREVWMDAxT08wMDAwMDAwMjAwMDAwODc3IiwiY2FzaGllclVybCI6Imh0dHA6Ly8xOTIuMTY4\nLjEuMjAwOjEwODQvT0NVUlJQQUlEMjAyMzExMDEwMjEzMzMxNjk4ODA0ODEzNzQyREVWMDAxT08w\nMDAwMDAwMjAwMDAwODc3IiwiY3VycmVuY3kiOiJJRFIiLCJjdXJyZW5jeU9yZGVyVm8iOnsiYW1v\ndW50IjoxMDAwMC4wMCwiY3VycmVuY3kiOiJJRFIiLCJleHRlcm5hbE9yZGVySWQiOiI1NTU1NTU1\nNTU1NTU1NTU0MzMiLCJtZXJjaGFudE5hbWUiOiJjbGFya19hZ2VudF9oYW1iaXQiLCJvcmRlcklk\nIjoiT0NVUlJQQUlEMjAyMzExMDEwMjEzMzMxNjk4ODA0ODEzNzc1REVWMDAxT08wMDAwMDAwNDAw\nMDAwODc4Iiwib3JkZXJTdGF0dXMiOiJBd2FpdGluZyBQYXltZW50Iiwib3JkZXJTdGF0dXNDb2Rl\nIjoxLCJvcmRlclRpbWUiOjE2OTg4MDQ4MTM3NzUsInBheVBhcmFtIjoie30iLCJwYXlUeXBlIjox\nMDQsInBheVR5cGVOYW1lIjoiVmlydHVhbCBBY2NvdW50cyIsInRyYWRlTm90ZSI6IiJ9LCJpc0Ny\nZWF0ZU9yZGVyIjp0cnVlLCJtZXJjaGFudElkIjoxNzA3Mjg1ODQwMzI2MTI3NjE3LCJwYXlUeXBl\nIjoxMDQsInVzZXJJbmZvTm8iOiJCUkkiLCJ2ZXJzaW9uIjoidjEifQ==&pm=W3siY3VycmVuY3lUeXBlIjoiTVhOIiwicGF5VHlwZXMiOlt7ImNvZGUiOjEwMiwidmFsdWUiOiJC\nQU5LIn1dfSx7ImN1cnJlbmN5VHlwZSI6Ik5HTiIsInBheVR5cGVzIjpbeyJjb2RlIjoxMDIsInZh\nbHVlIjoiQkFOSyJ9XX0seyJjdXJyZW5jeVR5cGUiOiJJRFIiLCJwYXlUeXBlcyI6W3siY29kZSI6\nMTAyLCJ2YWx1ZSI6IkJBTksifV19LHsiY3VycmVuY3lUeXBlIjoiSU5SIiwicGF5VHlwZXMiOlt7\nImNvZGUiOjEwMiwidmFsdWUiOiJCQU5LIn1dfSx7ImN1cnJlbmN5VHlwZSI6IkJSTCIsInBheVR5\ncGVzIjpbeyJjb2RlIjoxMDEsInZhbHVlIjoiUElYIn0seyJjb2RlIjoxMDMsInZhbHVlIjoiUElY\nX0RZTkFNSUMifV19XQ==",
"currency": "IDR",
"currencyOrderVo": {
"orderId": "OCURRPAID202311010213331698804813775DEV001OO0000000400000878",
"externalOrderId": "555555555555555433",
"currency": "IDR",
"amount": "10000",
"tradeNote": "",
"payTypeName": "Virtual Accounts"
}
}
}
Response parameter description
| Param | type | Desc |
|---|---|---|
| cashierUrl | String | Cashier link |
| orderId | String | System Order ID |
| externalOrderId | String | Merchant order ID |
| currency | String | currency code |
| amount | String | Receipt amount |
| tradeNote | String | Remark |
| payTypeName | String | Payment Type Name |
# 5.3 Create a new Ewallet type collection order
request method
post
Request URL
/api/v3/idn/ewallet/createCollectingOrder
request type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
request header
| Param | Desc | Sample |
|---|---|---|
| access_key | Merchant background acquisition | pFqV75X3 |
| timestamp | Unix timestamp 13 digit milliseconds | 1679724896223 |
| nonce | UUID V4 | 794c26b0-d33c-4394-b2bb-c485eca16d9e |
| sign | computed signature | kAXyh+eerqrefyaF8dyFB0M4FVo= |
request parameters
{
"currencyAmount":"10",
"channelType":"BANK",
"externalOrderId":"22222222222222",
"phone":"254115555088",
"bankName":"Impala credit",
"remark":"123",
"notifyUrl":https://dev-gw.hambit.co/api/v1/hambit/channel/notify/payout/1814182600440344577"
}
Description of request parameters
| Param | Desc | Sample | require |
|---|---|---|---|
| amount | Receipt amount, the decimal point cannot exceed 2 digits (String) | 10000 | required |
| channelType | Payment type (String) oneof=EWALLET | EWALLET | required |
| externalOrderId | Merchant order number max=64 (String) | 777777777777777721 | required |
| accountName | Bank Name oneof =OVO DANA LINKAJA SHOPEEPAY（String） | DANA | optional |
| accountNo | Wallet account hen the field 'account name' is OVO, it must be passed | 12312312 | optional |
| phone | Phone（String）OVO requires fields Phone Number, should begin with 628 or 08 | 628123456789 | optional |
| notifyUrl | Notification URL (String, URL) | http://192.168.1.135:30001 | optional |
| returnUrl | returnAddress(String, URL) | http://192.168.1.135:30001 | optional |
response type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
response data
{
"code": "200",
"success": true,
"msg": "成功",
"msgEn": "SUCCESS",
"data": {
"cashierUrl": "http://192.168.1.200:1084/OCURRPAID202311010213541698804834841DEV001OO0000000200000880?data=eyJjYXNoaWVyQ3VycmVuY3lBbW91bnQiOjEwMDAwLjAwLCJjYXNoaWVyRXhwaXJlVGltZSI6MTY5\nODgwNjYzNDg2MiwiY2FzaGllcklkIjoiT0NVUlJQQUlEMjAyMzExMDEwMjEzNTQxNjk4ODA0ODM0\nODQxREVWMDAxT08wMDAwMDAwMjAwMDAwODgwIiwiY2FzaGllclVybCI6Imh0dHA6Ly8xOTIuMTY4\nLjEuMjAwOjEwODQvT0NVUlJQQUlEMjAyMzExMDEwMjEzNTQxNjk4ODA0ODM0ODQxREVWMDAxT08w\nMDAwMDAwMjAwMDAwODgwIiwiY3VycmVuY3kiOiJJRFIiLCJjdXJyZW5jeU9yZGVyVm8iOnsiYW1v\ndW50IjoxMDAwMC4wMCwiY3VycmVuY3kiOiJJRFIiLCJleHRlcm5hbE9yZGVySWQiOiI3Nzc3Nzc3\nNzc3Nzc3Nzc3MjEiLCJtZXJjaGFudE5hbWUiOiJjbGFya19hZ2VudF9oYW1iaXQiLCJvcmRlcklk\nIjoiT0NVUlJQQUlEMjAyMzExMDEwMjEzNTQxNjk4ODA0ODM0ODg5REVWMDAxT08wMDAwMDAwNDAw\nMDAwODgxIiwib3JkZXJTdGF0dXMiOiJBd2FpdGluZyBQYXltZW50Iiwib3JkZXJTdGF0dXNDb2Rl\nIjoxLCJvcmRlclRpbWUiOjE2OTg4MDQ4MzQ4OTEsInBheVBhcmFtIjoiaHR0cHM6Ly9saW5rLmRh\nbmEuaWQvcGF5P2Jpek5vPTIwMjMxMTAxMTExMjEyODAwMTEwMTY2MzA1NDg4MzI5MTgwJnRpbWVz\ndGFtcD0xNjk4ODA0ODM2MTEyJm1pZD0yMTY2MjAwMDA1MzQ2MDg2NTI3NTQmc2lnbj1qM2RjaE1C\nN21IMjRMcnQ4TW5ydjllQ2NiSGJaZFBIejlxWk1Ub0hwMDVqUGdseE84eHZnQUNGS3ZjamZGbFNl\nN1pEWlVjTDU2MmVwcWlQUDQlMkZ6alo3TVB6SWx3UHJUeEdYaUwlMkZiUiUyRlQ0RmVhbERCbXpx\ndHBZNHJRWURzVzY4dktrRDMzYW1TeiUyQmI0JTJCakQ4ZzI0MFEwb2JPOXZ1WiUyRiUyRlYwTDNL\nJTJGbUY2NW8xazlWdW9EdnIyWVQlMkZJSzVvVFRabXpkODU1SFNaRllnVTBnMmtmV2dEZjVNanNV\neDJNUmNsZXJONTA5MUYlMkJYVDdQNHBZMEpBaXdjVHU1VktTb2QlMkI5c1ElMkZzNGY4cG1tV2l2\ncCUyRlJ3QiUyRnZqZFhsVkh4cVFSMkVjRzhIJTJGVWlTVFdJUFNEUnhOUDVHRHFpRWowSU9HY3hB\nYzdneUJ2aTFERnR4MERlMGN3STloTFElM0QlM0QmZm9yY2VUb0g1PWZhbHNlIiwicGF5VHlwZSI6\nMTA2LCJwYXlUeXBlTmFtZSI6IkVXYWxsZXQiLCJwYXlVcmwiOiJodHRwczovL2xpbmsuZGFuYS5p\nZC9wYXk/Yml6Tm89MjAyMzExMDExMTEyMTI4MDAxMTAxNjYzMDU0ODgzMjkxODAmdGltZXN0YW1w\nPTE2OTg4MDQ4MzYxMTImbWlkPTIxNjYyMDAwMDUzNDYwODY1Mjc1NCZzaWduPWozZGNoTUI3bUgy\nNExydDhNbnJ2OWVDY2JIYlpkUEh6OXFaTVRvSHAwNWpQZ2x4Tzh4dmdBQ0ZLdmNqZkZsU2U3WkRa\nVWNMNTYyZXBxaVBQNCUyRnpqWjdNUHpJbHdQclR4R1hpTCUyRmJSJTJGVDRGZWFsREJtenF0cFk0\nclFZRHNXNjh2S2tEMzNhbVN6JTJCYjQlMkJqRDhnMjQwUTBvYk85dnVaJTJGJTJGVjBMM0slMkZt\nRjY1bzFrOVZ1b0R2cjJZVCUyRklLNW9UVFptemQ4NTVIU1pGWWdVMGcya2ZXZ0RmNU1qc1V4Mk1S\nY2xlck41MDkxRiUyQlhUN1A0cFkwSkFpd2NUdTVWS1NvZCUyQjlzUSUyRnM0ZjhwbW1XaXZwJTJG\nUndCJTJGdmpkWGxWSHhxUVIyRWNHOEglMkZVaVNUV0lQU0RSeE5QNUdEcWlFajBJT0djeEFjN2d5\nQnZpMURGdHgwRGUwY3dJOWhMUSUzRCUzRCZmb3JjZVRvSDU9ZmFsc2UiLCJ0cmFkZU5vdGUiOiIi\nfSwiaXNDcmVhdGVPcmRlciI6dHJ1ZSwibWVyY2hhbnRJZCI6MTcwNzI4NTg0MDMyNjEyNzYxNywi\ncGF5VHlwZSI6MTA2LCJ1c2VySW5mb05vIjoiREFOQSIsInZlcnNpb24iOiJ2MSJ9&pm=W3siY3VycmVuY3lUeXBlIjoiTVhOIiwicGF5VHlwZXMiOlt7ImNvZGUiOjEwMiwidmFsdWUiOiJC\nQU5LIn1dfSx7ImN1cnJlbmN5VHlwZSI6Ik5HTiIsInBheVR5cGVzIjpbeyJjb2RlIjoxMDIsInZh\nbHVlIjoiQkFOSyJ9XX0seyJjdXJyZW5jeVR5cGUiOiJJRFIiLCJwYXlUeXBlcyI6W3siY29kZSI6\nMTAyLCJ2YWx1ZSI6IkJBTksifV19LHsiY3VycmVuY3lUeXBlIjoiSU5SIiwicGF5VHlwZXMiOlt7\nImNvZGUiOjEwMiwidmFsdWUiOiJCQU5LIn1dfSx7ImN1cnJlbmN5VHlwZSI6IkJSTCIsInBheVR5\ncGVzIjpbeyJjb2RlIjoxMDEsInZhbHVlIjoiUElYIn0seyJjb2RlIjoxMDMsInZhbHVlIjoiUElY\nX0RZTkFNSUMifV19XQ==",
"currency": "IDR",
"currencyOrderVo": {
"orderId": "OCURRPAID202311010213541698804834889DEV001OO0000000400000881",
"externalOrderId": "777777777777777721",
"currency": "IDR",
"amount": "10000",
"tradeNote": "",
"payTypeName": "EWallet"
}
}
}
Response parameter description
| Param | type | Desc |
|---|---|---|
| cashierUrl | String | Cashier link |
| orderId | String | System Order ID |
| externalOrderId | String | Merchant order ID |
| currency | String | currency code |
| amount | String | Receipt amount |
| tradeNote | String | Remark |
| payTypeName | String | Payment Type Name |
# 5.4 Create a new Qris type collection order
request method
post
Request URL
/api/v3/idn/qris/createCollectingOrder
request type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
request header
| Param | Desc | Sample |
|---|---|---|
| access_key | Merchant background acquisition | pFqV75X3 |
| timestamp | Unix timestamp 13 digit milliseconds | 1679724896223 |
| nonce | UUID V4 | 794c26b0-d33c-4394-b2bb-c485eca16d9e |
| sign | computed signature | kAXyh+eerqrefyaF8dyFB0M4FVo= |
request parameters
{
"amount":"10000",
"channelType":"QRIS",
"externalOrderId":"1231233123223122313312",
"notifyUrl":"http://192.168.1.135:30001",
"returnUrl":"http://192.168.1.135:30001"
}
Description of request parameters
| Param | Desc | Sample | require |
|---|---|---|---|
| amount | Receipt amount, the decimal point cannot exceed 2 digits (String) | 10000 | required |
| channelType | Payment type (String) oneof=QRIS | QRIS | required |
| externalOrderId | Merchant order number max=64 (String) | 1231233123223122313312 | required |
| notifyUrl | Notification URL (String, URL) | http://192.168.1.135:30001 | optional |
| returnUrl | returnAddress(String, URL) | http://192.168.1.135:30001 | optional |
response type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
response data
{
"code": "200",
"success": true,
"msg": "成功",
"msgEn": "SUCCESS",
"data": {
"cashierUrl": "http://192.168.1.200:1084/OCURRPAID202311010250241698807024604DEV001OO0000000200000891?data=eyJjYXNoaWVyQ3VycmVuY3lBbW91bnQiOjEwMDAwLjAwLCJjYXNoaWVyRXhwaXJlVGltZSI6MTY5\nODgwODgyNDYxNCwiY2FzaGllcklkIjoiT0NVUlJQQUlEMjAyMzExMDEwMjUwMjQxNjk4ODA3MDI0\nNjA0REVWMDAxT08wMDAwMDAwMjAwMDAwODkxIiwiY2FzaGllclVybCI6Imh0dHA6Ly8xOTIuMTY4\nLjEuMjAwOjEwODQvT0NVUlJQQUlEMjAyMzExMDEwMjUwMjQxNjk4ODA3MDI0NjA0REVWMDAxT08w\nMDAwMDAwMjAwMDAwODkxIiwiY3VycmVuY3kiOiJJRFIiLCJjdXJyZW5jeU9yZGVyVm8iOnsiYW1v\ndW50IjoxMDAwMC4wMCwiY3VycmVuY3kiOiJJRFIiLCJleHRlcm5hbE9yZGVySWQiOiIxMjMxMjMz\nMTIzMjIzMTIyMzEzMzEyIiwibWVyY2hhbnROYW1lIjoiY2xhcmtfYWdlbnRfaGFtYml0Iiwib3Jk\nZXJJZCI6Ik9DVVJSUEFJRDIwMjMxMTAxMDI1MDI0MTY5ODgwNzAyNDYzMERFVjAwMU9PMDAwMDAw\nMDQwMDAwMDg5MiIsIm9yZGVyU3RhdHVzIjoiQXdhaXRpbmcgUGF5bWVudCIsIm9yZGVyU3RhdHVz\nQ29kZSI6MSwib3JkZXJUaW1lIjoxNjk4ODA3MDI0NjMxLCJwYXlQYXJhbSI6IjAwMDIwMTAxMDIx\nMjI2NTcwMDExSUQuREFOQS5XV1cwMTE4OTM2MDA5MTUwMzQzNjgxMTA1MDIwOTM0MzY4MTEwNTAz\nMDNVS0U1MTQ0MDAxNElELkNPLlFSSVMuV1dXMDIxNUlEMjAyMjIyMjMzOTc2NjAzMDNVS0U1MjA0\nODk5OTUzMDMzNjA1NDA1MTAwMDA1ODAySUQ1OTA2UVJpbmRvNjAxNUtvdGEgSmFrYXJ0YSBTZTYx\nMDUxMjk1MDYyNzIwMTE1QkpSaXAzYmpvUXJxVlB2NjA0OTAwMTFJRC5EQU5BLldXVzA0MjVNRVIy\nMDIxMDcxNDAwNzc0NTA5NjA4NjQxMDUwMTE2MzA0MUFCRiIsInBheVR5cGUiOjEwNSwicGF5VHlw\nZU5hbWUiOiJRUklTIiwidHJhZGVOb3RlIjoiIn0sImlzQ3JlYXRlT3JkZXIiOnRydWUsIm1lcmNo\nYW50SWQiOjE3MDcyODU4NDAzMjYxMjc2MTcsInBheVR5cGUiOjEwNSwicmV0dXJuVXJsIjoiaHR0\ncHM6Ly9wbGF0Zm9ybS5oYW1iaXQuY28vIy9ob21lL2Rhc2hib2FyZCIsInZlcnNpb24iOiJ2MSJ9\n&pm=W3siY3VycmVuY3lUeXBlIjoiTVhOIiwicGF5VHlwZXMiOlt7ImNvZGUiOjEwMiwidmFsdWUiOiJC\nQU5LIn1dfSx7ImN1cnJlbmN5VHlwZSI6Ik5HTiIsInBheVR5cGVzIjpbeyJjb2RlIjoxMDIsInZh\nbHVlIjoiQkFOSyJ9XX0seyJjdXJyZW5jeVR5cGUiOiJJRFIiLCJwYXlUeXBlcyI6W3siY29kZSI6\nMTAyLCJ2YWx1ZSI6IkJBTksifV19LHsiY3VycmVuY3lUeXBlIjoiSU5SIiwicGF5VHlwZXMiOlt7\nImNvZGUiOjEwMiwidmFsdWUiOiJCQU5LIn1dfSx7ImN1cnJlbmN5VHlwZSI6IkJSTCIsInBheVR5\ncGVzIjpbeyJjb2RlIjoxMDEsInZhbHVlIjoiUElYIn0seyJjb2RlIjoxMDMsInZhbHVlIjoiUElY\nX0RZTkFNSUMifV19XQ==",
"currency": "IDR",
"currencyOrderVo": {
"orderId": "OCURRPAID202311010250241698807024630DEV001OO0000000400000892",
"externalOrderId": "1231233123223122313312",
"currency": "IDR",
"amount": "10000",
"tradeNote": "",
"payTypeName": "QRIS"
}
}
}
Response parameter description
| Param | type | Desc |
|---|---|---|
| cashierUrl | String | Cashier link |
| orderId | String | System Order ID |
| externalOrderId | String | Merchant order ID |
| currency | String | currency code |
| amount | String | Receipt amount |
| tradeNote | String | Remark |
| payTypeName | String | Payment Type Name |
# 5.5 Create a new transfer order
request method
post
Request URL
/api/v3/idn/createTransferOrder
request type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
request header
| Param | Desc | Sample |
|---|---|---|
| access_key | Merchant background acquisition | pFqV75X3 |
| timestamp | Unix timestamp 13 digit milliseconds | 1679724896223 |
| nonce | UUID V4 | 794c26b0-d33c-4394-b2bb-c485eca16d9e |
| sign | computed signature | kAXyh+eerqrefyaF8dyFB0M4FVo= |
request parameters
{
"currencyAmount": "10000.20",
"channelType": "BANK",
"externalOrderId": "826169739606698345",
"accountId": "13178968534",
"bankName": "AndhraBank",
"accountType": "IDR",
"accountName": "Yonatan",
"notifyUrl": "http://192.168.1.135:30001",
"remark": "123"
}
Description of request parameters
| Param | Desc | Sample | require |
|---|---|---|---|
| currencyAmount | The decimal of the payment amount cannot be greater than 2 digits (String) | 10000.20 | required |
| channelType | Payment Type oneof = BANK WALLET(String) | BANK | required |
| externalOrderId | Merchant order number max=64 (String) | 687279463984441035 | required |
| accountId | Bank account number (String) | 13178968584 | required |
| bankName | Bank name (String) | YesBank According to the actual situation | required |
| accountType | Bank account type oneof=IDR (String) | IDR | required |
| accountName | Account name (String) | Yonatan According to the actual situation | required |
| remark | Note max=255 (String) | 123 | optional |
| notifyUrl | Notification URL (String) | http://192.168.1.135:30001 | optional |
response type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
response data
{
"code" : "200" ,
"success" : true ,
"msg" : "Success" ,
"msgEn" : "SUCCESS" ,
"data" : {
"orderId" : "OCURRDRAW202308220659491692687589549DOCK02OO0000000200003653" ,
"orderStatus" : "Accepted" ,
"externalOrderId" : "826169739606698345" ,
"currencyType" : "IDR"
}
}
Response parameter description
| Param | type | Desc |
|---|---|---|
| orderId | String | System Order ID |
| orderStatus | String | Order Status |
| externalOrderId | String | merchant order id |
| currencyType | String | Fiat currency type |
# 5.6 Query collection orders
request method
post
Request URL
/api/v3/idn/query/collectingOrder
request type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
request header
| Param | Desc | Sample |
|---|---|---|
| access_key | Merchant background acquisition | pFqV75X3 |
| timestamp | Unix timestamp 13 digit milliseconds | 1679724896223 |
| nonce | UUID V4 | 794c26b0-d33c-4394-b2bb-c485eca16d9e |
| sign | computed signature | kAXyh+eerqrefyaF8dyFB0M4FVo= |
request parameters
{
"externalOrderId" : "241534072867503522" ,
"orderId" : "OCURRPAID202308220659471692687587691DOCK02OO0000000400003652"
}
Description of request parameters
| Param | Desc | require |
|---|---|---|
| externalOrderId | Merchant order number max=64 (String) | required |
| orderId | System order number (String) | required |
response type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
response data
{
"code" : "200" ,
"success" : true ,
"msg" : "Success" ,
"msgEn" : "SUCCESS" ,
"data" : [{
"orderId" : "OCURRPAID202308220659471692687587691DOCK02OO0000000400003652" ,
"cashierId" : "OCURRPAID202308220659471692687587416DOCK02OO0000000200003651" ,
"orderType" : 1 ,
"orderResourceType" : 2 ,
"userId" : "1663371399710216194" ,
"orderStatus" : 1 ,
"orderTime" : 1692687588000 ,
"channelOrderId" : "230822170261LXvDYM" ,
"externalOrderId" : "716134866255702461" ,
"orderAmount" : "40.2" ,
"orderActualAmount" : null ,
"orderFee" : null ,
"orderPayTime" : null ,
"orderCompleteTime" : null ,
"currencyType" : "IDR" ,
"payType" : 102 ,
"tradeNote" : "123" ,
"notifyUrl" : "http://192.168.1.135:30001/" ,
"markStatus" : 0 ,
"errorMsg" : "" ,
"errorMsgEn" : "" ,
"accountType" : "" ,
"accountName" : "" ,
"accountNo" : "" ,
"orderTypeCode" : "Pay" ,
"orderResourceTypeCode" : "Currency" ,
"orderStatusCode" : "Accepted" ,
"payTypeCode" : "BANK"
}]
}
Response parameter description
| Param | type | Desc |
|---|---|---|
| orderId | String | order ID |
| cashierId | String | Cashier ID |
| orderType | int64 | Order Type 1 - Collection |
| orderResourceType | int64 | The business type of the order 2-Fiat currency order |
| userId | String | User ID |
| orderStatus | int64 | Order status 1- pending payment 2- payment successful |
| orderTime | int64 | Order initiation time |
| channelOrderId | String | Order associated channel order ID |
| externalOrderId | String | Merchant order number |
| orderAmount | String | order amount |
| orderActualAmount | String | The actual amount of the order |
| order fee | int64 | Order handling fee |
| orderPayTime | int64 | order payment time |
| orderCompleteTime | int64 | order completion time |
| currencyType | String | currency type |
| payType | int64 | Payment type 102:BANK 202:BANK |
| tradeNote | String | Remark |
| notifyUrl | String | Callback URL |
| markStatus | int64 | mark status |
| errorMsg | String | error message |
| errorMsgEn | String | error message en |
| accountType | String | account type |
| accountName | String | account name |
| accountNo | String | account number |
| orderTypeCode | String | order type code |
| orderResourceTypeCode | String | The business type code to which the order belongs |
| orderStatusCode | String | orderStatusc description |
| payTypaCode | String | Payment type code reference payType |
# 5.7 Query transfer orders
request method
post
Request URL
/api/v3/idn/query/transferOrder
request type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
request header
| Param | Desc | Sample |
|---|---|---|
| access_key | Merchant background acquisition | pFqV75X3 |
| timestamp | Unix timestamp 13 digit milliseconds | 1679724896223 |
| nonce | UUID V4 | 794c26b0-d33c-4394-b2bb-c485eca16d9e |
| sign | computed signature | kAXyh+eerqrefyaF8dyFB0M4FVo= |
request parameters
{
"externalOrderId" : "241534072867503522" ,
"orderId" : "OCURRDRAW202308220659491692687589549DOCK02OO0000000200003653"
}
Description of request parameters
| Param | Desc | require |
|---|---|---|
| externalOrderId | Merchant order number max=64 (String) | required |
| orderId | System order number (String) | required |
response type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
response data
{
"code" : "200" ,
"success" : true ,
"msg" : "Success" ,
"msgEn" : "SUCCESS" ,
"data" : [{
"orderId" : "OCURRDRAW202308220659491692687589549DOCK02OO0000000200003653" ,
"cashierId" : "" ,
"orderType" : 2 ,
"orderResourceType" : 2 ,
"userId" : "1663371399710216194" ,
"orderStatus" : 1 ,
"orderTime" : 1692687590000 ,
"channelOrderId" : "" ,
"externalOrderId" : "826169739606698345" ,
"orderAmount" : "40.2" ,
"orderActualAmount" : "41" ,
"orderFee" : "0.8" ,
"orderPayTime" : null ,
"currencyType" : "IDR" ,
"payType" : 202 ,
"tradeNote" : "123" ,
"notifyUrl" : "http://192.168.1.135:30001" ,
"markStatus" : 0 ,
"errorMsg" : "" ,
"errorMsgEn" : "" ,
"accountType" : "" ,
"accountName" : "AndhraBank" ,
"accountNo" : "13178968534" ,
"orderTypeCode" : "Transfer" ,
"orderResourceTypeCode" : "Currency" ,
"orderStatusCode" : "Accepted" ,
"payTypeCode" : "BANK"
}]
}
Response parameter description
| Param | type | Desc |
|---|---|---|
| orderId | String | order ID |
| cashierId | String | Cashier ID |
| orderType | int64 | Order Type 2 - Pay on behalf |
| orderResourceType | int64 | The business type of the order 2-Fiat currency order |
| userId | String | User ID |
| orderStatus | int64 | Order status 1-accepted 2-bank processing 4-failed (not accepted by the bank) 8-success 16-failure |
| orderTime | int64 | Order initiation time |
| channelOrderId | String | Order associated channel order ID |
| externalOrderId | String | Merchant order number |
| orderAmount | String | order amount |
| orderActualAmount | String | The actual amount of the order |
| order fee | int64 | Order handling fee |
| orderPayTime | int64 | order payment time |
| currencyType | String | currency type |
| payType | int64 | Payment type 102:BANK 202:BANK |
| tradeNote | String | Remark |
| notifyUrl | String | Callback URL |
| markStatus | int64 | mark status |
| errorMsg | String | error message |
| errorMsgEn | String | error message en |
| accountType | String | account type |
| accountName | String | account name |
| accountNo | String | account number |
| orderTypeCode | String | order type code |
| orderResourceTypeCode | String | The business type code to which the order belongs |
| orderStatusCode | String | orderStatusDescription |
| payTypeCode | String | Payment type code reference payType |
# 5.8 Query balance
request method
Get
Request URL
/api/v3/idn/query/balance
request type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
request header
| Param | Desc | Sample |
|---|---|---|
| access_key | Merchant background acquisition | pFqV75X3 |
| timestamp | Unix timestamp 13 digit milliseconds | 1679724896223 |
| nonce | UUID V4 | 794c26b0-d33c-4394-b2bb-c485eca16d9e |
| sign | computed signature | kAXyh+eerqrefyaF8dyFB0M4FVo= |
response type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
response data
{
"code" : "200" ,
"success" : true ,
"msg" : "Success" ,
"msgEn" : "SUCCESS" ,
"data" : [{
"accountBalance" : "10026.1" ,
"accountFreezeAmount" : "0" ,
"accountStatusId" : 4 ,
"accountWaitSettledAmount" : "0" ,
"currencyType" : "IDR" ,
"accountStatus" : "InAndOut"
}]
}
Response parameter description
| Param | type | Desc |
|---|---|---|
| accountBalance | String | Account Available Balance |
| accountFreezeAmount | String | Account frozen amount |
| accountStatusId | int64 | account status id |
| accountWaitSettledAmount | String | Amount to be transferred from the account |
| currencyType | String | Fiat currency type |
| accountStatus | String | Account Status |
# 5.9 Inquiry Bank
request method
POST
Request URL
/api/v3/idn/query/bank
request type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
request header
| Param | Desc | Sample |
|---|---|---|
| access_key | Merchant background acquisition | pFqV75X3 |
| timestamp | Unix timestamp 13 digit milliseconds | 1679724896223 |
| nonce | UUID V4 | 794c26b0-d33c-4394-b2bb-c485eca16d9e |
| sign | computed signature | kAXyh+eerqrefyaF8dyFB0M4FVo= |
request parameters
{ "bankName" : "Bank BRI" }
If you need to query all bank values, pass an empty string, as follows:
{ "bankName" : "" }
Description of request parameters
| Param | Desc | require |
|---|---|---|
| bankName | Bank name (String) | required |
response type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
response data
{
"code" : "200" ,
"success" : true ,
"msg" : "Success" ,
"msgEn" : "SUCCESS" ,
"data" : [{
"bankName": "Bank BRI",
"bankCode": "002",
"currencyType": "IDR",
"channelBankId": "583",
"channelId": "1703647674332692481"
}]
}
Response parameter description
| Param | type | Desc |
|---|---|---|
| bankName | String | Bank name |
| bankCode | String | bank code |
| currencyType | String | currency type |
| channelBankId | String | Channel Bank ID |
| channelId | String | channel ID |
# 5.10 Bank List (Bank List for reference only, please refer to the query bank interface to return the data bill of lading)
| BankName |
|---|
| Bank BRI |
| Bank Mandiri |
| Bank BNI |
| Bank Danamon |
| Bank Permata |
| Bank Permata Syariah |
| Bank BCA |
| BII Maybank |
| Bank Panin |
| CIMB Niaga |
| Bank UOB INDONESIA |
| Bank OCBC NISP |
| CITIBANK |
| Bank Windu Kentjana International |
| Bank ARTHA GRAHA |
| Bank TOKYO MITSUBISHI UFJ |
| Bank DBS |
| Standard Chartered |
| Bank CAPITAL |
| ANZ Indonesia |
| Bank OF CHINA |
| Bank Bumi Arta |
| Bank HSBC |
| Bank Antardaerah |
| Bank Rabobank |
| Bank JTRUST INDONESIA |
| Bank MAYAPADA |
| Bank Jawa Barat |
| Bank DKI |
| Bank BPD DIY |
| Bank JATENG |
| Bank Jatim |
| Bank Jambi |
| Bank Jambi Syariah |
| Bank Aceh |
| Bank Aceh Syariah |
| Bank SUMUT |
| Bank NAGARI |
| Bank Riau |
| Bank Riau Syariah |
| Bank SUMSEL BABEL |
| Bank SUMSEL BABEL Syariah |
| Bank Lampung |
| Bank KALSEL |
| Bank KALBAR |
| Bank BPD Kaltim |
| Bank BPD Kalteng |
| Bank SULSELBAR |
| Bank Sulut |
| Bank NTB |
| Bank NTB Syariah |
| Bank BPD Bali |
| Bank NTT |
| Bank Maluku |
| Bank BPD Papua |
| Bank SULTENG |
| Bank Sultra |
| Bank BANTEN |
| Bank Nusantara Parahyangan |
| Bank Of India Indonesia |
| Bank Muamalat |
| Bank Mestika |
| Bank SHINHAN |
| Bank Sinarmas |
| Bank Maspion |
| Bank Ganesha |
| Bank ICBC |
| Bank QNB indonesia |
| Bank BTN |
| Bank Woori Saudara |
| Bank BTPN |
| Bank Victoria Syariah |
| Bank Jabar Banten Syariah |
| Bank Mega |
| Bank Bukopin |
| Bank Syariah Indonesia |
| Bank Jasa Jakarta |
| Bank KEB HANA |
| Bank MNC INTERNATIONAL |
| Bank YUDHA BHAKTI/ Bank Neo Commerce |
| Bank Rakyat Indonesia AGRONIAGA |
| Bank SBI Indonesia (Indomonex) |
| Bank Royal |
| Bank National Nobu |
| Bank MEGA SYARIAH |
| Bank INA |
| Bank PANIN SYARIAH |
| PRIMA MASTER BANK |
| Bank SYARIAH BUKOPIN |
| Bank Sahabat Sampoerna |
| Bank DINAR |
| Bank Seabank Indonesia |
| Bank BCA SYARIAH |
| Bank ARTOS/ Bank Jago |
| Bank BTPN SYARIAH |
| Bank MULTIARTA SENTOSA |
| Bank Mayora |
| Bank INDEX |
| CNB |
| Bank MANTAP |
| Bank VICTORIA INTL |
| HARDA |
| BPR KS |
| IBK |
| Bank CTBC Indonesia |
| Bank COMMONWEALTH |
| Dana |
| Gopay |
| LinkAja |
| OVO |
| ShopeePay |
| Bank BCA |
| Bank BRI |
| BANK MANDIRI |
| BANK BNI 46 |
| BANK CIMB NIAGA |
| BANK PERMATA |
| Bank BJB |
| BANK DANAMON INDONESIA |
| Bank BTN |
| BANK MAYBANK INDONESIA |
| BANK SINARMAS |
| BANK PANIN |
| BANK BNI SYARIAH |
| BANK SYARIAH MANDIRI |
| BPD DKI JAKARTA |
| BANK MEGA |
| BSI (Bank Syariah Indonesia) |
| Bank BTPN |
| BANK BRI SYARIAH |
| BANK MUAMALAT INDONESIA |
| BANK OCBC NISP |
| wallt OVO(WLLT) |
| wallt SHOPEEPAY(WLLT) |
| wallt DANA(WLLT) |
| wallt GOPAY(WLLT) |
# 6. Callback information
# 6.1 How to call back the interface for signature verification
# Signature verification instructions
API requests are likely to be tampered with during transmission over the internet. To ensure that callbacks have not been changed, you can set callback parameter signature authentication. The setting method is: log in to the cashier -> developer center -> callback address -> add.
# Signature verification steps
The overall process is roughly the same as the signature, except that the data used to verify the signature is different. The signature is to construct the data by itself, and the signature is to obtain the data (header, json)
- Take out the sign value in the header;
- Define a Map dictionary type object, and put the json parameters in the request into it in the form of key-value
- Take out the access_key, timestamp, and nonce in the header and put them into the Map defined in the previous step
- Sort the keys in the Map according to the ASCII code from small to large (lexicographic order) and convert the Map to a string in the form of "key1=value1&key2=value2";
- Encrypt the string converted in the previous step with secret_key by HMAC_SHA1 and transcode it with Base64, and verify the signed value with the sign extracted from the header in the first step. If they match, the signature verification will pass, otherwise, the signature verification will fail. The secret_key here needs to match the access_key when placing an order.
# 6.2 Payment callback
callback data
{
"currencyType" : "IDR" ,
"orderAmount" : "40.2" ,
"orderTime" : 1692687588000 ,
"payType" : 102 ,
"orderId" : "OCURRPAID202308220659471692687587691DOCK02OO0000000400003652" ,
"orderStatusCode" : 1 ,
"orderStatus" : "Wait pay" ,
"markStatus" : 0 ,
"payParam" : "https://rarpay.test.rarpay.com/index/pay/mchtestpage/tp/dd/ordernum/230822170261LXvDYM" ,
"externalOrderId" : "716134866255702461" ,
"tradeNote" : "123" ,
"payTypeName" : "BANK"
}
Callback data description
| Param | type | Desc |
|---|---|---|
| currencyType | String | Fiat currency type |
| orderAmount | float64 | Order Creation Amount |
| orderTime | int64 | Order creation time |
| payType | int64 | Payment Types |
| orderId | String | order ID |
| orderStatusCode | int64 | Order status code 1-pending payment 2- payment successful |
| orderStatus | String | orderStatusCode description |
| markStatus | String | mark status |
| payParam | String | Payment Types |
| externalOrderId | String | Merchant order ID |
| tradeNote | String | Remark |
| payTypeName | String | payment type name |
| errorMsg | String | error message |
| errorMsgEn | String | error message en |
*At any time, the merchant can log in to the backstage of the merchant to manually trigger the callback* (it is not recommended to initiate a manual callback if the order is not in the final state). The status is not final, and the platform will still initiate a notification when the order becomes final, please pay attention to the redundant processing at the business level)
# 6.3 transfer callback
callback data
{
"currencyType": "IDR",
"accountCode": "BRI",
"accountName": "Bank BRI",
"orderId": "OCURRDRAW202410191632291729355549579EDEG2OOO0000000224580757",
"orderFee": "50",
"orderStatus": "Completed",
"errorMsgEn": "complate",
"externalOrderId": "20241020003228610sk4ESXPk872c554",
"errorMsg": "complate",
"payTypeName": "BANK",
"orderAmount": "10000",
"orderTime": 1729355550000,
"payType": 202,
"userInfoName": "KSTB",
"accountNo": "2210097174",
"orderStatusCode": 8,
"markStatus": 0,
"orderPayTime": 1729355701000
}
Callback data description
| Param | type | Desc |
|---|---|---|
| currencyType | String | currency type |
| accountCode | String | account Code |
| orderPayTime | int | order Pay Time |
| userInfoNo | String | User Credential Information |
| accountName | String | account name |
| orderId | String | order ID |
| order fee | String | Order handling fee |
| orderStatus | String | orderStatusCode description |
| externalOrderId | int64 | Merchant order ID |
| tradeNote | String | Remark |
| payTypeName | float64 | payment type name |
| orderAmount | float64 | Order Creation Amount |
| orderTime | int64 | Order creation time |
| payType | int64 | Payment type |
| accountNo | String | Remark |
| orderStatusCode | String | Order status code 1-accepted 2-bank processing 4-failure (not accepted by the bank) 8-success 16-failure |
| markStatus | String | User ID Type |
| errorMsg | String | error message |
| errorMsgEn | String | error message en |
At any time, the merchant can log in to the backstage of the merchant to manually trigger the callback (it is not recommended to initiate a manual callback if the order is not in the final state). The status is not final, and the platform will still initiate a notification when the order becomes final, please pay attention to the redundant processing at the business level)
# 6.4 Callback response
Remarks: All callbacks include signature information. It is recommended that merchants do a callback signature verification. After receiving the callback information, the merchant will determine the final status of the order. Please respond to the website
Regarding the following information (content-type: application/json), if there is no normal response from the server, it will be within 30 minutes, with a total interval of three minutes, totaling 2
notice
{ "code" : 200 , "success" : true }
# 6.5 Callback Notification URL
Log in to the merchant background to configure a unified callback address (manually specify the callback UR address in the order, which has a higher priority than the uniformly configured callback address. For example, if the notifyUrl parameter is specified in the order, regardless of whether there is a unified configuration of the callback notification address, the URL in the order will be used. notifyUrl address)
Note that the http response status_code has the highest priority as long as the response status_code=200 is received and the response data is ignored
# 7. Public Response Code
| filed | type | Default value and comment |
|---|---|---|
| code | String | Success "200" Other please refer to the failure code |
| success | Bool | Success is true, failure is false, and code is kept in sync |
| msg | String | The textual description returned by the first-level code |
| data | object | Refer to the interface list chapter |
# 8. Failure code
| Code | Desc |
|---|---|
| 200 | normal |
| 300 | Parameter exception |
| 301 | IP has no authority |
| 307 | signature error |
| 500 | system error |