NAV Navbar
Logo

Overview

Iris is Midtrans’ cash management solution that allows you to disburse payments to any bank accounts in Indonesia securely and easily. Iris connects to the banks’ hosts to enable seamless transfer using integrated API’s.

Glossary

For the purpose of standardization and to prevent any misunderstanding, below our the terms we are going to use in this documentation:

Business Flow

Iris comes in 2 business schemes: aggregator and facilitator.

Aggregator

Using aggregator scheme, a partner will have a deposit account that can be topped up from time to time using various channels. Any payout/disbursement will be done from this deposit account as the source of fund.

In a nutshell, aggregator scheme is characterized by the following:

Facilitator

Facilitator scheme lets a partner to use their own bank account as the source of funds for disbursements. In addition to initiate transfers and payouts, partner can inquire their balance and check their statements using Iris’ API.

The facilitator scheme is characterized by the following:

Features

Real Time Transfers

Easy to Integrate API

Web Dashboard and Analytics

Setting Up Iris

Once a partner has registered, it will have an access to our sandbox environment. Iris’ partner portal will also be accessible.

Using the API key, a partner can start exploring Iris’ API. Certain API request can only be accessed based on the partner’s user role. Here below is the matrix of what a user can or cannot do:

Creator Approver
Create Payout Yes No
Release Payout No Yes
View/inquire Balance Yes Yes
View/inquire Statements Yes Yes

Getting Payout Notifications

Iris allows partners to receive realtime notifications about payout status, by configuring a endpoint url on the Iris Portal.

Once configured, Iris will send a HTTP POST payload to the url, containing the payout details along with the current status. These notifications are triggered everytime the status of the payout is updated on Iris.

Configuring the Endpoint URL

Payout Notification Payload

Parameter Description
reference_no Uniq reference_no of a payout
amount Amount of the processed payout
status processed : payout request is sent to the bank and completed
completed : payout request is sent to the bank and recieved by beneficiary account
failed : payout didn’t go through
updated_at Payout status update time in ISO8601 format

Validating Payout Notification

In order to increase security aspect, there are several ways to ensure notification received from Iris.

Signature Key

Sample code to generate signature key

    signature = OpenSSL::Digest::SHA512.new(payload + merchant_key).to_s

We add signature key information in our notification. The purpose of this signature key is to validate whether the notification is originated from Midtrans or not. Should the notification is not genuine, merchants can disregard the notification. We send the signature key via Header Iris-Signature.

Challenge Response

An additional mechanism we provide to verify the content and the origin of the notification is to challenge. This can be achieved by calling the Payout Details API.

Iris API

This Iris API contains features that can be used in your disbursement system.

HTTP(S) Request

Iris API can be requested through HTTP(S) Request to Midtrans Base URL endpoint. The HTTP(S) Header has to be used to allow proper authentication.

API Base URL

Development Environment : https://iris.sandbox.midtrans.com

Production Environment : https://app.midtrans.com/iris

HTTP(S) Header

Header Value Definition
Content-Type application/json The Content-Type field indicates that JSON type is acceptable to send to the recipient
Accept application/json The Accept field is used to specify that JSON type is acceptable for the response
Authorization Basic AUTH_STRING The Authorization field credentials can be found in Iris Portal sidemenu

Content-Type and Accept Header

In Iris API, the input and output parameters of the methods will be in JSON format. To accept JSON input and output parameters, you need to add the following HTTP(S) header:

Authorization Header

Generate AUTH_STRING using Ruby

    AUTH_STRING = Base64.strict_encode64(API_KEY + ":")

The authorization header utilizes API Key following HTTP(S) BASIC AUTH convention:

Authorization: Basic AUTH_STRING

AUTH_STRING = Base64(API_KEY + :)

Iris validates HTTP request by using Basic Authentication method. You can find your API_KEY, at Iris Portal on the sidebar

Ping

    $ curl -v BASE_URL/ping
    pong

Returns pong message for monitoring purpose

Create Beneficiaries

Request (application/json)

{
  "name": "John Doe",
  "account": "33452784",
  "bank": "bca",
  "alias_name": "johnbca",
  "email": "beneficiary@example.com"
}

Response 201 (application/json)

{
  "status": "created"
}

Use this API to create a new beneficiary information for quick access on the payout page in Iris Portal.

HTTP Request

POST BASE_URL/api/v1/beneficiaries

Request Parameters

Parameter Description
name string Name of the Beneficiary
account number Account number of the Beneficiary
Length should be within 6 to 20 characters
bank string Bank name used by the Beneficiary
alias_name string Alias name used by the Beneficiary
Length should be less than or equal to 20 characters
Only alphanumeric characters are allowed
email optional string Valid Email address for Beneficiary

Update Beneficiaries

Request (application/json)

{
  "name": "John Doe",
  "account": "334527843",
  "bank": "bca",
  "alias_name": "johnbca1",
  "email": "beneficiary1@example.com"
}

Response 201 (application/json)

{
  "status": "updated"
}

Use this API to update an existing beneficiary identified by its alias_name.

HTTP Request

PATCH BASE_URL/api/v1/beneficiaries/alias_name

Request Parameters

Parameter Description
name string Name of the Beneficiary
account number Account number of the Beneficiary
Length should be within 6 to 20 characters
bank string Bank name used by the Beneficiary
alias_name string Alias name used by the Beneficiary
Length should be less than or equal to 20 characters
only alphanumeric characters are allowed
email optional string Valid Email address for Beneficiary

List Beneficiaries

Response 201 (application/json)

[
    {
        "name": "John Doe",
        "bank": "danamon",
        "account": "1234567890",
        "alias_name": "johndanamon",
        "email": "john@danamnoexample.com"
    },
    {
        "name": "Mary Jane",
        "bank": "mandiri",
        "account": "1232133213",
        "alias_name": "marymandiri1",
        "email": "mary@mandiriexample.com"
    }
]

Use this API to fetch list of all beneficiaries saved in Iris Portal.

HTTP Request

GET BASE_URL/api/v1/beneficiaries

Create Payouts

Request (application/json)

{
  "payouts": [
    {
      "beneficiary_name": "Jon Snow",
      "beneficiary_account": "1172993826",
      "beneficiary_bank": "bni",
      "beneficiary_email": "beneficiary@example.com",
      "amount": 100000,
      "notes": "Payout April 17"
    },
    {
      "beneficiary_name": "John Doe",
      "beneficiary_account": "112673910288",
      "beneficiary_bank": "mandiri",
      "amount": 50000,
      "notes": "Payout May 17"
    }
  ]
}

Response 201 (application/json)

{
  "payouts": [
    {
      "status": "queued",
      "reference_no": "1d4f8423393005"
    },
    {
      "status": "queued",
      "reference_no": "10438f2b393005"
    }
  ]
}

This API is for Creator to create a payout. It can be used for single payout and also multiple payouts.

HTTP Request

POST BASE_URL/api/v1/payouts

Request Parameters

Parameter Description
beneficiary_name string Name of the Beneficiary
beneficiary_account number Account number of the Beneficiary
beneficiary_bank string Bank name used by the Beneficiary
beneficiary_email optional string Valid Email address for Beneficiary
amount number Payout amount
notes string Add a note to the payout (max 17 characters)

Response Parameters

Parameter Description
status queued : payout is waiting to be executed
processed : payout request is sent to the bank and completed
completed : payout request is sent to the bank and recieved by beneficiary account
failed : payout didn’t go through
reference_no uniq ID to identify the payout

Approve Payouts

Request (application/json)

{
  "reference_nos": ["10438f2b393005", "1d4f8423393005", "1d2e1123425937"],
  "otp": "335163"
}

Response 202 (application/json)

{
  "status": "ok"
}

Use this API for Apporver to approve multiple payout request.

HTTP Request

POST BASE_URL/api/v1/payouts/approve

Request Parameters

Parameter Description
reference_nos array of strings, uniq IDs to identify the payouts
otp number optional (based on config) Google auth otp (QR Code will be sent to approver’s email during partner registration)

Reject Payouts

Request (application/json)

{
  "reference_nos": ["10438f2b393005", "1d4f8423393005", "1d2e1123425937"],
  "reject_reason": "Reason to reject payouts"
}

Response 202 (application/json)

{
  "status": "ok"
}

Use this API for Apporver to reject multiple payout request.

HTTP Request

POST BASE_URL/api/v1/payouts/reject

Request Parameters

Parameter Description
reference_nos array of strings, uniq IDs to identify the payouts
reject_reason string Reason to reject the payouts

Get Payout Details

Response 200 (application/json)

{
  "amount": "200000",
  "beneficiary_name": "Ryan Renolds",
  "beneficiary_account": "33287352",
  "bank": "Bank Central Asia ( BCA )",
  "reference_no": "83hgf882",
  "notes": "Payout June 17",
  "beneficiary_email": "beneficiary@example.com",
  "status": "queued",
  "created_by": "John Doe",
  "created_at": "2017-01-11T00:00:00Z",
  "updated_at": "2017-01-11T00:00:00Z"
}

Get details of a single payout

HTTP Request

GET BASE_URL/api/v1/payouts/reference_no

Response Params

Parameter Description
amount Amount of the processed payout
beneficiary_name Name of the Beneficiary
beneficiary_account Account number of the Beneficiary
bank Bank name used by the Beneficiary
reference_no Uniq reference_no of a payout
notes Note added to a payout
status queued : payout is waiting to be executed
processed : payout request is sent to the bank and completed
completed : payout request is sent to the bank and recieved by beneficiary account
failed : payout didn’t go through
beneficiary_email Email of beneficiary (only present if email is added during payout create)
created_by Payout created by the maker
created_at Payout creation date in ISO8601 format
updated_at Payout updation date in ISO8601 format

Payout History

Request (application/json)

{
  "from_date": "2016-08-11",
  "to_date": "2016-08-12"
}

Response 200 (application/json)

[
  {
    "amount": "100000",
    "beneficiary_name": "John Doe",
    "beneficiary_account": "27128918",
    "bank": "Bank Central Asia ( BCA )",
    "reference_no": "ab45cdyr",
    "notes": "Payout March 17",
    "status": "queued",
    "created_by": "Jane Doe",
    "created_at": "2017-01-12T00:00:00Z",
    "updated_at": "2017-01-12T00:00:00Z"
  },
  {
    "amount": "200000",
    "beneficiary_name": "Ryan Renolds",
    "beneficiary_account": "33287352",
    "bank": "Bank Central Asia ( BCA )",
    "reference_no": "83hgf882",
    "notes": "Payout April 17",
    "status": "queued",
    "beneficiary_email": "beneficiary@example.com",
    "created_by": "John Doe",
    "created_at": "2017-01-11T00:00:00Z",
    "updated_at": "2017-01-11T00:00:00Z"
  }
]

Returns all the payout details for specific dates

HTTP Request

GET BASE_URL/api/v1/payouts

Request Parameters

Please check Restrictions and Query Params Logic for more.

Parameter Description
from_date start date range for payouts (YYYY-MM-DD)
to_date end date range for payouts (YYYY-MM-DD)

Response Parameters

Parameter Description
amount Amount of the processed payout
beneficiary_name Name of the Beneficiary
beneficiary_account Account number of the Beneficiary
bank Bank name used by the Beneficiary
reference_no Uniq reference_no of a payout
notes Note added to a payout
status queued : payout is waiting to be executed
processed : payout request is sent to the bank and completed
completed : payout request is sent to the bank and recieved by beneficiary account
failed : payout didn’t go through
beneficiary_email Email of beneficiary (only present if email is added during payout create)
created_by Payout created by the maker
created_at Payout creation date in ISO8601 format
created_at Payout updation date in ISO8601 format

FromToDate Restrictions

  1. We will only provide one months data
  2. We will not provide data which are six months old from current date
  3. from_date and to_date has to be in ISO8601 date format (YYYY-MM-DD)
  4. from_date is set to beginning of day (00:00:00) and to_date is set to end of day (23:59:59)

Logic for query params(from_date/to_date)

  1. When no params passed, provides payouts of last month
    • to_date (Today)
    • from_date (Today - 31)
  2. When from_date is not passed, provides payouts of one months from to_date
    • to_date (to_date)
    • from_date (to_date - 31)
  3. When to_date is not passed, provides payouts from from_date to a month later
    • to_date (from_date * 31)
    • from_date (from_date)
  4. When both the params are present and it does not obey the before mentioned restriction
    • to_date (to_date)
    • from_date (to_date - 31)
  5. When from_date is less than 6 months, we will reset from_date and provide data upto 6 months
    • from_date (the date 6 months ago from current date)

Transaction History

Request (application/json)

{
  "from_date": "2016-08-11",
  "to_date": "2016-08-12"
}

Response 200 (application/json)

[
  {
    "account": "Permata virtual account number",
    "type": "Topup",
    "amount": "300000",
    "status": "credit",
    "created_at": "2016-08-09T17:00:00Z"
  },
  {
    "reference_no": "1e4d9943929504",
    "beneficiary_name": "Test Benefeciary",
    "beneficiary_account": "7202",
    "account": "PT. Bank Central Asia Tbk.",
    "type": "Payout",
    "amount": "45000",
    "status": "debit",
    "created_at": "2016-08-09T17:00:00Z"
  }
]

List all transactions history for a month. You can specified start date and also end date for range transaction history.

HTTP Request

GET BASE_URL/api/v1/statements

Request Parameters

Please check Restrictions and Query Params Logic for more.

Parameter Description
from_date start date range for payouts (YYYY-MM-DD)
to_date end date range for payouts (YYYY-MM-DD)

Response Parameters

Parameter Description
reference_no Uniq reference_no of a payout (only if payout is present)
beneficiary_name Name of the Beneficiary (only if payout is present)
beneficiary_account Account number of the Beneficiary (only if payout is present)
type Transaction Type, one of Topup, Payout, Fee, Refund
account Name of beneficiary bank/channel used
amount Amount for a transaction
status Current status of the Transaction (credit/debit)
created_at Transaction creation date in ISO8601 format

Top Up Channel Information (Aggregator)

Response 200 (application/json)

[
  {
    "id":1,
    "virtual_account_type":"mandiri_bill_key",
    "virtual_account_number":"991385480006"
  },
  {
    "id":2,
    "virtual_account_type":"permata_virtual_account_number",
    "virtual_account_number":"8778003756104047"
  }
]

Provide top up information channel for Aggregator Partner

HTTP Request

GET BASE_URL/api/v1/channels

Simulate Top Up in sandbox environment

Using Permata VA

permata-va-1

permata-va-2

permata-va-3

Check Balance (Aggregator)

    {
      "balance": 25000
    }

For Aggregator Partner, you need to top up to Iris’ bank account. Every partner have their own balance in Iris’ bank account. Use this API is to get current balance information.

HTTP Request

GET BASE_URL/api/v1/balance

Return Parameter

Parameter Description
balance Balance information for partner

Bank Accounts (Facilitator)

[
  {
    "bank_account_id": "mandiri38fd1f0e",
    "bank_name": "mandiri",
    "account_name": "John Doe",
    "account_number": "189873746743",
    "status": "in_progress"
  },
  {
    "bank_account_id": "danamon64036485",
    "bank_name": "danamon",
    "account_name": "John Snow",
    "account_number": "77975396492",
    "status": "live"
  }
]

Show list of registered bank accounts for facilitator partner

HTTP

GET BASE_URL/api/v1/bank_accounts

Response Parameters

Parameter Description
bank_account_id Bank account ID to be used when creating payouts
bank_name Bank name of partner’s bank account
account_name Account name of partner’s bank account
account_number Account number of partner’s bank account
status in_progress: Registration process of bank account still in progress
live: Bank account already live and ready to use for payout

Reference

Testing

Here is a list of dummy bank account number that can be used for testing success payout in the Sandbox Environment, please make sure that you do not use this on Production mode.

Beneficiary Bank Beneficiary Account Beneficiary Name
Bank Mandiri 1380011819286 Mandiri Simulator A
1150006390175 Mandiri Simulator B
Bank Permata 4111911431 Permata Simulator A
Bank Danamon 000001137298 Danamon Simulator A
000001111111 Danamon Simulator B
000002678746 Danamon Simulator C
Bank BNI 0613007897 BNI Simulator A
0238272088 BNI Simulator B
Bank BRI 504101005099530 BRI Simulator A
Bank BCA 0611101146 BCA Simulator A
Bank CIMB 800057357100 CIMB Simulator A
860000165200 CIMB Simulator B

Supported Banks

List of banks supported in IRIS.

Bank Code Bank Name
aceh_syar PT. BPD Istimewa Aceh Syariah
agris PT. Bank Agris
agroniaga PT. Agroniaga Bank
akita PT. Bank Akita
andara PT. Bank Andara
anglomas PT. Anglomas International Bank
antar_daerah PT. Bank Antar Daerah
anz PT. ANZ Panin Bank
artajasa PT. Artajasa
artha PT. Bank Artha Graha International
artos PT. Bank Artos Indonesia
bali PT. BPD Bali
bangkok The Bangkok Bank PCL
bca PT. Bank Central Asia Tbk.
bca_syar PT. Bank BCA Syariah
bengkulu PT. BPD Bengkulu
bisnis PT. Bank Bisnis International
bjb PT. Bank Jabar dan Banten
bni PT. BNI 1946 (Persero) Tbk.
bni_syar PT. Bank BNI Syariah
bnp PT. Bank Nusantara Parahyangan
bnp_paribas PT. Bank BNP Paribas Indonesia
boa Bank of America NA
bri PT. BRI (Persero) Tbk.
bri_syar PT. Bank BRISyariah
btn PT. Bank Tabungan Negara (Persero)
btn_syar PT. BTN (Persero) Syariah
btpn PT. Bank Tabungan Pensiunan Nasional
btpn_syar PT. Bank Tabungan Pensiunan Nasional S
bukopin PT. Bukopin
bukopin_syar PT. Bank Syariah Bukopin
bumiputera PT. Bank Bumiputera
bumi_artha PT. Bank Bumi Arta
capital PT. Bank Capital Indonesia
centratama PT. Centratama Nasional Bank
chase JPMorgan Chase Bank NA
china Bank of China Limited
chinatrust PT. Bank Chinatrust Indonesia
cimb PT. Bank CIMB Niaga Tbk.
citibank Citibank NA
commonwealth PT. Bank Commonwealth
danamon PT. Bank Danamon Indonesia Tbk.
dbs PT. Bank DBS Indonesia
deutsche Deutsche Bank AG.
dipo PT. Bank Dipo International
diy PT. BPD DIY
diy_syar PT. BPD DIY Syariah
dki PT. BPD DKI Jakarta
dki_syar PT. BPD DKI Jakarta Syariah
fama PT. Bank Fama International
ganesha PT. Bank Ganesha
hana Bank Hana
harda PT. Bank Harda International
hsbc PT. Bank HSBC Indonesia
hs_1906 PT. Bank HS 1906
icbc PT. Bank ICBC Indonesia
ina_perdana PT. Bank Ina Perdana
index_selindo PT. Bank Index Selindo
jambi PT. BPD Jambi
jasa_jakarta PT. Bank Jasa Jakarta
jateng PT. BPD Jawa Tengah
jateng_syar BPD Jateng Syariah
jatim BPD Jawa Timur
jatim_syar BPD Jatim Syariah
jtrust PT. Bank JTrust Indonesia
kalbar PT. BPD Kalimantan Barat
kalbar_syar PT. BPD Kalimantan Barat Syariah
kalsel BPD Kalimantan Selatan
kalsel_syar BPD Kalimantan Selatan Syariah
kalteng PT. BPD Kalteng
kaltim PT. BPD Kalimantan Timur
kaltim_syar PT. BPD Kalimantan Timur Syariah
kesawan PT. Bank Kesawan
kesejahteraan PT. Bank Kesejahteraan Ekonomi
lampung BPD Lampung
liman PT. Bank Liman International
maluku PT. BPD Maluku
mandiri PT. Bank Mandiri (Persero) Tbk.
mandiri_syar PT. Bank Syariah Mandiri
maspion PT. Bank Maspion Indonesia
mayapada PT. Bank Mayapada
maybank PT. BII Tbk.
maybank_syar PT. BII Tbk. Syariah
mayora PT. Bank Mayora Indonesia
mega_syar PT. Bank Syariah Mega Indonesia
mega_tbk PT. Bank Mega Tbk.
mestika PT. Bank Mestika Dharma
metro PT. Bank Metro Ekspress
mitraniaga PT. Bank Mitraniaga
mitsubishi The BoT Mitsubishi UFJ LTD.
mizuho PT. Bank Mizuho Indonesia
mnc PT. Bank MNC Internasional Tbk.
muamalat PT. Bank Muamalat Indonesia
multiarta PT. Bank Multiarta Sentosa
mutiara PT. Bank Mutiara Tbk.
niaga_syar PT. Bank Niaga Tbk. Syariah
nobu PT. Bank National Nobu
ntb PT. Bank Pembangunan Daerah NTB
ntt BPD Nusa Tenggara Timur
ocbc PT. Bank OCBC NISP Tbk.
panin PT. Bank Panin Indonesia Tbk.
panin_syar PT. Bank Panin Syariah
papua PT. BPD Papua
permata PT. Bank Permata Tbk.
permata_syar PT. Bank Permata Tbk. Syariah
prima_master PT. Prima Master Bank
pundi PT. Bank Pundi Indonesia
purba PT. Bank Purba Danarta
rabobank PT. Bank Rabobank International I
rbos The Royal Bank of Scotland N.V.
resona PT. Bank Resona Perdania
riau PT. BPD Riau
royal PT. Bank Royal Indonesia
sampoerna PT. Bank Sahabat Sampoerna
sbi PT. Bank SBI Indonesia
sinarmas PT. Bank Sinarmas
sinarmas_syar PT. Bank Sinarmas Syariah
sinar_bali PT. Bank Sinar Harapan Bali
stanchard Standard Chartered Bank
sulsel PT. BPD Sulawesi Selatan
sulselbar PT. Bank Sulselbar Syariah
sulteng PT. BPD Sulawesi Tengah
sultenggara PT. BPD Sulawesi Tenggara
sulut BPD Sulawesi Utara
sumbar BPD Sumatera Barat
sumitomo PT. Bank Sumitomo Mitsui Indonesia
sumsel_babel BPD Sumsel dan Babel
sumut BPD Sumatera Utara
swadesi PT. Bank Swadesi Tbk.
uob PT. Bank UOB Indonesia
victoria PT. Bank Victoria International
victoria_syar PT. Bank Victoria Syariah
windu PT. Bank Windu Kentjana International
woori PT. Bank Woori Indonesia
yudha_bhakti PT. Bank Yudha Bhakti