NAV
API Reference

Introduction

Welcome to Midtrans API!

Midtrans API is a RESTful Web Service served as a communication bridge between merchant and our payment channels.

HTTP(S) Request

Midtrans 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://api.sandbox.midtrans.com/v2
Production Environment : https://api.midtrans.com/v2

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 base64(server key , :) The Authorization field credentials can be found in Midtrans Merchant Admin Portal

Content-Type and Accept Header

In Midtrans 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

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

Below is the step by step guideline:

  1. Place Server Key as Username, following the format of BASIC AUTH.
    Username:Password
  2. Since there is no Password for the server key, leave the password field blank.
  3. If the server key is: 94960ece-9513-4265-9cf2-67a4da330213.
    Following BASIC AUTH Username and password format will become:
    94960ece-9513-4265-9cf2-67a4da330213:
    Note: Make sure there is ":" character after the server key!
  4. Encode this value into base64 format, hence the result is:
    OTQ5NjBlY2UtOTUxMy00MjY1LTljZjItNjdhNGRhMzMwMjEzOg==
  5. To be authorized to use Midtrans API, you need to add the followoing HTTP(S) header:
    Authorization: Basic OTQ5NjBlY2UtOTUxMy00MjY1LTljZjItNjdhNGRhMzMwMjEzOg==

Midtrans API

API Methods

Endpoint HTTP Method Definition
/v2/token GET Tokenize Credit Card information before being charged
/v2/charge POST Perform a transaction with various available payment methods and features
/v2/capture POST Capture an authorized transaction for card payment
/v2/order_id/approve POST Approve a transaction with certain order_id which gets challenge status from Fraud Detection System
/v2/order_id/cancel POST Cancel a transaction with certain order_id. Cancelation can only be done before settlement process
/v2/order_id/expire POST Changing order_id with pending status to be expired
/v2/order_id/refund POST Changing order_id with settlement status to be refund
/v2/order_id/status GET Get information status of a transaction with certain order_id
/v2/order_id/status/b2b GET Get information status of multiple B2B transactions related to certain order_id
/v2/card/register GET Register card information (card number and expiry) to be used for two clicks and one click
/v2/point_inquiry/token_id GET Get the point balance of the card in denomination amount

Get Token

Token ID is a unique value that is associated with the customer credit card information during a transaction. Get Token method sends the credit card info via Midtrans.min.js to Midtrans server and returns token ID to the merchant being charged.

Midtrans Javascript Library

Midtrans Javascript library allows customer credit card to be securely sent to Midtrans server, without the merchant handling the credit card details.

To utilize this library, please add the following line of code at your payment page inside the <head> tag.

<script src="https://api.midtrans.com/v2/assets/js/midtrans.min.js" type="text/javascript"></script>

The Get Token function from the Javascript Library has to be triggered when the customer clicks pay:

// Create the card object with the required fields
function card () {
    return {
        // Contain Card Object explained below
    }
};

// Create the callback function according to Midtrans response
function callback(response) {
        // Handling of Midtrans Callback Response Object explained below
};

//Set your Midtrans credentials
Veritans.client_key = <YOUR_MIDTRANS_CLIENT_KEY>;

//Get token function to be triggered when click pay
Veritrans.token(card, callback);

Card Object

Field Description Example
card_number The 16 digits Credit Card number "4111 1111 1111 1111" or "4111111111111111"
card_cvv The numeric digit printed on the back of the card "123"
card_exp_month The card expiry month "03"
card_exp_year The card expiry year "2016"
bank The acquiring back where the card payment is processed "bni", "mandiri", "cimb", "bca", "bri", "maybank"
secure Flag for 3D Secure transaction true
gross_amount The transaction amount NOTE: Don't add decimal "200000"
installment The flag to enable installment true
installment_term The term of installment "3", "6"
token_id The previously saved token of credit card. Get the value from saved_token_id from initial charge response "481111-1114-0e68a4c4-85d3-48b5-b6cb-9945b2d3dcc9"
two_click The two clicks flag true
type The type of transaction "authorize"
channel The channel of transaction "migs"
point Point flag true
// Create the card object with the required fields
function card () {
    return {
        card_number: "4111 1111 1111 1111",
        card_cvv: "123",
        card_exp_month: "12",
        card_exp_year: "2018"
    }
};

The following card object has to be included in Get Token to access Midtrans feature

Feature Required Object
Normal Transaction card_number, card_cvv, card_exp_month, card_exp_year
3D Secure Transaction card_number, card_cvv, card_exp_month, card_exp_year, bank, secure, gross_amount
Installment card_number, card_cvv, card_exp_month, card_exp_year, bank, secure, gross_amount, installment, installment_term
Pre-authorization card_number, card_cvv, card_exp_month, card_exp_year, bank, secure, gross_amount, type
Two Clicks card_cvv, token_id, two_click, bank, secure, gross_amount

Callback Response Object

/*Create the callback response function.
NOTE: This example utilizes JQuery Fancybox.
You can use other javascript framework to display 3DS dialog*/

function callback(response) {
    if (response.redirect_url) {
      // If 3Dsecure transaction. Open 3Dsecure dialog
      console.log('Open Dialog 3Dsecure');
      openDialog(response.redirect_url);

    } else if (response.status_code == '200') {
      // success 3d secure or success normal
      //close 3d secure dialog if any
      closeDialog();

      // store token data in input #token_id
      $("#token-id").val(response.token_id);

    } else {
      // failed request token
      //close 3d secure dialog if any
      closeDialog();
      $('#submit-button').removeAttr('disabled');
      // Show status message.
      $('#message').text(response.status_message);
      console.log(JSON.stringify(response));
    }
  }

  // Open 3DSecure dialog box
  function openDialog(url) {
    // make sure to load fancybox in a script tag
    $.fancybox.open({
          href: url,
          type: 'iframe',
          autoSize: false,
          width: 400,
          height: 420,
          closeBtn: false,
          modal: true
      });
  }

  // Close 3DSecure dialog box
  function closeDialog() {
    $.fancybox.close();
  }
});
Field Description Example
status code The code of the response "200" for success, "400" when validation error
status_message The message of the status code "OK, success request new token"
validation_messages The validation errors [“card_exp_year must be greater than this year”, "card_expire_month must be greater than this year's month”]
redirect_url The 3DS URL to be displayed "https://api.sandbox.veritrans.co.id/v2/token/redirect/481111-1114-d3d690db-3e18-4edd-9fee-4d061e4eb6f3"
NOTE: The Javascript code shows how to display the 3DS Dialog
token_id The token id of a credit card "481111-1114-d3d690db-3e18-4edd-9fee-4d061e4eb6f3"
NOTE: token_id is essential during Card Payment [Charge Transaction]
eci The 3DS status indicator "05"

Charge features

Midtrans provides additional features that can be utilized by the merchants.

Set Custom Field

Set custom field charge request

{
  "payment_type": "bank_transfer",
  "bank_transfer": {
    "bank": "permata"
  },
  "transaction_details": {
    "order_id": "C17550",
    "gross_amount": 145000
  },
  "custom_field1": "custom field 1 content",
  "custom_field2": "custom field 2 content",
  "custom_field3": "custom field 3 content"
}

Set custom field charge response

{
    "status_code": "200",
    "status_message": "Success, Credit Card transaction is successful",
    "transaction_id": "1eae238a-cb9e-4f92-b284-aac8b39e4eab",
    "order_id": "C17550",
    "gross_amount": "145000.00",
    "payment_type": "credit_card",
    "transaction_time": "2016-06-28 09:42:20",
    "transaction_status": "capture",
    "fraud_status": "accept",
    "approval_code": "256084",
    "masked_card": "481111-1114",
    "bank": "bni"
}

Set custom field Notifications

{
  "masked_card": "481111-1114",
  "approval_code": "256084",
  "bank": "bni",
  "transaction_time": "2016-06-28 09:42:20",
  "custom_field1": "Toko Rani",
  "custom_field2": "Jakarta",
  "custom_field3": "RR",
  "gross_amount": "10000.00",
  "order_id": "C17550",
  "payment_type": "credit_card",
  "signature_key": "ad7ccda03d8ec6f2f415661fb511d47fcd17dcc7d7e1ade96a305dd5d3bc2bea5438a8bdfe1aeedabdefb226000338ac169fc18d5ae73788fd5e78dbac945ce4",
  "status_code": "200",
  "transaction_id": "1eae238a-cb9e-4f92-b284-aac8b39e4eab",
  "transaction_status": "capture",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}

Set Custom Fields is a feature that enables merchant to charge a transaction with a unique data according to merchant's need. Midtrans provides merchant with 3 custom fields that can be used for various utility. Convention of a custom field can be set from Midtrans Merchant Admin Portal, as follow below:

  1. Go to Configuration tab, under General Settings, set the custom fields label.
  2. Request Charge transaction with the custom fields value.
  3. These custom fields label and value can be checked at the Order ID of a transaction.
  4. Midtrans will include these custom fields when the HTTP POST Notification is sent.
JSON Attribute Type Description
custom_field1 String(255) The value of custom field 1
custom_field2 String(255) The value of custom field 2
custom_field3 String(255) The value of custom field 3

Set Custom Expiry

{
  "payment_type": "bank_transfer",
  "bank_transfer": {
    "bank": "permata"
  },
  "transaction_details": {
    "order_id": "C17550",
    "gross_amount": 145000
  },
  "custom_expiry": {
      "order_time": "2016-12-07 11:54:12 +0700",
      "expiry_duration": 60,
      "unit": "minute"
  }
}

Set Custom Expiry feature enables merchant to set an expiry time of payment with pending status for every transaction. The following payment is the list of payment with Pending Status:

JSON Attribute Type Description
order_time String(50) Time when the order is created in merchant website.
Format: yyyy-MM-dd hh:mm:ss Z.
NOTE: If attribute undefined, expiry time starts from transaction time

Symbol Meaning
yyyy 4-digits year
MM 2-digits month in year
dd 2-digits day in month
hh 2-digits hour (1-24)
mm 2-digits minutes fraction
ss 2-digits seconds fraction
Z RFC-822 Timezone format
expiry_duration String(50) Time duration the payment will remain valid
unit String(50) Unit for expiry_duration.
Valid values are: second, minute, hour, or day.
NOTE: If attribute undefined, default unit is minute

Capture Transaction

This method is used to capture transaction balance when transaction_status is authorize.

Capture Transaction Method

Endpoint HTTP Method Definition
BASE_URL/v2/{order_id/transaction_id}/capture POST Capture an authorized transaction for card payment

Capture Transaction Response

Success Capture Transaction Response

{
  "status_code" : "200",
  "status_message" : "Success, Credit Card capture transaction is successful",
  "transaction_id" : "ca297170-be4c-45ed-9dc9-be5ba99d30ee",
  "masked_card" : "451111-1117",
  "order_id" : "testing-0.4555-1414741517",
  "payment_type" : "credit_card",
  "transaction_time" : "2014-10-31 14:46:44",
  "transaction_status" : "capture",
  "fraud_status" : "accept",
  "bank" : "bni",
  "gross_amount" : "30000.00"
}

Error Capture Transaction Response

{
  "status_code" : "412",
  "status_message" : "Merchant cannot modify the status of the transaction"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status after capture credit card transaction
masked_card String First 6-digit and last 4-digit of customer's credit card number
status_code String Status code of transaction capture result
bank String The acquiring bank of the transaction
status_message String Description of transaction capture result

Approve Transaction

Approve method can be triggered to accept card payment transaction in which fraud_status is challenge.

Approve Transaction Method

Endpoint HTTP Method Definition
BASE_URL/v2/{order_id/transaction_id}/approve POST Approve Challenged Transaction

Approve Transaction Response

Success Approved Transaction Response

{
  "status_code" : "200",
  "status_message" : "Success, transaction is approved",
  "transaction_id" : "ca297170-be4c-45ed-9dc9-be5ba99d30ee",
  "masked_card" : "451111-1117",
  "order_id" : "testing-0.4555-1414741517",
  "payment_type" : "credit_card",
  "transaction_time" : "2014-10-31 14:46:44",
  "transaction_status" : "capture",
  "fraud_status" : "accept",
  "bank" : "bni",
  "gross_amount" : "30000.00"
}

Error Approve Transaction Response

{
  "status_code" : "412",
  "status_message" : "Merchant cannot modify the status of the transaction"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status after charge credit card transaction, the possible values are
capture : Transaction is accepted by the bank and ready for settlement.
deny: transaction is denied by the bank or FDS.
authorize: Credit card is authorized in pre-authorization feature
fraud_status String Detection result by Fraud Detection System (FDS). Possible Value:
accept : Approved by FDS.
challenge: Questioned by FDS. NOTE: Approve transaction to accept it or transaction will auto cancel during settlement.
deny: Denied by FDS. Transaction automatically failed
masked_card String First 6-digit and last 4-digit of customer's credit card number
status_code String Status code of transaction charge result
bank String The acquiring bank of the transaction
status_message String Description of transaction charge result

Cancel Transaction

Card Payment

Card payment can be voided with cancel method if transaction has not been settled. For Pre-Authorized transaction, Cancelling a Pre-Authorized transaction varies depends on the Acquiring Bank.

Acquiring Bank Trigger Cancel Method
BNI After pre-authorization payment has been captured
Mandiri After pre-authorization payment initially being Charged

Pending Payment

Payment with Pending Status can be voided with cancel method if transaction has not expired or has not been completed. The following payment is the list of payment with Pending Status:

Cancel Transaction Method

Endpoint HTTP Method Definition
BASE_URL/v2/{order_id/transaction_id}/cancel POST Cancel Transaction

Cancel Transaction Response and notification

Success Cancel Transaction Response

{
  "status_code" : "200",
  "status_message" : "Success, transaction is canceled",
  "transaction_id" : "249fc620-6017-4540-af7c-5a1c25788f46",
  "masked_card" : "481111-1114",
  "order_id" : "example-1424936368",
  "payment_type" : "credit_card",
  "transaction_time" : "2015-02-26 14:39:33",
  "transaction_status" : "cancel",
  "fraud_status" : "accept",
  "bank" : "bni",
  "gross_amount" : "30000.00"
}

Error Cancel Transaction Response

{
  "status_code" : "412",
  "status_message" : "Merchant cannot modify the status of the transaction"
}

Success Cancel Transaction notification

{
  "masked_card": "420194-2900",
  "approval_code": "325511",
  "bank": "mandiri",
  "eci": "05",
  "transaction_time": "2016-07-04 13:32:44",
  "gross_amount": "244108.00",
  "order_id": "160288131764",
  "payment_type": "credit_card",
  "signature_key": "71f3b14d3036d2a60dac7fef1cdde7bebdbb2dbeebc68bcf5e7819fe8be7c9241611ea1e769e0c6775735805174c02b9d6b5cf89a11de1861d5efb298c9898b7",
  "status_code": "202",
  "transaction_id": "ffd82cd2-4f0d-4b24-b4b8-e201b0c3d80e",
  "transaction_status": "cancel",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status after charge credit card transaction, the possible values are
capture : Transaction is accepted by the bank and ready for settlement.
deny: transaction is denied by the bank or FDS.
authorize: Credit card is authorized in pre-authorization feature
fraud_status String Detection result by Fraud Detection System (FDS). Possible Value:
accept : Approved by FDS.
challenge: Questioned by FDS. NOTE: Approve transaction to accept it or transaction will auto cancel during settlement.
deny: Denied by FDS. Transaction automatically failed
masked_card String First 6-digit and last 4-digit of customer's credit card number
status_code String Status code of transaction charge result
bank String The acquiring bank of the transaction
status_message String Description of transaction charge result

Expire transaction

Transaction status can be updated into expired if the customer has not complete the payment. The expired order id can be reuse again with the same or different payment method.

Expire Transaction Method

Endpoint HTTP Method Definition
BASE_URL/v2/{order_id/transaction_id}/expire POST Expire Transaction

Expire Transaction Response

Success Expire Transaction Response

{
  "status_code": "407",
  "status_message": "Success, transaction has expired",
  "transaction_id": "447e846a-403e-47db-a5da-d7f3f06375d6",
  "order_id": "vtmbill05",
  "payment_type": "echannel",
  "transaction_time": "2015-06-15 13:36:24",
  "transaction_status": "expire",
  "gross_amount": "10000.00"
}

Error Expire Transaction Response

{
  "status_code" : "412",
  "status_message" : "Merchant cannot modify the status of the transaction"
}

Expired Transaction notification

{
  "status_code": "202",
  "status_message": "Veritrans payment notification",
  "transaction_id": "841c7da8-530b-435a-9f67-c9d632d15537",
  "order_id": "1000176721005355",
  "gross_amount": "698879.00",
  "payment_type": "bank_transfer",
  "transaction_time": "2016-07-04 00:53:55",
  "transaction_status": "expire",
  "permata_va_number": "8778004890127981",
  "signature_key": "f1066b06ec8a4b7d6ffb941fd9772f6df304618e15e02cf17c2914cec12793e19c71653042f7f617b027eae6ecb6759529c67eca9af55264b736408d8b4df2b9"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status after charge credit card transaction, the possible values are
capture : Transaction is accepted by the bank and ready for settlement.
deny: transaction is denied by the bank or FDS.
authorize: Credit card is authorized in pre-authorization feature
status_code String Status code of transaction charge result
status_message String Description of transaction charge result

Refund transaction

Transaction status can be updated into refund if the customer decided to cancel completed/settlement payment. The refund order id cannot be reuse again with the same or different payment method.

Refund Transaction Method

Endpoint HTTP Method Definition
BASE_URL/v2/{order_id/transaction_id}/refund POST Refund Transaction

Refund Transaction Request

{
  "amount": 5000,
  "reason": "for some reason"
}
JSON Attribute Type Required Description
amount Long N Amount to be refunded. By default will refund whole transaction amount
reason String(255) N Reason justifying the refund

Refund Transaction Response

Success Full Refund Transaction Response

{
  "status_code": "200",
  "status_message": "Success, refund request is approved",
  "transaction_id": "447e846a-403e-47db-a5da-d7f3f06375d6",
  "order_id": "vtmbill05",
  "payment_type": "echannel",
  "transaction_time": "2015-06-15 13:36:24",
  "transaction_status": "refund",
  "gross_amount": "10000.00",
  "refund_chargeback_id": 1,
  "refund_amount": "10000.00"
}

Success Partial Refund Transaction Response

{
  "status_code": "200",
  "status_message": "Success, refund request is approved",
  "transaction_id": "447e846a-403e-47db-a5da-d7f3f06375d6",
  "order_id": "vtmbill05",
  "payment_type": "echannel",
  "transaction_time": "2015-06-15 13:36:24",
  "transaction_status": "partial_refund",
  "gross_amount": "10000.00",
  "refund_chargeback_id": 1,
  "refund_amount": "5000.00"
}

Error Refund Transaction Response

{
  "status_code" : "412",
  "status_message" : "Merchant cannot modify the status of the transaction"
}

Full Refund Transaction notification

{
  "status_code": "200",
  "status_message": "Veritrans payment notification",
  "transaction_id": "841c7da8-530b-435a-9f67-c9d632d15537",
  "order_id": "1000176721005355",
  "gross_amount": "698879.00",
  "payment_type": "bank_transfer",
  "transaction_time": "2016-07-04 00:53:55",
  "transaction_status": "refund",
  "permata_va_number": "8778004890127981",
  "signature_key": "f1066b06ec8a4b7d6ffb941fd9772f6df304618e15e02cf17c2914cec12793e19c71653042f7f617b027eae6ecb6759529c67eca9af55264b736408d8b4df2b9"
}

Partial Refund Transaction notification

{
  "status_code": "200",
  "status_message": "Veritrans payment notification",
  "transaction_id": "841c7da8-530b-435a-9f67-c9d632d15537",
  "order_id": "1000176721005355",
  "gross_amount": "698879.00",
  "payment_type": "bank_transfer",
  "transaction_time": "2016-07-04 00:53:55",
  "transaction_status": "partial_refund",
  "permata_va_number": "8778004890127981",
  "signature_key": "f1066b06ec8a4b7d6ffb941fd9772f6df304618e15e02cf17c2914cec12793e19c71653042f7f617b027eae6ecb6759529c67eca9af55264b736408d8b4df2b9"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status after charge credit card transaction, the possible values are
refund : Transaction is fully refunded.
partial_refund: transaction is partially refunded
status_code String Status code of transaction charge result
status_message String Description of transaction charge result
refund_chargeback_id String Identification of the refund process
refund_amount String Actual refunded amount

Get Transaction Status

Transaction status can be obtained by triggering the Get Status Method.

Get Transaction Status Method

Endpoint HTTP Method Definition
BASE_URL/v2/{order_id/transaction_id}/status GET Get Status Transaction

Get Status Transaction Response

Success Get Status Transaction Response

{
  "status_code" : "200",
  "status_message" : "Success, transaction found",
  "transaction_id" : "249fc620-6017-4540-af7c-5a1c25788f46",
  "masked_card" : "481111-1114",
  "order_id" : "example-1424936368",
  "payment_type" : "credit_card",
  "transaction_time" : "2015-02-26 14:39:33",
  "transaction_status" : "capture",
  "fraud_status" : "accept",
  "approval_code" : "1424936374393",
  "signature_key" : "2802a264cb978fbc59f631c68d120cbda8dc853f5dfdc52301c615cf4f14e7a0b09aa...",
  "bank" : "bni",
  "gross_amount" : "30000.00"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status after charge credit card transaction, the possible values are
capture : Transaction is accepted by the bank and ready for settlement.
deny: transaction is denied by the bank or FDS.
authorize: Credit card is authorized in pre-authorization feature
fraud_status String Detection result by Fraud Detection System (FDS). Possible Value:
accept : Approved by FDS.
challenge: Questioned by FDS. NOTE: Approve transaction to accept it or transaction will auto cancel during settlement.
deny: Denied by FDS. Transaction automatically failed
masked_card String First 6-digit and last 4-digit of customer's credit card number
status_code String Status code of transaction charge result
bank String The acquiring bank of the transaction
status_message String Description of transaction charge result
signature_key String Signature key to validate if the notification is originated from Midtrans
approval_code String Approval code from payment provider for successful transaction. It can be used for refund

Get Transaction Status B2B

Transaction status for all B2B transactions related to an order_id can be obtained by triggering the Get Status B2B Method.

Get Transaction Status B2B Method

Endpoint HTTP Method Definition
BASE_URL/v2/{order_id/transaction_id}/status/b2b GET Get Status B2B Transaction

Get Status Transaction B2B Parameter

Query Parameter Required Description
page N Index of the search. Default is 0.
per_page N Number of transactions which is presented. Default is 10.

Get Status Transaction B2B Response

Success Get Status B2B Transaction Response

{
  "status_code": "200",
  "status_message": "Success, transactions are retrieved",
  "transactions": [
    {
      "payment_type": "echannel",
      "bill_key": "990568881594",
      "transaction_time": "2016-09-17 06:36:31",
      "gross_amount": "6000.00",
      "order_id": "vttesta73fb08ebd1-160916233631561",
      "signature_key": "ae85d0ade1bcdfdce4400b63918a8250b3ce45056621c743f71c02197e851accae43787190ee343b18f665d811a4e4d372bddbd347bda588a90d89c1b1c4ed53",
      "status_code": "200",
      "transaction_id": "647c9366-596a-4ba2-b20f-77baaa1e6647",
      "transaction_status": "settlement",
      "fraud_status": "accept",
      "status_message": "Success, transaction is found"
    },
    {
      "payment_type": "echannel",
      "bill_key": "990568881594",
      "transaction_time": "2016-09-17 06:34:52",
      "gross_amount": "6000.00",
      "order_id": "vttesta73fb08ebd1",
      "signature_key": "e8ae2f8cba40fe505c3c0f8bfec8dbc748ee5c8d04ad0699f33d17b7fc6aba5b1218f518226b4ea2ff095cb60125a5e6e1cb345608446378d29cb10ad687f560",
      "status_code": "200",
      "transaction_id": "f9a6684f-e3b4-46dd-8b6c-b61d805b3c6f",
      "transaction_status": "settlement",
      "fraud_status": "accept",
      "status_message": "Success, transaction is found"
    }
  ]
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status after charge credit card transaction, the possible values are
capture : Transaction is accepted by the bank and ready for settlement.
deny: transaction is denied by the bank or FDS.
authorize: Credit card is authorized in pre-authorization feature
fraud_status String Detection result by Fraud Detection System (FDS). Possible Value:
accept : Approved by FDS.
challenge: Questioned by FDS. NOTE: Approve transaction to accept it or transaction will auto cancel during settlement.
deny: Denied by FDS. Transaction automatically failed
masked_card String First 6-digit and last 4-digit of customer's credit card number
status_code String Status code of transaction charge result
bank String The acquiring bank of the transaction
status_message String Description of transaction charge result
signature_key String Signature key to validate if the notification is originated from Midtrans
approval_code String Approval code from payment provider for successful transaction. It can be used for refund
transactions Array Collections of transaction status objects

Register Card

Register Card Status Method

Endpoint HTTP Method Definition
BASE_URL/v2/card/register GET Register card information (card number and expiry) to be used for two clicks and one click

Register Card Request

Put these parameters as query parameters on the URL.

JSON Attribute Type Required Description
card_number String Y Credit card number
card_exp_month String Y Credit card expiry month
card_exp_year String Y Credit card expiry year
client_key String Y Partner client key credential
callback String N Function name used for JSONP callback

Register Card Response

Success Register Card Response

{
  "status_code": "200",
  "saved_token_id": "436502PjvfpHomPBggDvfipaIYhV0009",
  "transaction_id": "50e7c4ac-772e-43fa-94fb-52559bce4fc0",
  "masked_card": "436502-0009"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
masked_card String First 6-digit and last 4-digit of customer's credit card number
status_code String Status code of transaction charge result
saved_token_id String Token id used for two clicks or one click

Point Inquiry

Point Inquiry Status Method

Endpoint HTTP Method Definition
BASE_URL/v2/point_inquiry/{token_id} GET Get the point balance of the card in denomination amount

Point Inquiry Response

Point Inquiry Request

Put these parameters as query parameters on the URL.

JSON Attribute Type Required Description
gross_amount String C The volume of the following transaction. This number can decide the remaining point balance amount which can be used on the response. NOTE: Needed for Mandiri Point

Success Point Inquiry Response

{
  "status_code": "200",
  "status_message": "Success, Credit Card Point inquiry is successful",
  "transaction_time": "2017-05-29 12:21:40",
  "point_balance_amount": "10000.00"
}
JSON Attribute Type Description
status_code String Status code of transaction result
status_message String Status message of transaction result
transaction_time String Time of the transactions
point_balance_amount String Denomination amount of the point balance

Credit Card

Integration steps:

  1. Exchange card data (consisting of the number, expiry month, expiry year and CVV) for a token.
  2. Perform charge transaction using the token.
  3. Handle notification.

Credit Card Charge

Complete credit card charge request

{
  "payment_type": "credit_card",
  "transaction_details": {
    "order_id": "C17550",
    "gross_amount": 145000
  },
  "credit_card": {
    "token_id": "< your token ID >" // Token ID from Get Token
  },
  "item_details": [{
      "id": "a1",
      "price": 145000,
      "quantity": 2,
      "name": "Apel",
      "brand": "Fuji Apple",
      "category": "Fruit",
      "merchant_name": "Fruit-store"
    }],
    "customer_details": {
      "first_name": "BUDI",
      "last_name": "UTOMO",
      "email": "test@midtrans.com",
      "phone": "+628123456",
      "billing_address": {
        "first_name": "BUDI",
        "last_name": "UTOMO",
        "email": "test@midtrans.com",
        "phone": "081 2233 44-55",
        "address": "Sudirman",
        "city": "Jakarta",
        "postal_code": "12190",
        "country_code": "IDN"
      },
      "shipping_address": {
        "first_name": "BUDI",
        "last_name": "UTOMO",
        "email": "test@midtrans.com",
        "phone": "0 8128-75 7-9338",
        "address": "Sudirman",
        "city": "Jakarta",
        "postal_code": "12190",
        "country_code": "IDN"
      }
    }
}

Charge method is triggered every time a transaction is performed. The attribute that is used is dependent on the payment method desired.

JSON Attribute Type Description
payment_type String (255)
'required'
Set credit card payment method.
Value is "credit_card"
transaction_details Object Details of the transaction will be paid by customer
credit_card Object Charge details using credit card
item_details Object Shopping item details will be paid by customer
customer_details Object Customer data who makes the purchase

Card Payment Charge Response and Notifications

Card Payment Charge Response

{
  "transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "order_id": "C17550",
  "gross_amount": "145000.00",
  "payment_type": "credit_card",
  "transaction_time": "2014-08-24 15:39:22",
  "transaction_status": "capture",
  "fraud_status": "accept",
  "masked_card": "481111-1114",
  "status_code": "200",
  "bank": "bni",
  "status_message": "Success, Credit Card 3D Secure transaction is successful",
  "approval_code": "1408869563148",
  "eci": "05"
}

Card Payment Charge Error Response

{
    "status_code": "411",
    "status_message": "Token id is missing, invalid, or timed out"
}

Card Payment Capture Notification

{
  "masked_card": "481111-1114",
  "approval_code": "T58755",
  "bank": "bni",
  "eci": "05",
  "transaction_time": "2014-08-24 15:39:22",
  "gross_amount": "145000.00",
  "order_id": "C17550",
  "payment_type": "credit_card",
  "signature_key": "8d22a6b625f395a1a2cf0e62497e20be433cbad3e8a8ff36bf6b40dbd47308125ccda93546eab8a3acd91390155082658ac25b10a6294c6660642e43a5edc8bb",
  "status_code": "200",
  "transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "transaction_status": "capture",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}

Card Payment Deny notification

{
  "masked_card": "481111-1114",
  "approval_code": "338016",
  "bank": "bni",
  "eci": "06",
  "transaction_time": "2014-08-24 15:39:22",
  "gross_amount": "145000.00",
  "order_id": "C17550",
  "payment_type": "credit_card",
  "signature_key": "763713b31cf59c886d3cc4a0c654a060a8e990080fe29fca75ae9e4ff9de804809c4e20977829844dac01a7ac1464a4eb095ad32482048398918987295dc5022",
  "status_code": "202",
  "transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "transaction_status": "deny",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}

Card Payment Challenge notification

{
  "masked_card": "481111-1114",
  "approval_code": "315762",
  "bank": "bni",
  "eci": "05",
  "transaction_time": "2014-08-24 15:39:22",
  "gross_amount": "145000.00",
  "order_id": "C17550",
  "payment_type": "credit_card",
  "signature_key": "393f8b6b27f9f6385d8391642942e9534fd20dad20c0631b75b0746bfc314482af4411c93e958b691a63e9154676905b906234d1f12fca031f5be5593f7ec2c6",
  "status_code": "201",
  "transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "transaction_status": "capture",
  "fraud_status": "challenge",
  "status_message": "Veritrans payment notification"
}

Card Payment Settlement notification

{
  "masked_card": "481111-1114",
  "approval_code": "131755",
  "bank": "bni",
  "eci": "05",
  "transaction_time": "2014-08-24 15:39:22",
  "gross_amount": "145000.00",
  "order_id": "C17550",
  "payment_type": "credit_card",
  "signature_key": "49e158a0c3f1913eae0902875324075c562daa39b2824b865db2242adea247a228960d2f1002392fdbc29c3271c2bc78ba72e588db9047a82932d0615ddc811f",
  "status_code": "200",
  "transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "transaction_status": "settlement",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}

Two of the most important information details in the JSON response is the transaction and fraud status, which can be found in transaction_status and fraud_status attribute.

  1. Transaction status capture and fraud_status accept: Transaction successful.
  2. Transaction status deny and fraud_status anything: Transaction rejected by bank or by Fraud Detection System (FDS).
  3. Transaction status capture and fraud_status challenge: Transaction challenge. You have to make a confirmation at Merchant Administration Portal (MAP).

At this point, the payment process of a transaction is complete. If the transaction_status value is capture and fraud_status value is accept, the customer’s credit card has been charged to your account. In addition to sending the transaction status to the customer, you can also update the respective database. Example, to mark if the respective order_id has been paid.

Transaction status can also be found in Merchant Administration Portal (MAP). You have to login to MAP to see the detail of the transaction. The other alternative to check on the transaction status is to use the command Acquiring Transaction Status.

By default, all credit card transactions from 00.00 until 23.59, will be settled on the day after at 16.00. The transaction status will be updated from capture into settlement. If there is any unapproved challenged transaction, Midtrans will cancel the transaction automatically. Midtrans will also send HTTP POST notification to merchant endpoint.

JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total ammount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status after charge credit card transaction, the possible values are
capture : Transaction is accepted by the bank and ready for settlement.
deny: transaction is denied by the bank or FDS.
authorize: Credit card is authorized in pre-authorization feature
fraud_status String Detection result by Fraud Detection System (FDS). Possible Value:
accept : Approved by FDS.
challenge: Questioned by FDS. NOTE: Approve transaction to accept it or transaction will auto cancel during settlement.
deny: Denied by FDS. Transaction automatically failed
masked_card String First 6-digit and last 4-digit of customer's credit card number
status_code String Status code of transaction charge result
bank String The acquiring bank of the transaction
status_message String Description of transaction charge result
approval_code String Approval code. It can be used for refund. This does not exist on denied transaction
eci String The 3D secure ECI Code

Card Features: BIN Promo

Card Payment BIN Promo Charge

{
  "payment_type": "credit_card",
  "transaction_details": {
    "order_id": "C17550",
    "gross_amount": 145000
  },
  "credit_card": {
    "token_id": "< your token ID >",
    "bins": ["48111111", "bni", "5"]
  }
}

To configure the BIN Promo feature, an additional attribute will be required in credit_card object:

JSON Attribute Type Description
token_id String Token ID represents customer's credit card information acquired from Get Token Response
bank String Acquiring bank
bins JSON Array List of credit card's BIN (Bank Identification Number) that is allowed for transaction.
All BIN can have 1 to 8 digits

BIN Promo Charge Response and Notifications

BIN Promo Charge Response and Notifications are identical with Card Payment Charge Response. Successful BIN Promo transaction is described as capture and is ready for settlement.

Card Features: Installment

Card Payment Installment Charge

{
  "payment_type": "credit_card",
  "transaction_details": {
    "order_id": "C17550",
    "gross_amount": 145000
  },
  "credit_card": {
    "token_id": "< your token ID >",
    "installment_term": 12
  }
}

You need an Installment Token to charge with Installment feature. To charge the installment feature, additional attributes will be required in credit card object:

JSON Attribute Type Description
token_id String Token ID represents customer's credit card information acquired from Get Token Response
bank String Acquiring bank
installment_term Array Integer Installment Tenor

Installment Charge Response and Notifications

Card Payment Installment Charge Response

{
      "status_code": "200",
      "status_message": "Success, Credit Card transaction is successful",
      "transaction_id": "c1e1cc28-5208-4965-bc99-076919dc0a26",
      "order_id": "20527106",
      "gross_amount": "1687180.00",
      "payment_type": "credit_card",
      "transaction_time": "2016-06-19 09:12:15",
      "transaction_status": "capture",
      "fraud_status": "accept",
      "approval_code": "R71372",
      "masked_card": "542640-9747",
      "bank": "bni",
      "installment_term": "6",
}

Card Payment Online Installment Capture Notifications

{
  "masked_card": "542640-9747",
  "approval_code": "R71372",
  "bank": "bni",
  "eci": "01",
  "installment_term": 6,
  "transaction_time": "2016-06-19 09:12:15",
  "gross_amount": "1687180.00",
  "order_id": "20527106",
  "payment_type": "credit_card",
  "signature_key": "4a4e59bdc26b3c473014f8dbc1bb9faf35c1f29c473f48666ea6faaf9d8eb80bf8e47be8d79ef4cdec820c6aecad7da198a64461cdf08937f7c56688fafb8448",
  "status_code": "200",
  "transaction_id": "c1e1cc28-5208-4965-bc99-076919dc0a26",
  "transaction_status": "capture",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}

Successful Installment transaction is described as capture and is ready for settlement.

Offline Installment

Card Payment Offline Installment Charge

{
  "payment_type": "credit_card",
  "transaction_details": {
    "order_id": "C17550",
    "gross_amount": 145000
  },
  "credit_card": {
    "token_id": "< your token ID >",
    "installment_term": 12,          
    "bins": ["48111111", "3111", "5"]
  }
}

Offline installment feature allow merchant to do installment conversion for transactions which is not supported by MID installment. To charge the offline installment feature in VT-Direct, additional attributes installment will be required with combination bin_filter. The purpose of bin_filter is to limit only certain cards can be used depends on the agreement between merchant and banks.

Below is the charge request for offline installment:

Offline Installment Charge Response and Notifications

Card Payment Offline Installment Charge Response

{
   "status_code": "200",
   "status_message": "Success, Credit Card transaction is successful",
   "transaction_id": "b046340b-dc40-480a-828f-085fc265850c",
   "order_id": "62465770",
   "gross_amount": "1352373.00",
   "payment_type": "credit_card",
   "transaction_time": "2016-06-19 05:41:18",
   "transaction_status": "capture",
   "fraud_status": "accept",
   "approval_code": "854442",
   "eci": "05",
   "masked_card": "414009-6871",
   "bank": "bni",
   "installment_term": "6"
}

Card Payment Offline Installment Notifications

{
  "masked_card": "414009-4550",
  "approval_code": "833736",
  "bank": "bni",
  "eci": "05",
  "installment_term": 12,
  "transaction_time": "2016-07-04 14:00:55",
  "gross_amount": "16277555.00",
  "order_id": "160288134251",
  "payment_type": "credit_card",
  "signature_key": "1742c43dbda320dfe26a0e570eb8c95f710058967a2bb45b3996b664e19feb30aec8a6458be56ee310e7941fb89e3e3da09833b0f858fc8226bfa0442af2b5b0",
  "status_code": "201",
  "transaction_id": "3c1b1f1a-bfcf-4fa1-9a93-bebf5b9cb488",
  "transaction_status": "capture",
  "fraud_status": "challenge",
  "status_message": "Veritrans payment notification"
}

Successful Installment transaction is described as capture and is ready for settlement.

Card Features: Pre-Authorization

Card Payment pre-Authorization Charge

{
  "payment_type": "credit_card",
  "transaction_details": {
    "order_id": "C17550",
    "gross_amount": 145000
  },
  "credit_card": {
    "token_id": "< your token ID >",
    "type": "authorize"   
  }
}

You need a Pre-Authorization Token from Get Token to charge with Pre-Authorization feature. To configure the Pre-Authorization feature in VT-Direct, an additional attribute will be required in credit card object.

JSON Attribute Type Description
token_id String Token ID represents customer's credit card information acquired from Get Token Response
bank String Acquiring bank
type String Attribute to enable the pre-authorization feature. Valid value authorize

Pre-Authorization Charge Response and Notifications

Card Payment Pre-Authorization Charge Response

{
    "status_code": "200",
    "status_message": "Success, Credit Card transaction is successful",
    "transaction_id": "be4f3e44-d6ee-4355-8c64-c1d1dc7f4590",
    "order_id": "C17550",
    "gross_amount": "145000.00",
    "payment_type": "credit_card",
    "transaction_time": "2016-07-02 14:00:27",
    "transaction_status": "authorize",
    "fraud_status": "accept",
    "approval_code": "003873",
    "eci": "05",
    "masked_card": "481111-1114",
    "bank": "bca"
}

Card Payment Pre-Authorization notification

{
  "masked_card": "481111-1114",
  "approval_code": "003873",
  "bank": "bca",
  "eci": "05",
  "transaction_time": "2016-07-02 14:00:27",
  "gross_amount": "145000.00",
  "order_id": "C17550",
  "payment_type": "credit_card",
  "signature_key": "7156a83f0beb052c689e3775e60049062dd84379eda494b929704955957a41949df03c7010a0ad888347828f04b9288bdf541e044569372d1ab957295a6c5a14",
  "status_code": "200",
  "transaction_id": "be4f3e44-d6ee-4355-8c64-c1d1dc7f4590",
  "transaction_status": "authorize",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}

Pre-Authorization Charge Response is different with Card Payment Charge Response. Successful Pre-Authorization transaction is described as authorize and can be settled only if the transaction has been captured. If the transaction is captured, the transaction status will be updated into capture and ready for settlement.

To charge for pre-Authorization, capture transaction method is used in which transaction_status is set to authorize.

{
    "transaction_id" : "1ac1a089d-a587-40f1-a936-a7770667d6dd",
    "gross_amount" : 55000              // <--- Value should not exceed the Charge Value on Pre-Authorization
}

Capture Transaction Method

Endpoint HTTP Method Definition
BASE_URL/capture POST Capture a Pre-Authorized Transaction

Body Message:

JSON Attribute Type Description
transaction_id String Transaction ID from Charge Pre-Authorization Response
gross_amount Long The value of transactions which will be paid by the customer. Note: Should not exceed the value of Charge Pre-Authorization transaction. If left undefined, capture full transaction

Capture Transaction Response and notification

Capture Transaction Response

{
    "status_code": "200",
    "status_message": "Success, Credit Card capture transaction is successful",
    "transaction_id": "1ac1a089d-a587-40f1-a936-a7770667d6dd",
    "order_id": "A27550",
    "payment_type": "credit_card",
    "transaction_time": "2014-08-25 10:20:54",
    "transaction_status": "capture",
    "fraud_status": "accept",
    "masked_card": "481111-1114",
    "bank": "bca",
    "eci": "05",
    "gross_amount": "55000.00"
}

Capture Transaction notification

{
  "masked_card": "481111-1114",
  "approval_code": "T67700",
  "bank": "bca",
  "eci": "05",
  "transaction_time": "2014-08-25 10:20:54",
  "gross_amount": "55000.00",
  "order_id": "A27550",
  "payment_type": "credit_card",
  "signature_key": "23a7036edb8171b926e5292c7729c6bd26ed3250e22aead55110e34086dbc8fb393e7d3b7f764428a27c76e77d0a3bb6a7ba867066b2fbf5dae9e0f8a6c0dc0d",
  "status_code": "200",
  "transaction_id": "1ac1a089d-a587-40f1-a936-a7770667d6dd",
  "transaction_status": "capture",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}
JSON Attribute Type Description
status_code String Status code of transaction charge result
status_message String Description of transaction charge result
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status after charge credit card transaction, the possible values are
capture : Transaction is accepted by the bank and ready for settlement.
deny: transaction is denied by the bank or FDS.
authorize: Credit card is authorized in pre-authorization feature
fraud_status String Detection result by Fraud Detection System (FDS). Possible Value:
accept : Approved by FDS.
challenge: Questioned by FDS. NOTE: Approve transaction to accept it or transaction will auto cancel during settlement.
deny: Denied by FDS. Transaction automatically failed
approval_code String Approval code from payment provider for successful transaction, it can be used for refund
eci String The 3D Secure ECI Code
masked_card String First 6-digit and last 4-digit of customer's credit card number
bank String The acquiring bank of the transaction

Card Features: One Click

One Click Initial Charge

Card Payment Initial One Click Charge

{
    "payment_type": "credit_card",
    "credit_card": {
        "token_id": "4811117d16c884-2cc7-4624-b0a8-10273b7f6cc8",
        "save_token_id": true     // <-- To flag that token is saved during initial charge
    },
    "transaction_details": {
        "order_id": "A87550",
        "gross_amount": 145000
    }
}

You need a Token from Get Token to charge with One Click feature. Add additional attribute when charging the initial transaction for One Click feature.

JSON Attribute Type Description
token_id String Token ID represents customer's credit card information acquired from Get Token Response
bank String Acquiring bank
save_token_id Boolean A flag to indicate one click feature to return a saved_token_id which can be used for the next transaction

One Click Initial Charge Response and Notifications

Card Payment Initial One Click Charge Response

{
    "status_code": "200",
    "status_message": "Success, Credit Card 3D Secure transaction is successful",
    "transaction_id": "f50c0aef-b629-4a5b-957b-4c52f45e2e63",
    "order_id": "A87550",
    "payment_type": "credit_card",
    "transaction_time": "2014-08-25 11:21:48",
    "transaction_status": "capture",
    "fraud_status": "accept",
    "masked_card": "481111-1114",
    "saved_token_id": "4811117d16c884-2cc7-4624-b0a8-10273b7f6cc8",
    "saved_token_id_expired_at": "2024-08-25 11:21:48",            
    "approval_code": "1408940508666",
    "gross_amount": "145000.00"
}

Card Payment Initial One Click Notifications

{
  "masked_card": "481111-1114",
  "approval_code": "1408940508666",
  "bank": "bni",
  "eci": "05",
  "saved_token_id": "4811117d16c884-2cc7-4624-b0a8-10273b7f6cc8",
  "saved_token_id_expired_at": "2024-08-25 11:21:48",
  "transaction_time": "2014-08-25 11:21:48",
  "gross_amount": "145000.00",
  "order_id": "A87550",
  "payment_type": "credit_card",
  "signature_key": "c77f17bf6a8dee35c19f02f2c33f9e4a2ee61b4bad15370a9f0f149a96909c8d887a0e0cddeb47bd02e88f369422aee6e323aaf938bb7bc5c55228459babbdb1",
  "status_code": "200",
  "transaction_id": "f50c0aef-b629-4a5b-957b-4c52f45e2e63",
  "transaction_status": "capture",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}

One Click Initial Charge Response and Notifications are identical with Card Payment Charge Response and Notifications, with additional attributes:

JSON Attribute Type Description
saved_token_id String Token ID of a credit card to be charged for the following transaction
saved_token_id_expired_at String Expiry date of the Token ID

One Click Following Charge

Card Payment Following One Click Charge

{
    "payment_type": "credit_card",
    "credit_card": {
        "token_id": "44811117d16c884-2cc7-4624-b0a8-10273b7f6cc8"
    },
    "transaction_details": {
        "order_id": "A87551",
        "gross_amount": 145000
    }
}

You need saved_token_id from initial Charge Response in order to charge the following One Click transaction.

JSON Attribute Type Description
token_id String saved_token_id represents customer's credit card information acquired from One Click initial charge response
bank String Acquiring bank

One Click Following Charge Response and Notifications

Following One Click Charge Response is identical with Card Payment Charge Response and Response. Successful One Click transaction is described as capture and is ready for settlement.

Card Features: Two Clicks

Two Clicks Initial Charge

Card Payment Initial Two Clicks Charge

{
    "payment_type": "credit_card",
    "credit_card": {
        "token_id": "4811117d16c884-2cc7-4624-b0a8-10273b7f6cc8",
        "save_token_id": true     // To flag that token is saved during initial charge
    },
    "transaction_details": {
        "order_id": "A87550",
        "gross_amount": 145000
    }
}

You need a Token from Get Token for initial charge with Two Clicks feature. Add this additional attribute when charging the initial transaction for Two Clicks feature.

JSON Attribute Type Description
token_id String Token ID represents customer's credit card information acquired from Get Token Response
bank String Acquiring bank

Two Clicks Initial Charge Response and Notifications

Card Payment Initial Two Clicks Charge Response

{
    "status_code": "200",
    "status_message": "Success, Credit Card 3D Secure transaction is successful",
    "transaction_id": "f50c0aef-b629-4a5b-957b-4c52f45e2e63",
    "order_id": "A87550",
    "payment_type": "credit_card",
    "transaction_time": "2014-08-25 11:21:48",
    "transaction_status": "capture",
    "fraud_status": "accept",
    "masked_card": "481111-1114",
    "saved_token_id": "4811117d16c884-2cc7-4624-b0a8-10273b7f6cc8",
    "saved_token_id_expired_at": "2024-08-25 11:21:48",
    "approval_code": "1408940508666",
    "gross_amount": "145000.00"
}

Card Payment Initial Two Clicks notification

{
  "masked_card": "481111-1114",
  "approval_code": "1408940508666",
  "bank": "bni",
  "eci": "05",
  "saved_token_id": "4811117d16c884-2cc7-4624-b0a8-10273b7f6cc8",
  "saved_token_id_expired_at": "2024-08-25 11:21:48",
  "transaction_time": "2014-08-25 11:21:48",
  "gross_amount": "145000.00",
  "order_id": "A87550",
  "payment_type": "credit_card",
  "signature_key": "c77f17bf6a8dee35c19f02f2c33f9e4a2ee61b4bad15370a9f0f149a96909c8d887a0e0cddeb47bd02e88f369422aee6e323aaf938bb7bc5c55228459babbdb1",
  "status_code": "200",
  "transaction_id": "f50c0aef-b629-4a5b-957b-4c52f45e2e63",
  "transaction_status": "capture",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}

Two Clicks Initial Charge Response is identical with Card Payment Charge Response, with the additional attributes:

JSON Attribute Type Description
saved_token_id String Token ID of a credit card to be charged for the following transaction
saved_token_id_expired_at String Expiry date of the Token ID

Two Clicks Following Charge

Card Payment Following Two Clicks Charge

{
    "payment_type": "credit_card",
    "credit_card": {
        "token_id": "481111-1114-7baba36c-5698-47cf-9170-80efd6a2e973"
    },
    "transaction_details": {
        "order_id": "A87551",
        "gross_amount": 145000
    }
}

You need the Two Clicks Token from Get Token in order to charge the following two clicks transaction.

JSON Attribute Type Description
token_id String Token ID represents customer's credit card information acquired from Get Token Response
bank String Acquiring bank

Two Clicks Following Payment Response and Notifications.

Following Two Clicks Charge Response is identical with Card Payment Charge Response and Notifications. Successful Two Clicks transaction is described as capture and is ready for settlement.

Card Features: Point

Card Payment Point Charge

{
    "payment_type": "credit_card",
    "credit_card": {
        "token_id": "4811117d16c884-2cc7-4624-b0a8-10273b7f6cc8",
        "point_redeem_amount": 145000
    },
    "transaction_details": {
        "order_id": "A87550",
        "gross_amount": 145000
    }
}

You need a Token from Get Token for initial charge with Two Clicks feature. Add this additional attribute when charging the initial transaction for Two Clicks feature.

JSON Attribute Type Description
token_id String Token ID represents customer's credit card information acquired from Get Token Response
bank String Acquiring bank
point_redeem_amount Long Amount to be redeemed with point

Point Charge Response and Notifications

Card Payment Point Charge Response

{
    "status_code": "200",
    "status_message": "Success, Credit Card 3D Secure transaction is successful",
    "transaction_id": "f50c0aef-b629-4a5b-957b-4c52f45e2e63",
    "order_id": "A87550",
    "payment_type": "credit_card",
    "transaction_time": "2014-08-25 11:21:48",
    "transaction_status": "capture",
    "fraud_status": "accept",
    "masked_card": "481111-1114",
    "point_redeem_amount": 145000,
    "point_balance_amount": "0.00",
    "approval_code": "1408940508666",
    "gross_amount": "145000.00"
}

Card Payment Point notification

{
  "masked_card": "481111-1114",
  "approval_code": "1408940508666",
  "bank": "bni",
  "eci": "05",
  "point_redeem_amount": 145000,
  "point_balance_amount": "0.00",
  "transaction_time": "2014-08-25 11:21:48",
  "gross_amount": "145000.00",
  "order_id": "A87550",
  "payment_type": "credit_card",
  "signature_key": "c77f17bf6a8dee35c19f02f2c33f9e4a2ee61b4bad15370a9f0f149a96909c8d887a0e0cddeb47bd02e88f369422aee6e323aaf938bb7bc5c55228459babbdb1",
  "status_code": "200",
  "transaction_id": "f50c0aef-b629-4a5b-957b-4c52f45e2e63",
  "transaction_status": "capture",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}

Point Charge Response is identical with Card Payment Charge Response, with the additional attributes:

JSON Attribute Type Description
point_redeem_amount Long Denomination amount redeemed
point_balance_amount String Remaining denomination amount

Credit Card - Promo (Beta)

Midtrans allows partners to use certain promotions on credit card transactions. Following steps are modified version of the usual Credit Card integration steps:

  1. Check for applicable promo
  2. Lock the promo
  3. Exchange card data via get token
  4. Perform charge transaction with previous token
  5. Handle notification

Check for applicable promo

GET /v3/promos?client_key=<valid client key>

Check promos sample response

{
  "status_code": "200",
  "status_message": "successful",
  "promos": [
    {
      "id": 1,
      "bins": ["48111", "48112"],
      "discount_amount": 50000,
      "discount_type": "FIXED",
      "start_date": "2016-03-26T14:30:01.990Z",
      "end_date": "2017-03-26T14:30:01.990Z",
      "promo_code": "FOODIE",
      "sponsor_name": "BANK1",
      "sponsor_message_en": "Discount from Bank1",
      "sponsor_message_id": "Diskon dari Bank1"
    }, {
      "id": 2,
      "bins": ["54", "35"],
      "discount_amount": 50000,
      "discount_type": "FIXED",
      "start_date": "2016-03-26T14:30:01.990Z",
      "end_date": "2017-03-26T14:30:01.990Z",
      "promo_code": "MAS",
      "sponsor_name": "BANK2",
      "sponsor_message_en": "Discount from Bank2",
      "sponsor_message_id": "Diskon dari Bank2"
   }
 ]
}
JSON Attribute Type Description
status_code String Status code of API result
status_message String Message describing the status code
promos Object Promotion details. See details below.
JSON Attribute Type Description
id Long Identifier of the promotion. IMPORTANT: Keep it for next step.
bins Array(String) List of card prefix available for the promotion
discount_amount Long Monetary value of the discount
discount_type String Type of the discount. Only FIXED for now.
start_date String Creation date of the discount
end_date String Expiration date of the discount
promo_code String Promotion code
sponsor_name String Issuer of the promotion
sponsor_message_en String Issuer message for the promotion (English)
sponsor_message_id String Issuer message for the promotion (Bahasa)

Lock the promo

GET /v3/hold

Lock promo sample request. This will ensure that users do not lose their promos if there is a surge of promo users and the amount allocated for it is exhausted.

Following Query Parameters are allowed

JSON Attribute Type Required Description
promo_token Long Y Identifier of the promotion. Equivalent to previous promos.id.
amount Long Y Initial transaction amount
client_key String Y Valid merchant client key

Lock promo sample response

{
  "success": true,
  "discount_token": "98fbd3ca-f4a8-44d0-a5f5-25e9747a3737",
  "promo_code": "MAS1",
  "expires_at": "2017-03-26T14:30:01.990Z",
  "discount_amount": 5000,
  "payment_amount": 10000
}
JSON Attribute Type Description
success Boolean Success flag for the locking attempt
discount_token String One time token for the discount usage. IMPORTANT: Keep it for next step.
promo_code String Promotion code
expires_at String Expiration date of the token
discount_amount Long Monetary value of the discount
payment_amount Long Initial transaction amount

Exchange card data via get token

Perform usual get token with gross_amount value equals to payment_amount substract by discount_amount received during lock promo. Example: payment_amount equals to 12000, discount_amount equals to 3000. The gross_amount used for get token should be 9000.

Perform charge transaction with previous token

Charge with promo sample request

{
  "payment_type": "credit_card",
  "transaction_details": {
    "order_id": "ORDER-ID-1",
    "gross_amount": 10000
  },
  "credit_card": {
    "token_id": "481111-9006-1601ae22-4da3-4252-bd8e-e908e0ce652b"
  },
  "promo_discount": {
    "token": "98fbd3ca-f4a8-44d0-a5f5-25e9747a3737",
    "amount": 5000
  }
}

Charge request body is similar to usual credit card charge except there is promo_discount object. Below is the details:

JSON Attribute Type Required Description
token String Y Discount token obtained during lock promo discount_token.
amount Long Y Monetary value of the discount

Charge with promo sample response

{
  "transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "order_id": "ORDER-ID-1",
  "gross_amount": "5000.00",
  "payment_type": "credit_card",
  "transaction_time": "2017-08-24 15:39:22",
  "transaction_status": "capture",
  "fraud_status": "accept",
  "masked_card": "481111-1114",
  "status_code": "200",
  "bank": "bni",
  "status_message": "Success, Credit Card 3D Secure transaction is successful",
  "approval_code": "1408869563148",
  "eci": "05",
  "discount_token": "98fbd3ca-f4a8-44d0-a5f5-25e9747a3737",
  "discount_amount": 5000

}

Charge response body is also similar to usual credit card charge except with two additional fields discount_token and discount_amount.

JSON Attribute Type Description
discount_token String One time token for the discount usage
discount_amount Long Monetary value of the discount

Handle notification

Handling the notification is exactly the same as normal credit card.

Bank Transfer

One of the payment method offered by Midtrans is Bank Transfer. By using this payment method, customer will have an option to make a payment via bank transfer and Midtrans will send real time notification when the customer complete the payment.

At this moment, Midtrans has integrated with 3 different bank transfer payment method:

Permata Virtual Account

Integration steps:

  1. Merchant send charge request to Midtrans.
  2. Display the virtual account number.
  3. Handle notification.

Permata Virtual Account Charge

{
  "payment_type": "bank_transfer",
  "bank_transfer": {
    "bank": "permata"       // <-- To flag that Permata Bank Virtual Account is used
  },
  "transaction_details": {
    "order_id": "H17550",
    "gross_amount": 145000
  }
}

Following attributes are required to charge Permata Virtual Account:

JSON Attribute Type Description
payment_type String Set Bank Transfer payment method. Value: bank_transfer
transaction_details Object Details of the transaction will be paid by customer
bank_transfer Object Charge details using bank transfer
item_details Object Shopping item details will be paid by customer
customer_details Object Customer data who makes the purchase

Permata Virtual Account Response and notification

Permata Virtual Account Charge Response

{
  "status_code": "201",
  "status_message": "Success, PERMATA VA transaction is successful",
  "transaction_id": "6fd88567-62da-43ff-8fe6-5717e430ffc7",
  "order_id": "H17550",
  "gross_amount": "145000.00",
  "payment_type": "bank_transfer",
  "transaction_time": "2016-06-19 13:42:29",
  "transaction_status": "pending",
  "fraud_status": "accept",
  "permata_va_number": "8562000087926752"
}

Permata Virtual Account Pending Notification

{
  "status_code": "201",
  "status_message": "Veritrans payment notification",
  "transaction_id": "6fd88567-62da-43ff-8fe6-5717e430ffc7",
  "order_id": "H17550",
  "gross_amount": "145000.00",
  "payment_type": "bank_transfer",
  "transaction_time": "2016-06-19 13:42:29",
  "transaction_status": "pending",
  "permata_va_number": "8562000087926752",
  "signature_key": "66aa11a65b18e9ee5da966ed18d5d2163812000eee37824ceb59aba1ded005e992e05a7dfac39098ebdb0e2c8b484e140b586246d34b4ca313c690cc6eae48cf"
}

Permata Virtual Account Settlement notification

{
  "status_code": "200",
  "status_message": "Veritrans payment notification",
  "transaction_id": "6fd88567-62da-43ff-8fe6-5717e430ffc7",
  "order_id": "H17550",
  "gross_amount": "145000.00",
  "payment_type": "bank_transfer",
  "transaction_time": "2016-06-19 18:23:21",
  "transaction_status": "settlement",
  "permata_va_number": "8562000087926752",
  "signature_key": "0c0df82489931602577d9e434966c0540249b7c0aeaae2b718305af89a11e2bf9b4008aba07d1b3b248b15b4fbecdd15e81dbb2648b974efc4e0656e8c976094"
}

Permata Virtual Account Expired notification

{
  "status_code": "202",
  "status_message": "Veritrans payment notification",
  "transaction_id": "6fd88567-62da-43ff-8fe6-5717e430ffc7",
  "order_id": "H17550",
  "gross_amount": "145000.00",
  "payment_type": "bank_transfer",
  "transaction_time": "2016-06-20 13:42:30",
  "transaction_status": "expire",
  "permata_va_number": "8562000087926752",
  "signature_key": "f1066b06ec8a4b7d6ffb941fd9772f6df304618e15e02cf17c2914cec12793e19c71653042f7f617b027eae6ecb6759529c67eca9af55264b736408d8b4df2b9"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status of bank transfer transaction, the possible value is
pending : Bank Transfer transaction is created
fraud_status String Detection result by Fraud Detection System (FDS). Possible Value:
accept : Approved by FDS.
status_code String Status code of transaction charge result
status_message String Description of transaction charge result
permata_va_number String Generated Virtual Account number. Customer has to know this number to complete the payment

BCA Virtual Account

Integration steps:

  1. Merchant send charge request to Midtrans.
  2. Display the virtual account number.
  3. Handle notification.

BCA Virtual Account Charge

{
    "payment_type": "bank_transfer",
    "transaction_details": {
        "gross_amount": 10000,
        "order_id": "{{$timestamp}}"
    },
    "customer_details": {
        "email": "budi.utomo@Midtrans.com",
        "first_name": "budi",
        "last_name": "utomo",
        "phone": "+6281 1234 1234"
    },
    "item_details": [
    {
       "id": "1388998298204",
       "price": 5000,
       "quantity": 1,
       "name": "Ayam Zozozo"
    },
    {
       "id": "1388998298205",
       "price": 5000,
       "quantity": 1,
       "name": "Ayam Xoxoxo"
    }
   ],
   "bank_transfer":{
     "bank": "bca",
     "va_number": "111111",
     "free_text": {
          "inquiry": [
                {
                    "id": "Free Text ID Free Text ID Free Text ID",
                    "en": "Free Text EN Free Text EN Free Text EN"
                }
          ],
          "payment": [
                {
                    "id": "Free Text ID Free Text ID Free Text ID",
                    "en": "Free Text EN Free Text EN Free Text EN"
                }
          ]
    }
  }
}

Following attributes are required to charge Permata Virtual Account:

JSON Attribute Type Description
payment_type String Set Bank Transfer payment method. Value: bank_transfer
transaction_details Object Details of the transaction will be paid by customer
bank_transfer Object Charge details using bank transfer
item_details Object Shopping item details will be paid by customer
customer_details Object Customer data who makes the purchase

BCA Virtual Account Response and notification

BCA Virtual Account Charge Response

{
  "status_code": "201",
  "status_message": "Success, Bank Transfer transaction is created",
  "transaction_id": "9aed5972-5b6a-401e-894b-a32c91ed1a3a",
  "order_id": "1466323342",
  "gross_amount": "20000.00",
  "payment_type": "bank_transfer",
  "transaction_time": "2016-06-19 15:02:22",
  "transaction_status": "pending",
  "va_numbers": [
    {
      "bank": "bca",
      "va_number": "91019021579"
    }
  ],
  "fraud_status": "accept"
}

BCA Virtual Account Pending notification

{
  "va_numbers": [
    {
      "bank": "bca",
      "va_number": "91019021579"
    }
  ],
  "transaction_time": "2016-06-19 15:02:22",
  "gross_amount": "20000.00",
  "order_id": "1466323342",
  "payment_type": "bank_transfer",
  "signature_key": "74d9b6f4cc36585d74e06c9dba360331e455171bcec35df60cf28a786436f8f96e6afcc1f091d6cb61411aec246ac28ba30b76d9b2c1cdb6409c0a70fcc1fe47",
  "status_code": "201",
  "transaction_id": "a9aed5972-5b6a-401e-894b-a32c91ed1a3a",
  "transaction_status": "pending",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}

BCA Virtual Account Settlement notification

{
  "va_numbers": [
    {
      "bank": "bca",
      "va_number": "91019021579"
    }
  ],
  "transaction_time": "2016-06-19 19:12:22",
  "gross_amount": "20000.00",
  "order_id": "1466323342",
  "payment_type": "bank_transfer",
  "signature_key": "fe5f725ea770c451017e9d6300af72b830a668d2f7d5da9b778ec2c4f9177efe5127d492d9ddfbcf6806ea5cd7dc1a7337c674d6139026b28f49ad0ea1ce5107",
  "status_code": "200",
  "transaction_id": "9aed5972-5b6a-401e-894b-a32c91ed1a3a",
  "transaction_status": "settlement",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}

BCA Virtual Account Expired notification

Send again
{
  "status_code": "202",
  "status_message": "Veritrans payment notification",
  "transaction_id": "9aed5972-5b6a-401e-894b-a32c91ed1a3a",
  "order_id": "1466323342",
  "gross_amount": "20000.00",
  "payment_type": "bank_transfer",
  "transaction_time": "2016-06-20 15:02:23",
  "transaction_status": "expire",
  "signature_key": "e4e829a5d9a1e342daf181c5fd750afa64dd5a5c9a6e0cfb636e7966295b2613fda22b4dc52b01c30618a50ff3524f57ec661a9dced249df93f163138a0df6b0"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status of bank transfer transaction, the possible value is
pending : Bank Transfer transaction is created
fraud_status String Detection result by Fraud Detection System (FDS). Possible Value:
accept : Approved by FDS.
status_code String Status code of transaction charge result
status_message String Description of transaction charge result
va_number Array of JSON Generated Virtual Account number and virtual account bank

Mandiri Bill Payment

Integration steps:

  1. Merchant send charge request to Midtrans.
  2. Display bill key and biller code to the customer.
  3. Handle notification.

Mandiri Bill Payment Charge

{
    "payment_type": "echannel",
    "transaction_details": {
        "order_id": "1388",
        "gross_amount": 95000
        },
    "item_details": [
        {
          "id": "a1",
          "price": 50000,
          "quantity": 2,
          "name": "Apel"
        },
        {
         "id": "a2",
          "price": 45000,
          "quantity": 1,
          "name": "Jeruk"
        }
    ],
    "echannel" : {
        "bill_info1" : "Payment For:",
        "bill_info2" : "debt"
    }
}

The following attribute can be used to perform a charge transaction with Mandiri Bill Payment:

JSON Attribute Type Description
payment_type String Set E-channel payment method. Value: echannel
transaction_details Object Details of the transaction will be paid by customer
echannel Object Charge details using Mandiri Bill Payment
item_details Object Shopping item details will be paid by customer
customer_details Object Customer data who makes the purchase

Mandiri Bill Response

Mandiri Bill Payment Charge Response

{
  "status_code": "201",
  "status_message": "Success, Mandiri Bill transaction is successful",
  "transaction_id": "883af6a4-c1b4-4d39-9bd8-b148fcebe853",
  "order_id": "tes",
  "gross_amount": "1000.00",
  "payment_type": "echannel",
  "transaction_time": "2016-06-19 14:40:19",
  "transaction_status": "pending",
  "fraud_status": "accept",
  "bill_key": "990000000260",
  "biller_code": "70012"
}

Mandiri Bill Payment Pending notification

{
  "status_code": "201",
  "status_message": "Veritrans payment notification",
  "transaction_id": "883af6a4-c1b4-4d39-9bd8-b148fcebe853",
  "order_id": "tes",
  "gross_amount": "1000.00",
  "payment_type": "echannel",
  "transaction_time": "2016-06-19 14:40:19",
  "transaction_status": "pending",
  "signature_key": "d1ebf5bf14a7c96ca58e719832de459898f61fa8d81560f59e9a38a5187383b1d507e3075277d9b1c6227926fc8a0448e164f1b9de33c8141f81c57b87d23775",
  "bill_key": "990000000260",
  "biller_code": "70012"
}

Mandiri Bill Payment Settlement notification

{
  "status_code": "200",
  "status_message": "Veritrans payment notification",
  "transaction_id": "883af6a4-c1b4-4d39-9bd8-b148fcebe853",
  "order_id": "tes",
  "gross_amount": "1000.00",
  "payment_type": "echannel",
  "transaction_time": "2016-06-19 15:10:29",
  "transaction_status": "settlement",
  "approval_code": "340093197",
  "signature_key": "bbceb3724b0b2446c59435795039fed2d249d3438f06bf90c999cc9d383b95170b7b58f9412fba25ce7756da8075ab1d78a48800156380a62dc84eb22b3f7de9",
  "bill_key": "990000000260",
  "biller_code": "70012"
}

Mandiri Bill Payment Expired notification

{
  "status_code": "202",
  "status_message": "Veritrans payment notification",
  "transaction_id": "883af6a4-c1b4-4d39-9bd8-b148fcebe853",
  "order_id": "tes",
  "gross_amount": "1000.00",
  "payment_type": "echannel",
  "transaction_time": "2016-06-20 14:40:19",
  "transaction_status": "expire",
  "signature_key": "69ef827242b29640a1193b6c2f32ba1374c04b969f7723984a6c676349ee7927cb6b263546d138e3a5c788829fbc4f114353b67becad2af7a86b1b741fc8d80a",
  "bill_key": "990000000260",
  "biller_code": "70012"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status of bank transfer transaction, the possible value is
pending : Bank Transfer transaction is created
fraud_status String Detection result by Fraud Detection System (FDS). Possible Value:
accept : Approved by FDS.
status_code String Status code of transaction charge result
status_message String Description of transaction charge result
biller_code String Midtrans Unique Biler Code Number. Value is 70012
bill_key String Merchant Biller Key ID to perform transaction

BNI Virtual Account

Integration steps:

  1. Merchant send charge request to Midtrans.
  2. Display the virtual account number.
  3. Handle notification.

BNI Virtual Account Charge

{
    "payment_type": "bank_transfer",
    "transaction_details": {
        "gross_amount": 10000,
        "order_id": "{{$timestamp}}"
    },
    "customer_details": {
        "email": "budi.utomo@Midtrans.com",
        "first_name": "budi",
        "last_name": "utomo",
        "phone": "+6281 1234 1234"
    },
    "item_details": [
    {
       "id": "1388998298204",
       "price": 5000,
       "quantity": 1,
       "name": "Ayam Zozozo"
    },
    {
       "id": "1388998298205",
       "price": 5000,
       "quantity": 1,
       "name": "Ayam Xoxoxo"
    }
   ],
   "bank_transfer":{
     "bank": "bni",
     "va_number": "111111"
  }
}

Following attributes are required to charge Permata Virtual Account:

JSON Attribute Type Description
payment_type String Set Bank Transfer payment method. Value: bank_transfer
transaction_details Object Details of the transaction will be paid by customer
bank_transfer Object Charge details using bank transfer
item_details Object Shopping item details will be paid by customer
customer_details Object Customer data who makes the purchase

BCA Virtual Account Response and notification

BCA Virtual Account Charge Response

{
  "status_code": "201",
  "status_message": "Success, Bank Transfer transaction is created",
  "transaction_id": "9aed5972-5b6a-401e-894b-a32c91ed1a3a",
  "order_id": "1466323342",
  "gross_amount": "20000.00",
  "payment_type": "bank_transfer",
  "transaction_time": "2016-06-19 15:02:22",
  "transaction_status": "pending",
  "va_numbers": [
    {
      "bank": "bni",
      "va_number": "8578000000111111"
    }
  ],
  "fraud_status": "accept"
}

BCA Virtual Account Pending notification

{
  "va_numbers": [
    {
      "bank": "bni",
      "va_number": "8578000000111111"
    }
  ],
  "transaction_time": "2016-06-19 15:02:22",
  "gross_amount": "20000.00",
  "order_id": "1466323342",
  "payment_type": "bank_transfer",
  "signature_key": "74d9b6f4cc36585d74e06c9dba360331e455171bcec35df60cf28a786436f8f96e6afcc1f091d6cb61411aec246ac28ba30b76d9b2c1cdb6409c0a70fcc1fe47",
  "status_code": "201",
  "transaction_id": "a9aed5972-5b6a-401e-894b-a32c91ed1a3a",
  "transaction_status": "pending",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}

BCA Virtual Account Settlement notification

{
  "va_numbers": [
    {
      "bank": "bni",
      "va_number": "8578000000111111"
    }
  ],
  "transaction_time": "2016-06-19 19:12:22",
  "gross_amount": "20000.00",
  "order_id": "1466323342",
  "payment_type": "bank_transfer",
  "signature_key": "fe5f725ea770c451017e9d6300af72b830a668d2f7d5da9b778ec2c4f9177efe5127d492d9ddfbcf6806ea5cd7dc1a7337c674d6139026b28f49ad0ea1ce5107",
  "status_code": "200",
  "transaction_id": "9aed5972-5b6a-401e-894b-a32c91ed1a3a",
  "transaction_status": "settlement",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}

BCA Virtual Account Expired notification

Send again
{
  "status_code": "202",
  "status_message": "Veritrans payment notification",
  "transaction_id": "9aed5972-5b6a-401e-894b-a32c91ed1a3a",
  "order_id": "1466323342",
  "gross_amount": "20000.00",
  "payment_type": "bank_transfer",
  "transaction_time": "2016-06-20 15:02:23",
  "transaction_status": "expire",
  "signature_key": "e4e829a5d9a1e342daf181c5fd750afa64dd5a5c9a6e0cfb636e7966295b2613fda22b4dc52b01c30618a50ff3524f57ec661a9dced249df93f163138a0df6b0"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status of bank transfer transaction, the possible value is
pending : Bank Transfer transaction is created
fraud_status String Detection result by Fraud Detection System (FDS). Possible Value:
accept : Approved by FDS.
status_code String Status code of transaction charge result
status_message String Description of transaction charge result
va_number Array of JSON Generated Virtual Account number and virtual account bank

Internet Banking

Internet banking payment methods allow the customer to pay using their internet banking account and debit their saving account in order to pay online transaction. At this moment, Midtrans has integrated with 5 different internet banking payment method:

BCA Klikpay

BCA Klikpay Charge

{
  "payment_type": "bca_klikpay",
  "transaction_details": {
    "order_id": "orderid-01",
    "gross_amount": 11000
  },
  "item_details": [
    {
      "id": "1",
      "price": 11000,
      "quantity": 1,
      "name": "Mobil "
    }
  ],
  "customer_details":{
    "first_name": "John",
    "last_name": "Baker",
    "email": "john.baker@email.com",
    "phone": "08123456789"
  },
  "bca_klikpay": {
    "type": 1,
    "description": "Pembelian Barang"
  }
}

BCA KlikPay is the online banking payment method provided by BCA. This method allows customer to perform transaction using either their internet banking account or their private-label BCA credit card. The highly secure payment method, utilizes an SMS token for user validation.

Integration steps:

  1. Merchant send charge request to Midtrans.
  2. Do redirection to address specified in the response.
  3. Handle notification.

Following attributes are required to charge BCA Klikpay:

JSON Attribute Type Description
payment_type String Set BCA Klikpay payment method. Value: bca_klikpay
transaction_details Object Details of the transaction will be paid by customer
bca_klikpay Object Charge details using BCA Klikpay
item_details Object Shopping item details will be paid by customer
customer_details Object Customer data who makes the purchase

BCA Klikpay Charge Response and notification

BCA Klikpay Charge Response

{
  "status_code": "201",
  "status_message": "OK, BCA KlikPay transaction is successful",
  "transaction_id": "ada84cd9-2233-4c67-877a-01884eece45e",
  "order_id": "orderid-01",
  "redirect_url": "https://api.sandbox.veritrans.co.id/v3/bca/klikpay/redirect/ada84cd9-2233-4c67-877a-01884eece45e",
  "gross_amount": "11000.00",
  "payment_type": "bca_klikpay",
  "transaction_time": "2016-06-19 15:42:36",
  "transaction_status": "pending",
  "fraud_status": "accept"
}

BCA Klikpay Pending notification

{
  "transaction_time": "2016-06-19 15:42:36",
  "gross_amount": "11000.00",
  "order_id": "orderid-01",
  "payment_type": "bca_klikpay",
  "signature_key": "e47d73b2a10347d291e85a7c39c5fa2a7b760f0af7d9882f9c1b26db06e1af948968184b78f67112158cdeddd2141fe41068fdb37361ce11c3d2509354224a80",
  "status_code": "201",
  "transaction_id": "ada84cd9-2233-4c67-877a-01884eece45e",
  "transaction_status": "pending",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}

BCA Klikpay Settlement notification

{
  "approval_code": "91231",
  "transaction_time": "2016-06-19 15:46:16",
  "gross_amount": "11000.00",
  "order_id": "orderid-01",
  "payment_type": "bca_klikpay",
  "signature_key": "35c4111539e184b268b7c1cd62a9c254e5d27c992c8fd55084f930b69b09eaafcfe14b0d512c697648295fdb45de777e1316b401f4729846a91b3de88cde3f05",
  "status_code": "200",
  "transaction_id": "ada84cd9-2233-4c67-877a-01884eece45e",
  "transaction_status": "settlement",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}

BCA Klikpay Expired notification

{
  "status_code": "202",
  "status_message": "Veritrans payment notification",
  "transaction_id": "ada84cd9-2233-4c67-877a-01884eece45e",
  "order_id": "orderid-01",
  "gross_amount": "11000.00",
  "payment_type": "bca_klikpay",
  "transaction_time": "2016-06-19 17:42:38",
  "transaction_status": "expire",
  "signature_key": "62a8c432bb5a288a0495dd4f868b0aede4535e0c8a9fbebb3c6e9d4ea0db6f1963e551e70a99e80512030afa5ba8268f9be7b17b13a422ebef4620988c55d5ed"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status of BCA Klikpay transaction, the possible value is
pending
fraud_status String Detection result by Fraud Detection System (FDS). Possible Value:
accept : Approved by FDS.
challenge: Questioned by FDS. NOTE: Approve transaction to accept it or transaction will auto cancel during settlement.
deny: Denied by FDS. Transaction automatically failed
status_code String Status code of transaction charge result
status_message String Description of transaction charge result
redirect_url String Redirect URL to BCA Klikpay payment page

Klikbca

Klikbca Charge

"payment_type" : "bca_klikbca",
"bca_klikbca" : {
   "description" : "testing transaction",
   "user_id" : "midtrans1012"
 },
"transaction_details" : {
   "order_id" : "3176440",
   "gross_amount" : "50000.00"
 },
 "item_details": [
   {
     "id": "1",
     "price": 50000,
     "quantity": 1,
     "name": "Mobil "
   }
 ],
 "customer_details" : {
   "first_name" : "Budi",
   "last_name" : "435547",
   "email" : "budi.utomo@yahoo.com"
 }

KlikBCA is an online banking payment method provided by BCA. This method allows customer to perform online transaction and complete the payment using BCA internet banking. Klikbca payment method utilizes BCA token for validation.

Integration steps:

  1. Merchant send charge request to Midtrans.
  2. Do redirection to address specified in the response.
  3. Handle notification.

Following attributes are required to charge BCA Klikpay:

JSON Attribute Type Description
payment_type String Set Klikbca payment method. Value: bca_klikbca
transaction_details Object Details of the transaction will be paid by customer
bca_klikbca Object Charge details using Klikbca
item_details Object Shopping item details will be paid by customer
customer_details Object Customer data who makes the purchase

Klikbca Charge Response and notification

Klikbca Charge Response

{
  "status_code": "201",
  "status_message": "Success, KlikBCA transaction is successful",
  "redirect_url": "https://www.klikbca.com",
  "transaction_id": "c0ba3583-5111-45a5-9f1c-84c9de7cb2f6",
  "order_id": "3176440",
  "gross_amount": "50000.00",
  "payment_type": "bca_klikbca",
  "transaction_time": "2016-06-19 15:53:25",
  "transaction_status": "pending",
  "approval_code": "tes01"
}

Klikbca Pending notification

{
  "status_code": "201",
  "status_message": "Veritrans payment notification",
  "transaction_id": "c0ba3583-5111-45a5-9f1c-84c9de7cb2f6",
  "order_id": "3176440",
  "gross_amount": "50000.00",
  "payment_type": "bca_klikbca",
  "transaction_time": "2016-06-19 15:53:25",
  "transaction_status": "pending",
  "approval_code": "YCB62E160704",
  "signature_key": "d4ae557ea12a03eed51714693b84e48665af5289bc53df9bae0fda7e3c6b6c03fd0b00bf1978d1932d9c718c5bb27bf1148e85401221df45daf4472a3b8ef30e",
}

Klikbca Settlement notification

{
  "status_code": "200",
  "status_message": "Veritrans payment notification",
  "transaction_id": "c0ba3583-5111-45a5-9f1c-84c9de7cb2f6",
  "order_id": "3176440",
  "gross_amount": "50000.00",
  "payment_type": "bca_klikbca",
  "transaction_time": "2016-06-19 15:58:15",
  "transaction_status": "settlement",
  "approval_code": "YCRHOM160704",
  "signature_key": "ef0f472fa8a5165dc9f2ff6300832eb28657e88b9f3335ae5ebb27c8ef258d203c6da18ac6cd5738d2e38c54dfec860d8e067bdbc759a1268ab04218ccab93cc",
}

Klikbca Expired notification

{
  "status_code": "202",
  "status_message": "Veritrans payment notification",
  "transaction_id": "c0ba3583-5111-45a5-9f1c-84c9de7cb2f6",
  "order_id": "3176440",
  "gross_amount": "50000.00",
  "payment_type": "bca_klikbca",
  "transaction_time": "2016-06-19 17:53:25",
  "transaction_status": "expire",
  "approval_code": "3176440",
  "signature_key": "17b0e97425a3e967b91fccab2261f7b26ce8fc79612bf1ea700b503f8a812213d51d171045c084b29ca2d56db69a2ff3fed813ca1ff8f3377baafcf005bdb6bf"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status of Klikbca transaction, the possible value is
pending
status_code String Status code of transaction charge result
status_message String Description of transaction charge result
redirect_url String Redirect URL to Klikbca payment page
approval_code String Successful Klikbca transaction approval code

Mandiri Clickpay

Mandiri Clickpay Charge

{
  "payment_type": "mandiri_clickpay",
  "mandiri_clickpay": {
    "card_number": "4111111111111111",
    "input1": "1111111111",
    "input2": "145000",
    "input3": "54321",
    "token": "000000"
  },
  "item_details": [
    {
      "id": "1",
      "price": 11000,
      "quantity": 1,
      "name": "Mobil "
    }
  ],
  "transaction_details": {
    "order_id": "E17550",
    "gross_amount": 11000
  },
  "customer_details": {
    "first_name": "Andri",
    "last_name": "Litani",
    "email": "andri@litani.com",
    "phone": "081122334455"
  }
}

Mandiri ClickPay is one of the internet banking payment method that is provided by Mandiri Bank. This method allows customer to perform transaction by filling in his 16 digits Mandiri Debit Card number and Mandiri PIN Token to validate transaction.

Integration steps:

  1. Merchant send charge request to Midtrans.
  2. Handle notification.

Following attributes are required to charge Mandiri Clickpay:

JSON Attribute Type Description
payment_type String Set Mandiri Clickpay payment method. Value: mandiri_clickpay
transaction_details Object Details of the transaction will be paid by customer
mandiri_clickpay Object Charge details using Mandiri Clikcpay

Symbol Meaning
card_number Mandiri Debit card number
input1 Last 10 digit of card_number
input2 Transaction's gross_amount
input3 5-digits random number given to the customer
token Number received by customer's physical token after input1, input2, input2 are entered.
item_details Object Shopping item details will be paid by customer
customer_details Object Customer data who makes the purchase

Mandiri Clickpay Charge Response and notification

Mandiri Clickpay Charge Response

{
    "status_code": "200",
    "status_message": "Success, Mandiri Clickpay transaction is successful",
    "transaction_id": "3bdddabe-a4ea-4233-81cc-09578178909f",
    "order_id": "100248319",
    "gross_amount": "156216.00",
    "payment_type": "mandiri_clickpay",
    "transaction_time": "2016-06-19 15:56:45",
    "transaction_status": "settlement",
    "fraud_status": "accept",
    "approval_code": "166JF5644001",
    "masked_card": "461699-9495"
}

Mandiri Clickpay Settlement notification

{
  "approval_code": "166JF5644001",
  "masked_card": "461699-9495",
  "transaction_time": "2016-06-19 15:56:45",
  "gross_amount": "156216.00",
  "order_id": "100248319",
  "payment_type": "mandiri_clickpay",
  "signature_key": "1e5d08e7f53cf0d4d07c85ad807fc091e59f579807b5a2e9728cb8d9ab11431d61673450944ef3fa7a87d7d2dbce8e90dc96012fc9950e3eb2d52521d5120a57",
  "status_code": "200",
  "transaction_id": "3bdddabe-a4ea-4233-81cc-09578178909f",
  "transaction_status": "settlement",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}

Mandiri Clickpay Deny notification

{
  "masked_card": "461699-9495",
  "transaction_time": "2016-06-19 15:56:45",
  "gross_amount": "156216.00",
  "order_id": "100248319",
  "payment_type": "mandiri_clickpay",
  "signature_key": "c2bdfd8d1b25100f5512b2573ecad8f2d324837a731362491b5a6b0bbd7ec74a032010754129f4c74f77a21796f747258ea611a3d5710648f63342570cdd0bb4",
  "status_code": "202",
  "transaction_id": "3bdddabe-a4ea-4233-81cc-09578178909f",
  "transaction_status": "deny",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status of Mandiri Clickpay transaction, the possible value is
settlement for successful transaction or deny for failed transaction
status_code String Status code of transaction charge result
status_message String Description of transaction charge result
fraud_status String Detection result by Fraud Detection System (FDS). Possible Value:
accept : Approved by FDS.
challenge: Questioned by FDS. NOTE: Approve transaction to accept it or transaction will auto cancel during settlement.
deny: Denied by FDS. Transaction automatically failed
masked_card String Masked card number for Mandiri debit card used by customer
approval_code String Successful Mandiri Clickpay transaction approval code

Epay BRI

Epay BRI Charge

{
  "payment_type": "bri_epay",
  "transaction_details": {
    "order_id": "2014111702",
    "gross_amount": 11000
  },
  "item_details": [
    {
      "id": "1",
      "price": 11000,
      "quantity": 1,
      "name": "Mobil "
    }
  ],
  "customer_details" : {
    "first_name": "Andri",
    "last_name": "Litani", // Optional
    "email": "andri@litani.com",
    "phone": "081122334455"
  }
}

e-Pay BRI is one of the internet banking payment method that is provided by BRI Bank. This method allows customer to perform transaction by redirecting the customer to the e-Pay BRI payment page.

Integration steps:

  1. Merchant send charge request to Midtrans.
  2. Do redirection to address specified in the response.
  3. Handle notification.

Following attributes are required to charge Epay BRI:

JSON Attribute Type Description
payment_type String Set Epay BRI payment method. Value: bri_epay
transaction_details Object Details of the transaction will be paid by customer
item_details Object Shopping item details will be paid by customer
customer_details Object Customer data who makes the purchase

Epay BRI Charge Response and notification

Epay BRI Charge Response

{
    "status_code": "201",
    "status_message": "Success, BRI E-Pay transaction is successful",
    "transaction_id": "f8635cd7-615d-4a6d-a806-c9ca4a56257e",
    "order_id": "2014111702",
    "redirect_url": "https://api.veritrans.co.id/v3/bri/epay/redirect/f8635cd7-615d-4a6d-a806-c9ca4a56257e",
    "gross_amount": "145000.00",
    "payment_type": "bri_epay",
    "transaction_time": "2016-06-19 16:00:05",
    "transaction_status": "pending",
    "fraud_status": "accept"
}

Epay BRI Pending notification

{
  "transaction_time": "2016-06-19 16:00:05",
  "gross_amount": "145000.00",
  "order_id": "2014111702",
  "payment_type": "bri_epay",
  "signature_key": "2ea1c4b7d7a41700848bbd248b85dd933e9fdff1f4d69fefa8eefac2bf92ac8a78dbc40a78b5d77315b704150bca14fcb76a4c770336295c63369c592787a03f",
  "status_code": "201",
  "transaction_id": "f8635cd7-615d-4a6d-a806-c9ca4a56257e",
  "transaction_status": "pending",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}

Epay BRI Settlement notification

{
  "approval_code": "201373311528",
  "transaction_time": "2016-06-19 16:04:02",
  "gross_amount": "145000.00",
  "order_id": "2014111702",
  "payment_type": "bri_epay",
  "signature_key": "13b6b8a2da46428812e7685463770e3704ece7fc3242a5f016f068b7b135e12a71afd02259fe4dbd8c97d747ae9cf8e13412842325ea8da4cf6d7177e32b7e31",
  "status_code": "200",
  "transaction_id": "f8635cd7-615d-4a6d-a806-c9ca4a56257e",
  "transaction_status": "settlement",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}

Epay BRI Deny notification

{
  "transaction_time": "2016-06-19 16:04:02",
  "gross_amount": "145000.00",
  "order_id": "2014111702",
  "payment_type": "bri_epay",
  "signature_key": "6f4c3f00e391e2a97199ace0c243419b12c58eb9ec698600c25f8e9103573ef5258460484d64d742a4cd221cef33b57e23c1a31efa2480e1490d89163b8079bc",
  "status_code": "202",
  "transaction_id": "f8635cd7-615d-4a6d-a806-c9ca4a56257e",
  "transaction_status": "deny",
  "fraud_status": "accept",
  "status_message": "Veritrans payment notification"
}

Epay BRI Expired notification

{
  "status_code": "202",
  "status_message": "Veritrans payment notification",
  "transaction_id": "f8635cd7-615d-4a6d-a806-c9ca4a56257e",
  "order_id": "2014111702",
  "gross_amount": "145000.00",
  "payment_type": "bri_epay",
  "transaction_time": "2016-06-19 18:00:05",
  "transaction_status": "expire",
  "signature_key": "75969ac3cd1538b860ddb49fce06084eae991093d6d7c4fb653efd0beb19b0f31b3e9c9568f1c1eae3deb988b379a2d7fb5dbf0099190d1a241fc07f4e4a82ed",
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status of Epay BRI transaction, the possible value is
pending
fraud_status String Detection result by Fraud Detection System (FDS). Possible Value:
accept : Approved by FDS.
challenge: Questioned by FDS. NOTE: Approve transaction to accept it or transaction will auto cancel during settlement.
deny: Denied by FDS. Transaction automatically failed
status_code String Status code of transaction charge result
status_message String Description of transaction charge result
redirect_url String Redirect URL to Epay BRI payment page

CIMB Clicks

{
  "payment_type": "cimb_clicks",
  "cimb_clicks": {
    "description": "Purchase of a special event item"   //Description of the purchase
  },
  "item_details": [
    {
      "id": "1",
      "price": 11000,
      "quantity": 1,
      "name": "Mobil "
    }
  ],
  "transaction_details": {
    "order_id": "H17550",
    "gross_amount": 11000
  },
  "customer_details" : {
    "first_name": "Andri",
    "last_name": "Litani",
    "email": "andri@litani.com",
    "phone": "081122334455"
  }
}

CIMB Clicks is one of the internet banking payment methods that is provided by CIMB Niaga Bank. This method allows the customer to perform a transaction by redirecting the customer to the CIMB Clicks payment page.

Integration steps:

  1. Merchant send charge request to Midtrans.
  2. Do redirection to address specified in the response.
  3. Handle notification.

Following attributes are required to charge CIMB Clicks:

JSON Attribute Type Description
payment_type String Set CIMB Clicks payment method. Value: cimb_clicks
transaction_details Object Details of the transaction will be paid by customer
cimb_clicks Object Charge details using CIMB Clicks
item_details Object Shopping item details will be paid by customer
customer_details Object Customer data who makes the purchase

CIMB Clicks Charge Response and Notifications

CIMB Clicks Charge Response

{
  "status_code": "201",
  "status_message": "Success, CIMB Clicks transaction is successful",
  "redirect_url": "https://api.midtrans.com/cimb-clicks/request?id=226f042f-020e-4829-8bd7-2de64b8673ce",
  "transaction_id": "226f042f-020e-4829-8bd7-2de64b8673ce",
  "order_id": "1000156414164125",
  "gross_amount": "392127.00",
  "payment_type": "cimb_clicks",
  "transaction_time": "2016-06-19 16:41:25",
  "transaction_status": "pending"
}

CIMB Clicks Pending notification

{
  "status_code": "201",
  "status_message": "Veritrans payment notification",
  "transaction_id": "226f042f-020e-4829-8bd7-2de64b8673ce",
  "order_id": "1000156414164125",
  "gross_amount": "392127.00",
  "payment_type": "cimb_clicks",
  "transaction_time": "2016-06-19 16:41:25",
  "transaction_status": "pending",
  "signature_key": "666617ddc981eb096b6f08ab8ee132b93c12d3b5b3817f00a02c5d4c71bd53fd7f39d55a92b2a1f729ee070fdb241b569dc90bfa61e41de16904075238d67d55",
}

CIMB Clicks Settlement notification

{
  "status_code": "200",
  "status_message": "Veritrans payment notification",
  "transaction_id": "226f042f-020e-4829-8bd7-2de64b8673ce",
  "order_id": "1000156414164125",
  "gross_amount": "392127.00",
  "payment_type": "cimb_clicks",
  "transaction_time": "2016-06-19 16:45:21",
  "transaction_status": "settlement",
  "approval_code": "RB5031388093",
  "signature_key": "3bcdf0700d3c8a288f279e4fe27a4012e916cb44120d541f6e4c48c83a107b605fdb063ae7c8744d15891047aeb1fc8d2e95741c0abc5f67e10e0b60244bc441"
}

CIMB Clicks Deny notification

{
  "status_code": "202",
  "status_message": "Veritrans payment notification",
  "transaction_id": "226f042f-020e-4829-8bd7-2de64b8673ce",
  "order_id": "1000156414164125",
  "gross_amount": "392127.00",
  "payment_type": "cimb_clicks",
  "transaction_time": "2016-06-19 16:44:21",
  "transaction_status": "deny",
  "signature_key": "b736864661f8cbf04b287ee5a9514589dbe2dc53e3949338d648144b6bad1bc77d1b495921f119e7a6bf5521b697ea5d629b5ea93f2bcda4ff13df744cfbf701"
}

CIMB Clicks Expired notification

{
  "status_code": "202",
  "status_message": "Veritrans payment notification",
  "transaction_id": "226f042f-020e-4829-8bd7-2de64b8673ce",
  "order_id": "1000156414164125",
  "gross_amount": "392127.00",
  "payment_type": "cimb_clicks",
  "transaction_time": "2016-06-19 18:41:25",
  "transaction_status": "expire",
  "signature_key": "3f1ddaf45b269df7a1638d6d4080957e1323df2cbc2da83549f86a23b17c2acae0215994bb60805455daf157125990414259e5319e84c9288fd6222e655c6756"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status of CIMB Clicks transaction, the possible value is
pending
status_code String Status code of transaction charge result
status_message String Description of transaction charge result
redirect_url String Redirect URL to CIMB Clicks payment page

Danamon Online Banking

{
  "payment_type": "danamon_online",
  "item_details": [
    {
      "id": "1",
      "price": 11000,
      "quantity": 1,
      "name": "Mobil "
    }
  ],
  "transaction_details": {
    "order_id": "H17550",
    "gross_amount": 11000
  },
  "customer_details" : {
    "first_name": "Andri",
    "last_name": "Litani",
    "email": "andri@litani.com",
    "phone": "081122334455"
  }
}

Danamon Online Banking (DOB) is one of the internet banking payment methods that is provided by Danamon Bank. This method allows the customer to perform a transaction by redirecting the customer to the DOB payment page.

Integration steps:

  1. Merchant send charge request to Midtrans.
  2. Do redirection to address specified in the response.
  3. Handle notification.

Following attributes are required to charge DOB:

JSON Attribute Type Description
payment_type String Set DOB payment method. Value: danamon_online
transaction_details Object Details of the transaction will be paid by customer
item_details Object Shopping item details will be paid by customer
customer_details Object Customer data who makes the purchase

DOB Charge Response and Notifications

DOB Charge Response

{
  "status_code": "201",
  "status_message": "Success, Danamon Online transaction is successful",
  "redirect_url": "https://api.midtrans.com/cimb-clicks/request?id=226f042f-020e-4829-8bd7-2de64b8673ce",
  "transaction_id": "226f042f-020e-4829-8bd7-2de64b8673ce",
  "order_id": "1000156414164125",
  "gross_amount": "392127.00",
  "payment_type": "danamon_online",
  "transaction_time": "2016-06-19 16:41:25",
  "transaction_status": "pending"
}

DOB Pending notification

{
  "status_code": "201",
  "status_message": "Veritrans payment notification",
  "transaction_id": "226f042f-020e-4829-8bd7-2de64b8673ce",
  "order_id": "1000156414164125",
  "gross_amount": "392127.00",
  "payment_type": "danamon_online",
  "transaction_time": "2016-06-19 16:41:25",
  "transaction_status": "pending",
  "signature_key": "666617ddc981eb096b6f08ab8ee132b93c12d3b5b3817f00a02c5d4c71bd53fd7f39d55a92b2a1f729ee070fdb241b569dc90bfa61e41de16904075238d67d55",
}

DOB Settlement notification

{
  "status_code": "200",
  "status_message": "Veritrans payment notification",
  "transaction_id": "226f042f-020e-4829-8bd7-2de64b8673ce",
  "order_id": "1000156414164125",
  "gross_amount": "392127.00",
  "payment_type": "danamon_online",
  "transaction_time": "2016-06-19 16:45:21",
  "transaction_status": "settlement",
  "approval_code": "RB5031388093",
  "signature_key": "3bcdf0700d3c8a288f279e4fe27a4012e916cb44120d541f6e4c48c83a107b605fdb063ae7c8744d15891047aeb1fc8d2e95741c0abc5f67e10e0b60244bc441"
}

DOB Deny notification

{
  "status_code": "202",
  "status_message": "Veritrans payment notification",
  "transaction_id": "226f042f-020e-4829-8bd7-2de64b8673ce",
  "order_id": "1000156414164125",
  "gross_amount": "392127.00",
  "payment_type": "danamon_online",
  "transaction_time": "2016-06-19 16:44:21",
  "transaction_status": "deny",
  "signature_key": "b736864661f8cbf04b287ee5a9514589dbe2dc53e3949338d648144b6bad1bc77d1b495921f119e7a6bf5521b697ea5d629b5ea93f2bcda4ff13df744cfbf701"
}

DOB Expired notification

{
  "status_code": "202",
  "status_message": "Veritrans payment notification",
  "transaction_id": "226f042f-020e-4829-8bd7-2de64b8673ce",
  "order_id": "1000156414164125",
  "gross_amount": "392127.00",
  "payment_type": "danamon_online",
  "transaction_time": "2016-06-19 18:41:25",
  "transaction_status": "expire",
  "signature_key": "3f1ddaf45b269df7a1638d6d4080957e1323df2cbc2da83549f86a23b17c2acae0215994bb60805455daf157125990414259e5319e84c9288fd6222e655c6756"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status of DOB transaction, the possible value is
pending
status_code String Status code of transaction charge result
status_message String Description of transaction charge result
redirect_url String Redirect URL to DOB payment page

E-wallet

One of the payment method offered by Midtrans is e-Wallet. By using this e-Wallet, customer will have an option to make a payment via e-Wallet and Midtrans will send real time notification when the customer complete the payment.

At this moment, Midtrans has integrated with 4 different e-Wallet payment methods:

Telkomsel Cash

{
  "customer_details": {
    "first_name": "Budi",
    "phone": "0812332423",
    "email": "budi.utomo@midtrans.com",
    "last_name": "Utomo"
  },
  "item_details": [
    {
      "id": "2964101",
      "price": 25000,
      "name": "Telkomsel REG 25000",
      "quantity": 1
    }
  ],
  "transaction_details": {
    "gross_amount": 25000,
    "order_id": "order01"
  },
  "telkomsel_cash": {
    "promo": false,
    "is_reversal": 0,
    "customer": "9932710273"
  },
  "payment_type": "telkomsel_cash"
}

Telkomsel Cash (T-CASH) is a service of electronic money (E-money) which makes it easy for you to perform financial transaction via mobile phone. This method allows customer to perform transaction by filling in his 10 digits token obtained from Telkomsel as validation of transactions.

Integration steps:

  1. Merchant send charge request to Midtrans.
  2. Do redirection to address specified in the response.
  3. Handle notification.

Following attributes are required to charge Telkomsel Cash:

JSON Attribute Type Description
payment_type String Set Telkomsel Cash payment method. Value: telkomsel_cash
transaction_details Object Details of the transaction will be paid by customer
telkomsel_cash Object Charge details using telkomsel cash
item_details Object Shopping item details will be paid by customer
customer_details Object Customer data who makes the purchase

Telkomsel Cash Charge Response and notification

Telkomsel Cash Charge Response

{
  "status_code": "200",
  "status_message": "Success, T-Cash transaction is successful",
  "transaction_id": "0528d852-76be-466a-993e-787241cc5d90",
  "order_id": "order01",
  "gross_amount": "25000.00",
  "payment_type": "telkomsel_cash",
  "transaction_time": "2016-06-19 16:08:09",
  "transaction_status": "settlement"
}

Telkomsel Cash Charge notification

{
  "status_code": "200",
  "status_message": "Veritrans payment notification",
  "transaction_id": "0528d852-76be-466a-993e-787241cc5d90",
  "order_id": "order01",
  "gross_amount": "25000.00",
  "payment_type": "telkomsel_cash",
  "transaction_time": "2016-06-19 16:08:09",
  "transaction_status": "settlement",
  "signature_key": "e1f0e8b349c171a191bd075ba30305c49a6ad930efd3e0bf5fee6ba8ddd67d7fbaad79cca9766895730c462f19bbe456c805fca68854e350a6ab385669f3959d"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status of Telkomsel Cash transaction, the possible value is
settlement for successful transaction or deny for failed transaction
status_code String Status code of transaction charge result
status_message String Description of transaction charge result

XL Tunai

{
  "payment_type": "xl_tunai",
  "transaction_details": {
    "order_id": "order02",
    "gross_amount": 90000
  },
  "item_details": [
    {
      "id": "1",
      "price": 90000,
      "quantity": 1,
      "name": "barang "
    }
  ],
  "customer_details" : {
    "first_name": "Andri",
    "last_name": "Litani",
    "email": "andri@litani.com",
    "phone": "081122334455"
  }
}

XL Tunai is an electronic money (E-money) from XL, that allows customers of XL perform financial transaction via mobile phone. This method allows customer to perform transaction by filling in specific number obtained from Midtrans as validation of transactions.

Integration steps:

  1. Merchant send charge request to Midtrans.
  2. Display ID and Order ID to the customer
  3. Handle notification.

Following attributes are required to charge XL Tunai:

JSON Attribute Type Description
payment_type String Set XL Tunai payment method. Value: xl_tunai
transaction_details Object Details of the transaction will be paid by customer
item_details Object Shopping item details will be paid by customer
customer_details Object Customer data who makes the purchase

XL Tunai Charge Response and notification

XL Tunai Charge Response

{
  "status_code": "201",
  "status_message": "Success, XL Tunai transaction is successful",
  "transaction_id": "796b1ae6-cfc3-4f01-85ed-c5feb898d898",
  "order_id": "order02",
  "gross_amount": "90000.00",
  "payment_type": "xl_tunai",
  "transaction_time": "2015-12-22 18:23:53",
  "transaction_status": "pending",
  "xl_tunai_order_id": "00314",
  "xl_tunai_merchant_id": "1211626"
}

XL Tunai Pending notification

{
  "status_code": "201",
  "status_message": "Veritrans payment notification",
  "transaction_id": "796b1ae6-cfc3-4f01-85ed-c5feb898d898",
  "order_id": "order02",
  "payment_type": "xl_tunai",
  "transaction_time": "2015-12-22 18:23:53",
  "transaction_status": "pending",
  "signature_key": "ac9d80e274499386400244bd3737ec0a378b05ccb2b1c0a244becdf1c74b9139cf1172c39d28025e9730f21ddb065388a9008164d717b13f76a95aee1c467aef",
  "gross_amount": "90000.00",
  "xl_tunai_order_id": "00314",
  "xl_tunai_merchant_id": "1211626"
}

XL Tunai Settlement notification

{
  "status_code": "200",
  "status_message": "Veritrans payment notification",
  "transaction_id": "796b1ae6-cfc3-4f01-85ed-c5feb898d898",
  "order_id": "order02",
  "payment_type": "xl_tunai",
  "transaction_time": "2015-12-22 18:24:44",
  "transaction_status": "settlement",
  "signature_key": "ac9d80e274499386400244bd3737ec0a378b05ccb2b1c0a244becdf1c74b9139cf1172c39d28025e9730f21ddb065388a9008164d717b13f76a95aee1c467aef",
  "gross_amount": "90000.00"
}

XL Tunai Expired notification

{
  "status_code": "202",
  "status_message": "Veritrans payment notification",
  "transaction_id": "796b1ae6-cfc3-4f01-85ed-c5feb898d898",
  "order_id": "order02",
  "payment_type": "xl_tunai",
  "transaction_time": "2015-12-23 18:23:52",
  "transaction_status": "expired",
  "signature_key": "ac9d80e274499386400244bd3737ec0a378b05ccb2b1c0a244becdf1c74b9139cf1172c39d28025e9730f21ddb065388a9008164d717b13f76a95aee1c467aef",
  "gross_amount": "90000.00"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status of XL Tunai transaction, the possible value is
pending
status_code String Status code of transaction charge result
status_message String Description of transaction charge result
xl_tunai_order_id String The transaction order ID paid by XL Tunai
xl_tunai_merchant_id String ID of the merchant which receive XL Tunai payment

Indosat Dompetku

Indosat Dompetku Charge

{
    "payment_type":
        "indosat_dompetku",
    "transaction_details": {
        "order_id": "1388",
        "gross_amount": 100000
        },
    "item_details": [ {
        "id": "1388",
        "price": 100000,
        "quantity": 1,
        "name": "Mie Ayam Original"
    } ],
    "customer_details": {
        "email": "obet.supriadi@gmail.com",
        "first_name": "Obet",
        "last_name": "Supriadi",
        "phone": "081311874839"
        },
    "indosat_dompetku": {
        "msisdn": "08123456789"
    }
}

Indosat Dompetku is an electronic money (E-money) from Indosat, that allows Indosat customers to pay online transactions via mobile phone. This method needs the customer to perform transaction by filling their indosat phone number as validation of transactions. Prior using Indosat dompetku as online payment method, the customer needs to register Indosat Dompetku account using their mobile phone and do top up.

Integration steps:

  1. Merchant send charge request to Midtrans.
  2. Handle notification.

Following attributes are required to charge Indosat Dompetku:

JSON Attribute Type Description
payment_type String Set Indosat Dompetku payment method. Value: indosat_dompetku
transaction_details Object Details of the transaction will be paid by customer
indosat_dompetku Object Charge details using Indosat Dompetku
item_details Object Shopping item details will be paid by customer
customer_details Object Customer data who makes the purchase

Indosat Dompetku Charge Response and Notifications

Indosat Dompetku Charge Response

{
    "status_code": "200",
    "status_message": "Success, Indosat Dompetku transaction is successful",
    "transaction_id": "01b33f31-3433-42df-b850-95dbc594c734",
    "order_id": "1432869511",
    "payment_type": "indosat_dompetku",
    "transaction_time": "2015-06-23 14:00:19",
    "transaction_status": "settlement",
    "gross_amount": "60000.00"
}

Indosat Dompetku Settlement Notifications

{
    "status_code": "200",
    "status_message": "Success, Indosat Dompetku transaction is successful",
    "transaction_id": "01b33f31-3433-42df-b850-95dbc594c734",
    "order_id": "1432869511",
    "payment_type": "indosat_dompetku",
    "transaction_time": "2015-06-23 14:00:19",
    "transaction_status": "settlement",
    "gross_amount": "60000.00"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status of Indosat Dompetku transaction, the possible value is
settlement for successful transaction or deny for failed transaction
status_code String Status code of transaction charge result
status_message String Description of transaction charge result

Mandiri E-cash

Mandiri E-cash Charge

{
  "payment_type": "mandiri_ecash",
  "mandiri_ecash": {
    "description": "Transaction Description"
  },
  "transaction_details": {
    "order_id": "order03",
    "gross_amount": 275000
  },
  "item_details": [
    {
      "id": "id1",
      "price": 275000,
      "quantity": 1,
      "name": "Bluedio H+ Turbine Headphone with Bluetooth 4.1 -",
      "store_id": 380,
      "store_name": "toko1"
    }
  ],
  "customer_details": {
    "first_name": "Budi",
    "last_name": "Utomo",
    "email": "budi.utomo@midtrans.com",
    "phone": "081223323423"
    }
  }
}

Mandiri E-cash is one of the e-wallet online payment method that is provided by Mandiri Bank. This method allows customer to perform online transaction by redirecting the customer to the Mandiri E-cash payment page. Prior to pay with Mandiri E-cash, the customer has to register and top up the balance to the Mandiri E-cash account.

Integration steps:

  1. Merchant send charge request to Midtrans.
  2. Do redirection to address specified in the response.
  3. Handle notification.

Following attributes are required to charge Mandiri E-cash:

JSON Attribute Type Description
payment_type String Set Mandiri E-cash payment method. Value: mandiri_ecash
transaction_details Object Details of the transaction will be paid by customer
mandiri_ecash Object Charge details using Mandiri E-cash
item_details Object Shopping item details will be paid by customer
customer_details Object Customer data who makes the purchase

Mandiri E-cash Charge Request and Notifications

Mandiri E-cash Charge Request

{
  "status_code": "201",
  "status_message": "Success, Mandiri Ecash transaction is successful. Please go to redirect_url",
  "redirect_url": "https://mandiriecash.com/ecommgateway/payment.html?id=JONNWQ1TQVLNLZC3GXKNZU1G5L2NJACM",
  "transaction_id": "1c28dbbb-8596-48e4-85d7-9f1382db8a1f",
  "order_id": "order03",
  "gross_amount": "275000.00",
  "payment_type": "mandiri_ecash",
  "transaction_time": "2016-06-19 15:50:12",
  "transaction_status": "pending"
}

Mandiri E-cash Pending notification

{
  "status_code": "201",
  "status_message": "Veritrans payment notification",
  "transaction_id": "1c28dbbb-8596-48e4-85d7-9f1382db8a1f",
  "order_id": "order03",
  "gross_amount": "275000.00",
  "payment_type": "mandiri_ecash",
  "transaction_time": "2016-06-19 15:50:12",
  "transaction_status": "pending",
  "signature_key": "40747f7f8f489c423c8ed72879ca8cb28dcd0c03fc9a192138667c4588f91486ae46094a6695d9fddbce0abab8055fd483b65ecf59e3c43d4a22cc024326993a"
}

Mandiri E-cash Settlement notification

{
  "status_code": "200",
  "status_message": "Veritrans payment notification",
  "transaction_id": "1c28dbbb-8596-48e4-85d7-9f1382db8a1f",
  "order_id": "order03",
  "gross_amount": "275000.00",
  "payment_type": "mandiri_ecash",
  "transaction_time": "2016-06-19 15:54:42",
  "transaction_status": "settlement",
  "signature_key": "973d175e6368ad844b5817882489e6b22934d796a41a0573c066b1e64532dc0001087b87d877a3eac37cba20a733e1305f5e62739e65ff501d5d33c5ac62530f"
}

Mandiri E-cash Expired notification

{
  "status_code": "202",
  "status_message": "Veritrans payment notification",
  "transaction_id": "1c28dbbb-8596-48e4-85d7-9f1382db8a1f",
  "order_id": "order03",
  "gross_amount": "275000.00",
  "payment_type": "mandiri_ecash",
  "transaction_time": "2016-06-20 15:50:12",
  "transaction_status": "expire",
  "signature_key": "53c6e2e3639a6b5c09b9103aa343f00cfd0168c6a69a2d4f2203bdc58072531ad7b340ea01725538996a7827c4ce091fb94d0aa70778a20c69d3f9991e0f65eb"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status of Mandiri E-cash transaction, the possible value is
pending
status_code String Status code of transaction charge result
status_message String Description of transaction charge result
redirect_url String Redirect URL to Mandiri E-cash payment page

Convenience Store

Convenience Store payment method allow the customer to pay online transaction in convenience store. At this moment, Midtrans has integrated with 2 different convenience stores:

Indomaret

{
  "payment_type": "cstore",
  "transaction_details": {
    "gross_amount": 162500,
    "order_id": "order04"
  },
  "cstore": {
    "store": "Indomaret",
    "message": "Tiket1 transaction"
  },
  "customer_details": {
    "first_name": "Budi",
    "last_name": "Utomo",
    "email": "budi.utomo@midtrans.com",
    "phone": "0811223344"
  },
  "item_details": [
    {
      "id": "id1",
      "price": 162500,
      "quantity": 1,
      "name": "tiket1"
    }
  ]
}

Indomaret is a feature provided by Indomaret where customer can make online payment at indomaret store. The customer only has to come to indomaret cashier and complete the payment. By using this convenience store channel, customer can pay the bill in any indomaret store. Midtrans will send notification in real time for every incoming payment.

Integration steps:

  1. Merchant send charge request to Midtrans.
  2. Display the payment code to the customer.
  3. Handle notification.

Following attributes are required to charge Indomaret:

JSON Attribute Type Description
payment_type String Set Convenience Store payment method. Value: cstore
transaction_details Object Details of the transaction will be paid by customer
cstore Object Charge details using Convenience Store
item_details Object Shopping item details will be paid by customer
customer_details Object Customer data who makes the purchase

Convenience Store Indomaret Charge Response and Notification

Convenience Store Indomaret Charge Response

{
  "status_code": "201",
  "status_message": "Success, cstore transaction is successful",
  "transaction_id": "e3f0b1b5-1941-4ffb-9083-4ee5a96d878a",
  "order_id": "order04",
  "gross_amount": "162500.00",
  "payment_type": "cstore",
  "transaction_time": "2016-06-19 17:18:07",
  "transaction_status": "pending",
  "payment_code": "25709650945026"
}

Convenience Store Indomaret Pending Notifications

{
  "status_code": "201",
  "status_message": "Veritrans payment notification",
  "transaction_id": "e3f0b1b5-1941-4ffb-9083-4ee5a96d878a",
  "order_id": "order04",
  "gross_amount": "162500.00",
  "payment_type": "cstore",
  "transaction_time": "2016-06-19 17:18:07",
  "transaction_status": "pending",
  "signature_key": "2d488c1ff0adc2396ee9b9765807b6d53182a0aa17cd9bb251b99879099d4f727903a75440b1814539f565774f7a80de0a7336c81d2071b4d3efe92f15400e41",
  "payment_code": "25709650945026"
}

Convenience Store Indomaret Settlement Notifications

{
  "status_code": "200",
  "status_message": "Veritrans payment notification",
  "transaction_id": "991af93c-1049-4973-b38f-d6052c72e367",
  "order_id": "order04",
  "gross_amount": "162500.00",
  "payment_type": "cstore",
  "transaction_time": "2016-06-20 11:44:07",
  "transaction_status": "settlement",
  "approval_code": "59061607081045705101",
  "signature_key": "a198f93ac43cf98171dcb4bd0323c7e3afbee77a162a09e2381f0a218c761a4ef0254d7650602971735c486fea2e8e9c6d41ee65d6a53d65a12fb1c824e86f9f",
  "payment_code": "25709650945026"
}

Convenience Store Indomaret Expired Notifications

{
  "status_code": "202",
  "status_message": "Veritrans payment notification",
  "transaction_id": "fd70880f-3458-4b16-9f09-289924185977",
  "order_id": "order04",
  "gross_amount": "162500.00",
  "payment_type": "cstore",
  "transaction_time": "2016-06-20 17:18:08",
  "transaction_status": "expire",
  "signature_key": "c260504a448018b4c4831b381f8a8c5088c37f2706dcc60b4d7d99a16e0ae3c22bc8945cb5177742386bab1ddb12e7c175e1f57686b488e215406fa40fc75481",
  "payment_code": "25709650945026"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status of CIMB Clicks transaction, the possible value is
pending
status_code String Status code of transaction charge result
status_message String Description of transaction charge result
payment_code String Unique payment code for customer to complete the payment in Indomaret

Kioson

{
  "payment_type": "cstore",
  "transaction_details": {
    "gross_amount": 162500,
    "order_id": "order05"
  },
  "cstore": {
    "store": "kioson",
    "message": "Tiket2 transaction"
  },
  "customer_details": {
    "first_name": "Budi",
    "last_name": "Utomo",
    "email": "budi.utomo@midtrans.com",
    "phone": "0811223344"
  },
  "item_details": [
    {
      "id": "id1",
      "price": 162500,
      "quantity": 1,
      "name": "tiket2"
    }
  ]
}

Kioson is a feature provided by Kioson where customer can make online payment at kioson store. The customer only has to come to kioson cashier and complete the payment. By using this convenience store channel, customer can pay the bill in any kioson store. Midtrans will send notification in real time for every incoming payment.

Integration steps:

  1. Merchant send charge request to Midtrans.
  2. Display the payment code to the customer.
  3. Handle notification.

Following attributes are required to charge Kioson:

JSON Attribute Type Description
payment_type String Set Convenience Store payment method. Value: cstore
transaction_details Object Details of the transaction will be paid by customer
cstore Object Charge details using Convenience Store
item_details Object Shopping item details will be paid by customer
customer_details Object Customer data who makes the purchase

Convenience Store Kioson Charge Response

Convenience Store Kioson Charge Response

{
    "status_code": "201",
    "status_message": "Success, cstore transaction is successful",
    "transaction_id": "f1d381f8-7519-4139-b28f-81c6b3dc38ea",
    "order_id": "order05",
    "gross_amount": "10500.00",
    "payment_type": "cstore",
    "transaction_time": "2016-06-28 16:22:49",
    "transaction_status": "pending",
    "fraud_status": "accept",
    "payment_code": "010811223344"
}
JSON Attribute Type Description
transaction_id String Transaction ID given by Midtrans
order_id String Order Id given by merchant
gross_amount String Total amount of transaction
payment_type String Transaction payment method
transaction_time String Timestamp of transaction
transaction_status String Transaction status of CIMB Clicks transaction, the possible value is
pending
status_code String Status code of transaction charge result
status_message String Description of transaction charge result
payment_code String Unique payment code for customer to complete the payment in Indomaret
fraud_status String Detection result by Fraud Detection System (FDS). Possible Value:
accept : Approved by FDS.
challenge: Questioned by FDS. NOTE: Approve transaction to accept it or transaction will auto cancel during settlement.
deny: Denied by FDS. Transaction automatically failed

Handing Notifications

Signature key logic

SHA512(order_id+status_code+gross_amount+serverkey)

Sample code generate signature key

<?php
$orderId = "1111";
$statusCode = "200";
$grossAmount = "100000.00";
$serverKey = "askvnoibnosifnboseofinbofinfgbiufglnbfg";
$input = $orderId.$statusCode.$grossAmount.$serverKey;
$signature = openssl_digest($input, 'sha512');
echo "INPUT: " , $input."<br/>";
echo "SIGNATURE: " , $signature;
?>

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

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 get status API. The response is the same as the notification status.

challenge response

Signature Key

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. Please find on the side, the logic of the signature key and the sample code to generate signature key.

Best Practice to Handle notification

Following are the standard types of notifications. Note different types of notifications can be added in addition to the below. Also new fields may be added to the existing notification, please confirm with the latest documentation for the exact fields.

Status Code

Status Codes used by Midtrans API are categorized into 2xx, 3xx, 4xx dan 5xx.

Code 2xx

Status Description
200 Credit Card: Success. Request is successful, and transaction is authorize, capture, settlement, cancel, approve challenge transactions, accepted by Midtrans and bank.

Other payment methods: Success. Transaction is settlement, cancel
201 Credit Card: Challenge. Transaction successfully sent to bank but the process has not been completed, need manual action from merchant to complete the transaction process. If the merchant does not perform any action until settlement time (H+1 16:00) Midtrans will cancel the transaction.

Bank Transfer: Pending. Transaction successfully sent to bank but the process has not been completed by the customer. By default the transaction will expire within 24 hours.

Cimb Clicks: Pending. Transaction successfully sent to bank but the process has not been completed by the customer. By default the transaction will expire within 2 hours.

BRI ePay: Pending. Transaction successfully sent to bank but the process has not been completed by the customer. By default the transaction will expire within 2 hours.

Klik BCA: Pending. Transaction successfully sent to bank but the process has not been completed by the customer. By default the transaction will expire within 2 hours.

BCA Klikpay: Pending. Transaction successfully sent to bank but the process has not been completed by the customer. By default the transaction will expire within 2 hours.

Mandiri Bill Payment: Pending. Transaction successfully sent to bank but the process has not been completed by the customer. By default the transaction will expire within 2 hours.

XL Tunai: Pending. Transaction successfully sent to provider but the process has not been completed by the customer. By default the transaction will expire within 2 hours.

Indomaret: Pending. Transaction successfully sent to provider but the process has not been completed by the customer. By default the transaction will expire within 2 hours
202 Credit Card: Denied. Transaction has been processed but is denied by payment provider or Midtrans' fraud detection system.

Other payment methods: Denied. Transaction has been processed but is denied by payment provider

Code 3xx

Status Description
300 Move Permanently, current and all future requests should be directed to the new URL

Code 4xx

Status Description
400 Validation Error, merchant sent bad request data example; validation error, invalid transaction type, invalid credit card format, etc.
401 Access denied due to unauthorized transaction, please check client key or server key
402 Merchant doesn't have access for this payment type
403 The requested resource is only capable of generating content not acceptable according to the accepting headers that sent in the request
404 The requested resource/transaction is not found (eg. order_id is not exist)
405 Http method is not allowed
406 Duplicate order ID. Order ID has already been utilized previously
407 Expired transaction
408 Merchant sent the wrong data type
409 Merchant has sent too many transactions for the same card number
410 Merchant account is deactivated. Please contact Midtrans support
411 Token id is missing, invalid, or timed out
412 Merchant cannot modify status of the transaction
413 The request cannot be processed due to malformed syntax in the request body

Code 5xx

Status Description
500 Internal Server Error
501 The feature has not finished yet, it will be available soon
502 Internal Server Error: Bank Connection Problem
503 Internal Server Error
504 Internal Server Error: Fraud detection is unavailable

JSON Object

Collection of JSON objects that are used in API Methods

Transaction Details

"transaction_details": {
    "order_id": "A87551",
    "gross_amount": 145000
}
JSON Attribute Type Required Description
order_id String(50) Y Order id of the transaction
gross_amount Long Y Gross value of the transaction NOTE: Don't add decimal

Credit Card

"credit_card": {
    "token_id": "4811117d16c884-2cc7-4624-b0a8-10273b7f6cc8",
    "bank": "bni",
    "installment_term": 6,
    "bins": ["4811", "5233"],
    "type": "authorize",
    "save_token_id": true,
    "channel": "migs"
}
JSON Attribute Type Required Description
token_id String(255) Y Token id represents customer credit card information
bank String(255) N Acquiring bank. Valid values: mandiri, bni, cimb, bca, maybank, and bri
installment_term integer N installment_term
bins JSON Array N List of credit card's BIN (Bank Identification Number) that is allowed for transaction
type String (255) N Used on preauthorization feature. Valid value: authorize
save_token_id Boolean N Used on 'one click' or 'two clicks' feature. Enabling it will return a saved_token_id that can be used for the next transaction
channel String(255) N channel for credit card transaction. Valid value: "migs"

Item Details

"item_details": [{
    "id": "a1",
    "price": 50000,
    "quantity": 2,
    "name": "Apel",
    "brand": "Fuji Apple",
    "category": "Fruit",
    "merchant_name": "Fruit-store",
    "tenor": "12",
    "code_plan": "000",
    "mid": "123456"
  }]
JSON Attribute Type Required Description
id String(255) N Item ID
price Number Y Price of the item NOTE: Don't add decimal
quantity Number Y Quantity of the item bought
name String(50) Y Name of the item
brand String(50) N Brand of the item
category String(50) N Category of the item
merchant_name String(50) N Merchant name selling the item
tenor Numeric(2) C Installment term NOTE: BCA KlikPay exclusive field
code_plan Numeric(3) C Installment code, use 000 for default NOTE: BCA KlikPay exclusive field
mid Numeric(9) C Installment mid NOTE: BCA KlikPay exclusive field

Customer Details

"customer_details": {
  "first_name": "TEST",
  "last_name": "UTOMO",
  "email": "test@midtrans.com",
  "phone": "+628123456",
  "billing_address": {
    "first_name": "TEST",
    "last_name": "UTOMO",
    "phone": "081 2233 44-55",
    "address": "Sudirman",
    "city": "Jakarta",
    "postal_code": "12190",
    "country_code": "IDN"
  },
  "shipping_address": {
    "first_name": "TEST",
    "last_name": "UTOMO",
    "phone": "0 8128-75 7-9338",
    "address": "Sudirman",
    "city": "Jakarta",
    "postal_code": "12190",
    "country_code": "IDN"
  }
}
JSON Attribute Type Required Description
first_name String(20) N Customer's first name
last_name String(20) N Customers last name
email String(255) N Customer's email address
phone String(19) N Customer's phone address. Minimum length is 5. Only accepts numeric and symbols +,-,(space), and (). The + symbol can only be placed in front
billing_address N JSON Array Customer's billing address
shipping_address N JSON Array Customer's shipping address

Billing address

JSON Attribute Type Required Description
first_name String(20) N Customer's billing first name
last_name String(20) N Customers billing last name
phone String(19) N Customer's billing phone address. Minimum length is 5. Only accepts numeric and symbols +,-,(space), and (). The + symbol can only be placed in front
address String(200) N Detail address of the billing address
city String(100) N City of the billing address
postal_code String(10) N Postal code of the billing address. Note: Format is alpha-numeric. It can accept "-" and space
country_code String(3) N Country ID of the billing address. (e.g IDN) ISO 3166-1 alpha-3

Shipping address

JSON Attribute Type Required Description
first_name String(20) N Customer's shipping first name
last_name String(20) N Customers shipping last name
phone String(19) N Customer's shipping phone address. Minimum length is 5. Only accepts numeric and symbols +,-,(space), and (). The + symbol can only be placed in front
address String(200) N Detail address of the shipping address
city String(100) N City of the shipping address
postal_code String(10) N Postal code of the shipping address. Note: Format is alpha-numeric. It can accept "-" and space
country_code String(3) N Country ID of the shipping address. (e.g IDN) ISO 3166-1 alpha-3

Bank Transfer

"bank_transfer":{
  "bank": "bca",
  "va_number": "111111",
  "free_text": {
       "inquiry": [
             {
                 "id": "Free Text ID Free Text ID Free Text ID",
                 "en": "Free Text EN Free Text EN Free Text EN"
             }
       ],
       "payment": [
             {
                 "id": "Free Text ID Free Text ID Free Text ID",
                 "en": "Free Text EN Free Text EN Free Text EN"
             }
       ]
 }
}
JSON Attribute Type Required Description
bank String(255) Y Bank name which process bank transfer transaction. Valid value is permata, bii, and bca
va_number String(255) N Custom va number assigned by merchant. Currently working for BCA VA only
free_text JSON Array N list of free texts NOTE: BCA VA only
JSON Attribute Type Required Description
inquiry JSON Array(10) N Free texts shown during inquiry
payment JSON Array(10) N Free texts shown during payment
JSON Attribute Type Required Description
id String(50) Y Free text message in Bahasa Indonesia
en String(50) Y Free text message in English

Echannel

"echannel" : {
    "bill_info1" : "Payment For:",
    "bill_info2" : "Tuition fee",
    "bill_info3" : "Name:",
    "bill_info4" : "Budi Utomo",
    "bill_info5" : "Class:",
    "bill_info6" : "Computer Science",
    "bill_info7" : "ID:",
    "bill_info8" : "VT-12345"
}
JSON Attribute Type Required Description
bill_info1 String(20) Y Label 1
bill_info2 String(20) Y Value for Label 1
bill_info3 String(20) N Label 2
bill_info4 String(20) N Value for Label 2
bill_info5 String(20) N Label 3
bill_info6 String(20) N Value for Label 3
bill_info7 String(20) N Label 4
bill_info8 String(20) N Value for Label 4

VA Number

"va_numbers": [
  {
    "bank": "bca",
    "va_number": "91019021579"
  }
]
JSON Attribute Type Required Description
bank String(255) Y Bank name which process bank transfer transaction. Valid value is permata, bii, and bca
va_number String(255) Y Virtual account number generated

Mandiri ClickPay

"mandiri_clickpay": {
  "card_number": "4617007700000039",
  "input1": "7700000039",
  "input2": "10000",
  "input3": "00000",
  "token": "000000"
}
JSON Attribute Type Required Description
card_number String(16) Y Card number registered for Mandiri ClickPay
input1 String(10) Y Last 10 digits of the card_number
input2 String Y Equivalent with the transaction amount
input3 String(5) Y Unique user generated id
token String(6) Y Token generated from Mandiri ClickPay APPLI 3 token based on input1, input2, input3

BCA Klikpay

"bca_klikpay": {
  "description": "Pembelian Barang"
}
JSON Attribute Type Required Description
description String(60) Y BCA Klikpay transaction description
misc_fee Long N Additional fee for documentation

BCA Klikbca

"bca_klikbca" : {
  "description" : "3176440",
  "user_id" : "midtrans1012"
}
JSON Attribute Type Required Description
description String(60) Y Klikbca transaction description
user_id String(12) Y Klikbca User ID

CIMB Clicks

"cimb_clicks": {
    "description": "Purchase of a special event item"   //Description of the purchase
}
JSON Attribute Type Required Description
description String(100) Y CIMB Clicks transaction description

Telkomsel Cash

"telkomsel_cash": {
    "customer": "0811111111",
    "promo": false,
    "is_reversal": 0
}
JSON Attribute Type Required Description
customer String(10) Y Telkomsel Cash token
promo Boolean N Flag to enable promo. Value is false
is_reversal Short N Reversal value. Value is 0

Mandiri E-cash

"mandiri_ecash": {
  "description": "Mandiri E-cash Transaction Description"
}
JSON Attribute Type Required Description
description String(255) Y Mandiri E-cash transaction description

Convenience Store

"cstore" : {
   "store" : "indomaret",
   "message" : "mangga"
}
JSON Attribute Type Required Description
store String(20) Y Store name
message String(20) N Label to be displayed in Indomaret POS

Transaction Status

Transaction Status used by Midtrans API.

Status Description Possible change(s)
authorize Transaction authorizes the credit card. Must be captured to process the balance. Note: Credit Card only capture, cancel
capture Transaction captures the credit card balance. Will be settled as batch. settlement, cancel
settlement Transaction is settled. refund, chargeback, partial_refund, partial_chargeback
deny Payment provider rejects the credentials used for payment. See status_message for deny details. N/A
pending Transaction is made available in Midtrans to be paid. settlement, deny, cancel, expire
cancel Transaction is cancelled. Can be triggered by Midtrans or partner themselves. N/A
refund Transaction is marked to be refunded. settlement
partial_refund Transaction is marked to be partially refunded. settlement
chargeback Transaction is marked to be charged back. Note: Credit Card only settlement
partial_chargeback Transaction is marked to be partially charged back. settlement
expire Transaction no longer available to be paid or processed N/A
failure Unexpected error during transaction processing N/A

Fraud Status

Fraud Status used by Midtrans API.

Status Description
accept Transaction is not considered as fraud.
deny Transaction is considered as fraud.
challenge We cannot determine the transaction. Merchant should take action to accept or deny.

API changelog

Version 2.24.12

June 8, 2017

Version 2.24.10

May 24, 2017

Version 2.24.2

April 6, 2017

Version 2.23.1

March 9, 2017

Version 2.21.10

January 13, 2017

Version 2.21.3

December 6, 2016

Version 2.10.0

November 23, 2016

Version 2.9.10

October 28, 2016

Version 2.9.9

October 25, 2016

Version 2.9.7

October 19, 2016

Added Changelog for Midtrans API

Deprecation Notices

December 1, 2016

We are going to prohibit the use of decimal gross_amount starting 15th January 2017. Below are the examples of valid and invalid parameters.

Example:

Invalid gross_amount will be rejected with 400 (validation error) status code.

Please switch to using the new hostnames and URL's immediately to avoid failures.