NAV undefined
undefined
bash php java

Introduction

Welcome! Here at Instamoney, our mission is to provide payments infrastructure that helps you succeed. We help with both the money in (accepting payments) and money out (disbursing payments). Use cases range from platform business to fintech lending and eCommerce, and everything else in between.

The Instamoney API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors.

Authentication

To successfully authenticate with Instamoney's API, you must append a colon and Base 64 encode the API key you find in the dashboard. For example if your API key is

sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==

First, add a colon at the end

sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==:

Finally, Base64 encode the colon appended key to get

c2tfdGVzdF9PWUNFZkw1eGdMTCtsOFp2SzdRYVNHR1ZNTjczb05FcGszeXorUnhuLzJiUy9MQ2dDUVorZ3c9PTo=

Instamoney API is organized around REST to make it cleaner and easier to understand. All our API responses return JSON. To let you explore our APIs, we provide you API keys for both the development and production environments. All requests made in the development environment will never hit the banking networks and will not cost you anything.

Before using the API, make sure that you have registered and get your account authenticated as API requests without authentication will fail. To authenticate your account, you have to include your secret API key in the request which can be accessed in Instamoney Dashboard. You can manage your API keys in the Dashboard > Settings > API Keys. Your development and production keys determine your environment. Your API keys should be kept private so do not share your secret API keys.

All the API requests should be made over HTTPS instead of HTTP (all calls made over plain HTTP will fail). We also provide PHP client libraries to save you time. We’re developing more libraries and plugins in the near future and if you write your own library, we would love to hear about it. Make sure you’ve completed the authentication before using our API.

Balances

Get balance

Endpoint: Get Balance

GET https://api.instamoney.co/balance?account_type={account_type}

Balance is like your wallet since it will tell you how much money is available to you on Instamoney. You can retrieve it to see the current balance on your Instamoney cash account. Your balance is debited on any money out transaction, e.g. when performing disbursements or Instamoney fees are charged. Your balance is credited when money comes into your account, e.g. fixed virtual accounts are paid or you deposit funds. You can assign your money into different accounts according to your business logic (eg: cash account, tax account, escrow account) and each account has its own balance that can be accessed in the dashboard.

Get Balance Request

Example Get Balance Request

curl https://api.instamoney.co/balance -X GET \
-u sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==:
<?php
  require 'vendor/autoload.php';

  $options['secret_api_key'] = 'sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==';

  $instamoneyPHPClient = new InstamoneyClient\InstamoneyPHPClient($options);

  $response = $instamoneyPHPClient->getBalance();
  print_r($response);
?>
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Response response = client.target("https://api.instamoney.co/balance")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Authorization", "Basic c2tfdGVzdF9PWUNFZkw1eGdMTCtsOFp2SzdRYVNHR1ZNTjczb05FcGszeXorUnhuLzJiUy9MQ2dDUVorZ3c9PTo=")
  .get();

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));

Get Balance allows you to retrieve the balance of your cash, escrow and tax account. Some use cases include: deciding when you may need to withdraw funds, determining if you have funds to disburse, and if you just like to check it’s still there :P

Currently, the API only supports querying the balance for your cash, escrow and tax account. Anything else related to the account (eg: adding new account, transferring money from accounts besides cash account, etc.) will be done at the beginning in initial configuration with our technical team.

Parameter Description
account_type
optional
default: CASH
string The selected account type (CASH or HOLDING).

Get Balance Response

Example Get Balance Response

{
  "balance": 1241231
}
Parameter Description
balance The balance remaining in your cash account

Virtual Accounts

Get banks for virtual accounts

Endpoint: Get Available Banks for Virtual Accounts

GET https://api.instamoney.co/available_virtual_account_banks

Example Get Banks for Virtual Accounts Request

curl https://api.instamoney.co/available_virtual_account_banks -X GET \
   -u sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==:
<?php
  require 'vendor/autoload.php';

  $options['secret_api_key'] = 'sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==';

  $instamoneyPHPClient = new InstamoneyClient\InstamoneyPHPClient($options);

  $response = $instamoneyPHPClient->getVirtualAccountBanks();
  print_r($response);
?>

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Response response = client.target("https://api.instamoney.co/available_virtual_account_banks")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Authorization", "Basic c2tfdGVzdF9PWUNFZkw1eGdMTCtsOFp2SzdRYVNHR1ZNTjczb05FcGszeXorUnhuLzJiUy9MQ2dDUVorZ3c9PTo=")
  .get();

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));

Get Banks for Virtual Accounts Response

Example Get Banks for Virtual Accounts Response

{
  "name": "Bank Negara Indonesia",
  "code": "BNI"
}
Parameter Description
name Full name of the bank
code Code of the bank, relevant during creation of virtual accounts

Create fixed virtual accounts

Endpoint: Create Fixed Virtual Account (FVA)

POST https://api.instamoney.co/callback_virtual_accounts

Fixed virtual accounts are dedicated virtual accounts under a name you choose, e.g. 'YourCompany - Becca Salim'. You will receive a callback each time this fixed virtual account is paid. Read more about fixed virtual accounts.

Create Fixed Virtual Accounts Request

Example Create Fixed Virtual Accounts Request

curl https://api.instamoney.co/callback_virtual_accounts -X POST \
   -u sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==: \
   -d external_id=demo_virtual_account_1475459775872 \
   -d bank_code=BNI \
   -d name='Rika Sutanto'
<?php
  require 'vendor/autoload.php';

  $options['secret_api_key'] = 'sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==';

  $instamoneyPHPClient = new InstamoneyClient\InstamoneyPHPClient($options);

  $external_id = 'demo_1475459775872';
  $bank_code = 'BNI';
  $name = 'Rika Sutanto';

  $response = $instamoneyPHPClient->createCallbackVirtualAccount($external_id, $bank_code, $name);
  print_r($response);
?>
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Entity payload = Entity.json("{  'external_id': 'user_1212412312',  'bank_code': 'BNI',  'name': 'William Sutanto'}");
Response response = client.target("https://api.instamoney.co/callback_virtual_accounts")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Authorization", "Basic c2tfdGVzdF9PWUNFZkw1eGdMTCtsOFp2SzdRYVNHR1ZNTjczb05FcGszeXorUnhuLzJiUy9MQ2dDUVorZ3c9PTo=")
  .post(payload);

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));
Parameter Description
external_id
required
string An ID of your choice. Often it is unique identifier like a phone number, email or transaction ID. Maximum length allowed is 1000 characters.
bank_code
required
string Bank code of the virtual account you want to create
Note: We highly recommend you redirect customers to pay into BNI Virtual Account for interbank transfers
name
required
string Name of user/virtual account, - this will be displayed in the bank's user interface, e.g. ATM confirmation screens. Note that this field can only contain letters and spaces and has no length restriction (though the banks will truncate as per their limitations)
virtual_account_number
optional
string The virtual account number you want to assign. If you do not send one, one will be picked at random
suggested_amount
optional
number The suggested amount you want to assign. If you do not send one, external id will be used
Note: suggested amounts is only supported for Mandiri and BRI
is_closed
optional
boolean When set to true, the virtual account will be closed and will only accept the amount specified in expected_amount
expected_amount
optional
number The amount that the virtual account will expect if is_closed is set to true
expiration_date
optional
ISO Date The time when the virtual account will be expired
is_single_use
optional
boolean When set to true, the virtual account will be inactive after it is paid

Create Fixed Virtual Accounts Response

Example Create Fixed Virtual Accounts Response

{
   "owner_id":"57b4e5181473eeb61c11f9b9",
   "external_id":"demo-1475804036622",
   "bank_code":"BNI",
   "merchant_code":"8808",
   "name":"Rika Sutanto",
   "account_number":"88082548",
   "is_closed": false,
   "id":"57f6fbf26b9f064272622aa6",
   "is_single_use": true,
   "status": "ACTIVE"
}
Parameter Description
owner_id Your user ID
external_id An ID of your choice which you provided upon request
bank_code Bank code for the relevant bank, e.g. BNI
merchant_code 5-digit merchant prefix to the full virtual account number
name Name for the fixed virtual account
account_number Complete virtual account number (including prefix). This is what a user will need to enter into an ATM or their Internet/mobile banking.
suggested_amount OPTIONAL suggested amount for created fixed virtual account
is_closed value that determines whether a virtual account is closed or not
expected_amount OPTIONAL the amount that is expected when is_closed is true
id Unique ID for the fixed virtual account.
is_single_use value that determines whether a virtual account will be inactive after it is paid
status Status of fixed virtual account that defines if it’s pending or inactive. Status is inactive either because it is a paid single use fixed virtual account or it is already expired.

Create Fixed Virtual Accounts Errors

Error Code Description
API_VALIDATION_ERROR
400
Inputs are failing validation. The errors field contains details about which fields are violating validation.
INVALID_JSON_FORMAT
400
The request body is not a valid JSON format.
VIRTUAL_ACCOUNT_NUMBER_OUTSIDE_RANGE
400
The virtual account number you want is outside your range.
BANK_NOT_SUPPORTED_ERROR
400
The bank code is not currently supported.
EXPIRATION_DATE_NOT_SUPPORTED_ERROR
400
Custom expiration date for the fixed virtual account is not currently supported.
EXPIRATION_DATE_INVALID_ERROR
400
Invalid custom expiration date because it's earlier than current time.
SUGGESTED_AMOUNT_NOT_SUPPORTED_ERROR
400
The suggested amount for the fixed virtual account is not currently supported.
EXPECTED_AMOUNT_REQUIRED_ERROR
400
The expected amount is required when is_closed is set to true.
CLOSED_VA_NOT_SUPPORTED_ERROR
400
The closed option for this virtual account is not currently supported.
DUPLICATE_CALLBACK_VIRTUAL_ACCOUNT_ERROR
400
The account number that you want to create is already exist
MINIMUM_EXPECTED_AMOUNT_ERROR
400
The expected amount can only be more than zero
MAXIMUM_EXPECTED_AMOUNT_ERROR
400
The expected amount can only be less than Rp.1000000000
CALLBACK_VIRTUAL_ACCOUNT_NAME_NOT_ALLOWED_ERROR
400
The name cannot contain bank or institution name

Update fixed virtual accounts

Endpoint: Update Fixed Virtual Account (FVA)

PATCH https://api.instamoney.co/callback_virtual_accounts/{fixed_virtual_account_id}

Fixed Virtual Account is so adaptable, and it's all based on your needs. Therefore, we provide you this endpoint to easily update your fixed virtual account as you like.

Update Fixed Virtual Accounts Request

Parameter Description
suggested_amount
optional
number suggested amount you want to assign
expected_amount
optional
number The amount that the virtual account will expect if is_closed is set to true
expiration_date
optional
ISO Date The time when the virtual account will be expired. You can set it to be days in the past to expire virtual account immediately
is_single_use
optional
boolean When set to true, the virtual account will be inactive after it is paid

Update Fixed Virtual Accounts Response

Example update Fixed Virtual Accounts Response

{
   "owner_id":"57b4e5181473eeb61c11f9b9",
   "external_id":"demo-1475804036622",
   "bank_code":"BNI",
   "merchant_code":"8808",
   "name":"Rika Sutanto",
   "account_number":"88082548",
   "suggested_amount":50000,
   "is_closed": false,
   "id":"57f6fbf26b9f064272622aa6",
   "is_single_use": true,
   "status": "ACTIVE"
}
Parameter Description
owner_id Your user ID
external_id An ID of your choice which you provided upon virtual account creation
bank_code Bank code for the relevant bank, e.g. BNI
merchant_code 5-digit merchant prefix to the full virtual account number
name Name for the fixed virtual account
account_number Complete virtual account number (including prefix). This is what a user will need to enter into an ATM or their Internet/mobile banking.
suggested_amount Suggested amount of updated fixed virtual account
id Unique ID for the fixed virtual account.
is_closed value that determines whether a virtual account is closed or not
expected_amount OPTIONAL the amount that is expected when is_closed is true
is_single_use value that determines whether a virtual account will be inactive after it is paid
status Status of fixed virtual account that defines if it’s pending or inactive. Status is inactive either because it is a paid single use fixed virtual account or it is already expired.

Update Fixed Virtual Accounts Errors

Error Code Description
API_VALIDATION_ERROR
400
Inputs are failing validation. The errors field contains details about which fields are violating validation.
INVALID_JSON_FORMAT
400
The request body is not a valid JSON format.
VIRTUAL_ACCOUNT_NUMBER_OUTSIDE_RANGE
400
The virtual account number you want is outside your range.
BANK_NOT_SUPPORTED_ERROR
400
The bank code is not currently supported.
SUGGESTED_AMOUNT_NOT_SUPPORTED_ERROR
400
The suggested amount for the fixed virtual account is not currently supported.
EXPECTED_AMOUNT_REQUIRED_ERROR
400
The expected amount is required when is_closed is set to true.
CLOSED_VA_NOT_SUPPORTED_ERROR
400
The closed option for this virtual account is not currently supported.
INACTIVE_VIRTUAL_ACCOUNT_ERROR
400
Account number that you want to update is inactive.
MINIMUM_EXPECTED_AMOUNT_ERROR
400
The expected amount can only be more than zero
MAXIMUM_EXPECTED_AMOUNT_ERROR
400
The expected amount can only be less than Rp.1000000000

Fixed virtual account callback

Endpoint: Fixed Virtual Account Callback

POST https://yourcompany.com/virtual_account_paid_callback_url
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Entity payload = Entity.json("{
    id: '57fb4e076fa3fa296b7f5a97',
    payment_id: 'demo-1476087608948_1476087303080',
    callback_virtual_account_id: '57fb4df9af86ce19778ad359',
    owner_id: '57b4e5181473eeb61c11f9b9',
    external_id: 'demo-1476087608948',
    account_number: '1547',
    bank_code: 'BNI',
    amount: 99000,
    transaction_timestamp: '2016-10-10T08:15:03.080Z',
    merchant_code: '8808',
    updated: '2016-10-10T08:15:03.404Z',
    created: '2016-10-10T08:15:03.404Z'
}");
Response response = client.target("https://api.instamoney.co/virtual_account_paid_callback_url")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("X-CALLBACK-TOKEN", 
  "c2tfdGVzdF9PWUNFZkw1eGdMTCtsOFp2SzdRYVNHR1ZNTjczb05FcGszeXorUnhuLzJiUy9MQ2dDUVorZ3c9PTo=")
  .post(payload);

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));

When someone pays into your fixed virtual account, our callback APIs will hit your URL that you already set in dashboard. Our callback API will also hit your URL upon fixed virtual account creations and updates. Please see Create Fixed Virtual Accounts for more details. For further information about callbacks please read these docs.

This example is only used to show the body parameters that send from Instamoney APIs to your callback URL and cannot be tested in here. If you want to test this callback request, use the test feature in dashboard and go to settings -> configuration -> fixed virtual account.

Fixed Virtual Account Payment Callback Request

Example Fixed Virtual Account Payment Callback Request

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "X-CALLBACK-TOKEN: 
     c2tfdGVzdF9PWUNFZkw1eGdMTCtsOFp2SzdRYVNHR1ZNTjczb05FcGszeXorUnhuLzJiUy9MQ2dDUVorZ3c9PTo=" \
     --data-binary "{
    id: \"57fb4e076fa3fa296b7f5a97\",
    payment_id: \"demo-1476087608948_1476087303080\",
    callback_virtual_account_id: \"57fb4df9af86ce19778ad359\",
    owner_id: \"57b4e5181473eeb61c11f9b9\",
    external_id: \"demo-1476087608948\",
    account_number: \"1547\",
    bank_code: \"BNI\",
    amount: 99000,
    transaction_timestamp: \"2016-10-10T08:15:03.080Z\",
    merchant_code: \"8808\",
    updated: \"2016-10-10T08:15:03.404Z\",
    created: \"2016-10-10T08:15:03.404Z\"
}" \
'https://api.instamoney.co/virtual_account_paid_callback_url'
Parameter Description
payment_id Our internal system’s payment ID
callback_virtual_account_id The id field value from the response when the fixed virtual account was created. See Create Fixed Virtual Accounts
owner_id Your user ID
external_id An ID of your choice which you provided upon virtual account creation
account_number This is the virtual account number (excluding the prefix). This works just like a bank account and is what a user will need to enter in their internet banking/ATM to send funds.
bank_code Bank code for the relevant bank, e.g. BNI
amount Nominal amount to transfer
merchant_code The merchant code will be the prefix for the virtual account number, e.g 01234 your_number
id ID of fixed virtual account payment

Fixed Virtual Account Creation / Update Callback Request

Example Fixed Virtual Account Creation / Update Callback Request

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "X-CALLBACK-TOKEN: 
     c2tfdGVzdF9PWUNFZkw1eGdMTCtsOFp2SzdRYVNHR1ZNTjczb05FcGszeXorUnhuLzJiUy9MQ2dDUVorZ3c9PTo=" \
     --data-binary "{
    id: \"57fb4e076fa3fa296b7f5a97\",
    owner_id: \"5824128aa6f9f9b648be9d76\",
    external_id: \"fixed-va-1487156410\",
    merchant_code: \"88608\",
    account_number: \"886081000123456\",
    bank_code: \"MANDIRI\",
    name: \"John Doe\",
    is_closed: false,    
    is_single_use: false,
    status: \"ACTIVE\",
    expiration_date: \"2048-02-15T11:01:52.722Z\",
    updated: \"2016-10-10T08:15:03.404Z\",
    created: \"2016-10-10T08:15:03.404Z\"
}" \
'https://api.instamoney.co/virtual_account_created_callback_url'
Parameter Description
owner_id Your user ID
external_id An ID of your choice which you provided upon request
bank_code Bank code for the relevant bank, e.g. MANDIRI
merchant_code 5-digit merchant prefix to the full virtual account number
name Name for the fixed virtual account
account_number Complete virtual account number (including prefix). This is what a user will need to enter into an ATM or their Internet/mobile banking.
suggested_amount OPTIONAL suggested amount for created fixed virtual account
is_closed value that determines whether a virtual account is closed or not
expected_amount OPTIONAL the amount that is expected when is_closed is true
id Unique ID for the fixed virtual account.
is_single_use value that determines whether a virtual account will be inactive after it is paid
status Status of fixed virtual account.

Fixed Virtual Account Callback Errors

Note that in the case where we don't get a successful response from your servers on the first try, we will retry 2 times more with a 30 second delay between each retry. After 3 failures, we get internal alerts that a callback has failed. Our team will then contact you to resolve the issue.

Get fixed virtual account payment

Endpoint: Get Fixed Virtual Account payment

GET https://api.instamoney.co/callback_virtual_account_payments/payment_id={payment_id}

Example Get Fixed Virtual Account Request

curl https://api.instamoney.co/callback_virtual_account_payments/payment_id={payment_id} -X GET \
    -u sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==:

When you receive our callback in your URL, you can verify that the callback you receive is coming from us.

Get Fixed Virtual Account Payment Request

Parameter Description
payment_id
required
string ID of the payment to retrieve

Get Fixed Virtual Account Payment Response

Example Get Fixed Virtual Account Response

{
    "id": "598d91b1191029596846047f",
    "payment_id": "1502450097080",
    "callback_virtual_account_id": "598d5f71bf64853820c49a18",
    "external_id": "demo-1502437214715",
    "merchant_code": "77517",
    "account_number": "1000016980",
    "bank_code": "BNI",
    "amount": 5000,
    "transaction_timestamp": "2017-08-11T11:14:57.080Z"
}
Parameter Description
id ID of the fixed virtual account payment
payment_id Our internal system’s payment ID
callback_virtual_account_id ID of the fixed virtual account payment that was paid
external_id External ID on the fixed virtual account payment
merchant_code 5-digit merchant prefix to the full virtual account number
account_number Account number of the virtual account
bank_code Bank code of the virtual account number
amount Amount that was paid to this virtual account payment
transaction_timestamp Date time that the fixed virtual account was paid

Get Fixed Virtual Account Payment Errors

Error Code Description
CALLBACK_VIRTUAL_ACCOUNT_PAYMENT_NOT_FOUND_ERROR
404
Could not find callback virtual account payment by payment id.

Get fixed virtual account

Endpoint: Get Fixed Virtual Account

GET https://api.instamoney.co/callback_virtual_accounts/{callback_virtual_account_id}

Example Get Fixed Virtual Account Request

curl https://api.instamoney.co/callback_virtual_accounts/{callback_virtual_account_id} -X GET \
  -u sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==:

Sometime, you need to know the detail for your fixed virtual account. This endpoint can be used to get the latest details from your fixed virtual account

Get Fixed Virtual Account Request

Parameter Description
callback_virtual_account_id
required
string ID of the fixed virtual account to retrieve

Get Fixed Virtual Account Response

Example Get Fixed Virtual Account Response

{
    "owner_id": "58cd618ba0464eb64acdb246",
    "external_id": "fixed-va-1507867286",
    "bank_code": "BRI",
    "merchant_code": "26215",
    "name": "Steve Wozniak",
    "account_number": "262151000393993",
    "is_single_use": false,
    "status": "ACTIVE",
    "expiration_date": "2048-10-12T17:00:00.000Z",
    "is_closed": false,
    "id": "59e03a976fab8b1850fdf347"
}
Parameter Description
owner_id ID of the business that own the fixed virtual account
external_id An ID of your choice which you provided upon virtual account creation
bank_code Bank code of the virtual account number
merchant_code 4 or 5-digit merchant prefix to the full virtual account number
name Name of the virtual account
account_number Account number of the virtual account
expiration_date Expiration date of the virtual account
is_closed Flag that define the fixed virtual account is close or open
id ID of the fixed virtual account
is_single_use Flag that define the fixed virtual account is single use or multiple use
status Status of fixed virtual account that defines if it’s active or inactive. Status is inactive either because it is a paid single use fixed virtual account or it is already expired.

Get Fixed Virtual Account Payment Errors

Error Code Description
CALLBACK_VIRTUAL_ACCOUNT_NOT_FOUND_ERROR
404
Could not find callback virtual account.

Retail Outlets

Create Fixed Payment Code

Endpoint: Create Fixed Payment Code (FPC)

POST https://api.instamoney.co/fixed_payment_code

One way for your customer to pay through Retail Outlets is by providing them Fixed Payment Code. Fixed payment code is a dedicated payment code under a name you choose, e.g. 'YourCompany - Becca Salim'. You will receive a callback each time this fixed payment code is paid.

Create Fixed Payment Code Request

Example Create Fixed Payment Code Request

curl https://api.instamoney.co/fixed_payment_code -X POST \
   -u sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==: \
   -d external_id=demo_fixed_payment_code_123 \
   -d retail_outlet_name=ALFAMART \
   -d name='Rika Sutanto' \
   -d expected_amount=10000
Parameter Description
external_id
required
string An ID of your choice. Often it is unique identifier like a phone number, email or transaction ID. Maximum length allowed is 1000 characters.
retail_outlet_name
required
string Name of the fixed payment code you want to create
name
required
string Name of user - this might be used by the Retail Outlets cashier to validate the end user
expected_amount
required
number The amount that is expected to be paid by end customer
payment_code
optional
string The fixed payment code that you want to assign. If you do not send one, one will be picked at random
expiration_date
optional
ISO Date The time when the fixed payment code will be expired
is_single_use
optional
boolean When set to true, the fixed payment code will be inactive after it is paid

Create Fixed Payment Code Response

Example Create Fixed Payment Code Response

{
    "owner_id": "5b614aa8e79f9214007244d4",
    "external_id": "123",
    "retail_outlet_name": "ALFAMART",
    "prefix": "TEST",
    "name": "Rika Sutanto",
    "payment_code": "TEST123456",
    "type": "USER",
    "expected_amount": 10000,
    "is_single_use": true,
    "expiration_date": "2049-07-31T17:00:00.000Z",
    "id": "5b61881e6cc2770f00117f73"
}
Parameter Description
owner_id Your user ID
external_id An ID of your choice which you provided upon request
retail_outlet_name Name for the relevant Retail Outlets, e.g. ALFAMART
prefix 3-6 characters that differentiate your fixed payment code from the others
name Name for the fixed payment code
payment_code Complete fixed payment code (including prefix). This is what a user will need to tell Retail Outlets cashier
expected_amount The amount that is expected to be paid by end customer
is_single_use Value that determines whether a fixed payment code will be inactive after it is paid or not
expiration_date The time when the fixed payment code will be expired
id Unique ID for the fixed payment code

Create Fixed Payment Code Errors

Error Code Description
API_VALIDATION_ERROR
400
Inputs are failing validation. The errors field contains details about which fields are violating validation.
INVALID_JSON_FORMAT
400
The request body is not a valid JSON format.
PAYMENT_CODE_OUTSIDE_RANGE
400
The fixed payment code you want is outside your range.
RETAIL_OUTLET_NOT_SUPPORTED_ERROR
400
The Retail Outlets is not currently supported.
DUPLICATE_PAYMENT_CODE_ERROR
400
The payment code that you want to create is already exist
EXPIRATION_DATE_INVALID_ERROR
400
Invalid custom expiration date because it's earlier than current time.
MINIMUM_EXPECTED_AMOUNT_ERROR
400
The expected amount can only be more than or equal Rp 10,0000
MAXIMUM_EXPECTED_AMOUNT_ERROR
400
The expected amount can only be less than or equal Rp 5,000,000

Update Fixed Payment Code

Endpoint: Update Fixed Payment Code (FPC)

PATCH https://api.instamoney.co/fixed_payment_code/{fixed_payment_code_id}

Fixed Payment Code is so adaptable, and it's all based on your needs. Therefore, we provide you this endpoint to easily update your fixed payment code as you like.

Update Fixed Payment Code Request

Example Create Fixed Payment Code Request

curl https://api.instamoney.co/fixed_payment_code/{fixed_payment_code_id} -X PATCH \
   -u sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==: \
   -d expected_amount=20000
   -d name='Joe Contini'
Parameter Description
name
optional
string Name for the fixed payment code
expected_amount
optional
number The amount that is expected to be paid by end customer
expiration_date
optional
ISO Date The time when the fixed payment code will be expired. You can set it to be days in the past to expire fixed payment code immediately

Update Fixed Payment Code Response

Example Update Fixed Payment Code Response

{
    "owner_id": "5b614aa8e79f9214007244d4",
    "external_id": "123",
    "retail_outlet_name": "ALFAMART",
    "prefix": "TEST",
    "name": "Joe Contini",
    "payment_code": "TEST123456",
    "type": "USER",
    "expected_amount": 20000,
    "is_single_use": true,
    "expiration_date": "2049-07-31T17:00:00.000Z",
    "id": "5b61881e6cc2770f00117f73"
}
Parameter Description
owner_id Your user ID
external_id An ID of your choice which you provided upon request
retail_outlet_name Name for the relevant Retail Outlets, e.g. ALFAMART
prefix 3-6 characters that differentiate your fixed payment code from the others
name Name for the fixed payment code
payment_code Complete fixed payment code (including prefix). This is what a user will need to tell Retail Outlets cashier
expected_amount The amount that is expected to be paid by end customer
is_single_use Value that determines whether a fixed payment code will be inactive after it is paid or not
expiration_date The time when the fixed payment code will be expired
id Unique ID for the fixed payment code

Update Fixed Payment Code Errors

Error Code Description
API_VALIDATION_ERROR
400
Inputs are failing validation. The errors field contains details about which fields are violating validation.
INVALID_JSON_FORMAT
400
The request body is not a valid JSON format.
PAYMENT_CODE_OUTSIDE_RANGE
400
The fixed payment code you want is outside your range.
INACTIVE_FIXED_PAYMENT_CODE_ERROR
400
Account number that you want to update is inactive.
MINIMUM_EXPECTED_AMOUNT_ERROR
400
The expected amount can only be more than or equal Rp 10,000
MAXIMUM_EXPECTED_AMOUNT_ERROR
400
The expected amount can only be less than or equal Rp 5,000,000

Get Fixed Payment Code

Endpoint: Get Fixed Payment Code

GET https://api.instamoney.co/fixed_payment_code/{fixed_payment_code_id}

Example Get Fixed Payment Code Request

curl https://api.instamoney.co/fixed_payment_code/{fixed_payment_code_id} -X GET \
  -u sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==:

Sometime, you need to know the detail for your fixed payment code. This endpoint can be used to get the latest details from your fixed payment code

Get Fixed Payment Code Request

Parameter Description
fixed_payment_code_id
required
string ID of the fixed payment code to retrieve

Get Fixed Payment Code Response

Example Get Fixed Payment Code Response

{
    "owner_id": "5b614aa8e79f9214007244d4",
    "external_id": "123",
    "retail_outlet_name": "ALFAMART",
    "prefix": "TEST",
    "name": "Joe Contini",
    "payment_code": "TEST123456",
    "type": "USER",
    "expected_amount": 20000,
    "is_single_use": true,
    "expiration_date": "2049-07-31T17:00:00.000Z",
    "id": "5b61881e6cc2770f00117f73"
}
Parameter Description
owner_id Your user ID
external_id An ID of your choice which you provided upon request
retail_outlet_name Name for the relevant Retail Outlets, e.g. ALFAMART
prefix 3-6 characters that differentiate your fixed payment code from the others
name Name for the fixed payment code
payment_code Complete fixed payment code (including prefix). This is what a user will need to tell Retail Outlets cashier
expected_amount The amount that is expected to be paid by end customer
is_single_use Value that determines whether a fixed payment code will be inactive after it is paid or not
expiration_date The time when the fixed payment code will be expired
id Unique ID for the fixed payment code

Get Fixed Payment Code Errors

Error Code Description
FIXED_PAYMENT_CODE_NOT_FOUND_ERROR
404
Could not find fixed payment code.

Fixed Payment Code Callback

Endpoint: Fixed Payment Code Callback

POST https://yourcompany.com/fixed_payment_code_paid_callback_url

When someone pays into your fixed payment code, our callback APIs will hit your URL that you already set in dashboard.

This example is only used to show the body parameters that send from Instamoney APIs to your callback URL and cannot be tested in here. If you want to test this callback request, use the test feature in dashboard and go to settings -> configuration -> retail outlets.

Fixed Payment Code Payment Callback Request

Example Fixed Payment Code Payment Callback Request

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "X-CALLBACK-TOKEN: c2tfdGVzdF9PWUNFZkw1eGdMTCtsOFp2SzdRYVNHR1ZNTjczb05FcGszeXorUnhuLzJiUy9MQ2dDUVorZ3c9PTo=" \
     --data-binary "{
    fixed_payment_code_payment_id: \"5b61ffc470f7f3470165e7b3\",
    owner_id: \"5b614aa8e79f9214007244d4\",
    fixed_payment_code_id: \"5b61f49e6cc2770f00117f82\",
    payment_id:\"1533149124896\",
    external_id: \"123\",
    payment_code: \"TEST123456\",
    prefix: \"TEST\",
    retail_outlet_name: 'ALFAMART',
    amount: 20000,
    name: 'Joe Contini',
    transaction_timestamp: \"2018-07-31T08:15:03.080Z\",
    updated: \"2016-10-10T08:15:03.404Z\",
    created: \"2016-10-10T08:15:03.404Z\"
}" \
'https://api.instamoney.co/fixed_payment_code_paid_callback_url'
Parameter Description
fixed_payment_code_payment_id Unique ID for the fixed payment code payment
owner_id Your user ID
fixed_payment_code_id Unique ID for the fixed payment code
payment_id Our internal system’s payment ID that can be used as payment reference
external_id An ID of your choice which you provided upon fixed payment code creation
payment_code Complete fixed payment code (including prefix). This is what a user will need to tell Retail Outlets cashier
prefix 3-6 characters that differentiate your fixed payment code from the others
retail_outlet_name Name for the relevant Retail Outlets, e.g. ALFAMART
amount Nominal amount that is paid
name Name for the fixed payment code
transaction_timestamp Date time that the fixed payment code was paid

Fixed Payment Code Callback Errors

Note that in the case where we don't get a successful response from your servers on the first try, we will retry 2 times more with a 30 second delay between each retry. After 3 failures, we get internal alerts that a callback has failed. Our team will then contact you to resolve the issue.

Disburse Funds

Disbursements allow you to instruct Instamoney to instantly send money to any bank account across Indonesia on your behalf.

Create disbursement

Endpoint: Create Disbursement

POST https://api.instamoney.co/disbursements

Create Disbursement Request

Example Create Disbursement Request

<?php
  require 'vendor/autoload.php';

  $options['secret_api_key'] = 'sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==';

  $instamoneyPHPClient = new InstamoneyClient\InstamoneyPHPClient($options);

  $external_id = 'demo_1475459775872';
  $amount = 17000;
  $bank_code = 'BCA';
  $account_holder_name = 'Bob Jones';
  $account_number = '1231241231';
  $disbursement_options['description'] = 'Reimbursement for shoes';

  $response = $instamoneyPHPClient->createDisbursement($external_id, $amount, $bank_code, $account_holder_name, $account_number, $disbursement_options);
  print_r($response);
?>
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Entity payload = Entity.json("{  'external_id': 'disbursement_12345',  'amount': 500000,  'bank_code': 'BCA',  'account_holder_name': 'Rizky',  'account_number': '1231241231',  'description': 'Custom description'}");
Response response = client.target("https://api.instamoney.co/disbursements")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Authorization", "Basic c2tfdGVzdF9PWUNFZkw1eGdMTCtsOFp2SzdRYVNHR1ZNTjczb05FcGszeXorUnhuLzJiUy9MQ2dDUVorZ3c9PTo=")
  .post(payload);

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));
Header Description
X-IDEMPOTENCY-KEY
optional
string A unique key to prevent processing duplicate requests. Can be your external_id or any GUID. Must be unique across development & production environments.

Characters Special and alphanumeric
Maximum length No maximum characters
Minimum length 1 character
Parameter Description
external_id
required
string ID of the disbursement in your system, used to reconcile disbursements after they have been completed.

Characters Special and alphanumeric
Maximum length 1000 maximum characters
Minimum length 1 character
bank_code
required
string Code of the destination bank

The bank code must match the bank codes here precisely
account_holder_name
required
string Name of account holder as per the bank's or e-wallet's records. Used for verification and error/customer support scenarios.

Characters Special and alphanumeric
Maximum length No maximum characters
Minimum length 1 character
account_number
required
string Destination bank account number. If disbursing to an e-wallet, phone number registered with the e-wallet account.

Characters Numeric and hyphens
BCA required length 10 characters
Other banks maximum length No maximum characters
Other banks minimum length 1 character
E-wallets Phone number registered with the e-wallet (Example: 0812XXXXXX)

*** We support disbursements to virtual accounts of major banks (BRI, BNI, Mandiri, CIMB Niaga, Permata, BTN, and NOBU Bank).
*** We support disbursements to major e-wallets (GoPay, OVO, and Mandiri e-cash).

description
required
string Description to send with the disbursement

Characters Special and alphanumeric
Maximum length No maximum characters
Minimum length 1 character
amount
required
number Amount to disburse

Characters Numerical integers, no decimals
Maximum limit (BCA, Mandiri, BNI, BNI Syariah) No Limit***
Minimum limit (BCA, Mandiri, BNI, BNI Syariah) No Limit
Maximum Limit (Other banks) Rp. 25.000.000
Minimum Limit (Other banks) Rp. 10.000

*** While there is theoretically no maximum transfer limit for transfers to these banks, please note that we may have to report all transaction amounts above Rp 100.000.000 to the financial authorities in Indonesia along with supporting documentation regarding the underlying transactions.

email_to
optional
string[] Email addresses that get notified of disbursement details after the disbursement is completed
Maximum 3 email addresses accepted.
email_cc
optional
string[] Email addresses that get notified as carbon copy receiver of disbursement details after the disbursement is completed.
Maximum 3 email addresses accepted.
Only allowed if email_to provided.
email_bcc
optional
string[] Email addresses that get notified as blind carbon copy receiver of disbursement details after the disbursement is completed.
Maximum 3 email addresses accepted.
Only allowed if email_to provided.

Create Disbursement Response

Example Create Disbursement Response

{
  "user_id": "5785e6334d7b410667d355c4",
  "external_id": "12345",
  "amount": 1000,
  "bank_code": "BCA",
  "account_holder_name": "RAIDY WIJAYA",
  "disbursement_description": "Refunds for shoes",
  "status": "PENDING",
  "id": "57f1ce05bb1a631a65eee662",
  "email_to": ["test+to1@instamoney.co","test+to2@instamoney.co"],
  "email_cc": ["test+cc@instamoney.co"],
  "email_bcc": ["test+bcc@instamoney.co"]
}
Parameter Description
user_id
required
string Your Instamoney Business ID
external_id
required
string Custom ID of your choice to identify the transaction. Our customers often use a phone number, email address, or transaction/order ID
amount
required
number Amount to disburse
bank_code
required
string Bank code of destination bank or e-wallet. See bank codes
account_holder_name
required
string Name of account holder as per the bank's or e-wallet’s records. Used for verification and error/customer support scenarios
disbursement_description
required
This is the description you give us :)
status
required
string
PENDING Transfer is initiated but not yet completed by bank.
id
required
string Unique disbursement ID
email_to
optional
string[] Email addresses that get notified of disbursement details after the disbursement is completed
This response parameter is only returned if this field is filled.
email_cc
optional
string[] Email addresses that get notified as carbon copy receiver of disbursement details after the disbursement is completed.
This response parameter is only returned if this field is filled.
email_bcc
optional
string[] Email addresses that get notified as blind carbon copy receiver of disbursement details after the disbursement is completed.
This response parameter is only returned if this field is filled.

Create Disbursement Errors

Error Code Description
API_VALIDATION_ERROR
400
Inputs are failing validation. The errors field contains details about which fields are violating validation.
INVALID_JSON_FORMAT
400
The request body is not a valid JSON format.
DISBURSEMENT_DESCRIPTION_NOT_FOUND_ERROR
400
Disbursement description is not set in Dashboard > Configuration > Disbursement. Add a default description before retrying.
DIRECT_DISBURSEMENT_BALANCE_INSUFFICIENT_ERROR
400
Not enough balance to disburse. Add more balance before retrying.
DUPLICATE_TRANSACTION_ERROR
400
Idempotency key has been used before. Use a unique idempotency key and try again.
BANK_CODE_NOT_SUPPORTED_ERROR
400
Destination bank code is not supported.
RECIPIENT_ACCOUNT_NUMBER_ERROR
400
For transfers to BCA, account_number input needs to be 10 digits. Check the account number length before retrying.
RECIPIENT_AMOUNT_ERROR
400
The transfer amount requested is lower than the prescribed minimum for the chosen destination bank. Amend the transfer amount before retrying.
MAXIMUM_TRANSFER_LIMIT_ERROR
400
The transfer amount requested is higher than the prescribed maximum for the chosen destination bank. Amend the transfer amount before retrying.
SERVER_ERROR
500
Error connecting to our server. Please use Get disbursement by external_id API to check whether the disbursement has already been created. If you receive DIRECT_DISBURSEMENT_NOT_FOUND_ERROR, the disbursement has not been created; please retry the disbursement request in 1-2 hours.

Get disbursement by id

Endpoint: Get Disbursement by id

GET https://api.instamoney.co/disbursements/{disbursement_id}

This endpoint queries the current status of a disbursement. This is often used for checking the status of a transaction.

Get Disbursement Request

Example Get Disbursement Request

curl https://api.instamoney.co/disbursements/57c9010f5ef9e7077bcb96b6 -X GET \
  -u sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==:
<?php
  require 'vendor/autoload.php';

  $options['secret_api_key'] = 'sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==';

  $instamoneyPHPClient = new InstamoneyClient\InstamoneyPHPClient($options);

  $disbursement_id = '587cc7ea77535fb94bb4e8eb';

  $response = $instamoneyPHPClient->getDisbursement($disbursement_id);
  print_r($response);
?>
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Response response = client.target("https://api.instamoney.co/disbursements/{disbursement_id}")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Authorization", "Basic c2tfdGVzdF9PWUNFZkw1eGdMTCtsOFp2SzdRYVNHR1ZNTjczb05FcGszeXorUnhuLzJiUy9MQ2dDUVorZ3c9PTo=")
  .get();

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));
Parameter Description
disbursement_id
required
string ID of the disbursement to retrieve
The disbursement_id must match the unique disbursement ID provided in our success response at disbursement creation precisely

Get Disbursement Response

Example Get Disbursement Response

{
  "user_id": "5785e6334d7b410667d355c4",
  "external_id": "disbursement_12345",
  "amount": 500000,
  "bank_code": "BCA",
  "account_holder_name": "Rizky",
  "disbursement_description": "Custom description",
  "status": "PENDING",
  "id": "57c9010f5ef9e7077bcb96b6",
  "email_to": ["test+to1@instamoney.co","test+to2@instamoney.co"],
  "email_cc": ["test+cc@instamoney.co"],
  "email_bcc": ["test+bcc@instamoney.co"]
}
Parameter Description
user_id Your Instamoney Business ID
external_id Custom ID set at disbursement creation. Our customers often use a phone number, email address, or transaction/order ID
amount Amount to disburse
bank_code Destination bank code. See bank codes
account_holder_name Bank account name as per the bank's records. Used for verification and error/customer support scenarios
disbursement_description This is the description you give us :)
status PENDING Transfer is initiated.
COMPLETED Bank has confirmed transmission of funds.
FAILED Bank rejected disbursement. We will not retry.
id Unique disbursement ID
email_to Email addresses that get notified of disbursement details after the disbursement is completed
This response parameter is only returned if this field is filled.
email_cc Email addresses that get notified as carbon copy receiver of disbursement details after the disbursement is completed.
This response parameter is only returned if this field is filled.
email_bcc Email addresses that get notified as blind carbon copy receiver of disbursement details after the disbursement is completed.
This response parameter is only returned if this field is filled.

Get Disbursement Errors

Error Code Description
INVALID_JSON_FORMAT
400
The request body is not a valid JSON format.
INVALID_PERMISSION_ERROR
403
Could not access that disbursement.
DIRECT_DISBURSEMENT_NOT_FOUND_ERROR
404
Could not find direct disbursement.

Get disbursement by external_id

Endpoint: Get Disbursement by external_id

GET https://api.instamoney.co/disbursements?external_id={external_id}

This endpoint queries the current status of all disbursements with requested external_id. This is often used to check the status of a transaction with external_id.

Get Disbursement Request

Example Get Disbursement Request

curl https://api.instamoney.co/disbursements?external_id=72655 -X GET \
  -u sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==:
<?php
  require 'vendor/autoload.php';

  $options['secret_api_key'] = 'sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==';

  $instamoneyPHPClient = new InstamoneyClient\InstamoneyPHPClient($options);

  $external_id = 'disbursement_12345';

  $response = $instamoneyPHPClient->getDisbursementByExternalId($external_id);
  print_r($response);
?>
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Response response = client.target("https://api.instamoney.co/disbursements?external_id={external_id}")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Authorization", "Basic c2tfdGVzdF9PWUNFZkw1eGdMTCtsOFp2SzdRYVNHR1ZNTjczb05FcGszeXorUnhuLzJiUy9MQ2dDUVorZ3c9PTo=")
  .get();

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));
Query Description
external_id
required
string Custom ID of the disbursement set by the customer at disbursement creation
The external_id must match the external_id used at disbursement creation precisely

Get Disbursement Response

Example Get Disbursement Response

[{
  "user_id": "5785e6334d7b410667d355c4",
  "external_id": "disbursement_12345",
  "amount": 500000,
  "bank_code": "BCA",
  "account_holder_name": "Rizky",
  "disbursement_description": "Custom description",
  "status": "PENDING",
  "id": "57c9010f5ef9e7077bcb96b6"
},{
  "user_id": "5785e6334d7b410667d355c4",
  "external_id": "disbursement_12345",
  "amount": 450000,
  "bank_code": "BNI",
  "account_holder_name": "Jajang",
  "disbursement_description": "Custom description",
  "status": "COMPLETED",
  "id": "5a963089fd5fe5b6508f0b7b",
  "email_to": ["test+to1@instamoney.co","test+to2@instamoney.co"],
  "email_cc": ["test+cc@instamoney.co"],
  "email_bcc": ["test+bcc@instamoney.co"]
}]
Parameter Description
user_id Your Instamoney Business ID
external_id Custom ID set at disbursement creation. Our customers often use a phone number, email address, or transaction/order ID
amount Amount to disburse
bank_code Destination bank code. See bank codes
account_holder_name Bank account name as per the bank's records. Used for verification and error/customer support scenarios
disbursement_description This is the description you give us :)
status PENDING Transfer is initiated.
COMPLETED Bank has confirmed transmission of funds.
FAILED Bank rejected disbursement. We will not retry.
id Unique disbursement ID
id Unique disbursement ID
email_to Email addresses that get notified of disbursement details after the disbursement is completed
This response parameter is only returned if this field is filled.
email_cc Email addresses that get notified as carbon copy receiver of disbursement details after the disbursement is completed.
This response parameter is only returned if this field is filled.
email_bcc Email addresses that get notified as blind carbon copy receiver of disbursement details after the disbursement is completed.
This response parameter is only returned if this field is filled.

Get Disbursement Errors

Error Code Description
DIRECT_DISBURSEMENT_NOT_FOUND_ERROR
404
Could not find direct disbursement.

Disbursement callback

Endpoint: Disbursement Callback

POST https://yourcompany.com/disbursement_callback_url
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Entity payload = Entity.json("{  'id': '57e214ba82b034c325e84d6e',  'user_id': '57c5aa7a36e3b6a709b6e148',  'external_id': 'disbursement_123124123',  'amount': 150000,  'bank_code': 'BCA',  'instamoney_fee_amount': 0,  'account_holder_name': 'INSTAMONEY',  'transaction_id': '57ec8b7e906aa2606ecf8ffc',  'transaction_sequence': '1799',  'disbursement_id': '57ec8b8130d2d0243f438e11',  'disbursement_description': 'Instamoney disbursement',  'failure_code': 'INVALID_DESTINATION',  'is_instant': false,  'status': 'FAILED',  'updated': '2016-10-10T08:15:03.404Z',  'created': '2016-10-10T08:15:03.404Z'}");
Response response = client.target("https://yourcompany.com/disbursement_callback_url")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .post(payload);

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));

When a disbursement transaction is successful, our callback APIs will hit your URL that you already set in dashboard. For further information about callbacks please read these docs.

This example is only used to show the body parameters that send from Instamoney APIs to your callback URL. If you want to test this callback request, use the test feature in dashboard and go to Settings -> Configuration -> Disbursement.

Disbursement Callback Request

Example Disbursement Callback Request

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "X-CALLBACK-TOKEN: c2tfdGVzdF9PWUNFZkw1eGdMTCtsOFp2SzdRYVNHR1ZNTjczb05FcGszeXorUnhuLzJiUy9MQ2dDUVorZ3c9PTo=" \
     --data-binary "{
    \"id\": \"57e214ba82b034c325e84d6e\",
    \"user_id\": \"57c5aa7a36e3b6a709b6e148\",
    \"external_id\": \"disbursement_123124123\",
    \"amount\": 150000,
    \"bank_code\": \"BCA\",
    \"account_holder_name\": \"INSTAMONEY\",
    \"disbursement_description\": \"Instamoney disbursement\",
    \"failure_code\": \"INVALID_DESTINATION\",
    \"is_instant\": false,
    \"status\": \"FAILED\",
    \"updated\": \"2016-10-10T08:15:03.404Z\",
    \"created\": \"2016-10-10T08:15:03.404Z\",
    \"email_to\": [\"test+to1@instamoney.co\", \"test+to2@instamoney.co\"],
    \"email_cc\": [\"test+cc@instamoney.co\"],
    \"email_bcc\": [\"test+bcc@instamoney.co\"]
}" \
'https://yourcompany.com/disbursement_callback_url'
Parameter Description
is_instant Indicates whether the disbursement is being disbursed instantly
user_id Your Instamoney Business ID
external_id Custom ID set at disbursement creation. Our customers often use a phone number, email address, or transaction/order ID
amount Amount to disburse
bank_code Destination bank code. See bank codes
account_holder_name Bank account name as per the bank's records. Used for verification and error/customer support scenarios
disbursement_description This is the description you give us :)
status COMPLETED Bank has confirmed transmission of funds.
FAILED Disbursement failed because of failure code
failure_code (optional) INSUFFICIENT_BALANCE The balance in your account is insufficient to make the disbursement in the desired amount
UNKNOWN_BANK_NETWORK_ERROR The bank networks have returned an unknown error to us. We are unable to predict whether the disbursement will succeed should you retry the same disbursement request.
TEMPORARY_BANK_NETWORK_ERROR The bank networks are experiencing a temporary error. Please retry the disbursement in 1-3 hours
INVALID_DESTINATION The banks have reported that the destination account is unregistered or blocked. If unsure about this, please retry again or contact the destination bank directly regarding the status of the destination account
SWITCHING_NETWORK_ERROR At least one of the switching networks is encountering an issue. Please retry the disbursement in 1-3 hours
REJECTED_BY_BANK The bank has rejected this transaction for unclear reasons. We are unable to predict whether the disbursement will succeed should you retry the same disbursement request.
TRANSFER_ERROR We’ve encountered a fatal error while processing this disbursement. Certain API fields in your request may be invalid. Please contact our customer support team for more information
TEMPORARY_TRANSFER_ERROR We’ve encountered a temporary issue while processing this disbursement. Please retry the disbursement in 1-2 hours

For detailed information regarding the different error codes above, please see Common Errors in Disbursements.
id Unique disbursement ID
email_to Email addresses that get notified of disbursement details after the disbursement is completed
This callback parameter is only returned if this field is filled.
email_cc Email addresses that get notified as carbon copy receiver of disbursement details after the disbursement is completed.
This callback parameter is only returned if this field is filled.
email_bcc Email addresses that get notified as blind carbon copy receiver of disbursement details after the disbursement is completed.
This callback parameter is only returned if this field is filled.

Disbursement Callback Errors

Note that in the case where we don't get a successful response from your servers on the first try, we will retry 2 times more with a 30 second delay between each retry. After 3 failures, we get internal alerts that a callback has failed. Our team will then contact you to resolve the issue.

Get available disbursement banks

Endpoint: Get Available Disbursement Banks

GET https://api.instamoney.co/available_disbursements_banks

Example Get Available Disbursement Banks Request

curl https://api.instamoney.co/available_disbursements_banks -X GET \
    -u sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==:
<?php
  require 'vendor/autoload.php';

  $options['secret_api_key'] = 'sk_test_OYCEfL5xgLL+l8ZvK7QaSGGVMN73oNEpk3yz+Rxn/2bS/LCgCQZ+gw==';

  $instamoneyPHPClient = new InstamoneyClient\InstamoneyPHPClient($options);

  $response = $instamoneyPHPClient->getAvailableDisbursementBanks();
  print_r($response);
?>
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;

Client client = ClientBuilder.newClient();
Response response = client.target("https://api.instamoney.co/available_disbursements_banks")
  .request(MediaType.APPLICATION_JSON_TYPE)
  .header("Authorization", "Basic c2tfdGVzdF9PWUNFZkw1eGdMTCtsOFp2SzdRYVNHR1ZNTjczb05FcGszeXorUnhuLzJiUy9MQ2dDUVorZ3c9PTo=")
  .get();

System.out.println("status: " + response.getStatus());
System.out.println("headers: " + response.getHeaders());
System.out.println("body:" + response.readEntity(String.class));

This API endpoint will provide you the current list of banks we support for disbursements. We support transfers to 140+ banks in Indonesia, including some BPDs and BPRs, and virtual accounts of major banks (BRI, BNI, Mandiri, CIMB Niaga, Permata, BTN, and NOBU Bank). We also support disbursements to major e-wallets (GoPay, OVO, and Mandiri e-cash). If you would like us to support payment to a specific destination, please contact us at support@instamoney.co.

Get Available Disbursement Banks Response

Get Available Disbursement Banks Response

[
  {
    "name": "Bank Mandiri",
    "code": "MANDIRI",
    "can_disburse": true,
    "can_name_validate": true
  },
  {
    "name": "Bank Rakyat Indonesia (BRI)",
    "code": "BRI",
    "can_disburse": true,
    "can_name_validate": true
  },
  {
    "name": "Bank Central Asia (BCA)",
    "code": "BCA",
    "can_disburse": true,
    "can_name_validate": true
  }
]
Parameter Description
name Full name of the bank or e-wallet
code Code of the bank or e-wallet you would like to disburse to

Errors

Below are some of most common errors across all our endpoints. Specific errors are located under each endpoint. If you have any questions please contact us.

Error code Meaning
400 Bad request, e.g. validation error
401 Unauthorised access, e.g. the wrong API key
403 Forbidden access, e.g. API key does not have permission for this endpoint
404 Page or data not found
500 Unhandled error - contact us when this happens. If this was a response to a request to send money, please check the status of the resource (eg. disbursement, credit card refund) before retrying to ensure that the request will not be processed twice.