NAV
←
API Reference
shell php javascript python go

Introduction

Welcome to Midtrans API!

Midtrans API is a RESTful Web Service that acts as a communication bridge between you and Midtrans's payment channels. It helps you to easily accept payments, disburse funds, manage subscriptions, and much more in automated manner. You can choose to integrate with a wide variety of payment options provided by Midtrans. Our highly generic API is structured for all the payment methods. You just need to change the payment method and add the payment specific parameters to integrate with different payment methods.

You can test the payment integration using Midtrans Sandbox Environment. After testing this integration, you can start real time transaction by Switching to Production Environment. For more details, refer to Retrieving API Access Keys Midtrans provides Sandbox Environment for ease of integration. You can use the Sandbox Environment to test your integrations, before going for real-time transactions. After you are satisfied with the results, you can switch to Production Environment.

Getting Started

Sample Request - Get Status API
(Note: Replace YOUR_API_KEY with your API key)

curl --location --request GET 'https://api.sandbox.midtrans.com/v2/SANDBOX-G710367688-806/status' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: {YOUR_API_KEY}' \
--data-raw '

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.sandbox.midtrans.com/v2/SANDBOX-G710367688-806/status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS =>"\n\n",
  CURLOPT_HTTPHEADER => array(
    "Accept: application/json",
    "Content-Type: application/json",
    "Authorization: {YOUR_API_KEY}"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "{YOUR_API_KEY}");

var raw = "\n\n";

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://api.sandbox.midtrans.com/v2/SANDBOX-G710367688-806/status", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
  import requests

url = "https://api.sandbox.midtrans.com/v2/SANDBOX-G710367688-806/status"

payload = "\n\n"
headers = {
  'Accept': 'application/json',
  'Content-Type': 'application/json',
  'Authorization': '{YOUR_API_KEY}'
}

response = requests.request("GET", url, headers=headers, data = payload)

print(response.text.encode('utf8'))
package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.sandbox.midtrans.com/v2/SANDBOX-G710367688-806/status"
  method := "GET"

  payload := strings.NewReader("\n\n")

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
  }
  req.Header.Add("Accept", "application/json")
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("Authorization", "{YOUR_API_KEY}")

  res, err := client.Do(req)
  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)

  fmt.Println(string(body))
}

Sample Response - Get Status API

{
    "masked_card": "411111-1111",
    "approval_code": "1599493766402",
    "bank": "bni",
    "channel_response_code": "00",
    "channel_response_message": "Approved",
    "transaction_time": "2020-09-07 22:49:26",
    "gross_amount": "10000.00",
    "currency": "IDR",
    "order_id": "SANDBOX-G710367688-806",
    "payment_type": "credit_card",
    "signature_key": "4d4abc70f5a88b09f48f3ab5cb91245feb0b3d89181117a677767b42f8cbe477f5a0d38af078487071311f97da646c1eb9542c1bbf0b19fa9f12e64605ac405e",
    "status_code": "200",
    "transaction_id": "3853c491-ca9b-4bcc-ac20-3512ff72a5d0",
    "transaction_status": "cancel",
    "fraud_status": "challenge",
    "status_message": "Success, transaction is found",
    "merchant_id": "G710367688",
    "card_type": "credit"
}

To get started with Midtrans API, follow the steps given below.

  1. Login to MAP account.
  2. Select Sandbox environment.
  3. Retrieve API access Keys.
  4. Create a transaction to generate an Order ID or use SANDBOX-G710367688-806.
  5. Send GET Status API using the order ID from step 3.

After successful transaction, Midtrans responds with a status code:200 and other details of the transaction. You can send more requests as required.

Authorization

To ensure secure client server communication, every API call should be authorized. Out of the various Authorization methods available, Midtrans uses BASIC AUTH. The format for BASIC AUTH is Username:Password. Using BASIC AUTH, API key can be passed as either Username or Password. For Midtrans, API key is passed as the Username, paired with an empty value for Password. It is then encoded into Base64 format and used as the authorization header.

Authorization Header

The Midtrans authorization header follows HTTP(S) BASIC AUTH convention. It utilizes Merchant Server Key as Username and blank value for Password.

Authorization Header Example

Server Key SB-Mid-server-abc123cde456
BASIC AUTH format SB-Mid-server-abc123cde456:
Base64 U0ItTWlkLXNlcnZlci1hYmMxMjNjZGU0NTY6
Authorization Basic U0ItTWlkLXNlcnZlci1hYmMxMjNjZGU0NTY6

To get the authorization header, follow the steps given below.

  1. Get the Server Key.
    The Server Key is unique for Sandbox environment and Production environment. To obtain the respective Server Key follow the links given below.
  2. Replace Username and Password.
    The BASIC AUTH format is Username:Password. Replace Username with Server Key and leave Password blank. So, this results in a string {Your_Server_Key}:.
  3. Encode the resulting string to Base64 format.
  4. Include this Base64 encoded string in the HTTP(S) header.
    Prepend the authorization method (Basic) and a space () to the encoded string. The authorization header is as given below:
    Authorization: Basic [Base64({Your_Server_Key}:)]
    For an example key, refer to the table given on the right.

HTTP(S) Request

You can communicate with Midtrans API by sending HTTP(S) request. The request consists of Base URL and HTTP(S) Header. The Base URL specifies the resource to which the request is applied. The HTTP(S) Header carries the data type of the request, data type of the response, and the authentication information. Midtrans then sends a response back in JSON format.

API Base URL

The Base URLs are as given below.

Sandbox Environment: https://api.sandbox.midtrans.com
Production Environment: https://api.midtrans.com

HTTP(S) Header

An HTTP Header is used in an HTTP request to provide information about the request. The HTTP Header for Midtrans API request carries the following information.

Header Value Definition
Content-Type application/json Indicates data type of the request.
Accept application/json Indicates the expected data type of the response.
Authorization Basic base64(server key , :) Contains the credentials to authenticate a user. Midtrans uses Basic AUTH for authentication. For more details, refer Authorization.

Content-Type and Accept Header

The input and output parameters for Midtrans API are in JSON format.

To accept JSON input and output parameters, you need to add the following HTTP(S) Header.

JSON Object

A collection of JSON objects that are used in API Methods is given below.

Transaction Details Object

"transaction_details": {
    "order_id": "A87551",
    "gross_amount": 145000
}
JSON Attribute Description Type Required
order_id Order Id of the transaction.
Note: Allowed Symbols are dash(-), underscore(_), tilde (~), and dot (.)		 String(50) Required
gross_amount Total transaction amount in IDR.
Note: Do not add decimal.		 Long Required

Credit Card Object

"credit_card": {
    "token_id": "4811117d16c884-2cc7-4624-b0a8-10273b7f6cc8",
    "bank": "bni",
    "installment_term": 6,
    "bins": ["4811", "5233"],
    "type": "authorize",
    "save_token_id": true
}
JSON Attribute Description Type Required
token_id Token id represents customer credit card information. String(255) Required
bank Name of the acquiring bank. Valid values are: mandiri, bni, cimb, bca, maybank, and bri. String(255) Optional
installment_term Installment tenure in terms of months. Integer Optional
bins List of credit card's BIN (Bank Identification Number) that is allowed for transaction. JSON Array Optional
type Used as preauthorization feature. Valid value: authorize. String (255) Optional
save_token_id Used on 'One Click' or 'Two Clicks' feature. Enabling it will return a saved_token_id that can be used for the next transaction. Boolean Optional

Item Details Object

"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 Description Type Required
id Item ID. String N
price Price of the item in IDR.
Note: Do not add decimal.		 Integer Required
quantity Quantity of the item purchased by the customer. Integer Required
name Name of the item. String Required
brand Brand name of the item. String Optional
category Category of the item. String Optional
merchant_name Name of the merchant selling the item. String Optional
tenor Installment term, use two digits numeric. For example, 03, 06, 09, 12, 24.
Note: This is a BCA KlikPay exclusive field.		 Integer(2) Conditional
code_plan Installment code, use 000 for default.
Note: This is a BCA KlikPay exclusive field.		 Integer(3) Conditional
mid Installment Merchant ID.
Note: This is a BCA KlikPay exclusive field.		 Integer(9) Conditional

Customer Details Object

"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 Description Type Required
first_name Customer's first name. String(255) Optional
last_name Customer's last name. String(255) Optional
email Customer's email address. String(255) Optional
phone Customer's phone number. String(255) Optional
billing_address Customer's billing address. JSON Array Optional
shipping_address Customer's shipping address. JSON Array Optional

Billing Address Object

JSON Attribute Description Type Required
first_name Customer's first name. String(255) Optional
last_name Customer's last name. String(255) Optional
phone Customer's phone number. String(255) Optional
address Customer's billing address. String(255) Optional
city City of the billing address. String(255) Optional
postal_code Postal code of the billing address.
Note: Allowed characters are alphabets, numbers, dash (-), and space ().		 String(255) Optional
country_code Country ID of the billing address. Value: IDN. ISO 3166-1 alpha-3.
Note: Currently only IDN is supported.		 String(3) Optional

Shipping Address Object

JSON Attribute Description Type Required
first_name Customer's shipping first name. String(255) Optional
last_name Customer's shipping last name. String(255) Optional
phone Customer's shipping phone number. String(255) Optional
address Customer's shipping address. String(255) Optional
city City of the shipping address. String(255) Optional
postal_code Postal code of the shipping address.
Note: Allowed characters are alphabets, numbers, dash (-), and space ().		 String(255) Optional
country_code Country ID of the shipping address. Value: IDN. ISO 3166-1 alpha-3
Note: Currently only IDN is supported.		 String(3) Optional

Bank Transfer Object

Bank Transfer BCA VA Object

"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"
             }
       ]
  },
  "bca": {
    "sub_company_code": "00000"
  }
}

Bank Transfer Permata VA Object

"bank_transfer":{
  "bank": "permata",
  "va_number": "111111",
  "permata": {
    "recipient_name": "SUDARSONO"
  }
}
JSON Attribute Description Type Required
bank Bank name which processes bank transfer transaction. Possible values are permata, bni, bri, and bca. String(255) Required
va_number Custom VA number assigned by you. If shorter than minimum then Midtrans will add trailing 0s as most significant bits. If longer than maximum then Midtrans will trim the remaining least significant bits.
  • BCA VA: Accepts 6-11 digits
  • Permata VA Facilitator: Accepts 10 digits.
  • BNI VA: Accepts 8 (For 5 digits Client ID) or 12 digits (For 3 digits Client ID).
  • BRI VA: Accepts 18 digits.
 String(255) Optional
free_text List of free texts.
Note: Right now only used for BCA VA.		 JSON Object Array Optional
bca Specific parameters for BCA VA. JSON Object Optional
permata Specific parameters for Permata VA. JSON Object Optional

Free Text Object

JSON Attribute Description Type Required
inquiry Free texts shown during inquiry. JSON Object Array(10) Optional
payment Free texts shown during payment. JSON Object Array(10) Optional

Inquiry/Payment Object

JSON Attribute Description Type Required
id Free text message in Bahasa Indonesia. String(50) Required
en Free text message in English. String(50) Required

BCA VA Object

JSON Attribute Description Type Required
sub_company_code BCA sub company code directed for this transactions.
Note: Default is 00000.		 String Optional

Permata VA Object

JSON Attribute Description Type Required
recipient_name Recipient name shown on the payment details. It is shown as 20 characters uppercase string.
Note: Default is merchant name.		 String Optional

E-Channel Object

"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 Description Type Required
bill_info1 Label 1. Mandiri allows only 10 characters. Exceeding characters will be truncated. String(255) Required
bill_info2 Value for Label 1. Mandiri allows only 30 characters. Exceeding characters will be truncated. String(255) Required
bill_info3 Label 2. Mandiri allows only 10 characters. Exceeding characters will be truncated. String(255) Optional
bill_info4 Value for Label 2. Mandiri allows only 30 characters. Exceeding characters will be truncated. String(255) Optional
bill_info5 Label 3. Mandiri allows only 10 characters. Exceeding characters will be truncated. String(255) Optional
bill_info6 Value for Label 3. Mandiri allows only 30 characters. Exceeding characters will be truncated. String(255) Optional
bill_info7 Label 4. Mandiri allows only 10 characters. Exceeding characters will be truncated. String(255) Optional
bill_info8 Value for Label 4. Mandiri allows only 30 characters. Exceeding characters will be truncated. String(255) Optional

VA Number Object

"va_numbers": [
  {
    "bank": "bca",
    "va_number": "91019021579"
  }
]
JSON Attribute Description Type Required
bank Name of the bank that processes bank transfer transaction. Valid values are permata, bni, bri, and bca. String(255) Required
va_number Virtual account number generated by Midtrans. String(255) Required

Payment Amount Object

"payment_amounts": [
  {
    "paid_at": "2016-06-19 20:12:22",
    "amount": "20000.00"
  }
]
JSON Attribute Description Type Required
paid_at Timestamp of payment in ISO 8601 format. Time Zone: GMT+7. String Required
amount Amount paid by the customer. String Required

BCA Klikpay Object

"bca_klikpay": {
  "description": "Pembelian Barang"
}
JSON Attribute Description Type Required
description Description of the BCA KlickPay transaction. String(60) Required
misc_fee Additional fee for documentation. Long Optional

BCA Klikbca Object

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

CIMB Clicks Object

"cimb_clicks": {
    "description": "Purchase of a special event item"
}
JSON Attribute Description Type Required
description Description of CIMB transaction. This will be displayed on the CIMB email notification. String(100) Required

Convenience Store Object

"cstore" : {
  "store" : "indomaret",
  "message" : "mangga",
  "alfamart_free_text_1": "1st row of receipt,",
  "alfamart_free_text_2": "This is the 2nd row,",
  "alfamart_free_text_3": "3rd row. The end."
}
JSON Attribute Description Type Required
store The name of the convenience store. String(20) Required
message Label displayed in Indomaret POS. String(20) Optional
alfamart_free_text_1 Customizable first row of text on the Alfamart printed receipt. String (40) Optional
alfamart_free_text_2 Customizable second row of text on the Alfamart printed receipt. String (40) Optional
alfamart_free_text_3 Customizable second row of text on the Alfamart printed receipt. String (40) Optional

Action Object

{
    "name": "cancel",
    "method": "POST",
    "url": "https://api.midtrans.com/v2/e48447d1-cfa9-4b02-b163-2e915d4417ac/cancel",
    "fields": []
}
JSON Attribute Description Type Required
name Action name. String Required
method HTTP method used for the action. String Required
url HTTP URL target for the action. String Required
fields Parameters which can be sent for the action. Only for HTTP methods other than GET. Array(String) Conditional

GoPay Object

"gopay": {
  "enable_callback": true,
  "callback_url": "someapps://callback",
  "account_id": "00000269-7836-49e5-bc65-e592afafec14",
  "payment_option_token": "eyJ0eXBlIjogIkdPUEFZX1dBTExFVCIsICJpZCI6ICIifQ=="
}
JSON Attribute Description Type Required
enable_callback Required for GoPay deeplink/QRIS. To determine appending callback URL in the deeplink. Default value: false. Boolean Optional
callback_url The HTTP or Deeplink URL to which the customer is redirected from Gojek app after successful payment. Default value: callback_url in dashboard settings.
For GoPay Tokenization, please make sure callback_url is the same URL submitted on onboarding process.		 String Optional
account_id Required for GoPay Tokenization. The customer account ID linked during Create Pay Account API. String Conditional
payment_option_token Required for GoPay Tokenization. Token to specify the payment option made by the customer from Get Pay Account API metadata. String Conditional
pre_auth Set the value to true to reserve the specified amount from the customer balance. Once the customer balance is reserved, you can initiate a subsequent Capture API request. Default value: false. Boolean Optional

QRIS Object

"qris": {
  "acquirer": "gopay"
}
JSON Attribute Description Type Required
acquirer The acquirer for QRIS. Possible values are airpay shopee, gopay. Default value: gopay. String Optional

ShopeePay Object

"shopeepay": {
  "callback_url": "https://midtrans.com/"
}
JSON Attribute Description Type Required
callback_url The URL to redirect the customer back from the ShopeePay app. Default value is the finish URL, configured on your MAP account. String Optional

Subscription Schedule Object

"schedule": {
  "interval": 1,
  "interval_unit": "month",
  "max_interval": 12,
  "current_interval": 2,
  "start_time": "2019-05-29 09:11:01",
  "previous_execution_at": "2019-05-29 09:11:01",
  "next_execution_at": "2019-06-29 09:11:01"
}
JSON Attribute Description Type
interval Subscription interval specified by you. Integer
interval_unit Unit of time interval.
Note: Currently supports only month.		 String
max_interval Maximum interval of subscription. Subscription ends after the maximum interval is reached. Integer
current_interval Current interval of subscription. Integer
start_time Timestamp of subscription in yyyy-MM-dd HH:mm:ss format. Time Zone: GMT+7 . String
previous_execution_at Timestamp of last succeeded charge in yyyy-MM-dd HH:mm:ss format. Time Zone: GMT+7.
Note: On create subscription, timestamp value will be the same as start_time, but if start_time has not passed yet, the value will be null.		 String
next_execution_at Timestamp of next scheduled charge in yyyy-MM-dd HH:mm:ss format. Time Zone: GMT+7. String

Create Subscription Schedule Object

"schedule": {
  "interval": 1,
  "interval_unit": "month",
  "max_interval": 12,
  "start_time": "2019-05-29 09:11:01 +0700"
}
JSON Attribute Description Type
interval Subscription's interval given by merchant. Integer
interval_unit Interval temporal unit.
Note: currently supports only day, week, and month.		 String
max_interval Maximum interval of subscription. Subscription will end after maximum interval is reached. Integer
start_time Timestamp of subscription in yyyy-MM-dd HH:mm:ss Z. The value must be after the current time. If specified, first payment will happen on start_time. If start_time is not specified, the default value for start_time will be current time and first payment will happen at the first interval after current time. String

Update Subscription Schedule Object

"schedule": {
  "interval": 1
}
JSON Attribute Description Type
interval Subscription's interval given by merchant. Integer

Subscription Customer Details Object

"customer_details": {
  "first_name": "TEST",
  "last_name": "UTOMO",
  "email": "test@midtrans.com",
  "phone": "+628123456"
}
JSON Attribute Description Type Required
first_name Customer's first name. String(255) Optional
last_name Customer's last name. String(255) Optional
email Customer's email address. String(255) Optional
phone Customer's phone number. String(255) Optional

Subscription GoPay Object

"gopay": {
  "account_id": "phy56f8f-2683-4248-8080-e59b36c6bbgf"
}
JSON Attribute Description Type Required
account_id GoPay Account ID from Core API. String Required

Shipping Address Object

JSON Attribute Description Type Required
order_id Order Id of the transaction.
Note: Allowed Symbols are dash(-), underscore(_), tilde (~), and dot (.)		 String(50) Required
gross_amount Total transaction amount in IDR.
Note: Do not add decimal.		 Long Required

Handling Notifications

When a customer completes the transaction or when the transaction status changes, Midtrans sends you real time notification.

Receiving Notifications

In order to increase the security aspect, there are several ways to ensure that the notifications received by Merchant backend, are actually sent by Midtrans.

Signature Key

Midtrans adds a Signature Key in every notification. Signature Key is another option to verify the integrity of notification. The logic of the Signature Key and the sample code to generate the Signature Key are given on the side. If the generated Signature Key does not match with the Signature Key on the notification, ignore the notification.

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;
  ?>

Challenge Response

This is an additional method to verify the authenticity of the notification. It can be achieved by calling the get status API. The response is the same as the notification status.

challenge response

Best Practices to Handle Notification

The guidelines to handle the notifications are given below.

In addition to the types of notification given below, different notifications can be added. New field may also be added to the existing notification. Please check with the latest documentation for the exact fields.

Override Notification URL

Merchant can opt to edit or add custom notification URLs on every transaction. It can be achieved by attaching additional HTTP headers to the charge request.

Sample Header with Append and Override Notification

Append Notification Sample

curl -X POST \
  https://api.midtrans.com/v2/charge \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic NjJiMTVhN2QtZTVmOC00YjNjLTllYWItY2E4MjdjYTM3ZjU1Og==' \
  -H 'Content-Type: application/json' \
  -H 'X-Append-Notification: https://example.com/test1,https://example.com/test2' \
  -H 'cache-control: no-cache' \
  -d '{
    "payment_type": "gopay",
    "transaction_details": {
        "order_id": "1553229166",
        "gross_amount": 10000
    }
}'

Midtrans provides two headers given below.

  1. X-Append-Notification: to add new notification URL(s) alongside the settings on dashboard.

Override Notification Sample

curl -X POST \
  https://api.midtrans.com/v2/charge \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic NjJiMTVhN2QtZTVmOC00YjNjLTllYWItY2E4MjdjYTM3ZjU1Og==' \
  -H 'Content-Type: application/json' \
  -H 'X-Override-Notification: https://example.com/test1,https://example.com/test2' \
  -H 'cache-control: no-cache' \
  -d '{
    "payment_type": "gopay",
    "transaction_details": {
        "order_id": "1553229166",
        "gross_amount": 10000
    }
}'
  1. X-Override-Notification: to use new notification URL(s) disregarding the settings on dashboard.

Both the headers can receive up to a maximum of three URLs.

Let us assume that you have set https://example.com as your notification URL on the dashboard.

If you set X-Append-Notification with values https://example.com/test1,https://example.com/test2, then every HTTP notification for that specific transaction is sent to the URLs given below.

  1. https://example.com,
  2. https://example.com/test1, and
  3. https://example.com/test2

If you set X-Override-Notification with values https://example.com/test1,https://example.com/test2, then every HTTP notification for that specific transaction is sent to the URLs given below.

  1. https://example.com/test1 and
  2. https://example.com/test2

Status Code

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

Code 2xx

Status Description
200 Payment Card: Success. Request is successful. Transaction status is authorize, capture, settlement, cancel. Approval of challenge transactions is accepted by Midtrans.

Other payment methods: Success. The transaction status is settlement or cancel.
201 Payment Card: Pending. Transaction is successfully made but the 3D secure process has yet to be completed. Transaction will expire expire within 15 minutes. Or, on some rare occasion, Challenge. The transaction is successfully sent to the bank but yet to be approved. You need to manually approve the transaction. If no action is taken until settlement time (D+1 16:00), Midtrans will cancel the transaction.

Bank Transfer: Pending. The transaction is successfully sent to the bank but the process is not completed by the customer. By default, the transaction expires within 24 hours.

GoPay: Pending. The transaction is created successfully on GoPay but it is not completed by the customer. By default, the transaction expires within 15 minutes.

CIMB Click: Pending. The transaction is successfully sent to the bank but the process is not completed by the customer. By default, the transaction expires within two hours.

BRI ePay: Pending. The transaction is successfully sent to the bank but the process is not completed by the customer. By default, the transaction expires within two hours.

Klik BCA: Pending. The transaction is successfully sent to the bank but the process is not completed by the customer. By default, the transaction expires within two hours.

BCA KlikPay: Pending. The 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. The transaction is successfully sent to the bank but the process is not completed by the customer. By default, the transaction expires within two hours.

XL Tunai: Pending. The transaction is successfully sent to the provider but the process is not completed by the customer. By default, the transaction expires within two hours.

Indomaret: Pending. The transaction is successfully sent to the provider but the process is not completed by the customer. By default, the transaction expires within two hours.
202 Payment Card: Denied. The transaction has been processed but is denied by payment provider or Midtrans Fraud Detection System.

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

Code 3xx

Status Description
300 Move permanently. All current and future requests should be directed to the new URL permanently.

Code 4xx

Status Description
400 Validation Error. You have sent bad request data like invalid transaction type, invalid payment card format, and so on.
401 Access denied due to unauthorized transaction. Please check Client Key or Server Key.
402 No access for this payment type.
403 The requested resource is not capable of generating content in the format specified in the request headers.
404 The requested resource/transaction is not found. Please check order_id or other details sent in the request.
405 HTTP method is not allowed.
406 Duplicate order ID. order_id has already been utilized previously.
407 Expired transaction.
408 Wrong data type.
409 You have sent too many transactions for the same card number.
410 Your account is deactivated. Please contact Midtrans support.
411 token_id is missing, invalid, or timed out.
412 You cannot modify status of the transaction.
413 The request cannot be processed due to syntax error in the request body.
414 Refund request is rejected due to merchant insufficient funds.
429 API rate limit exceeded. The global rate limit is applied to Create Pay Account API and Charge API

Code 5xx

Status Description
500 Internal Server Error.
501 The feature is not available.
502 Internal Server Error: Bank Connection Problem.
503 Bank/partner is experiencing connection issue.
504 Internal Server Error: Midtrans Fraud Detection System is unavailable.
505 Failure to create requested VA number. Try again later.

Payment API

Payment API is intended for performing transactions and deduct funds from the customer, depending on the payment method selected. You can tokenize, approve, deny, refund, or cancel a transactions.

API Methods

HTTP Method Endpoint Description
GET /v2/token Tokenize payment card information before being charged.
POST /v2/charge Perform a transaction with various available payment methods and features. Example given: Credit Card Charge.
POST /v2/capture Capture an authorized transaction for card payment.
POST /v2/order_id/approve Approve a transaction with certain order_id which gets challenge status from Fraud Detection System.
POST /v2/order_id/deny Deny a transaction with a specific order_id, flagged as challenge by Fraud Detection System.
POST /v2/order_id/cancel Cancel a transaction with a specific order_id. Cancelation can only be done before settlement process.
POST /v2/order_id/expire Update the transaction status of a specific order_id, from pending to expired.
POST /v2/order_id/refund Update the transaction status of a specific order_id, from settlement to refund.
POST /v2/order_id/refund/online/direct Send refund to the customer's bank or the payment provider and update the transaction status to refund.
GET /v2/order_id/status Get the transaction status of a specific order_id.
GET /v2/order_id/status/b2b Get the transaction status multiple B2B transactions related to certain order_id.
GET /v2/card/register Register customer's card information (card number and expiry) to be used for One Click and Two Click transactions.
GET /v2/point_inquiry/token_id Get the point balance of the card in denomination amount.
POST /v2/pay/account Used to link the customer's account to create payment for certain channel.
GET /v2/pay/account/account_id Get customer payment account details.
POST /v2/pay/account/account_id/unbind Unbind a linked customer account.
GET /v1/bins/bin_number Get Bin Metadata.

Get Token

Import Midtrans JavaScript Library

<script id= "midtrans-script" src="https://api.midtrans.com/v2/assets/js/midtrans-new-3ds.min.js" data-environment="<production|sandbox>" data-client-key="<INSERT CLIENT KEY HERE>" type="text/javascript"></script>

Token ID is a unique value that is associated with the customer’s credit card information during a transaction. The GET Token method sends the credit card information via Midtrans.min.js to Midtrans server and returns the Token ID to you.

To utilize Midtrans JavaScript library, add the code given on the right, in your payment page inside the <head> tag.

Midtrans JavaScript Library

Midtrans JavaScript library consists of two functions as given below.

  1. Get Card Token: Securely sends the customer’s payment card details to Midtrans server, without the merchant handling the credit card details.
  2. Redirect: Redirects the customer to 3DS authentication page.
Attribute Description
data-environment The environment which the request is pointing to. Possible values are production and sandbox.
data-client-key Your Client key. For more details, refer Retrieving API Access Keys.

Getting Card Token

GET Card Token Request

Get Card Token function

// Create the card object with the required fields
var card = {
  card_number: "4811111111111114",
  card_cvv: "123",
  card_exp_month: "12",
  card_exp_year: "2022"
}

var options = {
  onSuccess: function(response) {
      // Implement success handling here
  },
  onFailure: function(response) {
      // Implement error handling here
  }
}

MidtransNew3ds.getCardToken(card, options);

The card object attributes are given below. Depending on the token type, some parameters are conditional.

JSON Attribute Description Normal Two Clicks Remarks
card_number The 16 digits Credit Card number. Required Conditional Space() is allowed.
For example, 4111 1111 1111 1111 or 4111111111111111 both are valid.
card_cvv The CVV number printed on the card. Required Required For example, 123.
card_exp_month The card expiry month in MM format. Required Conditional For example, 12.
card_exp_year The card expiry year in YYYY format. Required Conditional For example, 2022.
token_id The token ID of credit card saved previously. Its value is same as the saved_token_id retrieved from initial Charge response. Conditional Required For example, 481111-1114-0e68a4c4-85d3-48b5-b6cb-9945b2d3dcc9.

GET Card Token Response

Callback response object attributes are listed below.

JSON Attribute Description Remarks
status_code Status code of transaction charge result. "200" for success, "400" when validation error.
status_message Status message describing the result of the API request. "OK, success request new token".
validation_messages The message describing the error. “card_exp_year must be greater than this year”, "card_exp_month must be greater than this year's month”.
token_id The token id of the card. "481111-1114-d3d690db-3e18-4edd-9fee-4d061e4eb6f3"
Note: token_id is required during Card Payment Charge Transaction.

Available options are given below.

Name Description
onSuccess This function is called only when get token responds with status code 200.
onFailure This function is called for all the other status codes except 200.

Redirecting to 3DS Page (Already Support 3DS 2.0)

Redirect function

var options = {
    // In case, Merchant needs to override for each transactions
    callbackUrl = "<ANY LINK>"
}

MidtransNew3ds.redirect(redirect_url, options);

How Midtrans redirects customer via HTML form (POST Method)

<form id="veritrans" method="post" action="<callbackUrl>">
    <input type="hidden" name="response" value="<JSON FORMAT CALLBACK OBJECT>"/>
</form>

After proceeding card transaction to Charge API request, if the transaction needs 3DS authentication, you will receive redirect_url in the response. You can optionally use built-in MidtransNew3ds.redirect function to redirect the customer.

After 3DS process is completed, the customer is redirected back to the website specified in callbackUrl or the Finish Redirect URL configured on your MAP account. This final redirect is HTTP POST method. It contains JSON string encapsulated as value of response key of the POST form-data.

Callback response object attributes are listed below.

JSON Attribute Description Type
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type The payment method used by the customer. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Transaction status after charge credit card transaction. 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.
pending: Credit card is pending and you will need to rely on the http notification webhook to receive the final transaction status..		 String
fraud_status Detection result by Fraud Detection System (FDS). Possible values are
accept : Approved by FDS.
challenge: Questioned by FDS. Note: Approve transaction to accept it or transaction gets automatically canceled during settlement.
deny: Denied by FDS. Transaction automatically failed.		 String
masked_card First 6-digits and last 4-digits of customer's credit card number. String
status_code Status code of transaction charge result. String
bank The name of the acquiring bank. String
status_message Status message describing the result of the API request. String
approval_code Approval code. It can be used for refund. This does not exist on denied transaction. String
eci The 3D secure ECI Code. String
channel_response_code Response code from payment channel provider. String
channel_response_message Response message from payment channel provider. String
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.		 String
card_type Type of card used for the transaction. Possible values are credit, debit. String
three_ds_version 3DS Version that used for transaction (This field only present for 3DS Transaction). Possible values are 1, 2 String
three_ds_challenge_completion 3DS Challenge completion state to indicate the customer has submit the OTP or not(it doesn't matter if the OTP is valid or not). Possible values are true, false Boolean

Optional parameter is given below.

Name Description Required
callbackUrl To override where the customer gets redirected after 3DS authentication is done. Optional

Opening 3DS Page via iFrame (Already Support 3DS 2.0)

Sample code to open redirect_url on iFrame (JQuery - FancyBox)

// 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()
}

var options = {
  performAuthentication: function(url) {
    openDialog(url)
  },
  onSuccess: function(response) {
    // Successful handling
    closeDialog()
  },
  onPending: function(response) {
    // Pending handling
    closeDialog()
  },
  onFailure: function(response) {
    // Failure handling
    closeDialog()
  }
}

MidtransNew3ds.authenticate(redirect_url,options)

Optionally, you can use MidtransNew3ds.performAuthentication function to open redirect_url as iFrame. It is a substitute to the redirection scheme.

After 3DS process is completed by a customer, your website receives JSONP callback containing the transaction result.

Callback response object attributes are listed below.

JSON Attribute Description Type
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type The payment method used by the customer. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Transaction status after charge credit card transaction. 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.
pending: Credit card is pending and you will need to rely on the http notification webhook to receive the final transaction status.		 String
fraud_status Detection result by Fraud Detection System (FDS). Possible values are
accept : Approved by FDS.
challenge: Questioned by FDS. Note: Approve transaction to accept it or transaction gets automatically canceled during settlement.
deny: Denied by FDS. Transaction automatically failed.		 String
masked_card First 6-digits and last 4-digits of customer's credit card number. String
status_code Status code of transaction charge result. String
bank The acquiring bank of the transaction. String
status_message Description of transaction charge result. String
approval_code Approval code. It can be used for refund. This does not exist on denied transaction. String
eci The 3D secure ECI Code. String
channel_response_code Response code from payment channel provider. String
channel_response_message Response message from payment channel provider. String
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.		 String
card_type Type of card used for the transaction. Possible values are credit, debit. String
three_ds_version 3DS Version that used for transaction (This field only present for 3DS Transaction). Possible values are 1, 2 String

Available options are given below.

Name Description
performAuthentication Implementation to open redirect URL in iFrame.
onSuccess Handle to receive successful callback response.
onPending Handle to receive callback response. Only applicable when merchant applied for async endpoint.
onFailure Handle to receive failure response.

Charge Transactions

Midtrans provides facility to add more features to Charge Transaction. Using these features, you can -

Set Custom Field

Sample Request - Set Custom Field

{
  "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"
}

Sample Response - Set Custom Field

{
    "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"
}

Sample Response - 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": "midtrans payment notification"
}

Set Custom Fields is a feature that enables you to charge a transaction with unique data according to your need. Midtrans provides three custom fields to save custom data about the transaction.

The steps to set these custom fields are given below.

  1. Set Custom field label on MAP.

    a. Login to your MAP account.
    b. On the Dashboard, go to Settings > General Settings > Interface Settings.
    c. Enter custom text in Custom field 1 label, Custom field 2 label, Custom field 3 label.
    d. Click Save.

  2. Send Charge API request with the custom fields value.

  3. The label and value of the custom fields can be checked using the Order ID of a transaction.

  4. Midtrans sends HTTP POST Notification with these custom fields to Payment Notification URL specified on MAP.

JSON Attribute Description Type
custom_field1 The value of custom field 1. String(255)
custom_field2 The value of custom field 2. String(255)
custom_field3 The value of custom field 3. String(255)

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 you to set an expiry time for the payment of every transaction with transaction_status:pending. The list of payment methods, with transaction_status:pending is given below.

For QRIS with acquirer AirPay (Shopee) and ShopeePay, the allowed maximum time of expiry is one hour. The transaction is rejected if the custom expiry exceeds the allowed maximum time.

JSON Attribute Description Type
order_time Timestamp at which the order is created on your website, in ISO 8601 format. Time Zone: GMT+7.
Note: If not defined, expiry time starts from transaction time.		 String(50)
expiry_duration Time duration for which the payment remains valid. String(50)
unit Unit for expiry_duration.
Possible values are second, minute, hour, or day.
Note: Default value is minute.		 String(50)

Set Metadata

Sample Request - Set metadata Charge

{
  "payment_type": "bank_transfer",
  "bank_transfer": {
    "bank": "permata"
  },
  "transaction_details": {
    "order_id": "C17550",
    "gross_amount": 145000
  },
  "metadata": {
    "you": "can",
    "put": "any",
    "parameter": "you like"
  }
}

Sample Response - Success

{
    "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"
}

Sample Response - Notification

{
  "masked_card": "481111-1114",
  "approval_code": "256084",
  "bank": "bni",
  "transaction_time": "2016-06-28 09:42:20",
  "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": "midtrans payment notification",
  "metadata": {
    "you": "can",
    "put": "any",
    "parameter": "you like"
  }
}

Set Metadata is similar to Set Custom Field which enables you to put free-form JSON object instead of String. You can use this metadata as a transaction tag and retrieve it using Get Status or HTTP Notifications URL. Additionally, you can also configure the fraud detection rules based on the metadata fields.

JSON Attribute Description Type
metadata Object containing the metadata parameters. JSON Object

Capture Transaction

Capture transaction is triggered to capture the transaction balance when transaction_status:authorize. This is only available after Pre-Authorized Credit Card Transactions.

Capture Transaction Method

HTTP Method Endpoint Definition
POST BASE_URL/v2/capture Capture an authorized transaction for card payment.

Capture Transaction Request

Sample Request - Capture

{
  "transaction_id": "be4f3e44-d6ee-4355-8c64-c1d1dc7f4590",
  "gross_amount": 145000
}
JSON Attribute Description Type Required
transaction_id Transaction ID given by Midtrans. String(255) Required
gross_amount Total amount of transaction in IDR. By default it captures whole transaction amount.
Note: Decimal values are invalid.		 Long Optional

Capture Transaction Response

Sample Response - Success

{
  "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"
}

Sample Response - Error

{
  "status_code" : "412",
  "status_message" : "Merchant cannot modify the status of the transaction"
}
JSON Attribute Description Type
status_code Status code of transaction capture result. String
status_message Description of transaction capture result. String
order_id Order ID specified by you. String
transaction_id Transaction ID given by Midtrans. String
masked_card First 6-digits and last 4-digits of customer's card number. String
gross_amount Total amount of transaction in IDR. String
order_id Order ID specified by you. String
payment_type The payment method used by the customer. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Transaction status after capture card transaction. String
fraud_status Detection result by Fraud Detection System (FDS). Possible values are
accept : Approved by FDS.
challenge: Questioned by FDS.
Note: Approve transaction to accept it or transaction gets automatically canceled during settlement.
deny: Denied by FDS. Transaction automatically failed.		 String
bank The name of the acquiring bank. String
gross_amount Total amount of transaction in IDR. String

Approve Transaction

Approve transaction is triggered to accept the card payment transaction with fraud_status:challenge.

Approve Transaction Method

Sample Request - Approve Charge

HTTP Method Endpoint Definition
POST BASE_URL/v2/{order_id OR transaction_id}/approve Approve challenged transaction

Approve Transaction Response

Sample Response - Success

{
  "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"
}

Sample Response - Error

{
  "status_code" : "412",
  "status_message" : "Merchant cannot modify the status of the transaction"
}
JSON Attribute Description Type
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type The payment method used by the customer. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Transaction status after charge credit card transaction. 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.		 String
fraud_status Detection result by Fraud Detection System (FDS). Possible values are
accept : Approved by FDS.
challenge: Questioned by FDS.
Note: Approve transaction to accept it or transaction gets automatically canceled during settlement.
deny: Denied by FDS. Transaction automatically failed.		 String
masked_card First 6-digits and last 4-digits of customer's credit card number. String
status_code Status code of transaction charge result. String
bank The name of the acquiring bank. String
status_message Description of transaction charge result. String

Deny Transaction

Deny transaction is triggered to immediately deny the card payment transaction with fraud_status:challenge.

Deny Transaction Method

Sample Request - Deny Charge

HTTP Method Endpoint Definition
POST BASE_URL/v2/{order_id OR transaction_id}/deny Deny Challenged Transaction

Deny Transaction Response

Sample Response - Success

{
  "status_code" : "200",
  "status_message" : "Success, transaction is denied",
  "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" : "deny",
  "fraud_status" : "deny",
  "bank" : "bni",
  "gross_amount" : "30000.00"
}

Sample Response - Error

{
  "status_code" : "412",
  "status_message" : "Merchant cannot modify the status of the transaction"
}
JSON Attribute Description Type
status_code Status code of transaction charge result. String
status_message Description of transaction charge result. String
transaction_id Transaction ID given by Midtrans. String
masked_card First 6-digits and last 4-digits of customer's credit card number. String
order_id Order ID specified by you. String
payment_type The payment method used by the customer. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Transaction status after charge credit card transaction. 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.		 String
fraud_status Detection result by Fraud Detection System (FDS). Possible values are
accept: Approved by FDS.
challenge: Questioned by FDS.
Note: Approve transaction to accept it or transaction gets automatically canceled during settlement.
deny: Denied by FDS. Transaction is failed automatically.		 String
bank The acquiring bank of the transaction. String
gross_amount Total amount of transaction in IDR. String

Cancel Transaction

Cancel transaction is triggered to void the transaction.

Card Payment

Card payment can be voided with Cancel method if the transaction has not been settled. The time interval during which the pre-authorized transaction can be cancelled depends on the Acquiring Bank.

Acquiring Bank Trigger Cancel Method
BNI After pre-authorization payment has been captured.
Mandiri After the initial charge of the pre-authorized payment.
BCA, BRI, MAYBANK Before and after pre-authorization payment has been captured.

Pending Payment

Payment with transaction_status:pending can be voided with cancel method if the transaction has not expired or has not been completed. The list of payment methods with transaction_status:pending are given below.

Cancel Transaction Method

Sample Request - Cancel Charge

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

Cancel Transaction Response and Notification

Sample Response - Success

{
  "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"
}

Sample Response - Error

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

Sample Response - Success 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": "midtrans payment notification"
}
JSON Attribute Description Type
status_code Status code of transaction cancel result. String
status_message Description of transaction cancel result. String
transaction_id Transaction ID given by Midtrans. String
masked_card First 6-digits and last 4-digits of customer's credit card number. String
order_id Order ID specified by you. String
payment_type The payment method used by the customer. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Transaction status after charge credit card transaction. Possible values are
capture : Transaction is accepted by the bank and ready for settlement.
Note: Cancel transaction to deny / cancel it. Otherwise, transaction is settled automatically.
deny: transaction is denied by the bank or FDS.
authorize: Credit card is authorized in pre-authorization feature.		 String
fraud_status Detection result by Fraud Detection System (FDS). Possible values are
accept : Approved by FDS.
challenge: Questioned by FDS.
deny: Denied by FDS. Transaction automatically failed.		 String
bank The acquiring bank of the transaction. String
gross_amount Total amount of transaction in IDR. String

Expire transaction

Expire transaction is triggered to update the transaction_status to expire, when the customer fails to complete the payment. The expired order_id can be reused for the same or different payment methods.

Expire Transaction Method

Sample Request - Expire Charge

HTTP Method Endpoint Definition
POST BASE_URL/v2/{order_id OR transaction_id}/expire Expire the transaction.

Expire Transaction Response and Notifications

Sample Response - Success

{
  "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"
}

Sample Response - Error

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

Sample Response - Expired Notification

{
  "status_code": "202",
  "status_message": "midtrans 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 Description Type
status_code Status code of transaction charge result. String
status_message Description of transaction charge result. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
payment_type The payment method used by the customer. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Transaction status after charge credit card transaction. 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.		 String
gross_amount Total amount of transaction in IDR. String

Refund transaction

Refund transaction is triggered to update the transaction status to refund, when the customer decides to cancel a completed transaction or a payment that is settled. The same refund_id cannot be reused.

Refund transaction is supported only for credit_card payment method. Banks which support this method are BNI, Mandiri, and CIMB.

Refund Transaction Method

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

Refund Transaction Request

Sample Request - Refund Charge

{
 "refund_key": "reference1",
  "amount": 5000,
  "reason": "for some reason"
}
JSON Attribute Description Type Required
refund_key Merchant refund ID. If not passed then Midtrans creates a new one. It is recommended to use this parameter to avoid double refund attempt. Allowed characters are alphabets, numbers, dash (-), and underscore (_). String Optional
amount Amount to be refunded. By default whole transaction amount is refunded. Long Optional
reason Reason justifying the refund. String(255) Optional

Refund Transaction Response and Notification

Sample Response - Success (Full Refund)

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

Sample Response - Success (Partial Refund)

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

Sample Response - Error (Invalid Refund)

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

Sample Response - Error (Invalid Amount)

{
  "status_code" : "414",
  "status_message" : "Refund request is rejected due to invalid amount"
}

Sample Response - Error (Invalid Refund ID)

{
  "status_code" : "406",
  "status_message" : "Duplicate refund ID"
}

Sample Response - Notification

{
  "status_code" : "200",
  "status_message" : "midtrans payment notification",
  "transaction_id" : "249fc620-6017-4540-af7c-5a1c25788f46",
  "masked_card" : "481111-1114",
  "order_id" : "example-1424936368",
  "payment_type" : "credit_card",
  "transaction_time" : "2021-02-26 14:39:33",
  "transaction_status" : "partial_refund",
  "fraud_status" : "accept",
  "approval_code" : "1424936374393",
  "signature_key" : "2802a264cb978fbc59f631c68d120cbda8dc853f5dfdc52301c615cf4f14e7a0b09aa...",
  "bank" : "bni",
  "gross_amount" : "30000.00",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit",
  "refund_amount": "12000.00",
  "refunds": [
    {
      "refund_chargeback_id": 1,
      "refund_amount": "5000.00",
      "created_at": "2015-02-27 00:14:20",
      "reason": "some reason",
      "refund_key": "reference1",
      "refund_method": "online"
    },
    {
      "refund_chargeback_id": 2,
      "refund_amount": "7000.00",
      "created_at": "2015-02-28 01:23:15",
      "reason": "",
      "refund_key": "reference2",
      "refund_method": "offline"
    },
  ]
}

Sample Response - Notification (Bank Confirmed)

{
  "status_code" : "200",
  "status_message" : "midtrans payment notification",
  "transaction_id" : "249fc620-6017-4540-af7c-5a1c25788f46",
  "masked_card" : "481111-1114",
  "order_id" : "example-1424936368",
  "payment_type" : "credit_card",
  "transaction_time" : "2021-02-26 14:39:33",
  "transaction_status" : "partial_refund",
  "fraud_status" : "accept",
  "approval_code" : "1424936374393",
  "signature_key" : "2802a264cb978fbc59f631c68d120cbda8dc853f5dfdc52301c615cf4f14e7a0b09aa...",
  "bank" : "bni",
  "gross_amount" : "30000.00",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit",
  "refund_amount": "12000.00",
  "refunds": [
    {
      "refund_chargeback_id": 1,
      "refund_amount": "5000.00",
      "created_at": "2015-02-27 00:14:20",
      "reason": "some reason",
      "refund_key": "reference1",
      "refund_method": "online",
      "bank_confirmed_at": "2015-02-27 02:30:20"
    },
    {
      "refund_chargeback_id": 2,
      "refund_amount": "7000.00",
      "created_at": "2015-02-28 01:23:15",
      "reason": "",
      "refund_key": "reference2",
      "refund_method": "offline",
      "bank_confirmed_at": "2015-02-27 02:30:20"
    },
  ]
}
JSON Attribute Description Type
status_code Status code of transaction charge result. String
status_message Description of transaction charge result. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
payment_type The payment method used by the customer. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Transaction status after refund action. Possible values are
refund : Transaction is fully refunded.
partial_refund: transaction is partially refunded.		 String
gross_amount Total amount of transaction in IDR. String
refund_chargeback_id Identification of the refund process. String
refund_amount Total amount to be refunded in IDR. String
refund_key Merchant refund reference key. String

For notification JSON attributes, please follow the description on Get Status Response.

Direct Refund Transaction

Unlike the Refund Transaction, Direct Refund transaction is triggered to send the refund request directly to the bank or to the third-party payment provider. This method is faster than the standard operation process which may take one to two days, after the initial refund request. The status of corresponding transaction is updated immediately after receiving refund result from the third-party payment provider. HTTP notification is sent only if the refund is successful.

Direct Refund transaction is only supported for GoPay, QRIS, ShopeePay, and Credit Card payment methods. Currently for Credit Card payment method, Midtrans only supports BCA, MAYBANK, and BRI banks.

For QRIS with acquirers AirPay (Shopee) and ShopeePay, the maximum refund window is 24 hours since the transaction is paid. Refund is not allowed from 11:55 PM to 6:00 AM GMT+7. If you send Direct Refund during this timeframe, the request gets rejected by ShopeePay.

Direct Refund Transaction Method

HTTP Method Endpoint Definition
POST BASE_URL/v2/{order_id **OR** transaction_id}/refund/online/direct Direct Refund Transaction

Direct Refund Transaction Request

Sample Request - Direct Refund Charge

{
  "refund_key": "reference1",
  "amount": 5000,
  "reason": "for some reason"
}
JSON Attribute Description Type Required
refund_key Merchant refund ID. If not passed then Midtrans creates a new refund ID. It is recommended to use this parameter to avoid double refund attempt. String Optional
amount Amount to be refunded. By default whole transaction amount is refund. Long Optional
reason Reason justifying the refund. String(255) Optional

Direct Refund Transaction Response and Notifications

Sample Response - Success

{
  "status_code": "200",
  "status_message": "Success, refund request is approved by the bank",
  "transaction_id": "fddb5889-fd39-46fe-809d-30679fe42434",
  "order_id": "MID-1620622357",
  "gross_amount": "10000.00",
  "payment_type": "credit_card",
  "transaction_time": "2016-06-28 09:42:20",
  "transaction_status": "refund",
  "refund_chargeback_id": 47594,
  "refund_amount": "10000.00",
  "refund_key": "01f1f771-b75c-48ef-b21d-193a79f8aa5b"
}

Sample Response - Rejected Direct Refund

{
  "status_code": "202",
  "status_message": "Refund denied by the bank",
  "transaction_id": "fddb5889-fd39-46fe-809d-30679fe42434",
  "order_id": "MID-1620622357",
  "gross_amount": "10000.00",
  "payment_type": "credit_card",
  "transaction_time": "2016-06-28 09:42:20",
  "transaction_status": "settlement",
  "refund_chargeback_id": 47594,
  "refund_amount": "0.00",
  "refund_key": "01f1f771-b75c-48ef-b21d-193a79f8aa5b"
}

Sample Response - Error (Invalid Direct Refund)

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

Sample Response - Error (Invalid Amount)

{
  "status_code" : "414",
  "status_message" : "Refund request is rejected due to invalid amount"
}

Sample Response - Error (Refund ID Already Exists)

{
  "status_code" : "406",
  "status_message" : "Duplicate refund ID"
}

Sample Response - Notification

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

Sample Response - Notification (Refund Partial Amount)

{
  "status_code": "200",
  "status_message": "midtrans payment notification",
  "transaction_id": "841c7da8-530b-435a-9f67-c9d632d15537",
  "order_id": "1000176721005355",
  "gross_amount": "698879.00",
  "payment_type": "credit_card",
  "transaction_time": "2016-07-04 00:53:55",
  "transaction_status": "partial_refund",
  "signature_key": "f1066b06ec8a4b7d6ffb941fd9772f6df304618e15e02cf17c2914cec12793e19c71653042f7f617b027eae6ecb6759529c67eca9af55264b736408d8b4df2b9"
}
JSON Attribute Description Type
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type The payment method used by the customer. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Transaction status after refund action. Possible values are
refund : Transaction is fully refunded.
partial_refund: transaction is partially refunded.		 String
status_code Status code of transaction charge result. String
status_message Description of transaction charge result. String
refund_chargeback_id Identification of the refund process. String
refund_amount Cumulative amount refunded. String
refund_key Merchant refund reference. Allowed characters are alphabets, numbers, dash (-), and underscore (_). String

Get Transaction Status

Get Transaction Status is triggered to obtain the transaction_status and other details of a specific transaction.

Get Transaction Status Method

Sample Request - Get Transaction Charge

HTTP Method Endpoint Definition
GET BASE_URL/v2/{order_id OR transaction_id}/status Get the status of transaction.

Get Status Transaction Response

Sample Response - Success

{
  "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",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit"
}

Sample Response - Success (Refund)

{
  "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" : "partial_refund",
  "fraud_status" : "accept",
  "approval_code" : "1424936374393",
  "signature_key" : "2802a264cb978fbc59f631c68d120cbda8dc853f5dfdc52301c615cf4f14e7a0b09aa...",
  "bank" : "bni",
  "gross_amount" : "30000.00",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit",
  "refund_amount": "12000.00",
  "refunds": [
    {
      "refund_chargeback_id": 1,
      "refund_amount": "5000.00",
      "created_at": "2015-02-27 00:14:20",
      "reason": "some reason",
      "refund_key": "reference1"
    },
    {
      "refund_chargeback_id": 2,
      "refund_amount": "7000.00",
      "created_at": "2015-02-28 01:23:15",
      "reason": "",
      "refund_key": "reference2"
    },
  ]
}

Sample Response - Success (Refunded Transaction - Bank Confirmed)

{
  "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" : "partial_refund",
  "fraud_status" : "accept",
  "approval_code" : "1424936374393",
  "signature_key" : "2802a264cb978fbc59f631c68d120cbda8dc853f5dfdc52301c615cf4f14e7a0b09aa...",
  "bank" : "bni",
  "gross_amount" : "30000.00",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit",
  "refund_amount": "12000.00",
  "refunds": [
    {
      "refund_chargeback_id": 1,
      "refund_amount": "5000.00",
      "created_at": "2015-02-27 00:14:20",
      "reason": "some reason",
      "refund_key": "reference1",
      "refund_method": "online",
      "bank_confirmed_at": "2015-02-27 02:30:20"
    },
    {
      "refund_chargeback_id": 2,
      "refund_amount": "7000.00",
      "created_at": "2015-02-28 01:23:15",
      "reason": "",
      "refund_key": "reference2",
      "refund_method": "offline",
      "bank_confirmed_at": "2015-02-27 02:30:20"
    },
  ]
}
JSON Attribute Description Type
status_code Status code of transaction charge result String
status_message Description of transaction charge result. String
transaction_id Transaction ID given by Midtrans. String
masked_card First 6-digit and last 4-digit of customer's credit card number. String
order_id Order ID specified by you. String
payment_type The payment method used by the customer. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Transaction status after charge credit card transaction. 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.		 String
fraud_status Detection result by Fraud Detection System (FDS). Possible values are
accept: Approved by FDS.
challenge: Questioned by FDS. Note: Approve transaction to accept it or transaction gets automatically canceled during settlement.
deny: Denied by FDS. Transaction automatically failed.		 String
approval_code Approval code from payment provider for successful transaction. It can be used for refund. String
signature_key Signature key to validate if the notification is originated from Midtrans. String
bank The acquiring bank of the transaction. String
gross_amount Total amount of transaction in IDR. String
channel_response_code Response code from payment channel provider. String
channel_response_message Response message from payment channel provider String
card_type Type of card used. Possible values are credit, debit. String
refund_amount Cumulative refund amount in `IDR`. String
refunds List of refund details related to the transaction. Only available on transaction status partial_refund or refund. JSON Array
   refund_chargeback_id Midtrans refund ID. Integer
   refund_amount Amount of the specific refund. String
   created_at Timestamp of the refund creation. String
   reason Reason the refund is created. String
   refund_key Merchant refund reference. String
   refund_method Refund confirmation method. The value is applied after Midtrans confirm the refund request (1 day after request is made). Possible values are online, offline. String
   bank_confirmed_at Timestamp of receipt of refund request confirmation from acquiring bank. String

Get Transaction Status B2B

Get Transaction Status B2B is triggered to obtain the transaction status for all B2B transactions related to an order_id.

Get Transaction Status B2B Method

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

Get Status Transaction B2B Request

Sample Request - Get Status Transaction B2B

Query Parameter Description Required
page Index of the search. Default is 0. Optional
per_page Number of transactions displayed per page. Default is 10. Optional

Say merchant has five transactions created under a certain order_id A. The transactions are B, C, D, E, F (ordered to the latest). Below are the examples on how merchant can use page and per_page parameters.

  1. per_page is not set, page is not set: Merchant gets F, E, D, C, B, A
  2. per_page is set 2, page is not set: Merchant gets F, E
  3. per_page is set 2, page is set 1: Merchant gets D, C
  4. per_page is set 3, page is set 1: Merchant gets C, B, A

Get Status Transaction B2B Response

Sample Response - Success

{
  "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 Description Type
status_code Status code of transaction charge result String
status_message Description of transaction charge result. String
transactions Details of transaction JSON Array
   payment_type The payment method used by the customer. String
   bill_key String
   transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
   gross_amount Total amount of transaction in IDR. String
   order_id Order ID specified by you. String
   signature_key Signature key to validate if the notification is originated from Midtrans. String
   status_code Status code of transaction charge result. String
   transaction_id Transaction ID given by Midtrans. String
   transaction_status Transaction status after charge credit card transaction. 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.		 String
   fraud_status Detection result by Fraud Detection System (FDS). Possible values are
accept : Approved by FDS.
challenge: Questioned by FDS. Note: Approve transaction to accept it or transaction gets automatically canceled during settlement.
deny: Denied by FDS. Transaction automatically failed.		 String
   status_message Description of transaction charge result. String

Register Card

Register Card can be triggered to register the card information of the customer for future one click and two click transactions.

Register Card Status Method

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

Register Card Request

Sample Request - Register Card Status Charge

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

Register Card Response

Sample Response - Success

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

Point Inquiry

Point Inquiry is triggered to obtain the balance amount on the card.

Point Inquiry Status Method

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

Point Inquiry Request

Sample request - Point inquiry

Query Parameter Description Type Required
gross_amount The amount of the following transaction in IDR. This number can decide the remaining point balance amount which can be used on the response.
Note: Required for Mandiri Point.		 String Conditional

Point Inquiry Response

Sample Response - Success

{
  "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 Description Type
status_code Status code of transaction result. String
status_message Status message of transaction result. String
transaction_time Time of the transactions. String
point_balance_amount Amount corresponding to the point balance in IDR. String

Create Pay Account

Create Pay Account is triggered to link the customer's account to be used for payments using specific payment channel.

HTTP Method Endpoint Definition
POST BASE_URL/v2/pay/account Link the customer account to be used for specific payment channels.

Create Pay Account Request

Sample Request - Create Pay Charge

{
  "payment_type": "gopay",
  "gopay_partner": {
    "phone_number": "81212345678",
    "country_code": "62",
    "redirect_url": "https://www.gojek.com"
  }
}
JSON Attribute Description Type Required
payment_type Payment channel where the account is register to. String Required
gopay_partner GoPay linking specific parameters. Object Conditional
   phone_number Phone number linked to the customer's account. String Required
   country_code Country code associated with the phone number. String Required
   redirect_url URL where user is redirected to after finishing the confirmation on Gojek app. String Optional

Create Pay Account Response

Sample Response - Success

{
  "status_code": "201",
  "payment_type": "gopay",
  "account_id": "00000269-7836-49e5-bc65-e592afafec14",
  "account_status": "PENDING",
  "actions": [
    {
      "name": "activation-link-url",
      "method": "GET",
      "url": "http://api.midtrans.com/v2/gopay/redirect/gpar_6123269-1425-21e3-bc44-e592afafec14/link"
    },
    {
      "name": "activation-link-app",
      "method": "GET",
      "url": "http://api.midtrans.com/v2/gopay/redirect/gpad_6123269-1425-21e3-bc44-e592afafec14/link"
    }
  ]
}

Sample Response - Failed

{
  "status_code": "202",
  "payment_type": "gopay",
  "channel_response_code": "105",
  "channel_response_message": "User Not Found"
}
JSON Attribute Description Type
status_code Status code of the API result. String
payment_type Payment channel associated with the account. String
account_id Customer account id to be used for payment. String
account_status Status of the account. Possible values are PENDING, EXPIRED, ENABLED, and DISABLED. String
channel_response_code Response code from payment channel provider. String
channel_response_message Response message from payment channel provider. String
actions Follow up actions to be performed. Array(Object)

Use any one of the two redirection URLs given below.

Get Pay Account

Get Pay Account is triggered to create a customer account to use for specific payment channel.

Sample Request - Get Pay Account Charge

HTTP Method Endpoint Definition
GET BASE_URL/v2/pay/account/account_id Create customer account to be used for specific payment channels.

Get Pay Account Response

Sample Response - Pending

{
  "status_code": "201",
  "payment_type": "gopay",
  "account_id": "00000269-7836-49e5-bc65-e592afafec14",
  "account_status": "PENDING"
}

Sample Response - Expired

{
  "status_code": "204",
  "payment_type": "gopay",
  "account_id": "00000269-7836-49e5-bc65-e592afafec14",
  "account_status": "EXPIRED"
}

Sample Response - Enabled

{
  "status_code": "200",
  "payment_type": "gopay",
  "account_id": "00000269-7836-49e5-bc65-e592afafec14",
  "account_status": "ENABLED",
  "metadata": {
    "payment_options": [
      {
        "name": "GOPAY_WALLET",
        "active": true,
        "balance": {
          "value": "1000000.00",
          "currency": "IDR"
        },
        "metadata": {},
        "token": "eyJ0eXBlIjogIkdPUEFZX1dBTExFVCIsICJpZCI6ICIifQ=="
      },
      {
        "name": "PAY_LATER",
        "active": true,
        "balance": {
          "value": "350000.00",
          "currency": "IDR"
        },
        "metadata": {},
        "token": "eyJ0eXBlIjogIlBBWV9MQVRFUiIsICJpZCI6ICIifQ=="
      }
    ]
  }
}

Sample Response - Disabled

{
  "status_code": "204",
  "payment_type": "gopay",
  "account_id": "00000269-7836-49e5-bc65-e592afafec14",
  "account_status": "DISABLED"
}
JSON Attribute Description Type
status_code Status code of the API result. String
payment_type Payment channel associated with the account. String
account_id Customer account ID to be used for payment. String
account_status Status of the account. Possible values are PENDING, EXPIRED, ENABLED, and DISABLED. String
metadata Additional data from the specific payment provider, that is, GoPay. Object

Unbind Pay Account

Unbind Pay Account is triggered to remove the linked customer account.

Sample Request - Unbind Pay Charge

HTTP Method Endpoint Definition
POST BASE_URL/v2/pay/account/{account_id}/unbind Unbind a linked customer account.

Unbind Pay Account Response

Sample Response - Success

{
  "status_code": "204",
  "payment_type": "gopay",
  "account_id": "00000269-7836-49e5-bc65-e592afafec14",
  "account_status": "DISABLED",
  "channel_response_code": "0",
  "channel_response_message": "Process service request successfully."
}

Sample Response - Denied

{
  "status_code": "202",
  "payment_type": "gopay",
  "account_id": "00000269-7836-49e5-bc65-e592afafec14",
  "channel_response_code": "1001",
  "channel_response_message": "Caller authentication error."
}
JSON Attribute Description Type
status_code Status code of the API result. String
payment_type Payment channel associated with the account. String
account_id Customer account id to be used for payment. String
account_status Status of the account.
Possible values are PENDING, EXPIRED, ENABLED, DISABLED.		 String
channel_response_code Response code from payment channel provider. String
channel_response_message Response message from payment channel provider. String

Bin API

Bin API is triggered to get metadata for a particular bin, such as card type (Credit or Debit), the card network provider (Visa, MasterCard), and so on.

Bin API Method

Sample Request - Bin Charge

HTTP Method Endpoint Definition
GET BASE_URL/v1/bins/bin_number Get Bin Metadata.

Bin API Response

Sample Response - Success

{
    "data": {
        "country_name": "Indonesia",
        "country_code": "id",
        "brand": "visa",
        "bin_type": "credit",
        "bin_class": "gold",
        "bin": "455633",
        "bank_code": "bca",
        "bank": "bank central asia"
    }
}
JSON Attribute Description Type Required
data Information about the card. Object Conditional
   country_name Name of the country from which the card is issued. For example, Indonesia. String Optional
   country_code The country code. For example, id. String Optional
   brand The card network provider. For example, visa. String Optional
   bin_type The type of BIN. For example, credit. String Required
   bin_class The class of BIN. For example, gold. String Optional
   bin Requested Bin number. For example, 455633. String Required
   bank_code The three letter bank code. For example, bca. String Optional
   bank Name of the bank on the card. For example, Bank Central Asia. String Optional

Authorization Header

The request is authorized using the same method as HTTP(S) Request. Either the Midtrans Client Key or Midtrans Server key can be used.

It is highly recommended to use Midtrans Client Key if the request is made from a browser or a mobile device.

Rate Limit

Bin requests are rate-limited by 100 requests per minute. If the number of attempted requests exceeds the limit, Midtrans API responds with 409 status code.

Response Codes

Code Description
200 OK.
404 Particular Bin does not exist.
401 Credential is empty or wrong. Please recheck the authorization configuration.
409 Request exceeds the rate limit.

Response Object

JSON Attribute Description Type Required
bank The name of the bank on the card. For example, Bank Central Asia. String Optional
bank_code The bank code. For example, bca. String Optional
bin The requested Bin number. For example, 455633. String Required
bin_type The type of payment card. For example, credit or debit. String Required
bin_class Card Class. For example, gold. String Optional
brand The name of the bank issuing the payment card. For example, visa. String Optional
country_name Country issuing the payment card. For example, Indonesia. String Optional
country_code Code name of the country issuing the payment card. For example, id. String Optional

Idempotent Requests

Idempotency-Key is a unique value that is put on header on API requests. Midtrans API accepts Idempotency-Key on header to safely handle retry request without performing the same operation twice. This is helpful for cases where you have not received the response because of network issue or other unexpected error.

Use case sample:

If you send a request with idempotency key:A, but Midtrans doesn't send any response due to unexpected error, you can safely retry request with idempotency key:A, to get a response. It is ensured that the request is processed only once.

Midtrans handles idempotent request by saving only the successful response. Midtrans returns this response to you if you create a request with the same Idempotency-Key regardless of the request body. Please note that the key value lifetime is five minutes. After five minutes, Midtrans processes the request again. For example, second charge request might get conflict exception because it uses the same order id. It is important to note that the Idempotency-Key is global across any endpoints. It is recommended to generate a new Idempotency-Key value for every different operation on the same transaction.

There's also a special case where we handle an "on-process" request. If you retry a request while the first request is still in process and have not received a response yet, Midtrans returns a response with HTTP status code 202 until the first request finishes processing.

Midtrans API accepts Idempotency-Key value on all POST requests except request to /token and /account endpoint.

The maximum length of Idempotency-Key is 36. Midtrans ignores the usage of Idempotency-Key if it is longer than the maximum length. To create random unique key, we suggest the use of UUID to avoid Idempotency-Key collision between requests.

Subscription API

Subscription API is intended for recurring transactions - transactions that deduct customer's funds at a pre-defined time interval.

You can perform recurring transaction by creating subscription details. Midtrans will attempt to auto-deduct customer funds at the set time interval based on the subscription details (subscription schedule, amount, currency, and so on) created. Hence, you need not do recurring transactions manually.

API Methods

HTTP Method Endpoint Definition
POST /v1/subscriptions Create a subscription that contains all the details for creating transaction.
GET /v1/subscriptions/subscription_id Retrieve the subscription details with a given subscription_id.
POST /v1/subscriptions/subscription_id/disable Disable the customer's subscription. The customer will not be charged in the future for this subscription.
POST /v1/subscriptions/subscription_id/enable Enable the customer's subscription.
PATCH /v1/subscriptions/subscription_id Update existing subscription details.

Create Subscription

Create a subscription transaction by sending all the details required to create a transaction. The details such as name, amount, currency, payment_type, token, and schedule are sent in the request. Successful request returns id status:active, and other subscription details.

Create Subscription Method

HTTP Method Endpoint Description
POST BASE_URL/v1/subscriptions Create subscription

Create Subscription Request

Sample Request - Create Subscription

{
    "name": "MONTHLY_2019",
    "amount": "14000",
    "currency": "IDR",
    "payment_type": "credit_card",
    "token": "481111DasKBLCCXbuKfEbVlFiBZr1114",
    "schedule": {
      "interval": 1,
      "interval_unit": "month",
      "max_interval": 12,
      "start_time": "2020-07-22 07:25:01 +0700"
    },
    "metadata": {
      "description": "Recurring payment for A"
    },
    "customer_details": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "johndoe@email.com",
      "phone": "+62812345678"
    },
    "gopay": {
      "account_id": "0dd2cd90-a9a9-4a09-b393-21162dfb713b"
    }
}
JSON Attribute Description Type Required
name Name of the subscription. It is used to generate order ID for the transaction.
Note: Allowed symbols are dash(-), underscore(_), tilde (~), and dot (.).		 String(15) Required
amount The amount to be charged to the customer.
Note: Do not use decimal.		 String Required
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.		 String Required
payment_type The payment method used by the customer. Value: credit_card.
Note: Currently only credit_card is supported.		 String Required
token The saved_token_id received in the Charge response. String Required
schedule Details of the subscription schedule. Object Required
metadata Metadata of subscription specified by you.
Note: Limit the size to less than 1KB.		 Object Optional
customer_details Details of the customer. Object Optional
gopay GoPay subscription information, required if payment type is gopay. Object Optional

Create Subscription Response

Sample Response - Success

{
  "id": "d98a63b8-97e4-4059-825f-0f62340407e9",
  "name": "MONTHLY_2019",
  "amount": "14000",
  "currency": "IDR",
  "created_at": "2019-05-29T09:11:01.810452",
  "schedule": {
    "interval": 1,
    "interval_unit": "month",
    "start_time": "2019-05-29T09:11:01.803677",
    "previous_execution_at": "2019-05-29T09:11:01.803677",
    "next_execution_at": "2019-06-29T09:11:01.803677"
  },
  "status": "active",
  "token": "481111DasKBLCCXbuKfEbVlFiBZr1114",
  "payment_type": "credit_card",
  "metadata": {
    "description": "Recurring payment for A"
  },
  "customer_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@email.com",
    "phone": "+62812345678"
  }
}
JSON Attribute Description Type
id Subscription ID given by Midtrans. String
name Subscription name specified by you. String
amount Amount specified by you for recurring charge. String
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.		 String
created_at Subscription schedule creation timestamp in ISO 8601 format. Time Zone: GMT + 7. String
schedule Details of the subscription schedule. Object
status Current subscription status.
Possible values are active, inactive.		 String
token Payment token used for subscription. String
payment_type The payment method used by the customer. Value: credit_card.
Note: Currently only credit_card is supported.		 String
metadata Metadata of subscription specified by you.
Note: Limit the size to less than 1KB.		 Object
customer_details Details of the customer. Object
status_message Description of the error. String
validation_message Detailed description of the error. Array(String)

Sample Response - Status Code: 400

{
  "status_message": "Invalid parameter.",
  "validation_messages": [
    "subscription.amount is required"
  ]
}

Sample Response - Status Code: 500

{
  "status_message": "Sorry, Our system is recovering from unexpected issues. Please retry."
}

Get Subscription

Retrieve the subscription details of a customer using the subscription_id. Successful request returns subscription object and status:active.

Get Subscription Method

HTTP Method Endpoint Description
GET BASE_URL/v1/subscriptions/{subscription_id} Retrieve subscription details

Get Subscription Response

Sample Response - Success

{
  "id": "d98a63b8-97e4-4059-825f-0f62340407e9",
  "name": "MONTHLY_2019",
  "amount": "14000",
  "currency": "IDR",
  "created_at": "2019-05-29T09:11:01.810452",
  "schedule": {
    "interval": 1,
    "interval_unit": "month",
    "start_time": "2019-05-29T09:11:01.803677",
    "previous_execution_at": "2019-05-29T09:11:01.803677",
    "next_execution_at": "2019-06-29T09:11:01.803677"
  },
  "status": "active",
  "token": "481111DasKBLCCXbuKfEbVlFiBZr1114",
  "payment_type": "credit_card",
  "transaction_ids": [
    "9beb839d-8fe2-41ec-bc5e-045e5001d286",
    "eb47cd5d-acd3-4e53-a155-7bd41aa38052",
    "9d286585-bd19-43be-95dc-da3d32ab18af",
    "ec3175c6-9f0a-4ce5-9332-abfb1db0852f",
    "00f7d40d-26e2-4624-a797-9ddc54ca9987",
    "421bd123-d8b2-4476-bcea-165f9e176cbb"
  ],
  "metadata": {
    "description": "Recurring payment for A"
  },
  "customer_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@email.com",
    "phone": "+62812345678"
  }
}
JSON Attribute Description Type
id Subscription ID given by Midtrans. String
name Subscription name given by you. String
amount Amount specified by you for recurring charge. String
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.		 String
created_at Timestamp at which the subscription schedule is created in ISO 8601 format. Time Zone (GMT+7). String
schedule Details of the subscription schedule. Object
status Current subscription Status.
Note: Possible status values are active and inactive.		 String
token Payment token used for subscription. String
payment_type The payment method used by the customer. Value: credit_card.
Note: Currently only credit_card is supported.		 String
transaction_ids List of transaction IDs which are successfully charged. Array(String)
metadata Metadata of subscription specified by you.
Note: Limit the size to less than 1KB.		 Object
customer_details Details of the customer. Object
status_message Description of the error String

Sample Response - Status Code: 404

{
  "status_message": "Subscription doesn't exist."
}

Sample Response - Status Code: 500

{
  "status_message": "Sorry, Our system is recovering from unexpected issues. Please retry."
}

Disable Subscription

Disable a customer's subscription account with a specific subscription_id so that the customer is not charged for the subscription in the future. Successful request returns status_message indicating that the subscription details are updated.

Disable Subscription Method

HTTP Method Endpoint Description
POST BASE_URL/v1/subscriptions/{subscription_id}/disable Disable subscription

Disable Subscription Response

Sample Response - Success

{
  "status_message": "Subscription is updated."
}
JSON Attribute Description Type
status_message Message describing the status of the result of API request. String

Sample Response - Status Code: 404

{
  "status_message": "Subscription doesn't exist."
}

Sample Response - Status Code: 500

{
  "status_message": "Sorry, our system is recovering from unexpected issues. Please retry."
}

Enable Subscription

Activate a customer's subscription account with a specific subscription_id, so that the customer can start paying for the subscription immediately. Successful request returns status_message indicating that the subscription details are updated.

Enable Subscription Method

HTTP Method Endpoint Description
POST BASE_URL/v1/subscriptions/{subscription_id}/enable Enable subscription

Enable Subscription Response

Sample Response - Success

{
  "status_message": "Subscription is updated."
}
JSON Attribute Description Type
status_message Status message describing the result of the API request. String

Sample Response - Status Code: 404

{
  "status_message": "Subscription doesn't exist."
}

Sample Response - Status Code: 500

{
  "status_message": "Sorry, Our system is recovering from unexpected issues. Please retry."
}

Update Subscription

Update the details of a customer's existing subscription account with the specific subscription_id. Successful request returns status_message indicating that the subscription details are updated.

Update Subscription Method

HTTP Method Endpoint Description
PATCH BASE_URL/v1/subscriptions/{subscription_id} Update subscription

Update Subscription Request

Sample Request Body

{
    "name": "MONTHLY_2019",
    "amount": "14000",
    "currency": "IDR",
    "token": "481111DasKBLCCXbuKfEbVlFiBZr1114",
    "schedule": {
      "interval": 1
    },
    "gopay": {
      "account_id": "0dd2cd90-a9a9-4a09-b393-21162dfb713b"
    }
}
JSON Attribute Description Type Required
name Subscription name specified by you.
Note: Allowed symbols are dash(-), underscore(_), tilde (~), and dot (.).		 String(15) Required
amount Amount specified by you for recurring charge. String Required
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.		 String Required
token Saved payment token.
Note: For credit_card, use saved_token_id received in Charge response.		 String Required
schedule Details of the subscription schedule. Object Required
gopay Gopay subscription information. Object Optional

Update Subscription Response

Sample Response - Successful

{
  "status_message": "Subscription is updated."
}
JSON Attribute Description Type
status_message Message describing the status of the result of API request. String

Sample Response - Status Code: 404

{
  "status_message": "Subscription doesn't exist."
}

Sample Response - Status Code: 500

{
  "status_message": "Sorry, Our system is recovering from unexpected issues. Please retry."
}

Card Payment

Using Card payment method, customers can make payments using a credit card or any online-transaction-capable debit card within Visa, MasterCard, JCB, or Amex network. Midtrans sends real-time notification when the customer completes the payment.

The steps to integrate with Midtrans are given below.

  1. Get token.
  2. Send Charge request using the token.
  3. For 3D secure transactions, redirect the customer to the address specified in the response. (Optional)
  4. Handle notifications.

Charge Transactions on Card

Charge method is triggered every time a transaction is performed. Send a Charge API request with payment details, transaction details, card details, customer details, item details, and shipping address. Successful request returns status_code:200. The attribute that is used is dependent on the payment method desired.

Card Charge Request

Sample Request - Card Charge

{
  "payment_type": "credit_card",
  "transaction_details": {
    "order_id": "C17550",
    "gross_amount": 145000
  },
  "credit_card": {
    "token_id": "< your token ID >"
  },
  "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"
      }
    }
}
JSON Attribute Description Type Required
payment_type The payment method used by the customer.
Value: credit_card.
Note: For any transactions using payment card (credit or debit), payment_type is credit_card.		 String (255) Required
transaction_details The details of the specific transaction such as order_id and gross_amount. Object Required
credit_card The details of the payment card used for the transaction. Object Required
item_details Details of the item(s) purchased by the customer. Object Optional
customer_details Details of the customer. Object Optional

Card Charge Response and Notifications

Sample Response - Success

{
  "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",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "currency": "IDR",
  "card_type": "credit"
}

Sample Response - Error

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

Sample Response - Capture Notification

{
  "masked_card": "481111-1114",
  "approval_code": "T58755",
  "bank": "bni",
  "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": "midtrans payment notification",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit"
}

Sample Response - Deny Notification

{
  "masked_card": "481111-1114",
  "approval_code": "338016",
  "bank": "bni",
  "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": "midtrans payment notification",
  "channel_response_code": "05",
  "channel_response_message": "Do not honor",
  "card_type": "credit"
}

Sample Response - Challenge Notification

{
  "masked_card": "481111-1114",
  "approval_code": "315762",
  "bank": "bni",
  "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": "midtrans payment notification",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit"
}

Sample Response - Settlement Notification

{
  "masked_card": "481111-1114",
  "approval_code": "131755",
  "bank": "bni",
  "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": "midtrans payment notification",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit"
}
JSON Attribute Description Type
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type The payment method used by the customer.
Value: credit_card.
Note: For any transactions using payment card (credit or debit), payment_type is credit_card.		 String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Transaction status after charge card transaction. Possible values are
capture: Transaction is accepted by the bank and ready for settlement.
deny: Transaction is denied by the bank or FDS.
authorize: Card is authorized in Pre-authorization feature.		 String
fraud_status Detection result by Fraud Detection System (FDS). Possible values are
accept: Approved by FDS.
challenge: Questioned by FDS.
Note: Approve transaction to accept it or transaction gets cancelled automatically during settlement.
deny: Denied by FDS. Transaction automatically failed.		 String
masked_card First 6-digits and last 4-digits of customer's card number. String
status_code Status code of transaction charge result. String
bank The name of the Acquiring Bank. String
status_message Status message describing the result of the API request. String
approval_code Approval code. It can be used for refund. This does not exist on denied transaction. String
channel_response_code Response code from payment channel provider. String
channel_response_message Response message from payment channel provider. String
card_type Type of payment card used for the transaction. Possible values are credit, debit. String

The transaction_status and fraud_status attributes are the two most important details received in the JSON response.

Card Feature: 3D Secure (3DS)

Three Domain Secure (3DS) is a security feature which requires the customer to complete an additional verification step while making payments using card. 3DS can be enabled/disabled for specific transactions. Always enable 3DS, to prevent unnecessary security and chargeback risks. Successful request returns `redirect_url` to redirect customer to the authentication page. After completing the authentication process, you will receive notification containing the transaction details and 3DS result.

3D Secure 2 (3DS2) is the new authentication protocol for online card payments. 3DS2 is designed to improve upon 3D Secure 1 (3DS1) by addressing the old protocol's pain points, and delivering a much smoother and integrated user experience. Registration of card and password is not required by the cardholder, unlike in 3DS1.

For merchants who already implement 3DS 1.0 New flow(Authentication field in Charge Request) there is no request changes, because Midtrans will automatically handle 3DS 2.0
Since 3DS 2.0 already support frictionless flow, not all transactions goes through the 3DS process will be directed to OTP challenge.
- If transaction is considered safe by 3DS 2.0, the transaction will be processed immediately without Challenge OTP (Frictionless benefit).
- If 3DS 2.0 transaction require OTP Challenge, there will be new flow changes that were previously Synchronous for 3DS 1.0 but for 3DS 2.0 will become Asynchronous. So after Challenge OTP, the transaction could be still Pending. Merchant needs to wait for successful notification from Midtrans or try Get Status to Midtrans several times in next minute to check for transaction status.
- there is a new field "three_ds_challenge_completion" on response to indicate the customer has submit the OTP or not(it doesn't matter if the OTP is valid or not). Since 3DS 2.0 is Asynchronous this field may still not be updated due to 3DS Server having a delay when sending the notification related to this state to Midtrans.

3DS Charge Request

Sample Request - 3DS Charge

{
  "payment_type": "credit_card",
  "transaction_details": {
    "order_id": "C17550",
    "gross_amount": 145000
  },
  "credit_card": {
    "token_id": "< your token ID >",
    "authentication": true,
    "callback_type": "js_event"
  }
}

The credit_card object in Charge request to configure 3DS feature is identical with Card Charge Request, with the additional attributes given below.

JSON Attribute Description Type Required
token_id Token ID represents customer's card information acquired from Get Card Token response. String Required
authentication Flag to enable the 3D secure authentication. Default value is false. Boolean Optional
callback_type Determines how the transaction status is updated to the merchant frontend. Possible values are js_event (default) and form. For more details, refer Handling 3DS Callback. String Optional

3DS Charge Response and Notifications

Sample Response - Success

{
  "status_code": "201",
  "status_message": "Credit Card transaction is in progress",
  "transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "order_id": "C17550",
  "redirect_url": "https://api.veritrans.co.id/v2/token/rba/redirect/451249-2595-e14aac7f-cfb3-4ab2-98ab-5cc5e70f4b2c",
  "gross_amount": "145000.00",
  "currency": "IDR",
  "payment_type": "credit_card",
  "transaction_time": "2018-09-12 22:10:23",
  "transaction_status": "pending",
  "masked_card": "481111-1114",
  "card_type": "credit",
  "three_ds_version": "2"
}

Sample Response - Pending after submit OTP 3DS 2.0

{
  "status_code": "201",
  "status_message": "Credit Card transaction is in progress",
  "transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "order_id": "C17550",
  "redirect_url": "https://api.veritrans.co.id/v2/token/rba/redirect/451249-2595-e14aac7f-cfb3-4ab2-98ab-5cc5e70f4b2c",
  "gross_amount": "145000.00",
  "currency": "IDR",
  "payment_type": "credit_card",
  "transaction_time": "2018-09-12 22:10:23",
  "transaction_status": "pending",
  "masked_card": "481111-1114",
  "card_type": "credit",
  "three_ds_version": "2",
  "three_ds_challenge_completion": false
}

Sample Response - Error Response

{
  "status_code": "400",
  "status_message": "One or more parameters in the payload is invalid.",
  "id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "validation_messages": [
    "unsupported token request parameter(s)"
  ]
}

Sample Response - 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": "midtrans payment notification",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit",
  "three_ds_version": "2"
}

Sample Response - Capture Notification after submit OTP 3DS 2.0

{
  "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": "midtrans payment notification",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit",
  "three_ds_version": "2",
  "three_ds_challenge_completion": true
}

Sample Response - 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": "midtrans payment notification",
  "channel_response_code": "05",
  "channel_response_message": "Do not honor",
  "card_type": "credit",
  "three_ds_version": "2"
}

Sample Response - 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": "midtrans payment notification",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit",
  "three_ds_version": "2"
}

Sample Response - 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": "midtrans payment notification",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit",
  "three_ds_version": "2"
}

The 3DS response is identical with Card Payment Charge Response, with the additional attributes given below.

JSON Attribute Description Type
redirect_url The URL to redirect the user to 3D Secure authentication page. String
eci The 3D secure ECI Code indicating the result of the 3DS process. String

Handling 3DS Callback (Already Support 3DS 2.0)

By default, 3DS callback scheme is set as js_event. It is optimized for merchants who prefer to open the 3DS page without leaving from their page.

Midtrans JavaScript library provides functions to handle the redirect URL and its callback response.

Authenticate function from the JavaScript Library to handle the redirect URL and callback response

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

//Authenticate function
Veritrans.authenticate(redirect_url, callback);

Sample Callback Function Implementation

function callback(response) {
  if (response.redirect_url) {
    // initially Midtrans will put the redirect URL into the response
    // it will be up to merchant on how to open it
    console.log('Open Dialog 3Dsecure');
    openDialog(response.redirect_url);

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

    handleSuccessfulResponse(response);
  } else {
    // failed transaction
    // close 3d secure dialog if any
    closeDialog();

    handleFailedResponse(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();
}

function handleSuccessfulResponse(response) {
  // dummy function
}

function handleFailedResponse(response) {
  // another dummy function
}

Callback via form is a simple web redirection. From the merchant website, the customer is redirected to 3DS page and then back to merchant website. For callback via js-event open 3DS page in an iFrame, and the callback happens as a JSONP.

JSON Attribute Description Type
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type The payment method used by the customer.
Value: credit_card.
Note: For any transactions using payment card (credit or debit), payment_type is credit_card.		 String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Transaction status after charge card transaction. Possible values are
capture: Transaction is accepted by the bank and ready for settlement.
deny: transaction is denied by the bank or FDS.
authorize: card is authorized in Pre-authorization feature.
pending: Credit card is pending and you will need to rely on the http notification webhook to receive the final transaction status.		 String
fraud_status Detection result by Fraud Detection System (FDS). Possible values are
accept: Approved by FDS.
challenge: Questioned by FDS.
Note: Approve transaction to accept it or transaction will get cancelled automatically during settlement.
deny: Denied by FDS. Transaction automatically failed.		 String
masked_card First 6-digits and last 4-digits of customer's card number. String
status_code Status code of transaction charge result. String
bank The name of the Acquiring Bank. String
status_message Status message describing the result of the API request. String
approval_code Approval code. It can be used for refund. This does not exist on denied transaction. String
eci The 3D secure ECI Code indicating the result of the 3DS process. String
channel_response_code Response code from payment channel provider. String
channel_response_message Response message from payment channel provider. String
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.		 String
card_type Type of payment card used for the transaction. Possible values are credit, debit. String
three_ds_version 3DS Version that used for transaction (This field only present for 3DS Transaction). Possible values are 1, 2 String
three_ds_challenge_completion 3DS Challenge completion state to indicate the customer has been submitted the OTP or not(it doesn't matter if the OTP is valid or not). Possible values are true, false Boolean

Card Feature: BIN Promo

Midtrans allows its partners to use certain promotions on card transactions. The additional attributes in credit-card object required to configure BIN Promo feature are token_id, bins, bank. Successful request returns transaction_status:capture and is ready for settlement.

BIN Promo Charge Request

Sample Request - BIN Promo Charge

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

The credit_card object in Charge request to configure BIN Promo feature is identical with Card Charge Request, with the additional attributes given below.

JSON Attribute Description Type
token_id Token ID represents customer's card information acquired from Get Card Token response. String
bank The name of the Acquiring Bank. String
bins List of card's BIN (Bank Identification Number) allowed for transaction.
For example "bins": ["48111111", "bni", "5"]; 48111111 = Allows only card number beginning with 48111111, bni = Allows only card issued by BNI, 5 = Allows only card beginning with 5 (Mastercard).		 JSON Array

BIN Promo Charge Response and Notifications

The 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.

Sample Response - BIN Promo Charge

Card Feature: Installment

You can use Midtrans Installment Payment feature so that the customers can pay their bills in small amounts over a fixed period of time. These can be Online Installment Payment or Offline Installment Payment depending on the Acquiring Bank and the Card Issuing Bank. Successful request returns transaction_status:capture and is ready for settlement.

Online Installment Charge Request

In Online Installment feature, the Acquiring Bank and the Card Issuing Bank are the same.

You need a token from Get Card Token response to charge with Online Installment feature.

Sample Request - Online Installment Charge

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

The credit_card object in Charge request to configure Online Installment feature is identical with Card Charge Request, with the additional attributes given below.

JSON Attribute Description Type
token_id Token ID represents customer's card information acquired from Get Card Token response. String
bank The name of the Acquiring Bank. Note: For Online installment, Acquiring Bank and Card Issuing Bank are the same. String
installment_term Installment tenure in months. Integer

Online Installment Charge Response and Notifications

Sample Response - Success

{
      "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",
      "channel_response_code": "00",
      "channel_response_message": "Approved",
      "currency": "IDR",
      "card_type": "credit"
}

Sample Response - Online Installment Capture

{
  "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": "midtrans payment notification",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit"
}

Successful installment transaction responds with transaction_status: capture and is ready for settlement.

Offline Installment

Sample Request - 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 allows merchants to do installment conversion for transactions which are not supported by MID installment.

The credit_card object in Charge request to configure Offline Installment feature is identical with Card Charge Request, with the additional attribute bins. The purpose of bins is to limit the use of certain cards depending on the agreement between you and the bank.

JSON Attribute Description Type
token_id Token ID represents customer's card information acquired from Get Card Token response. String
bank The name of the Acquiring Bank. Note: For Offline installment, Acquiring Bank and Card Issuing Bank are different. String
installment_term Installment tenure in months. Integer
bins List of card's BIN (Bank Identification Number) that is allowed for transaction. JSON Array

Offline Installment Charge Response and Notifications

Sample Response - Success

{
   "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",
   "channel_response_code": "00",
   "channel_response_message": "Approved",
   "currency": "IDR",
   "card_type": "credit"
}

Sample Response - 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": "midtrans payment notification",
  "card_type": "credit"
}

Successful installment transaction responds with transaction_status: capture and is ready for settlement.

Card Feature: Pre-Authorization

Pre-authorization payment feature temporarily blocks the fund from the customer's account. Successful Pre-authorization can be settled only if the transaction has been captured. You can initiate "capture" action through Capture API. By default, reserved fund will be released after seven days if there is no "capture" action for that transaction.

You need a token from Get Card Token response to charge with Pre-authorization feature.

Pre-Authorization Charge Request

Sample Request - Pre-Authorization Charge

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

The credit_card object in Charge request to configure Pre-authorization feature is identical with Card Payment Charge Request, with the additional attributes given below.

JSON Attribute Description Type
token_id Token ID represents customer's card information acquired from Get Card Token response. String
type Flag to indicate if the transaction is pre-authorized or automatically captured. Valid value: authorize. String

Pre-Authorization Charge Response and Notifications

Sample Response - Success

{
    "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",
    "channel_response_code": "0",
    "channel_response_message": "Approved",
    "currency": "IDR",
    "card_type": "credit"
}

Sample Response - Pre-Authorization

{
  "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": "midtrans payment notification",
  "channel_response_code": "0",
  "channel_response_message": "Approved",
  "card_type": "credit"
}

Pre-authorization Charge response is different from the Card Payment Charge response. Successful Pre-authorization transaction is described as authorize and can be settled only if the transaction has been captured. To charge the customer after Pre-authorization, Capture Transaction method is used with transaction_status set to authorize. If the transaction is captured, the transaction status is updated to capture and is ready for settlement.

Capture Transaction Method

Endpoint HTTP Method Definition
BASE_URL/capture POST Capture a Pre-authorized transaction.

Capture Transaction Request

Sample Request - Capture transaction

{
    "transaction_id" : "1ac1a089d-a587-40f1-a936-a7770667d6dd",
    "gross_amount" : 55000 // <--- Value should not exceed the Charge Value on Pre-Authorization
}
JSON Attribute Description Type
transaction_id Transaction ID from Charge Pre-Authorization Response. String
gross_amount Total amount of transaction in IDR.
Note: This value should not exceed gross_amount specified in Pre-Authorization Charge request. If left undefined, capture full transaction amount specified in Pre-Authorization Charge request.		 Long

Capture Transaction Response and Notification

Sample Response - Success

{
    "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",
    "channel_response_code": "0",
    "channel_response_message": "Approved",
    "currency": "IDR",
    "card_type": "credit"
}

Sample Response - Capture 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": "midtrans payment notification",
  "channel_response_code": "0",
  "channel_response_message": "Approved",
  "card_type": "credit"
}
JSON Attribute Description Type
status_code Status code of transaction charge result. String
status_message Description of transaction charge result. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by merchant. String
gross_amount Total amount of transaction in IDR. String
payment_type The payment method used by the customer. Value: credit_card.
Note: For any transactions using payment card (credit or debit), payment_type is credit_card.		 String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Transaction status after charge card transaction. Possible values are
capture: Transaction is accepted by the bank and ready for settlement.
deny: Transaction is denied by the bank or FDS.
authorize: Card is authorized in Pre-authorization feature.		 String
fraud_status Detection result by Fraud Detection System (FDS). Possible values are
accept: Approved by FDS.
challenge: Questioned by FDS.
Note: Approve transaction to accept it, or the transaction will get cancelled automatically during settlement.
deny: Denied by FDS. Transaction automatically failed.		 String
approval_code Approval code from payment provider for successful transaction. It can be used for refund. String
eci The 3D secure ECI Code indicating the result of the 3DS process. String
masked_card First 6-digits and last 4-digits of customer's card number. String
bank The name of the Acquiring Bank. String
channel_response_code Response code from payment channel provider. String
channel_response_message Response message from payment channel provider. String
card_type Type of payment card used for the transaction. Possible values are credit, debit. String

Card Feature: One Click

One Click feature allows your customers to make purchases with just one click using previously saved payment information. The additional attributes in credit-card object required to configure One Click feature are token_id, saved_token_id. Successful request returns transaction_status:capture and is ready for settlement.

You need a token from Get Card Token response to charge with One Click feature.

One Click Initial Charge Request

Sample Request - 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
    }
}

The credit_card object in Charge request to configure the initial One Click feature is identical with Card Charge Request, with the additional attributes given below.

JSON Attribute Description Type
token_id Token ID represents customer's card information acquired from Get Card Token response. String
save_token_id A flag to indicate whether the token_id is saved for future transactions. Boolean

One Click Initial Charge Response and Notifications

Sample Response - Card Payment Initial One Click

{
    "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",
    "bank": "bni",
    "channel_response_code": "00",
    "channel_response_message": "Approved",
    "currency": "IDR",
    "card_type": "credit"
}

Sample Response - Initial One Click 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": "midtrans payment notification",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit"
}

One Click Initial Charge response and notifications are identical with Card Payment Charge response and notifications, with additional attributes given below.

JSON Attribute Description Type
saved_token_id Token ID of a card to be charged for the future transactions. String
saved_token_id_expired_at Expiry date of the Token ID. String

One Click Subsequent Charge

Sample Request - Subsequent 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 future One Click transactions.

JSON Attribute Description Type
token_id saved_token_id represents customer's card information acquired from One Click initial Charge response. String

One Click Subsequent Charge Response and Notifications

Subsequent One Click Charge response is identical with [Card Payment Charge Response](#card -charge-response-and-notifications). Successful One Click transaction is described as capture and is ready for settlement.

Card Feature: Two Clicks

Two Click feature allows your customers to make purchases with just two clicks using previously saved card information and CVV number. Customers can save their card credentials and to trigger a payment, the customer has to input CVV only.

You need a token from Get Card Token response to charge with Two Clicks feature.

Two Clicks Initial Charge

Sample Request - 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
    }
}

The credit_card object in Charge request to charge the initial transaction for Two Clicks feature is identical with Card Charge Request, with the additional attributes given below.

JSON Attribute Description Type
token_id Token ID represents customer's card information acquired from Get Card Token response. String

Two Clicks Initial Charge Response and Notifications

Sample Response - Two Clicks Initial Charge

{
    "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",
    "bank": "bni",
    "channel_response_code": "00",
    "channel_response_message": "Approved",
    "currency": "IDR",
    "card_type": "credit"
}

Sample Response - 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": "midtrans payment notification",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit"
}

Two Clicks initial Charge response is identical with Card Payment Charge Response, with the additional attributes given below.

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

Two Clicks Subsequent Charge

Sample Request - 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
    }
}

In order to charge the Two Clicks transaction, you need the Card Token from GET Token.

JSON Attribute Description Type
token_id Token ID represents customer's card information acquired from Get Card Token response. String

Two Clicks Subsequent Payment Response and Notifications.

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

Card Feature: Point

Sample Request - 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
    }
}

To perform point transaction, you need to send point_redeem_amount parameter. You can get the value from Point Inquiry API. Currently, point transaction is only supported by BNI and Mandiri.

The credit_card object in Charge request for Point feature is identical with Card Charge Request, with the additional attributes given below.

JSON Attribute Description Type
token_id Token ID represents customer's card information acquired from Get Card Token response. String
bank The name of the Acquiring Bank. To make sure the request is going on-us. String
point_redeem_amount Amount to be redeemed with point.
Note: Use -1 for full redemption. For Mandiri, you can only do full redemption. For partial redemption in BNI, you can redeem the point_redeem_amount lesser than the point_balance_amount received on Point Inquiry API.		 Long

Point Charge Response and Notifications

Sample Response - Success

{
    "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_redeem_quantity": 1450,
    "point_balance_amount": "0.00",
    "approval_code": "1408940508666",
    "gross_amount": "145000.00",
    "bank": "bni",
    "channel_response_code": "00",
    "channel_response_message": "Approved",
    "currency": "IDR"
}

Sample Response - Notification

{
  "masked_card": "481111-1114",
  "approval_code": "1408940508666",
  "bank": "bni",
  "eci": "05",
  "point_redeem_amount": 145000,
  "point_redeem_quantity": 1450,
  "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": "midtrans payment notification",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit"
}

Point Charge response is identical with Card Payment Charge Response, with the additional attributes given below.

JSON Attribute Description Type
point_redeem_amount Amount redeemed in IDR. Long
point_redeem_quantity Point representation of point_redeem_amount. Long
point_balance_amount Balance amount in IDR. String

Card Payment - Full PAN

Full PAN simplifies the process of recurring transaction on payment card by removing the tokenization step in a normal Card Payment transaction. This can be used only if you have a PCI license.

To better understand the integration, the transactions are categorized into the following:

Non-3DS Integration

Send a Charge API request with payment_type, transaction_details, cstore, customer_details, item_details. Successful response returns the redirect_url. The steps to integrate with Non-3DS are given below.

  1. Send the Charge request to Midtrans.
  2. Handle notifications.

Non 3DS Full PAN Charge Request

Sample Request - Non 3DS Full PAN Charge

{
  "payment_type": "credit_card",
  "transaction_details": {
    "order_id": "C17550",
    "gross_amount": 145000
  },
  "credit_card": {
    "card": {
      "number": "4811111111111114",
      "expiry_month": "3",
      "expiry_year": "2020",
      "cvv": "123"
    },
    "dynamic_descriptor": {
      "merchant_name": "Fuji Apple Inc",
      "city_name": "Jakarta",
      "country_code": "ID"
    }
  },
  "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"
      }
    }
}
JSON Attribute Description Type Required
payment_type The payment method used by the customer.
Value: credit_card.		 String (255) Required
transaction_details The details of the specific transaction such as order_id and gross_amount. Object Required
credit_card The details of the payment card used for the transaction. Object Required
item_details Details of the item(s) purchased by the customer. Object Optional
customer_details Details of the customer. Object Optional

The credit_card object in Charge request to configure Non-3DS full PAN feature is identical with Card Charge Request, with the additional attributes given below.

JSON Attribute Description Type Required
card The details of the payment card used for the transaction. Object Required
number Primary Account Number (PAN) of credit card. Integer (13-19) Required
expiry_month Credit card expiry month. Integer (1-2) Required
expiry_year Credit card expiry year. Integer (4) Required
cvv Also known as Card Security Code (CSV) shown at the back of the credit card.
Note: If card.cvv is not passed, then transaction will be treated as recurring. 		Integer (3-4) Required
dynamic_descriptor Details of the merchant. Object Required
merchant_name First 25 digit on customer's billing statement. Mostly used to show merchant name or product name.
Note: Only works for BNI. 		String (25) Required
city_name First 25 digit on customer's billing statement. Mostly used to show merchant name or product name.
Note: Only works for BNI. 		String (13) Optional
country_code Last two digit on customer's billing statement. Mostly used to show country code.
Note: Only works for BNI. 		String (2) Optional

Non 3DS Full PAN Charge Response and Notifications

Sample Response - Success

{
  "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",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "currency": "IDR",
  "card_type": "credit"
}

Sample Response - Deny Notification

{
  "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": "deny",
  "fraud_status": "accept",
  "masked_card": "481111-1114",
  "status_code": "202",
  "bank": "bni",
  "status_message": "Deny by Bank [CIMB] with code [05] and message [Do not honor]",
  "approval_code": "      ",
  "channel_response_code": "05",
  "channel_response_message": "Do not honor",
  "currency": "IDR",
  "card_type": "credit"
}

Sample Response - Challenge Notification

{
  "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": "authorize",
  "fraud_status": "challenge",
  "masked_card": "481111-1114",
  "status_code": "201",
  "bank": "bni",
  "status_message": "Success, Credit Card 3D Secure transaction is successful",
  "approval_code": "1408869563148",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "currency": "IDR",
  "card_type": "credit"
}

Sample Response - Validation Error Notification

{
    "status_code": "400",
    "status_message": "One or more parameters in the payload is invalid.",
    "id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
    "validation_messages": [
        "unsupported token request parameter(s)"
    ]
}

Sample Response - Settlement Notification

{
  "masked_card": "481111-1114",
  "approval_code": "131755",
  "bank": "bni",
  "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": "midtrans payment notification",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit"
}
JSON Attribute Description Type
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type The payment method used by the customer. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Transaction status after charge payment card transaction. Possible values are
capture : Transaction is accepted by the bank and ready for settlement.
deny: transaction is denied by the bank or FDS.
authorize: Payment card is authorized in pre-authorization feature.		 String
fraud_status Detection result by Fraud Detection System (FDS). Possible values are
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.		 String
masked_card First 6-digit and last 4-digit of customer's payment card number. String
status_code Status code of transaction charge result. String
bank The acquiring bank of the transaction. String
status_message Status message describing the result of the API request. String
approval_code Approval code. It can be used for refund. This does not exist on denied transaction. String
channel_response_code Response code from payment channel provider. String
channel_response_message Response message from payment channel provider. String
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.		 String
card_type Type of card used. Possible values are credit, debit. String

3DS Integration

Three Domain Secure (3DS) is a security feature which requires the customer to complete an additional verification step while making payments using card. 3DS can be enabled/disabled for specific transactions. Always enable 3DS, to prevent unnecessary security and chargeback risks. Successful request returns `redirect_url` to redirect customer to the authentication page. After completing the authentication process, you will receive notification containing the transaction details and 3DS result.

3D Secure 2 (3DS2) is the new authentication protocol for online card payments. 3DS2 is designed to improve upon 3D Secure 1 (3DS1) by addressing the old protocol's pain points, and delivering a much smoother and integrated user experience. Registration of card and password is not required by the cardholder, unlike in 3DS1.

For merchants who already implement 3DS 1.0 New flow(Authentication field in Charge Request) there is no request changes, because Midtrans will automatically handle 3DS 2.0
Since 3DS 2.0 already support frictionless flow, not all transactions goes through the 3DS process will be directed to OTP challenge.
- If transaction is considered safe by 3DS 2.0, the transaction will be processed immediately without Challenge OTP (Frictionless benefit).
- If 3DS 2.0 transaction require OTP Challenge, there will be new flow changes that were previously Synchronous for 3DS 1.0 but for 3DS 2.0 will become Asynchronous. So after Challenge OTP, the transaction could be still Pending. Merchant needs to wait for successful notification from Midtrans or try Get Status to Midtrans several times in next minute to check for transaction status.
- there is a new field "three_ds_challenge_completion" on response to indicate the customer has submit the OTP or not(it doesn't matter if the OTP is valid or not). Since 3DS 2.0 is Asynchronous this field may still not be updated due to 3DS Server having a delay when sending the notification related to this state to Midtrans.

The steps to integrate using 3DS are given below.

  1. Send the Charge request to Midtrans.
  2. Open Redirect URL.
  3. Handle notifications.

Send a Charge API request with payment_type, transaction_details, cstore, customer_details, item_details. Successful response returns the redirect_url.

3DS Full PAN Charge Request

Sample Request - 3DS Full PAN Charge

{
  "payment_type": "credit_card",
  "transaction_details": {
    "order_id": "C17550",
    "gross_amount": 145000
  },
  "credit_card": {
    "card": {
      "number": "4811111111111114",
      "expiry_month": "3",
      "expiry_year": "2020",
      "cvv": "123"
    },
    "dynamic_descriptor": {
      "merchant_name": "Fuji Apple Inc",
      "city_name": "Jakarta",
      "country_code": "ID"
    },
    "authentication": true
  },
  "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"
      }
    }
}
JSON Attribute Description Type Required
payment_type The payment method used by the customer.
Value is credit_card.		 String (255) Required
transaction_details The details of the specific transaction such as order_id and gross_amount. Object Required
credit_card The details of the payment card used for the transaction. Object Required
item_details Details of the item(s) purchased by the customer. Object Optional
customer_details Details of the customer. Object Optional

The credit_card object in Charge request to configure 3DS full PAN feature is identical with Card Charge Request, with the additional attributes given below.

JSON Attribute Description Type Required
authentication Flag to enable the 3D secure authentication. Default value is false. Boolean Optional
callback_type Determines how the transaction status is updated to the merchant frontend. Possible values are js_event (default) and form. For more details, refer Open 3DS Authentication. String Optional

3DS Full PAN Charge Response and Notifications

Sample Response - Success

{
  "status_code": "201",
  "status_message": "Credit Card transaction is in progress",
  "transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "order_id": "C17550",
  "redirect_url": "https://api.veritrans.co.id/v2/token/rba/redirect/451249-2595-e14aac7f-cfb3-4ab2-98ab-5cc5e70f4b2c",
  "gross_amount": "145000.00",
  "currency": "IDR",
  "payment_type": "credit_card",
  "transaction_time": "2018-09-12 22:10:23",
  "transaction_status": "pending",
  "masked_card": "481111-1114",
  "card_type": "credit",
  "three_ds_version": "2"
}

Sample Response - Pending after submit OTP 3DS 2.0

{
  "status_code": "201",
  "status_message": "Credit Card transaction is in progress",
  "transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "order_id": "C17550",
  "redirect_url": "https://api.veritrans.co.id/v2/token/rba/redirect/451249-2595-e14aac7f-cfb3-4ab2-98ab-5cc5e70f4b2c",
  "gross_amount": "145000.00",
  "currency": "IDR",
  "payment_type": "credit_card",
  "transaction_time": "2018-09-12 22:10:23",
  "transaction_status": "pending",
  "masked_card": "481111-1114",
  "card_type": "credit",
  "three_ds_version": "2",
  "three_ds_challenge_completion": false
}

Sample Response - Validation Error Notification

{
  "status_code": "400",
  "status_message": "One or more parameters in the payload is invalid.",
  "id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "validation_messages": [
    "unsupported token request parameter(s)"
  ]
}

Sample Response - 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": "midtrans payment notification",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit",
  "three_ds_version": "2"
}

Sample Response - Capture Notification after submit OTP 3DS 2.0

{
  "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": "midtrans payment notification",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit",
  "three_ds_version": "2",
  "three_ds_challenge_completion": true
}

Sample Response - 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": "midtrans payment notification",
  "channel_response_code": "05",
  "channel_response_message": "Do not honor",
  "card_type": "credit",
  "three_ds_version": "2"
}

Sample Response - 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": "midtrans payment notification",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit",
  "three_ds_version": "2"
}

Sample Response - 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": "Midtrans payment notification",
  "channel_response_code": "00",
  "channel_response_message": "Approved",
  "card_type": "credit",
  "three_ds_version": "2"
}
JSON Attribute Description Type
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String.
payment_type The payment method used by the customer. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Transaction status after charge payment card transaction. Possible values are
capture: Transaction is accepted by the bank and ready for settlement.
deny: transaction is denied by the bank or FDS.
authorize: Payment card is authorized in pre-authorization feature.
pending: Credit card is pending and you will need to rely on the http notification webhook to receive the final transaction status.		 String
fraud_status Detection result by Fraud Detection System (FDS). Possible values are
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.		 String
masked_card First 6-digit and last 4-digit of customer's payment card number. String
status_code Status code of transaction charge result. String
bank The name of the acquiring bank of the transaction. String
status_message Status message describing the result of the API request. String
approval_code Approval code. It can be used for refund. This does not exist on denied transaction. String
eci The 3D secure ECI Code. String
channel_response_code Response code from payment channel provider. String
channel_response_message Response message from payment channel provider. String
redirect_url URL to redirect the customer to finish 3DS authentication. String
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.		 String
card_type Type of card used. Possible values are credit, debit. String
three_ds_version 3DS Version that used for transaction (This field only present for 3DS Transaction). Possible values are 1, 2 String
three_ds_challenge_completion 3DS Challenge completion state to indicate the customer has submit the OTP or not(it doesn't matter if the OTP is valid or not). Possible values are true, false Boolean

Bank Transfer

Bank Transfer is one of the payment methods offered by Midtrans. By using this method, your customers can make a payment via bank transfer and Midtrans will send real time notification when the payment is completed.

A list of bank transfer payment methods supported by Midtrans is given below.

Permata Virtual Account

The steps to integrate with Permata Virtual Account are given below.

  1. Send the Charge API request to Midtrans.
  2. Display the virtual account number.
  3. Handle notifications.

Send a Charge API request with the details of the transaction such as payment_type, transaction_details, bank_transfer, item_details, and customer_details. Successful request returns a VA number.

Permata Charge API Request

Sample Request - Charge API

{
  "payment_type": "bank_transfer",
  "bank_transfer": {
    "bank": "permata",
    "permata": {
      "recipient_name": "SUDARSONO"
    }
  },
  "transaction_details": {
    "order_id": "H17550",
    "gross_amount": 145000
  }
}
JSON Attribute Description Type Required
payment_type Set Bank Transfer payment method. Value: bank_transfer. String Required
bank_transfer Charge details using bank transfer. Object Required
transaction_details The details of the specific transaction such as order_id and gross_amount. Object Required
item_details Details of the item(s) purchased by the customer. Object Required
customer_details Details of the customer. Object Required

Permata Virtual Account Response and Notifications

Sample Response - Success

{
  "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"
}

Sample Response - Pending

{
  "status_code": "201",
  "status_message": "midtrans 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",
  "fraud_status": "accept",
  "permata_va_number": "8562000087926752",
  "signature_key": "66aa11a65b18e9ee5da966ed18d5d2163812000eee37824ceb59aba1ded005e992e05a7dfac39098ebdb0e2c8b484e140b586246d34b4ca313c690cc6eae48cf"
}

Sample Response - Settlement

{
  "status_code": "200",
  "status_message": "midtrans 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",
  "fraud_status": "accept",
  "permata_va_number": "8562000087926752",
  "signature_key": "0c0df82489931602577d9e434966c0540249b7c0aeaae2b718305af89a11e2bf9b4008aba07d1b3b248b15b4fbecdd15e81dbb2648b974efc4e0656e8c976094"
}

Sample Response - Expired

{
  "status_code": "202",
  "status_message": "midtrans 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",
  "fraud_status": "accept",
  "permata_va_number": "8562000087926752",
  "signature_key": "f1066b06ec8a4b7d6ffb941fd9772f6df304618e15e02cf17c2914cec12793e19c71653042f7f617b027eae6ecb6759529c67eca9af55264b736408d8b4df2b9"
}
JSON Attribute Description Type
status_code Status code of transaction charge result. String
status_message Description of transaction charge result. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type Transaction payment method. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Status of bank transfer transaction. Value:
pending : Bank Transfer transaction is created.		 String
fraud_status Detection result by Fraud Detection System (FDS). Value:
accept : Approved by FDS.		 String
permata_va_number Virtual Account number generated by Midtrans. Customer has to know this number to complete the payment. String
signature_key Combination of parameters such as order_id, status_code, gross_amount, server_key to verify integrity of payload/response. String

BCA Virtual Account

The steps to integrate with BCA Virtual Account are given below.

  1. Send the Charge API request to Midtrans.
  2. Display the virtual account number.
  3. Handle notifications.

Send a Charge API request with the details of the transaction such as payment_type, bank_transfer, bca, transaction_details, item_details, and customer_details. Successful request returns a VA number.

BCA Charge API Request

Sample Request - Charge API

{
    "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"
                }
          ]
    },
    "bca": {
        "sub_company_code": "00000"
    }
  }
}
JSON Attribute Description Type Required
payment_type Set Bank Transfer payment method. Value: bank_transfer String Required
transaction_details The details of the specific transaction such as order_id and gross_amount. Object Required
customer_details Details of the customer. Object Required
item_details Details of the item(s) purchased by the customer. Object Required
bank_transfer Charge details using bank transfer. Object Required

BCA Virtual Account Response and Notifications

Sample Response - Success

{
  "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",
  "currency": "IDR"
}

Sample Response - Pending

{
  "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": "midtrans payment notification"
}

Sample Response - Settlement

{
  "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": "midtrans payment notification"
}

Sample Response - Expired

{
  "status_code": "202",
  "status_message": "midtrans 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 Description Type
status_code Status code of transaction charge result. String
status_message Description of transaction charge result. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type Transaction payment method. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Status of bank transfer transaction. Value:
pending : Bank Transfer transaction is created.		 String
fraud_status Detection result by Fraud Detection System (FDS). Value:
accept : Approved by FDS.		 String
va_numbers Bank name and Virtual Account number generated by Midtrans. JSON Array
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently, only IDR is supported.		 String
signature_key Combination of parameters such as order_id, status_code, gross_amount, server_key to verify integrity of payload/response. String

Mandiri Bill Payment

The steps to integrate with Mandiri Bill Payment are given below.

  1. Send the Charge API request to Midtrans.
  2. Display bill key and biller code to the customer.
  3. Handle notifications.

Send a Charge API request with the details of the transaction such as payment_type, echannel, transaction_details, item_details, and customer_details. Successful request returns a VA number.

Mandiri Charge API Request

Sample Request - Charge API

{
    "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"
    }
}
JSON Attribute Description Type Required
payment_type Set E-channel payment method. Value: echannel. String Required
transaction_details The details of the specific transaction such as order_id and gross_amount. Object Required
item_details Details of the item(s) purchased by the customer. Object Required
customer_details Details of the customer. Object Required
echannel Charge details using Mandiri Bill Payment. Object Required

Mandiri Bill Response and Notifications

Sample Response - Success

{
  "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",
  "currency": "IDR"
}

Sample Response - Pending

{
  "status_code": "201",
  "status_message": "midtrans 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"
}

Sample Response - Settlement

{
  "status_code": "200",
  "status_message": "midtrans 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"
}

Sample Response - Expired

{
  "status_code": "202",
  "status_message": "midtrans 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 Description Type
status_code Status code of transaction charge result. String
status_message Description of transaction charge result. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type Transaction payment method. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Status of bank transfer transaction. Value:
pending : Bank Transfer transaction is created.		 String
fraud_status Detection result by Fraud Detection System (FDS). Value:
accept : Approved by FDS.		 String
bill_key Merchant Biller Key ID to perform transaction. String
biller_code Midtrans Unique Biler Code Number. Value is 70012. String
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.		 String
signature_key Combination of parameters such as order_id, status_code, gross_amount, server_key to verify integrity of payload/response. String

BNI Virtual Account

The steps to integrate with BNI Virtual Account are given below.

  1. Send the Charge API request to Midtrans.
  2. Display the virtual account number.
  3. Handle notifications.

Send a Charge API request with the details of the transaction such as payment_type, bank_transfer, transaction_details, item_details, and customer_details. Successful request returns a VA number.

BNI Charge API Request

Sample Request - Charge API

{
    "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"
  }
}
JSON Attribute Description Type Required
payment_type Set Bank Transfer payment method. Value: bank_transfer String Required
transaction_details The details of the specific transaction such as order_id and gross_amount. Object Required
customer_details Details of the customer. Object Required
item_details Details of the item(s) purchased by the customer. Object Required
bank_transfer Charge details using bank transfer. Object Required

BNI Virtual Account Response and Notifications

Sample Response - Success

{
  "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",
  "currency": "IDR"
}

Sample Response - Pending

{
  "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": "midtrans payment notification"
}

Sample Response - Settlement

{
  "va_numbers": [
    {
      "bank": "bni",
      "va_number": "8578000000111111"
    }
  ],
  "payment_amounts": [
    {
      "paid_at": "2016-06-19 20:12:22",
      "amount": "20000.00"
    }
  ],
  "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": "midtrans payment notification"
}

Sample Response - Expired

Send again
{
  "status_code": "202",
  "status_message": "midtrans 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 Description Type
status_code Status code of transaction charge result. String
status_message Description of transaction charge result. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type Transaction payment method. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Status of bank transfer transaction. Value:
pending : Bank Transfer transaction is created.		 String
fraud_status Detection result by Fraud Detection System (FDS). Value:
accept : Approved by FDS.		 String
va_numbers Bank name and Virtual Account number generated by Midtrans. JSON Array
payment_amounts Payment histories for the transaction. JSON Array
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.		 String
signature_key Combination of parameters such as order_id, status_code, gross_amount, server_key to verify integrity of payload/response. String

BRI Virtual Account

The steps to integrate with BRI Virtual Account are given below.

  1. Send the Charge API request to Midtrans.
  2. Display the virtual account number.
  3. Handle notifications.

Send a Charge API request with the details of the transaction such as payment_type, bank_transfer, transaction_details, item_details, and customer_details. Successful request returns a VA number.

BRI Charge API Request

Sample Request - Charge API

{
    "payment_type": "bank_transfer",
    "transaction_details": {
        "gross_amount": 10000,
        "order_id": "1597067145"
    },
    "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": "bri",
     "va_number": "111111"
  }
}
JSON Attribute Description Type Required
payment_type Set Bank Transfer payment method. Value: bank_transfer. String Required
transaction_details The details of the specific transaction such as order_id and gross_amount. Object Required
customer_details Details of the customer. Object Required
item_details Details of the item(s) purchased by the customer. Object Required
bank_transfer Charge details using bank transfer. Object Required

BRI Virtual Account Response and Notifications

Sample Response - Success

{
  "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": "bri",
      "va_number": "8578000000111111"
    }
  ],
  "fraud_status": "accept",
  "currency": "IDR"
}

Sample Response - Pending

{
  "va_numbers": [
    {
      "bank": "bri",
      "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": "midtrans payment notification"
}

Sample Response - Settlement

{
  "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": "midtrans payment notification"
}

Sample Response - Expired

Send again
{
  "status_code": "202",
  "status_message": "midtrans 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 Description Type
status_code Status code of transaction charge result. String
status_message Description of transaction charge result. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type Transaction payment method. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Status of bank transfer transaction. Value:
pending : Bank Transfer transaction is created.		 String
fraud_status Detection result by Fraud Detection System (FDS). Value:
accept : Approved by FDS.		 String
va_numbers Bank name and Virtual Account number generated by Midtrans. JSON Array
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.		 String
signature_key Combination of parameters such as order_id, status_code, gross_amount, server_key to verify integrity of payload/response. String

Internet Banking

Internet Banking payment method allows the customer to pay using their Internet banking account. It debits amount from the customer's savings account in order to pay for an online transaction. Currently, Midtrans is linked with five different Internet Banking payment methods given below.

BCA Klikpay

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

The steps to integrate with BCA KlikPay are given below.

  1. Send the Charge API request to Midtrans.
  2. Redirect the customer to URL specified in the response.
  3. Handle notifications.

Send a Charge API request with the details of the transaction such as payment_type, bca_klikpay, transaction_details, item_details, and customer_details. Successful request returns a redirect URL.

BCA KlikPay Charge API Request

Sample Request - Charge API

{
  "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": {
    "description": "Pembelian Barang"
  }
}
JSON Attribute Description Type Required
payment_type Set BCA Klikpay payment method. Value: bca_klikpay. String Required
transaction_details The details of the specific transaction such as order_id and gross_amount. Object Required
item_details Details of the item(s) purchased by the customer. Object Required
customer_details Details of the customer. Object Required
bca_klikpay Charge details using BCA Klikpay. Object Required

BCA Klikpay Charge Response and Notifications

Sample Response - Success

{
  "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",
  "currency": "IDR"
}

Sample Response - Pending

{
  "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": "midtrans payment notification"
}

Sample Response - Settlement

{
  "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": "midtrans payment notification"
}

Sample Response - Expired

{
  "status_code": "202",
  "status_message": "midtrans 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",
  "fraud_status": "accept",
  "signature_key": "62a8c432bb5a288a0495dd4f868b0aede4535e0c8a9fbebb3c6e9d4ea0db6f1963e551e70a99e80512030afa5ba8268f9be7b17b13a422ebef4620988c55d5ed"
}
JSON Attribute Description Type
status_code Status code of transaction charge result. String
status_message Status message describing the result of the API request. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
redirect_url Redirect URL to BCA Klikpay payment page. String
gross_amount Total amount of transaction in IDR. String
payment_type The payment method used by the customer. Value:bca_klickpay. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Status of BCA Klikpay transaction. Possible values are
pending, settlement, expire.		 String
fraud_status Detection result by Fraud Detection System (FDS). Possible values are
accept : Approved by FDS.
challenge: Questioned by FDS. Note: Approve transaction to accept it or transaction will get automatically cancelled during settlement.
deny: Denied by FDS. Transaction automatically failed.		 String
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently, only IDR is supported.		 String
signature_key Combination of parameters such as order_id, status_code, gross_amount, and server_key to verify integrity of payload/response. String
approval_code Successful BCA KlikPay transaction approval code. String

KlikBCA

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

The steps to integrate with KlickBCA are given below.

  1. Send the Charge API request to Midtrans.
  2. Redirect the customer to URL specified in the response.
  3. Handle notifications.

Send a Charge API request with the details of the transaction such as payment_type, bca_klikbca, transaction_details, item_details, and customer_details. Successful request returns a redirect URL.

KlikPay Charge API Request

Sample Request - Charge API

"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"
 }
JSON Attribute Description Type Required
payment_type Set Klikbca payment method. Value: bca_klikbca. String Required
transaction_details The details of the specific transaction such as order_id and gross_amount. Object Required
bca_klikbca Charge details using KlikBCA. Object Required
item_details Details of the item(s) purchased by the customer. Object Required
customer_details Details of the customer. Object Required

KlikBCA Charge Response and Notifications

Sample Response - Success

{
  "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"
}

Sample Response - Pending

{
  "status_code": "201",
  "status_message": "midtrans 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",
}

Sample Response - Settlement

{
  "status_code": "200",
  "status_message": "midtrans 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",
}

Sample Response - Expired

{
  "status_code": "202",
  "status_message": "midtrans 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 Description Type
status_code Status code of transaction charge result. String
status_message Status message describing the result of the API request. String
redirect_url Redirect URL to KlikBCA payment page. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type The payment method used by the customer. Value: bca_klikbca. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Status of KlikBCA transaction. Possible values are
settlement, expire, pending.		 String
approval_code Successful KlikBCA transaction approval code. String
signature_key Combination of parameters such as order_id, status_code, gross_amount, and server_key to verify integrity of payload/response. String

ePay BRI

ePay BRI is one of the Internet banking payment methods provided by Bank BRI. This method allows the customer to perform transactions by redirecting the customer to the ePay BRI payment page.

The Steps to integrate with ePay BRI are given below.

  1. Send the Charge API request to Midtrans.
  2. Redirect the customer to URL specified in the response.
  3. Handle notifications.

Send a Charge API request with the details of the transaction such as payment_type, transaction_details, item_details, and customer_details. Successful request returns a redirect URL.

ePay Charge API Request

Sample Request - Charge API

{
  "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"
  }
}
JSON Attribute Description Type Required
payment_type Set ePay BRI payment method. Value: bri_epay. String Required
transaction_details The details of the specific transaction such as order_id and gross_amount. Object Required
item_details Details of the item(s) purchased by the customer. Object Required
customer_details Details of the customer. Object Required

ePay BRI Charge Response and Notifications

Sample Response - Success

{
    "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",
    "currency": "IDR"
}

Sample Response - Pending

{
  "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": "midtrans payment notification"
}

Sample Response - Settlement

{
  "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": "midtrans payment notification"
}

Sample Response - Deny

{
  "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": "midtrans payment notification"
}

Sample Response - Expired

{
  "status_code": "202",
  "status_message": "midtrans 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 Description Type
status_code Status code of transaction charge result. String
status_message Status message describing the result of the API request. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
redirect_url Redirect URL to ePay BRI payment page. String
gross_amount Total amount of transaction in IDR. String
payment_type The payment method used by the customer. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Status of ePay BRI transaction. Possible values are
pending, expire, settlement.		 String
fraud_status Detection result by Fraud Detection System (FDS). Possible values are
accept : Approved by FDS.
challenge: Questioned by FDS. Note: Approve transaction to accept it or transaction will get automatically cancelled during settlement.
deny: Denied by FDS. Transaction automatically failed.		 String
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently, only IDR is supported.		 String
signature_key Combination of parameters such as order_id, status_code, gross_amount, and server_key to verify integrity of payload/response. String
approval_code Successful ePay BRI transaction approval code. String

CIMB Clicks

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

The Steps to integrate with CIMB Clicks are given below.

  1. Send the Charge API request to Midtrans.
  2. Redirect the customer to URL specified in the response.
  3. Handle notifications.

Send a Charge API request with the details of the transaction such as payment_type, cimb_clicks, transaction_details, item_details, and customer_details. Successful request returns a redirect URL.

CIMB Clicks Charge API Request

Sample Request - Charge API

{
  "payment_type": "cimb_clicks",
  "cimb_clicks": {
    "description": "Purchase of a special event item"
  },
  "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"
  }
}
JSON Attribute Description Type Required
payment_type Set CIMB Clicks payment method. Value: cimb_clicks. String Required
transaction_details The details of the specific transaction such as order_id and gross_amount. Object Required
cimb_clicks Charge details using CIMB Clicks. Object Required
item_details Details of the item(s) purchased by the customer. Object Required
customer_details Details of the customer. Object Required

CIMB Clicks Charge Response and Notifications

Sample Response - Success

{
  "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"
}

Sample Response - Pending

{
  "status_code": "201",
  "status_message": "midtrans 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",
}

Sample Response - Settlement

{
  "status_code": "200",
  "status_message": "midtrans 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"
}

Sample Response - Deny

{
  "status_code": "202",
  "status_message": "midtrans 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"
}

Sample Response - Expired

{
  "status_code": "202",
  "status_message": "midtrans 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 Description Type
status_code Status code of transaction charge result. String
status_message Status message describing the result of the API request. String
redirect_url Redirect URL to CIMB Clicks payment page. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type The payment method used by the customer. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Status of CIMB Clicks transaction. Value: pending. String
signature_key Combination of parameters such as order_id, status_code, gross_amount, and server_key to verify integrity of payload/response. String
approval_code Successful CIMB Clicks transaction approval code. String

Danamon Online Banking

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

The steps to integrate with Danamon Online Banking are given below.

  1. Send the Charge API request to Midtrans.
  2. Redirect the customer to URL specified in the response.
  3. Handle notifications.

Send a Charge API request with the details of the transaction such as payment_type, transaction_details, item_details, and customer_details. Successful request returns a redirect URL.

Danamon Online Banking Charge API Request

Sample Request - Charge API

{
  "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"
  }
}
JSON Attribute Description Type Required
payment_type Set DOB payment method. Value: danamon_online. String Required
item_details Details of the item(s) purchased by the customer. Object Required
transaction_details The details of the specific transaction such as order_id and gross_amount. Object Required
customer_details Details of the customer. Object Required

DOB Charge Response and Notifications

Sample Response - Success

{
  "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",
  "fraud_status": "accept"
}

Sample Response - Pending

{
  "status_code": "201",
  "status_message": "midtrans 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",
  "fraud_status": "accept",
  "signature_key": "666617ddc981eb096b6f08ab8ee132b93c12d3b5b3817f00a02c5d4c71bd53fd7f39d55a92b2a1f729ee070fdb241b569dc90bfa61e41de16904075238d67d55",
}

Sample Response - Settlement

{
  "status_code": "200",
  "status_message": "midtrans 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",
  "fraud_status": "accept",
  "approval_code": "RB5031388093",
  "signature_key": "3bcdf0700d3c8a288f279e4fe27a4012e916cb44120d541f6e4c48c83a107b605fdb063ae7c8744d15891047aeb1fc8d2e95741c0abc5f67e10e0b60244bc441"
}

Sample Response - Deny

{
  "status_code": "202",
  "status_message": "midtrans 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",
  "fraud_status": "accept",
  "signature_key": "b736864661f8cbf04b287ee5a9514589dbe2dc53e3949338d648144b6bad1bc77d1b495921f119e7a6bf5521b697ea5d629b5ea93f2bcda4ff13df744cfbf701"
}

Sample Response - Expired

{
  "status_code": "202",
  "status_message": "midtrans 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",
  "fraud_status": "accept",
  "signature_key": "3f1ddaf45b269df7a1638d6d4080957e1323df2cbc2da83549f86a23b17c2acae0215994bb60805455daf157125990414259e5319e84c9288fd6222e655c6756"
}
JSON Attribute Description Type
transaction_id Transaction ID given by Midtrans. String
status_code Status code of transaction charge result. String
status_message Status message describing the result of the API request. String
redirect_url Redirect URL to DOB payment page. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type The payment method used by the customer. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Status of DOB transaction. Possible values are
expire, deny, accept.		 String
fraud_status Detection result by Fraud Detection System (FDS). Possible values are
accept : Approved by FDS.
challenge: Questioned by FDS. Note: Approve transaction to accept it or transaction will get automatically cancelled during settlement.
deny: Denied by FDS. Transaction automatically failed.		 String
signature_key Combination of parameters such as order_id, status_code, gross_amount, and server_key to verify integrity of payload/response. String
approval_code Successful Danamon Online transaction approval code. String

E-Money

E-Money is one of the payment methods offered by Midtrans. By using this method, your customers can make a payment via E-Money and Midtrans will send real time notification when the payment is completed.

Midtrans has integrated with E-Money payment methods given below.

QRIS

QRIS is a QR payment standard in Indonesia, developed by Bank Indonesia (BI). Users can scan and pay the QR from any payment providers registered as the issuer here.

For QRIS, we are currently integrated with the acquirers given below.

  1. GoPay
  2. AirPay Shopee (ShopeePay)

The steps to integrate with QRIS are given below.

  1. Send the Charge API request to Midtrans with the selected acquirer.
  2. Show the rendered QR string to the users.
  3. Handle notifications.

Send a Charge API request with the details of the transaction such as payment_type, qris, transaction_details, item_details, and customer_details. Successful request returns a QR code image URL.

QRIS Charge API Request

Sample Request - Charge API

{
  "payment_type": "qris",
  "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 -"
    }
  ],
  "customer_details": {
    "first_name": "Budi",
    "last_name": "Utomo",
    "email": "budi.utomo@midtrans.com",
    "phone": "081223323423"
  },
  "qris": {
    "acquirer": "gopay"
  }
}

The attributes to be sent to charge QRIS are given below.

JSON Attribute Description Type Required
payment_type Set QRIS payment method. Value: qris String Required
transaction_details The details of the specific transaction such as order_id and gross_amount. Object Required
item_details Details of the item(s) purchased by the customer. Object Required
customer_details Details of the customer. Object Required
qris Charge details using QRIS. Object Required

QRIS Charge Response and Notifications

Sample Response - Success

{
    "status_code": "201",
    "status_message": "QRIS transaction is created",
    "transaction_id": "0d8178e1-c6c7-4ab4-81a6-893be9d924ab",
    "order_id": "order03",
    "merchant_id": "M099098",
    "gross_amount": "275000.00",
    "currency": "IDR",
    "payment_type": "qris",
    "transaction_time": "2020-09-29 11:46:13",
    "transaction_status": "pending",
    "fraud_status": "accept",
    "acquirer": "gopay",
    "actions": [
        {
            "name": "generate-qr-code",
            "method": "GET",
            "url": "https://api.midtrans.com/v2/qris/0d8178e1-c6c7-4ab4-81a6-893be9d924ab/qr-code"
        }
    ]
}

Sample Response - Pending

{
  "transaction_time":"2020-09-29 11:18:06",
  "transaction_status":"pending",
  "transaction_id":"ce0a3584-5a0c-4049-ad88-5590a96be4fe",
  "status_message":"midtrans payment notification",
  "status_code":"201",
  "signature_key":"b1798748303cf0817733c1e312d630793b84d8125a96af0cb7251f8266d5c5256285084ba3ffbfae1f264a031d41927124fba0b552f249ee68180e9c7566448e",
  "payment_type":"qris",
  "order_id":"order03",
  "merchant_id":"M099098",
  "gross_amount":"275000.00",
  "fraud_status":"accept",
  "currency":"IDR",
  "acquirer":"gopay"
}

Sample Response - Settlement

{
  "transaction_type":"on-us",
  "transaction_time":"2020-09-29 11:27:33",
  "transaction_status":"settlement",
  "transaction_id":"9f07920a-6145-4d1e-9fc2-66e6fd6bc6fc",
  "status_message":"midtrans payment notification",
  "status_code":"200",
  "signature_key":"155b03b554092326ad9d2ed936f5765fe759b6bc491c0161a26e4340978fb6e8f07683bf012552a9498bfc919abab834aade57eda01f7a18a3490a515cf17632",
  "settlement_time":"2020-09-29 11:30:44",
  "payment_type":"qris",
  "order_id":"order03",
  "merchant_id":"M099098",
  "issuer":"gopay",
  "gross_amount":"275000.00",
  "fraud_status":"accept",
  "currency":"IDR",
  "acquirer":"gopay"
}

Sample Response - Expired

{
  "transaction_time":"2020-09-29 11:31:39",
  "transaction_status":"expire",
  "transaction_id":"9728e0fd-a49c-4c25-8c88-404ef1c45e0e",
  "status_message":"midtrans payment notification",
  "status_code":"202",
  "signature_key":"4580d8fc6c4a8dca3319efc1f629b8b33e923ec62b2e6ad7254ed6230ef0e57977b2f6124ba8f2a7a71c53ac7368f3f795ffbdecac3b5cf23e82f1ca5440ad1a",
  "payment_type":"qris",
  "order_id":"order03",
  "merchant_id":"M099098",
  "gross_amount":"275000.00",
  "fraud_status":"accept",
  "currency":"IDR",
  "acquirer":"gopay"
}
JSON Attribute Description Type
status_code Status code of transaction charge result. String
status_message Description of transaction charge result. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type Transaction payment method. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Status of QRIS transaction. Possible values are
pending, settlement, expire, deny.		 String
transaction_type To determine how the transaction is being acquired. Possible values are on-us or off-us. String
issuer The provider that is making the payment over the QR. String
actions Actions which can be performed with this transaction. Use generate-qr-code action to render the QR code image (PNG format). Array(Object)
acquirer The provider creating the QR and accepting the payment. The value is the same as the one set in the charge request. String
merchant_id Merchant ID given by Midtrans. String
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.		 String
signature_key Combination of parameters such as order_id, status_code, gross_amount, server_key to verify integrity of payload/response. String

GoPay

GoPay is an E-Money payment method by Gojek. Users can pay using the Gojek apps, or any QRIS compatible app. The user flow is different for web browser (on a computer or a tablet) and smartphone:

  1. QR Code - This is the user flow on a web browser (on a computer or a tablet). User is shown a QR code and asked to scan using any QRIS compatible app, such as Gojek app. (Sequence Diagram for QR Code)
  2. Deeplink - This is the user flow on a SmartPhone/mobile device. User gets redirected to the Gojek apps to finish payment. (Sequence Diagram Deeplink)

By default, GoPay transaction expiry is fifteen minutes.

Sequence Diagram for QR Code GoPay QR Code flow
Sequence Diagram for Deeplink GoPay Deeplink flow

The steps to integrate with GoPay are given below.

  1. Create payment instructions for users (see example below).
  2. Send the Charge API request to Midtrans.
  3. Alter payment flow depending on the device used:
    • Show QR code image (on a computer or a tablet).
    • Create redirect link to Gojek app (on SmartPhone/mobile device).
  4. Handle notifications.
Instruction Example
For QR Code
  1. Tap Pay using GoPay.
  2. Click Pay Now. QR code will be displayed.
  3. Open Gojek app on your mobile phone.
  4. Scan the QR code.
  5. Verify your payment details and then click Pay.
  6. Verify your Security PIN and finish your transaction.
GoPay QR Instruction 1 GoPay QR Instruction 2
For Deeplink
  1. Tap Pay using GoPay.
  2. You will be redirected to Gojek app.
  3. Verify your payment details and then click Pay.
  4. Verify your Security PIN and finish your transaction.
GoPay UI

Send a Charge API request with the details of the transaction such as payment_type, gopay, transaction_details, item_details, and customer_details. Successful request returns a deeplink redirect URL or QR code image URL.

GoPay Charge API Request

Sample Request - Charge API

{
  "payment_type": "gopay",
  "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 -"
    }
  ],
  "customer_details": {
    "first_name": "Budi",
    "last_name": "Utomo",
    "email": "budi.utomo@midtrans.com",
    "phone": "081223323423"
  },
  "gopay": {
    "enable_callback": true,
    "callback_url": "someapps://callback"
  }
}

The attributes to be sent to charge GoPay are given below.

JSON Attribute Description Type Required
payment_type Set GoPay payment method. Value: gopay. String Required
transaction_details The details of the specific transaction such as order_id and gross_amount. Object Required
item_details Details of the item(s) purchased by the customer. Object Required
customer_details Details of the customer. Object Required
gopay Charge details using GoPay. Object Required

GoPay Charge Response and Notifications

Sample Response - Success

{
    "status_code": "201",
    "status_message": "GO-PAY billing created",
    "transaction_id": "e48447d1-cfa9-4b02-b163-2e915d4417ac",
    "order_id": "SAMPLE-ORDER-ID-01",
    "gross_amount": "10000.00",
    "payment_type": "gopay",
    "transaction_time": "2017-10-04 12:00:00",
    "transaction_status": "pending",
    "actions": [{
            "name": "generate-qr-code",
            "method": "GET",
            "url": "https://api.midtrans.com/v2/gopay/e48447d1-cfa9-4b02-b163-2e915d4417ac/qr-code"
        },
    {
            "name": "deeplink-redirect",
            "method": "GET",
            "url": "gojek://gopay/merchanttransfer?tref=1509110800474199656LMVO&amount=10000&activity=GP:RR&callback_url=someapps://callback?order_id=SAMPLE-ORDER-ID-01"
        },
        {
            "name": "get-status",
            "method": "GET",
            "url": "https://api.midtrans.com/v2/e48447d1-cfa9-4b02-b163-2e915d4417ac/status"
        },
        {
            "name": "cancel",
            "method": "POST",
            "url": "https://api.midtrans.com/v2/e48447d1-cfa9-4b02-b163-2e915d4417ac/cancel",
            "fields": []
        }
    ],
    "channel_response_code": "200",
    "channel_response_message": "Success",
  "currency": "IDR"
}

Sample Response - Pending

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

Sample Response - Settlement

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

Sample Response - Expired

{
  "status_code": "202",
  "status_message": "midtrans payment notification",
  "transaction_id": "1c28dbbb-8596-48e4-85d7-9f1382db8a1f",
  "order_id": "order03",
  "gross_amount": "275000.00",
  "payment_type": "gopay",
  "transaction_time": "2016-06-20 15:50:12",
  "transaction_status": "expire",
  "signature_key": "53c6e2e3639a6b5c09b9103aa343f00cfd0168c6a69a2d4f2203bdc58072531ad7b340ea01725538996a7827c4ce091fb94d0aa70778a20c69d3f9991e0f65eb"
}
JSON Attribute Description Type
status_code Status code of transaction charge result. String
status_message Description of transaction charge result. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type Transaction payment method. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Status of GoPay transaction. Possible values are
pending, settlement, expire, deny.		 String
actions Actions which can be performed with this transaction. Use generate-qr-code action to render the QR code image (PNG format). Use deeplink-redirect action to redirect to Gojek apps. Array(Object)
channel_response_code Response code from payment channel provider. String
channel_response_message Response message from payment channel provider. String
signature_key Combination of parameters such as order_id, status_code, gross_amount, server_key to verify integrity of payload/response. String

In addition to the standard mobile apps flow, you can implement deeplink callback to redirect customer back from Gojek to your app.

Pre-requisites: E-commerce needs to prepare a deeplink which accepts two query parameters.

Query Parameter Description Type
order_id Order ID sent on the Charge Request. String
result Result of the transaction to decide what kind of page to show to customer. Possible values are success or failure. String

Warning: It is highly recommended to avoid using value passed on result to update status on backend. There is HTTP notification for this use case.

The steps to integrate with GoPay deeplink (Please look into the GoPay Charge API Request for sample implementation) are given below.

  1. Set enable_callback parameter in the charge request to true.
  2. Set callback_url with the deeplink URL redirecting to E-commerce apps.
  3. Handle redirection with above parameters.

GoPay Tokenization

GoPay Tokenization allows you to link your customer GoPay account. The flow is similar to card tokenization where you can use the linked customer account for transaction authorization.

GoPay Tokenization Flow

Send a Charge API request with the details of the transaction such as payment_type, gopay, and transaction_details. Successful request returns a status_code:200.

The steps to integrate with GoPay Tokenization are given below.

  1. Link customer account only if the customer phone number is not yet linked to GoPay.
  2. Fetch customer account. If the linking of customer account is successful, then the payment options available to the customer are- GOPAY_WALLET and PAY_LATER. Customer can select any of these options. From metadata, store the token of the payment option. You can also use this API to fetch the customer balance.
  3. If the linking is already successful then the customer can proceed with the charge. Sample Charge API request is shown on the side.
  4. If the status_code in the response is 200, then the transaction is completed. If the status_code is 201, then you need to open the verification URL in the actions to the customer. Once the verification is done, it will redirect back to the callback URL that is set on your dashboard.

Use the following two redirection URLs only.


verification-link-url is for transaction verification in browser or webview. This redirection is recommended for desktop. The customer will receive a push notification from their Gojek app. Once the customer verifies the transaction on the app, it will be automatically redirected to the merchant page. For merchants with special agreement with GoPay, this page may also show OTP/PIN page.


verification-link-app is for transaction verification in Gojek app. This might not be applicable for all merchants. The customer will need to input OTP/PIN from the Gojek app.

GoPay Tokenization Charge API Request

Sample Request - Charge API

{
  "payment_type": "gopay",
  "gopay": {
    "account_id": "00000269-7836-49e5-bc65-e592afafec14",
    "payment_option_token": "eyJ0eXBlIjogIkdPUEFZX1dBTExFVCIsICJpZCI6ICIifQ==",
    "callback_url": "https://midtrans.com/"
  },
  "transaction_details": {
    "gross_amount": 100000,
    "order_id": "order-1234"
  }
}

The attributes to be sent to charge GoPay Tokenization are given below.

JSON Attribute Description Type Required
payment_type Set GoPay payment method. Value: gopay. String Required
gopay Charge details using GoPay. Object Required
transaction_details The details of the specific transaction such as order_id and gross_amount. Object Required
callback_url Please make sure callback_url is the same URL submitted on onboarding process. String Optional

GoPay Tokenization Charge Response and Notifications

Sample Response - Settlement

{
  "status_code": "200",
  "status_message": "Success, GoPay transaction is successful",
  "transaction_id": "00000269-7836-49e5-bc65-e592afafec14",
  "order_id": "order-1234",
  "gross_amount": "100000.00",
  "currency": "IDR",
  "payment_type": "gopay",
  "transaction_time": "2016-06-28 09:42:20",
  "transaction_status": "settlement",
  "fraud_status": "accept",
}

Sample Response - Pending

{
  "status_code": "201",
  "status_message": "GoPay transaction is created. Action(s) required",
  "transaction_id": "00000269-7836-49e5-bc65-e592afafec14",
  "order_id": "order-1234",
  "gross_amount": "100000.00",
  "currency": "IDR",
  "payment_type": "gopay",
  "transaction_time": "2016-06-28 09:42:20",
  "transaction_status": "pending",
  "fraud_status": "accept",
  "actions": [
    {
      "name": "verification-link-url",
      "method": "GET",
      "url": "http://api.midtrans.com/v2/gopay/redirect/gppr_6123269-1425-21e3-bc44-e592afafec14/charge"
    },
    {
      "name": "verification-link-app",
      "method": "GET",
      "url": "http://api.midtrans.com/v2/gopay/redirect/gppd_6123269-1425-21e3-bc44-e592afafec14/charge"
    }
  ]
}

Sample Response - Deny

{
  "status_code": "202",
  "status_message": "GoPay transaction is denied",
  "transaction_id": "a8a91ece-24f9-427d-a588-b9a2428acda0",
  "order_id": "order-1234",
  "gross_amount": "100000.00",
  "currency": "IDR",
  "payment_type": "gopay",
  "transaction_time": "2016-06-28 09:42:20",
  "transaction_status": "deny",
  "fraud_status": "accept",
}
JSON Attribute Description Type
status_code Status code of transaction charge result. String
status_message Description of transaction charge result. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type Transaction payment method. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Status of GoPay transaction. Possible values are
pending, settlement, expire, deny.		 String
actions Actions which can be performed with this transaction. Use verification-link-url or verification-link-app to do the verification and to redirect the customer to callback URL. Array(Object)
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.		 String

GoPay Tokenization Features: Pre-Auth

Merchant that enables GoPay Tokenization could opt to do pre-auth transactions. Pre-auth allows merchant to reserve the customer balance before the goods or services are delivered. The reservation has a time limit of 24 hours for merchant to capture it. Capturing a reservation is a process to settle the customer balance into merchant account.

The steps to integrate Gopay Tokenization Pre-Auth feature are given below.

  1. The linking process is exactly same as GoPay Tokenization linking process above.
  2. If the linking is already successful then the customer can proceed with the charge. The only difference is that merchant needs to pass pre_auth: "true" parameter. See example on the side.
  3. If the status_code in the response is 200, then the transaction is authorized. If the status_code is 201, then you need to open the verification URL in the actions to the customer. Once the verification is done, it will be redirected back to the callback URL that is set on your dashboard.
  4. You need to call Capture API, within 24 hours of authorization. Please note that we do not accept partial amount capture for GoPay.
  5. As an option, you can also cancel the authorization by calling the Cancel API.

Send a Charge API request with the details of the transaction and pre_auth:true. Successful request returns a status_code:200.

Pre-Auth Charge API Request

Sample Request - Charge API

{
  "payment_type": "gopay",
  "gopay": {
    "account_id": "00000269-7836-49e5-bc65-e592afafec14",
    "payment_option_token": "eyJ0eXBlIjogIkdPUEFZX1dBTExFVCIsICJpZCI6ICIifQ==",
    "pre_auth": true, // the default value is false
  },
  "transaction_details": {
    "gross_amount": 100000,
    "order_id": "order-1234"
  }
}

The attributes to be sent to charge API are given below.

JSON Attribute Description Type Required
payment_type Set GoPay payment method. Value: gopay. String Required
gopay Charge details using GoPay. Object Required
transaction_details The details of the specific transaction such as order_id and gross_amount. Object Required

Pre-Auth Charge Response and Notifications

Sample Response - Success

{
  "status_code": "200",
  "status_message": "Success, GoPay transaction is successful",
  "transaction_id": "00000269-7836-49e5-bc65-e592afafec14",
  "order_id": "order-1234",
  "gross_amount": "100000.00",
  "currency": "IDR",
  "payment_type": "gopay",
  "transaction_time": "2016-06-28 09:42:20",
  "transaction_status": "authorize",
  "fraud_status": "accept",
  "channel_response_code": "0",
  "channel_response_message": "Process service request successfully."
}

Sample Response - Pending

{
  "status_code": "201",
  "status_message": "GoPay transaction is created. Action(s) required",
  "transaction_id": "00000269-7836-49e5-bc65-e592afafec14",
  "order_id": "order-1234",
  "gross_amount": "100000.00",
  "currency": "IDR",
  "payment_type": "gopay",
  "transaction_time": "2016-06-28 09:42:20",
  "transaction_status": "pending",
  "fraud_status": "accept",
  "actions": [
    {
      "name": "verification-link-url",
      "method": "GET",
      "url": "http://api.midtrans.com/v2/gopay/redirect/gppr_6123269-1425-21e3-bc44-e592afafec14/charge"
    },
    {
      "name": "verification-link-app",
      "method": "GET",
      "url": "http://api.midtrans.com/v2/gopay/redirect/gppd_6123269-1425-21e3-bc44-e592afafec14/charge"
    }
  ]
}

Sample Response - Deny

{
  "status_code": "202",
  "status_message": "GoPay transaction is denied",
  "transaction_id": "a8a91ece-24f9-427d-a588-b9a2428acda0",
  "order_id": "order-1234",
  "gross_amount": "100000.00",
  "currency": "IDR",
  "payment_type": "gopay",
  "transaction_time": "2016-06-28 09:42:20",
  "transaction_status": "deny",
  "fraud_status": "accept",
}
JSON Attribute Description Type
status_code Status code of transaction charge result. String
status_message Description of transaction charge result. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type Transaction payment method. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Status of GoPay transaction. Possible values are
pending, settlement, expire, deny.		 String
actions Actions which can be performed with this transaction. Use verification-link-url or verification-link-app to do the verification and to redirect the customer to callback URL. Array(Object)
channel_response_code Response code from payment channel provider. String
channel_response_message Response message from payment channel provider. String
signature_key Combination of parameters such as order_id, status_code, gross_amount, server_key to verify integrity of payload/response. String
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.		 String

ShopeePay

ShopeePay is an E-Money payment method by Shopee. Users will be redirected from the merchant app to pay using the Shopee app. As this payment method requires Shopee app, it is only applicable for merchant integrating from their mobile app. By default, ShopeePay transaction expiry is 5 minutes.

The steps to integrate with ShopeePay are given below.

  1. Send the Charge API request to Midtrans.
  2. Open the redirect url in the response to get redirected to Shopee app.
  3. Handle the redirect from Shopee app back to merchant app.
  4. Handle notifications.

Send a Charge API request with the details of the transaction such as payment_type, shopeepay, transaction_details, item_details, and customer_details. Successful request returns a redirect URL.

ShopeePay Charge API Request

ShopeePay Charge Request

{
    "payment_type": "shopeepay",
    "transaction_details": {
        "order_id": "test-order-shopeepay-001",
        "gross_amount": 25000
    },
    "item_details": [
        {
            "id": "id1",
            "price": 25000,
            "quantity": 1,
            "name": "Brown sugar boba milk tea"
        }
    ],
    "customer_details": {
        "first_name": "John",
        "last_name": "Brandon",
        "email": "john.brandon@go-jek.com",
        "phone": "0819323212312"
    },
    "shopeepay": {
        "callback_url": "https://midtrans.com/"
    }
}

Attributes to be sent to charge ShopeePay are given below.

JSON Attribute Description Type Required
payment_type Set ShopeePay payment method. Value: shopeepay String Required
transaction_details The details of the specific transaction such as order_id and gross_amount. Object Required
item_details Details of the item(s) purchased by the customer. Object Required
customer_details Details of the customer. Object Required
shopeepay Charge details using ShopeePay. Object Required

ShopeePay Charge Response and Notifications

Sample Response - Success

{
    "status_code": "201",
    "status_message": "ShopeePay transaction is created",
    "channel_response_code": "0",
    "channel_response_message": "success",
    "transaction_id": "bb379c3a-218b-47c7-9b0b-25f71f0f1231",
    "order_id": "test-order-shopeepay-001",
    "merchant_id": "YON001",
    "gross_amount": "25000.00",
    "currency": "IDR",
    "payment_type": "shopeepay",
    "transaction_time": "2020-09-29 11:16:23",
    "transaction_status": "pending",
    "fraud_status": "accept",
    "actions": [
        {
            "name": "deeplink-redirect",
            "method": "GET",
            "url": "https://wsa.uat.wallet.airpay.co.id/universal-link/wallet/pay?deep_and_deferred=1&token=dFhkbmR1bTBIamhW5n7WPz2OrczCvb8_XiHliB9nROFMVByjtwKMAl6G0Ax0cMr79M4hwjs"
        }
    ]
}

Sample Response - Pending

{
  "transaction_time":"2020-09-29 11:16:23",
  "transaction_status":"pending",
  "transaction_id":"bb379c3a-218b-47c7-9b0b-25f71f0f1231",
  "status_message":"midtrans payment notification",
  "status_code":"201",
  "signature_key":"dd627b40a8951f8c15af2d0f4e96ceae748af857e1d697f4bdb631a37227a4de45952a909c5f08d92228dd27e590586996ab1cf82b658ee99fae08d3e26f3348",
  "payment_type":"shopeepay",
  "order_id":"test-order-shopeepay-001",
  "merchant_id":"YON001",
  "gross_amount":"25000.00",
  "fraud_status":"accept",
  "currency":"IDR"
}

Sample Response - Settlement

{
  "transaction_time":"2020-09-29 11:22:38",
  "transaction_status":"settlement",
  "transaction_id":"6f4595c8-7ed6-4ade-818f-865fdd0e47aa",
  "status_message":"midtrans payment notification",
  "status_code":"200",
  "signature_key":"a8abc37da315aa7c01c18817f4740db68392a15aa2e01fe4637dbaff49364e18e9367731a53569d23a90c06e8e06794eec9d5395c2bd5f39c0a58d0ab8d2d059",
  "settlement_time":"2020-09-29 11:23:44",
  "payment_type":"shopeepay",
  "order_id":"test-order-shopeepay-003",
  "merchant_id":"YON001",
  "gross_amount":"25000.00",
  "fraud_status":"accept",
  "currency":"IDR"
}

Sample Response - Expired

{
  "transaction_time":"2020-09-29 11:24:57",
  "transaction_status":"expire",
  "transaction_id":"6637ee65-69cd-44ff-8650-5fb746c492aa",
  "status_message":"midtrans payment notification",
  "status_code":"202",
  "signature_key":"d6452333ab67dfb2adb784f529d9c27dc149adffb74fcc1d45d98418f7c7a68a2e86a6f5ede9be83795aa147d27e030282343a36f11d14858d6b5425de153362",
  "payment_type":"shopeepay",
  "order_id":"test-order-shopeepay-004",
  "merchant_id":"YON001",
  "gross_amount":"25000.00",
  "fraud_status":"accept",
  "currency":"IDR"
}
JSON Attribute Description Type
status_code Status code of transaction charge result. String
status_message Description of transaction charge result. String
actions Actions which can be performed with this transaction. Use deeplink-redirect action to redirect to Shopee apps. Array(Object)
channel_response_code Response code from payment channel provider. String
channel_response_message Response message from payment channel provider. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by you. String
gross_amount Total amount of transaction in IDR. String
payment_type Transaction payment method. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Status of ShopeePay transaction. Possible values are
pending, settlement, expire, deny.		 String
signature_key Combination of parameters such as order_id, status_code, gross_amount, server_key to verify integrity of payload/response. String
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.		 String

Over the Counter

Over the Counter payment method allows the customer to shop online and make the payments at the nearest convenience store. Currently, Midtrans has integrated with two convenience stores given below.

Indomaret

Using Over the Counter payment feature provided by Indomaret, the customer can perform online shopping and complete the payment at Indomaret store. Midtrans sends a real-time notification to you for every incoming payment.

The steps to integrate with Indomaret stores are given below.

  1. Send Charge API request to Midtrans.
  2. Display the payment code to the customer.
  3. Handle notifications.

Send a Charge API request with payment details, transaction details, convenience store details, customer details, and item details. Successful request returns status_code:201.

Indomaret Charge API Request

Sample Request - Indomaret Charge

{
  "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"
    }
  ]
}
JSON Attribute Description Type Required
payment_type The payment method used by the customer. Value: cstore. String Required
transaction_details The details of the specific transaction such as
order_id and gross_amount.		 Object Required
cstore Details of the convenience store. Object Required
customer_details Details of the customer. Object Required
item_details Details of the item(s) purchased by the customer. Object Required

Indomaret Charge Response and Notifications

Sample Response - Success

{
  "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"
}

Sample Response - Indomaret Pending Notifications

{
  "status_code": "201",
  "status_message": "midtrans 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",
  "store": "indomaret"
}

Sample Response - Indomaret Settlement Notifications

{
  "status_code": "200",
  "status_message": "midtrans 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",
  "store": "indomaret"
}

Sample Response - Indomaret Expired Notifications

{
  "status_code": "202",
  "status_message": "midtrans 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",
  "store": "indomaret"
}
JSON Attribute Description Type
status_code Status code of transaction charge result. String
status_message Message describing the status of the result of API request. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by merchant. String
gross_amount Total amount of transaction in IDR. String
payment_type Payment method used by the customer. Value: cstore. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone (GMT+7). String
transaction_status Transaction status of the Indomaret transaction. Possible values are pending, settlement, and expire. String
signature_key Special string to verify the integrity of the response. For more details, refer Verifying Notification Authenticity. String
payment_code Unique payment code for the customer to complete the payment in Indomaret. String
store Convenience store identifier. String

Alfamart

Using Over the Counter payment feature provided by Alfamart, the customer can perform online shopping and complete the payment at various stores under Alfa group. The supported stores are: Alfamart, Alfamidi, DAN+DAN, and Lawson (Coming soon). Midtrans will send a real-time notification to you for every incoming payment.

The steps to integrate with Alfamart stores are given below.

  1. Send Charge API request to Midtrans.
  2. Display the payment code to the customer.
  3. Handle notification.

Send a Charge API request with payment details, transaction details, convenience store details, customer details, and item details. Successful response returns status_code:201.

Alfamart Charge API Request

Sample Request - Charge API

{
  "payment_type": "cstore",
  "transaction_details": {
    "gross_amount": 162500,
    "order_id": "order05"
  },
  "cstore": {
    "store": "alfamart",
    "alfamart_free_text_1": "Thanks for shopping with us!,",
    "alfamart_free_text_2": "Like us on our Facebook page,",
    "alfamart_free_text_3": "and get 10% discount on your next purchase."
  },
  "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"
    }
  ]
}
JSON Attribute Description Type
payment_type The payment method used by the customer. Value: cstore. String
transaction_details The details of the specific transaction such as order_id and gross_amount. Object
cstore Details of the convenience store. Object
customer_details Details of the customer. Object
item_details Details of the item(s) purchased by the customer. Object

Alfamart Charge Response and Notifications

Sample Response - Success

{
    "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",
    "store": "alfamart"
}

Sample Response - Alfamart Pending Notifications

{
  "status_code": "201",
  "status_message": "midtrans 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",
  "store": "alfamart"
}

Sample Response - Alfamart Settlement Notifications

{
  "status_code": "200",
  "status_message": "midtrans 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",
  "store": "alfamart"
}

Sample Response - Alfamart Expired Notifications

{
  "status_code": "202",
  "status_message": "midtrans 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",
  "store": "alfamart"
}
JSON Attribute Description Type
status_code Status code of transaction charge result. String
status_message Message describing the status of the result of API request. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by merchant. String
gross_amount Total amount of transaction in IDR. String
payment_type The payment method used by the customer. Value: cstore. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone (GMT+7). String
transaction_status Transaction status of Indomaret transaction. Possible values are pending, settlement, and expire. String
fraud_status Detection result by Fraud Detection System (FDS). Possible values are
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.		 String
payment_code Unique payment code for customer to complete the payment in Alfamart. String
store Convenience store identifier. String
signature_key Special string to verify the integrity of the response. For more details refer Verifying Notification Authenticity. String

Cardless Credit

Cardless Credit allows customers to enroll in an affordable monthly payment plan so they don't have to pay all at once. It provides E-commerce, access to certain customer markets which lack payment cards but prefer installment. Currently, Midtrans has integrated with Akulaku Cardless Credit payment method only.

Akulaku

In addition to their shopping mall business, Akulaku has been enabling E-commerce to sell their merchandise in installment. It allows their customers to pay in installment without a payment card as long as they are registered to Akulaku.

The steps to integrate with Akulaku Cardless Credit are given below.

  1. Send Charge API request to Midtrans.
  2. Redirect the customer to the provider website.
  3. Handle notifications.

Send a Charge API request with the details of the transaction such as payment_type, transaction_details, item_details, and customer_details. Successful request returns a URL to Akulaku's website.

Akulaku Charge API Request

Sample Request - Akulaku Charge

{
  "payment_type": "akulaku",
  "transaction_details": {
    "order_id": "orderid-01",
    "gross_amount": 11000
  },
  "item_details": [
    {
      "id": "1",
      "price": 11000,
      "quantity": 1,
      "name": "Sepatu "
    }
  ],
  "customer_details":{
    "first_name": "John",
    "last_name": "Baker",
    "email": "john.baker@email.com",
    "phone": "08123456789"
  }
}
JSON Attribute Description Type Required
payment_type The Cardless Credit payment method used by the customer. Value: akulaku.
Note: Currently only akulaku is supported.		 String Required
transaction_details The details of the specific transaction such as order_id and gross_amount. Object Required
item_details Details of the item(s) purchased by the customer. Object Required
customer_details Details of the customer. Object Required

Akulaku Charge API Response and Notifications

Sample Response - Success

{
    "status_code": "201",
    "status_message": "Success, Akulaku transaction is created",
    "transaction_id": "b3a40398-d95d-4bb9-afe8-9a57bc0786ea",
    "order_id": "orderid-01",
    "redirect_url": "https://api.sandbox.veritrans.co.id/v2/akulaku/redirect/b3a40398-d95d-4bb9-afe8-9a57bc0786ea",
    "gross_amount": "11000.00",
    "currency": "IDR",
    "payment_type": "akulaku",
    "transaction_time": "2018-08-24 16:20:36",
    "transaction_status": "pending",
    "fraud_status": "accept",
    "channel_response_code": "",
    "channel_response_message": ""
}

Sample Response - Pending Notification

{
  "transaction_time": "2018-08-24 16:20:36",
  "gross_amount": "11000.00",
  "order_id": "orderid-01",
  "payment_type": "akulaku",
  "signature_key": "e47d73b2a10347d291e85a7c39c5fa2a7b760f0af7d9882f9c1b26db06e1af948968184b78f67112158cdeddd2141fe41068fdb37361ce11c3d2509354224a80",
  "status_code": "201",
  "transaction_id": "b3a40398-d95d-4bb9-afe8-9a57bc0786ea",
  "transaction_status": "pending",
  "fraud_status": "accept",
  "status_message": "midtrans payment notification"
}

Sample Response - Settlement Notification

{
  "transaction_time": "2018-08-24 16:20:36",
  "gross_amount": "11000.00",
  "order_id": "orderid-01",
  "payment_type": "akulaku",
  "signature_key": "35c4111539e184b268b7c1cd62a9c254e5d27c992c8fd55084f930b69b09eaafcfe14b0d512c697648295fdb45de777e1316b401f4729846a91b3de88cde3f05",
  "status_code": "200",
  "transaction_id": "b3a40398-d95d-4bb9-afe8-9a57bc0786ea",
  "transaction_status": "settlement",
  "fraud_status": "accept",
  "status_message": "midtrans payment notification"
}

Sample Response - Expired Notification

{
  "transaction_time": "2018-08-24 16:20:36",
  "gross_amount": "11000.00",
  "order_id": "orderid-01",
  "payment_type": "akulaku",
  "signature_key": "62a8c432bb5a288a0495dd4f868b0aede4535e0c8a9fbebb3c6e9d4ea0db6f1963e551e70a99e80512030afa5ba8268f9be7b17b13a422ebef4620988c55d5ed",
  "status_code": "202",
  "transaction_id": "b3a40398-d95d-4bb9-afe8-9a57bc0786ea",
  "transaction_status": "expire",
  "fraud_status": "accept",
  "status_message": "midtrans payment notification"
}

Sample Response - Deny Notification

{
  "transaction_time": "2018-08-24 16:20:36",
  "gross_amount": "11000.00",
  "order_id": "orderid-01",
  "payment_type": "akulaku",
  "signature_key": "c2bdfd8d1b25100f5512b2573ecad8f2d324837a731362491b5a6b0bbd7ec74a032010754129f4c74f77a21796f747258ea611a3d5710648f63342570cdd0bb4",
  "status_code": "202",
  "transaction_id": "b3a40398-d95d-4bb9-afe8-9a57bc0786ea",
  "transaction_status": "deny",
  "fraud_status": "accept",
  "status_message": "midtrans payment notification"
}
JSON Attribute Description Type
status_code Status code of transaction charge result. String
status_message Status message describing the result of the API request. String
transaction_id Transaction ID given by Midtrans. String
order_id Order ID specified by the merchant. String
redirect_url The redirect URL to Akulaku payment page. String
gross_amount Total transaction amount in IDR. String
currency ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.		 String
payment_type Payment method used by the customer. String
transaction_time Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. String
transaction_status Transaction status of Akulaku transaction. Possible values are pending, deny. String
fraud_status Detection result by Fraud Detection System (FDS). Possible values are accept : Approved by FDS and challenge: Questioned by FDS.
Note: You have to approve the transaction to accept it or transaction will get cancelled automatically during settlement.
deny: Denied by FDS. Transaction is automatically failed.		 String
channel_response_code Response code from the channel. For more details, refer Channel Response Code. Integer
channel_response_message Response message from the channel. For more details, refer Channel Response Code. String

Channel Response Code

The values and descriptions of channel_response_code and channel_response_message included on API response for some payment channels are given below.

Payment Card Response Codes

Payment card is divided into two categories based on its channel to acquirer: Host-to-Host and MIGS.

Host-to-Host

The banks included in this category are CIMB Niaga, Bank Mandiri, BNI, and Bank Mega.

Response Code Message Description
00 Approved Transaction was successful.
01 Refer to Issuer The customer’s bank (Card Issuer) has indicated a problem with the payment card number. The customer should contact their bank and should use an alternate payment card.
02 Refer to Issuer, special The customer’s bank (Card Issuer) has indicated a problem with the payment card number. The customer should contact their bank and should use an alternate payment card.
03 No Merchant The Merchant ID is invalid. You should contact your Bank and ensure that you have provided the correct Merchant Account Number.
04 Pick Up Card The customer’s bank (Card Issuer) has declined the transaction and requests to retain customer's payment card. This happens when the card is reported to be lost or stolen. The customer should use an alternate payment card.
05 Do Not Honor The customer’s bank has declined the transaction as the payment card number has failed a security check, or the funds have been frozen or depleted. The customer should use an alternate payment card.
06 Error The customer’s bank (Card Issuer) has declined the transaction as there is a problem with the payment card number. The customer should contact their bank. The customer should use an alternate payment card.
07 Pick Up Card, Special The customer’s bank (Card Issuer) has declined the transaction and requested that your customer’s payment card be retained (card reported lost or stolen). The customer should use an alternate payment card.
09 Request In Progress The customer’s bank (Card Issuer) has indicated a problem with the payment card number. The customer should contact their bank and should use an alternate payment card.
12 Invalid Transaction The customer’s bank (Card Issuer) has declined the transaction because of an invalid format or field. Check the transaction information and try processing the transaction again.
13 Invalid Amount An invalid character such as a symbol or space, is passed to the Midtrans. Check your code implementation. Note: This error happens only in Sandbox environment. For Production environment the amount is verified by Midtrans.
14 Invalid Card Number The customer’s bank (Card Issuer) has declined the transaction as the payment card number does not exist. Check the payment card information and try processing the transaction again.
15 No Issuer The customer’s bank (Card Issuer) does not exist. Check the payment card information and try processing the transaction again.
19 Re-enter Last Transaction The transaction has not been processed and the customer should attempt to process the transaction again.
21 No Action Taken The customer’s bank (Card Issuer) has indicated a problem with the payment card number. The customer should contact their bank and use an alternate payment card.
22 Suspected Malfunction The customer’s bank (Card Issuer) cannot be contacted during the transaction. The customer should check the payment card information and try processing the transaction again.
23 Unacceptable Transaction Fee An unspecified error has occurred.
25 Unable to Locate Record On File The customer’s bank (Card Issuer) does not recognize the payment card details. The customer should check the payment card information and try processing the transaction again.
30 Format Error The customer’s bank (Card Issuer) does not recognize the transaction details. The customer should check the transaction information and try processing the transaction again.
31 Bank Not Supported By Switch The customer’s bank (Card Issuer) has declined the transaction as it does not allow transactions originating through mail, telephone, fax, email, or Internet orders. This error occurs with customers attempting to use a Discover Card. The customer should use an alternate payment card.
33 Expired Card, Capture The customer’s bank (Card Issuer) has declined the transaction as payment card has expired or the date is incorrect. Check the expiry date in the transaction and try processing the transaction again.
34 Suspected Fraud, Retain Card The customer’s bank (Card Issuer) has declined the transaction as there is a suspected fraud on this payment card number.
35 Card Acceptor, Contact Acquirer, Retain Card The customer’s bank (Card Issuer) has declined the transaction and requested that the customer’s payment card be retained (card reported lost or stolen). The customer should use an alternate payment card.
36 Restricted Card, Retain Card The customer’s bank (Card Issuer) has declined the transaction and requested to retain the customer’s payment card (card reported lost or stolen). The customer should use an alternate payment card.
37 Contact Acquirer Security Department, Retain Card The customer’s bank (Card Issuer) has declined the transaction and requested to retain the customer’s payment card (card reported lost or stolen). The customer should use an alternate payment card.
38 PIN Tries Exceeded, Capture The customer’s bank (Card Issuer) has declined the transaction as the customer has entered the incorrect PIN three times. The customer’s bank (Card Issuer) has requested you to retain the payment card. The customer should contact the bank and use alternative card.
39 No Credit Account The customer’s bank has declined the transaction as the payment card number used is not a credit account. The customer should use an alternate payment card.
40 Function Not Supported The customer’s bank (Card Issuer) has declined the transaction as it does not allow this type of transaction. The customer should use an alternate payment card.
41 Lost Card The customer’s bank (Card Issuer) has declined the transaction as the card has been reported lost. The customer should use an alternate payment card.
42 No Universal Account The customer’s bank (Card Issuer) has declined the transaction as the account type selected is not valid for this payment card number. The customer should use an alternate payment card.
43 Stolen Card The customer’s bank (Card Issuer) has declined the transaction as the card has been reported stolen. The customer should use an alternate payment card.
44 No Investment Account The customer’s bank (Card Issuer) has declined the transaction as the account type selected is not valid for this payment card number. The customer should use an alternate payment card.
51 Insufficient Funds The customer’s bank (Card Issuer) has declined the transaction as the payment card does not have sufficient funds. The customer should use an alternate payment card.
52 No Cheque Account The customer’s bank (Card Issuer) has declined the transaction as the payment card number is associated to a cheque account that does not exist. The customer should use an alternate payment card.
53 No Savings Account The customer’s bank (Card Issuer) has declined the transaction as the payment card number is associated to a savings account that does not exist. The customer should use an alternate payment card.
54 Expired Card The customer’s bank (Card Issuer) has declined the transaction as the payment card appears to have expired. The customer should check the expiry date entered and try again, or use an alternate payment card.
55 Incorrect PIN The customer’s bank (Card Issuer) has declined the transaction as the customer has entered an incorrect PIN. The customer should re-enter their PIN or use an alternate payment card.
56 No Card Record The customer’s bank has declined the transaction as the payment card number does not exist. The customer should use an alternate payment card.
57 Function Not Permitted to Cardholder The customer’s bank has declined the transaction as this payment card cannot be used for this type of transaction. The customer should use an alternate payment card.
58 Function Not Permitted to Terminal The customer’s bank has declined the transaction as this payment card cannot be used for this type of transaction. This may be associated with a test payment card number. The customer should use an alternate payment card.
59 Suspected Fraud The customer’s bank has declined this transaction as the payment card appears to be fraudulent.
60 Acceptor Contact Acquirer The customer’s bank (Card Issuer) has declined the transaction. The customer should contact their bank and retry the transaction.
61 Exceeds Withdrawal Limit The customer’s bank has declined the transaction as it will exceed the customer’s card limit. The customer should use an alternate payment card.
62 Restricted Card The customer’s bank has declined the transaction as the payment card has some restrictions. The customer should use an alternate payment card.
63 Security Violation The customer’s bank has declined the transaction. The customer should use an alternate payment card.
64 Original Amount Incorrect The customer’s bank has declined the transaction due to the amount attempting to be processed. The customer should check the transaction amount and try again.
66 Acceptor Contact Acquirer, Security The customer’s bank has declined the transaction and request you to contact the bank. The customer should use an alternate payment card.
67 Capture Card The customer’s bank has declined the transaction as the card is suspected to be counterfeit. The customer’s bank (Card Issuer) has requested that your customer’s payment card be retained. The customer should use an alternate payment card.
75 PIN Tries Exceeded The customer’s bank has declined the transaction as the customer has entered the incorrect PIN more than three times. The customer should use an alternate payment card.
82 CVV Validation Error The customer’s bank has declined the transaction as the CVV is incorrect. The customer should check the CVV details and try again. If not successful, the customer should use an alternate payment card.
90 Cutoff In Progress The customer’s bank is temporarily not able to process this customer’s payment card. The customer should attempt to process this transaction again.
91 Card Issuer Unavailable The customer’s bank is unable to be contacted to authorize the transaction. The customer should attempt to process this transaction again.
92 Unable To Route Transaction The customer’s bank cannot be found for routing. This response code is often returned when the customer is using a test payment card number. The customer should attempt to process this transaction again.
93 Cannot Complete, Violation Of The Law The customer’s bank has declined the transaction and requested the customer to contact their bank. The customer should use an alternate payment card.
94 Duplicate Transaction The customer’s bank has declined the transaction as this transaction appears to be a duplicate transmission. No action required.
96 System Error The customer’s bank was not able to process the transaction. The customer should attempt to process this transaction again.
N0 CSC not provided - credit transaction is not allowed Transaction failed. Customers should try using another card.
N7 Decline for CVV2 failure (for Visa cards only) The customer’s bank has declined the transaction as the CVV is incorrect. The customer should check the CVV details and try again. If not successful, the customer should use an alternate payment card.
Q5 Already settled - can't settle twice in a day Transaction has been settled, hence cannot be settled anymore.
Z2 The transaction has already been reversed Transaction has been reversed, hence cannot be reversed anymore.
Z3 Transaction amount is greater than authorized The customer's bank has declined the capture transaction since the amount is greater than the authorized amount. The customer should use an alternate payment card.

MIGS

The banks included in this category are: BCA, BRI, Maybank.

Code Message Explanation
0 Transaction Successful Transaction was successful.
? Response Unknown Need to check directly with the Acquiring Bank.
1 Transaction could not be processed There is an issue with merchant's account or the ID. Or the Access Code used is incorrect.
2 Transaction Declined – Contact Issuing Bank The customer should contact their bank and use an alternate payment card.
3 Declined – No reply from Bank The customer should use an alternate payment card.
4 Transaction Declined – Expired Card The customer’s bank (Card Issuer) has declined the transaction as payment card has expired or the date is incorrect. Check the expiry date in the transaction and try processing the transaction again.
5 Transaction Declined – Insufficient credit The customer’s bank (Card Issuer) has declined the transaction as the payment card does not have sufficient funds. The customer should use an alternate payment card.
6 Transaction Declined – Bank system error The customer's bank or the acquiring bank experienced a system error.
7 Payment Server Processing Error Typically caused by invalid input data such as an invalid payment card number. Processing errors can also occur. The customer should check the payment card information and try processing the transaction again.
8 Transaction Declined – Transaction Type Not Supported The customer’s bank (Card Issuer) has declined the transaction as it does not allow this type of transaction. The customer should use an alternate payment card.
9 Bank Declined Transaction (Do not contact Bank) The customer should use an alternate payment card. Can be caused by following reasons:
  • Transaction Aborted (A)
  • Transaction Blocked (B)
  • Transaction Cancelled (C)
  • Deferred Transaction (D)
  • Transaction Declined – Refer to card issuer (E)
  • Authentication Failed (F)
  • Card Security Code Failed (I)
  • Shopping Transaction Locked - This indicates that there is another transaction taking place using the same shopping transaction number (L)
  • Cardholder is not enrolled in 3D Secure - Authentication Only (N)
  • Transaction is Pending (P)
  • Retry Limits Exceeded, Transaction Not Processed (R)
  • Card Security Code Failed (U)

GoPay Response Codes

Code Message Explanation
900 GENERIC_SERVICE_ERROR Intermittent service error. Try again later.
901 ATTRIBUTE_NOT_AVAILABLE_ERROR Internal System Error.
902 MALFORMED_JSON Internal System Error.
903 FORBIDDEN_OPERATION Internal System Error.
101 WALLET_NOT_FOUND Internal System Error.
102 MERCHANT_NOT_AUTHORIZED Internal System Error.
103 ILLEGAL_KYC_TYPE Internal System Error.
104 ILLEGAL_USER_TYPE Internal System Error.
105 USER_NOT_FOUND Internal System Error.
106 RESERVATION_NOT_FOUND Internal System Error.
107 VOUCHER_BATCH_NOT_FOUND Internal System Error.
108 SPONSOR_NOT_FOUND Internal System Error.
109 CURRENTLY_NOT_ALLOWED Internal System Error.
110 UNAUTHORIZED Internal System Error.
111 PIN_ALREADY_SETUP Internal System Error.
112 WALLET_BLOCKED Internal System Error.
113 INVALID_PIN_FORMAT Internal System Error.
114 PHONE_NUMBER_NOT_FOUND Internal System Error.
115 WALLET_PHONE_NUMBER_NOT_MATCHED Internal System Error.
116 MERCHANT_NOT_FOUND Internal System Error.
117 KYC_NOT_AVAILABLE Internal System Error.
118 WALLET_RULESET_NOT_FOUND Internal System Error.
119 INCORRECT_PIN Internal System Error.
120 PIN_NOT_SETUP Internal System Error.
121 NEW_PIN_SAME_AS_OLD_PIN Internal System Error.
122 ILLEGAL_RECEIVER Internal System Error.
123 KYC_NOT_APPROVED Internal System Error.
124 KYC_PENDING Internal System Error.
125 PIN_IS_REQUIRED Internal System Error.
126 CUSTOMER_WALLET_BLOCKED Internal System Error.
127 SERVICE_PROVIDER_WALLET_BLOCKED Internal System Error.
128 LEDGER_WALLET_NOT_FOUND Internal System Error.
129 WALLET_ALREADY_EXISTS Internal System Error.
130 SERVICE_BLOCKED Internal System Error.
131 LINKED_WALLET_NOT_FOUND Internal System Error.
132 TRANSACTION_IN_PROGRESS Internal System Error.
133 SETTLEMENT_FAILED Internal System Error.
134 MERCHANT_INFORMATION_CACHE_STORE_FAILED Internal System Error.
135 TRANSACTION_NOT_FOUND Internal System Error.
142 INVALID_MERCHANT_IDENTIFIER Internal System Error.
151 AMEND_RESERVATION_INVALID_AMOUNT Internal System Error.
153 INVALID_PAYMENT_OPTION The token is invalid for the payment.
154 INVALID_USER_LOCALE User locale is invalid.
158 INVALID_TRANSACTION_TYPE Payment not eligible for refund.
159 PAYMENT_OPTION_NOT_FOUND Payment option not found.
161 UNSUPPORTED_SERVICE_COUNTRY Unsupported country.
000 AUTHORIZATION_REQUIRED Internal System Error.
001 REQUEST_ID_REQUIRED Internal System Error.
201 NOT_ENOUGH_BALANCE Internal System Error.
202 EXCESSIVE_BALANCE Refund failed because customer balance exceeds their upper limit.
203 RESERVATION_REDEEMED Internal System Error.
204 RESERVATION_EXPIRED Internal System Error.
205 ZERO_PAGE_SIZE Internal System Error.
206 DUPLICATE_RESERVATION Internal System Error.
207 RESERVATION_PROCESSED Internal System Error.
208 INVALID_POINTS_RESERVATION Internal System Error.
209 INVALID_RESERVATION_AMOUNT Internal System Error.
210 RESERVATION_AMOUNT_DOES_NOT_MATCH_PAYMENT Internal System Error.
211 WALLET_BALANCE_LIMIT_VIOLATED Internal System Error.
212 INVALID_MDR Internal System Error.
213 MONTHLY_WALLET_BALANCE_LIMIT_EXCEEDED Internal System Error.
214 RESERVATION_CANCELLED Internal System Error.
215 RECEIVER_MAX_WALLET_BALANCE_LIMIT_EXCEEDED Internal System Error.
216 RECEIVER_MONTHLY_WALLET_BALANCE_LIMIT_EXCEEDED Internal System Error.
220 CURRENCY_MISMATCH Currency is invalid for the payment
301 MALFORMED_PHONE_NUMBER Internal System Error.
302 MISMATCHING_PASSWORD_AND_CONFIRMATION Internal System Error.
303 FIELD_CANNOT_BE_BLANK Internal System Error.
304 MALFORMED_EMAIL_ADDRESS Internal System Error.
305 ILLEGAL_LENGTH_FOR_FIELD Internal System Error.
307 ILLEGAL_SERVICE_PROVIDER_TYPE Internal System Error.
308 PHONE_NUMBER_ALREADY_TAKEN Internal System Error.
309 ACTIVE_WALLET_ALREADY_ASSOCIATED_WITH_PHONE_NUMBER Internal System Error.
310 MALFORMED_DATA Internal System Error.
501 MALFORMED_TRANSACTION Internal System Error.
502 MALFORMED_TRANSACTION_REQUEST Internal System Error.
503 JOURNAL_LOG_NOT_FOUND Internal System Error.
601 VOUCHER_NOT_FOUND Internal System Error.
602 VOUCHER_EXPIRED Internal System Error.
603 VOUCHER_REDEEMED Internal System Error.
604 VOUCHER_DISABLED Internal System Error.
605 VOUCHER_NOT_YET_AVAILABLE Internal System Error.
606 VOUCHER_BATCH_INVALID Internal System Error.
607 MALFORMED_POINTS_VOUCHER_TRANSACTION_REQUEST Internal System Error.
608 VOUCHER_NOT_ALLOCATED_TO_WALLET_ID Internal System Error.
609 VOUCHER_RESERVATION_NOT_FOUND Internal System Error.
610 VOUCHER_RESERVED Internal System Error.
611 NOT_ENOUGH_VOUCHERS Internal System Error.
612 VOUCHER_ALLOCATION_FAILED Internal System Error.
613 VOUCHER_BATCH_GROUP_NOT_FOUND Internal System Error.
614 VOUCHER_BATCH_SUPER_GROUP_NOT_FOUND Internal System Error.
615 VOUCHER_ALLOCATION_RATE_LIMIT_EXCEEDED Internal System Error.
616 MALFORMED_VOUCHER_BATCHES_REQUEST Internal System Error.
617 VOUCHER_BATCH_GROUP_INVALID_DUPLICATE_ERROR Internal System Error.
618 VOUCHER_BATCH_GROUP_INVALID_REQUEST Internal System Error.
619 VOUCHER_BATCH_GROUP_INVALID_ATTRIBUTE_ERROR Internal System Error.
620 VOUCHER_BATCH_SUPER_GROUP_INVALID_DUPLICATE_ERROR Internal System Error.
621 VOUCHER_BATCH_SUPER_GROUP_INVALID_REQUEST Internal System Error.
622 VOUCHER_REDEMPTION_TIME_RESTRICTED Internal System Error.
623 INVALID_VOUCHER_BATCH_DATA Internal System Error.
624 VOUCHER_PICKS_COUNT_EXCEEDED_ERROR Internal System Error.
625 RESERVED_VOUCHERS_FOR_ALLOCATION_NOT_FOUND Internal System Error.
626 RESERVE_FOR_ALLOCATION_REFERENCE_ID_NOT_FOUND Internal System Error.
627 INVALID_VOUCHER_REFUND_REQUEST Internal System Error.
628 VOUCHER_NOT_AVAILABLE_WITH_POINTS Internal System Error.
629 VOUCHER_BATCH_NO_LONGER_AVAILABLE Internal System Error.
701 POINTS_TOKEN_ALLOCATION_ERROR Internal System Error.
703 POINTS_TOKEN_NOT_ALLOCATED_ERROR Internal System Error.
704 POINTS_TOKEN_DUPLICATE_JOURNAL_LOG_ID_ERROR Internal System Error.
705 POINTS_TOKEN_NO_MORE_AVAILABLE_ERROR Internal System Error.
706 POINTS_TOKEN_UNRECOGNIZED_SERVICE_TYPE_ERROR Internal System Error.
707 POINTS_TOKEN_POINTS_NOT_ENABLED_ERROR Internal System Error.
708 UNKNOWN_POINTS_TOKEN_TYPE_ERROR Internal System Error.
709 POINTS_TOKEN_TYPE_DUPLICATE_ERROR Internal System Error.
710 POINTS_TOKEN_ALLOCATION_RATE_LIMIT_EXCEEDED Internal System Error.
711 POINTS_TOKEN_TIER_CONFIG_NOT_FOUND Internal System Error.
712 POINTS_TOKEN_CONFIG_TIER_INVALID_BOUNDARY_ERROR Internal System Error.
713 POINTS_TOKEN_CONFIG_TIERS_INVALID_RANGE_ERROR Internal System Error.
714 POINTS_TOKEN_DUPLICATE_TRANSACTION_REFERENCE_ERROR Internal System Error.
715 POINTS_TOKEN_ALREADY_REDEEMED_ERROR Internal System Error.
801 DIRECT_DEBIT_TOKEN_NOT_FOUND Internal System Error.
802 DIRECT_DEBIT_REGISTER_CARD_ERROR Internal System Error.
803 DIRECT_DEBIT_CARD_NOT_FOUND Internal System Error.
804 DIRECT_DEBIT_PAYMENT_ERROR Internal System Error.
805 DIRECT_DEBIT_CARD_ALREADY_REGISTERED Internal System Error.
806 DIRECT_DEBIT_CARD_DELETE_ERROR Internal System Error.
807 DIRECT_DEBIT_CARD_EXCEED_LIMIT Internal System Error.
808 DIRECT_DEBIT_OTP_IS_REQUIRED Internal System Error.
809 DIRECT_DEBIT_OTP_IS_INVALID Internal System Error.
810 DIRECT_DEBIT_OTP_RESENT_COUNT_REACHED Internal System Error.
811 DIRECT_DEBIT_INSUFFICIENT_BALANCE Internal System Error.
812 DIRECT_DEBIT_CARD_BLOCKED Internal System Error.
813 DIRECT_DEBIT_TIMEOUT Internal System Error.
814 DIRECT_DEBIT_INVALID_REQUEST Internal System Error.
815 DIRECT_DEBIT_UNAUTHORIZED_REQUEST Internal System Error.
816 DIRECT_DEBIT_MERCHANT_TIMEOUT Internal System Error.
817 DIRECT_DEBIT_PAYMENT_REJECTED Internal System Error.
818 DIRECT_DEBIT_REFRESH_CARDS_ERROR Internal System Error.
819 DIRECT_DEBIT_PAYMENT_NOT_FOUND Internal System Error.
822 CARD_PAYMENT_INVALID_TOKEN_ERROR Invalid card token
823 DIRECT_DEBIT_PAYMENT_STATUS_NOT_MODIFYABLE Payment is not eligible for cancellation
824 DIRECT_DEBIT_INVALID_INTENT Invalid intent
825 DIRECT_DEBIT_REQUEST_REJECTED The debit request is denied by bank/payment partner.
827 INCORRECT_CVV_ERROR Incorrect CVV.
831 DIRECT_DEBIT_CARD_EXPIRED Direct debit card expired.
832 DIRECT_DEBIT_COUNTRY_NOT_SUPPORTED Direct debit country is not supported for transaction.
833 DIRECT_DEBIT_3DS_CHECK_FAILED 3D Secure check failed.
1101 USER_BANK_ACCOUNT_ALREADY_REGISTERED Internal System Error.
1102 USER_BANK_ACCOUNT_INVALID_BANK_CODE_OR_SHORT_NAME Internal System Error.
1103 USER_BANK_ACCOUNT_NOT_FOUND Internal System Error.
1104 USER_DEFAULT_BANK_ACCOUNT_CANNOT_BE_DEACTIVATED Internal System Error.
1105 USER_BANK_ACCOUNT_ALREADY_DEACTIVATED Internal System Error.
1106 USER_GROUP_NOT_DEFINED Internal System Error.
1201 P2P_RATE_LIMIT_EXCEEDED Internal System Error.
1202 P2P_PROFILE_RATE_LIMIT_EXCEEDED Internal System Error.
1203 PIN_RATE_LIMIT_EXCEEDED Internal System Error.
1301 WALLET_GROUP_NOT_FOUND Internal System Error.
1302 WALLET_GROUP_ALREADY_EXISTS Internal System Error.
1303 WALLET_LIMITS_INVALID_VALUE Internal System Error.
1304 WALLET_GROUP_NOT_ALLOWED Target group not allowed
1401 WITHDRAWAL_RATE_LIMIT_EXCEEDED Internal System Error.
1402 WITHDRAWAL_BATCH_NOT_FOUND Internal System Error.
1403 WITHDRAWAL_INVALID_FILE_FORMAT Internal System Error.
1404 WITHDRAWAL_REQUEST_NOT_FOUND Internal System Error.
1405 WITHDRAWAL_FEATURE_DISABLED Internal System Error.
1406 WITHDRAWAL_MULTI_REQUEST_FOUND Internal System Error.
1407 WITHDRAWAL_DAILY_MAXIMUM_REQUEST_LIMIT_EXCEEDED Internal System Error.
1408 WITHDRAWAL_WEEKLY_MAXIMUM_REQUEST_LIMIT_EXCEEDED Internal System Error.
1409 WITHDRAWAL_DAILY_MAXIMUM_AMOUNT_LIMIT_EXCEEDED Internal System Error.
1410 WITHDRAWAL_USER_BANK_NOT_SUPPORTED Internal System Error.
1411 WITHDRAWAL_AMOUNT_LIMIT_VOILATED Internal System Error.
1412 WITHDRAWAL_FEATURE_DISABLED_HOLIDAY Internal System Error.
1413 WITHDRAWAL_FEATURE_DISABLED_BANK_MAINTENANCE Internal System Error.
1414 WITHDRAWAL_MIN_AMOUNT_LIMIT_VIOLATED Internal System Error.
1415 WITHDRAWAL_MAX_AMOUNT_LIMIT_VIOLATED Internal System Error.
1418 WITHDRAWAL_VALIDATE_BANK_ACCOUNT_ERROR Bank account validation failed.
1419 WITHDRAWAL_VALIDATE_BANK_ACCOUNT_NOT_FOUND Account not found.
1420 WITHDRAWAL_VALIDATE_BANK_ACCOUNT_BAD_INPUT Invalid field on bank validation request.
1421 WITHDRAWAL_VALIDATE_BANK_ACCOUNT_TOO_MANY_ATTEMPTS User ID has exceed rate limit.
1422 WITHDRAWAL_VALIDATE_BANK_ACCOUNT_NOT_VALID Withdrawal to the selected bank account is not permitted.
1423 WITHDRAWAL_BANK_NOT_FOUND The specified bank code is not found in the system.
1424 WITHDRAWAL_KYC_TYPE_NOT_SUPPORTED Invalid KYC type.
1426 WITHDRAWAL_INVALID_PARTNER_BANK The combination of partner and allowed banks are not valid.
1428 WITHDRAWAL_INVALID_GROUP Invalid withdrawal group.
1500 KYC_DOCUMENT_NOT_FOUND Internal System Error.
1501 KYC_ALREADY_APPROVED_OR_REJECTED Internal System Error.
1503 KYC_APPROVAL_LOG_NOT_FOUND Internal System Error.
1504 INVALID_KYC_APPROVAL_LEVEL Internal System Error.
1505 INVALID_KYC_TYPE Internal System Error.
1601 INVALID_OTP_ACTION Internal System Error.
1602 OTP_RESENT_COUNT_REACHED Internal System Error.
1603 OTP_IS_REQUIRED Internal System Error.
1604 OTP_IS_INVALID Internal System Error.
1605 OTP_NOT_FOUND_IN_CACHE Internal System Error.
1606 OTP_DECRYPTION_ERROR Internal System Error.
1607 INVALID_QR_CODE_DATA Internal System Error.
1608 QR_CODE_DATA_CHECKSUM_VALIDATION_FAILURE Internal System Error.
1609 OTP_GENERATE_COUNT_REACHED Internal System Error.
1610 OTP_EXPIRED Internal System Error.
1701 MID_NOT_FOUND Internal System Error.
1702 INVALID_KARTUKU_TRANSACTION_STATE Internal System Error.
1703 MIDTRANS_MERCHANT_NOT_ACTIVE Internal System Error.
1801 INTENT_NOT_SUPPORTED Internal System Error.
1802 WALLET_DETAILS_MISSING Internal System Error.
1803 WALLET_TYPE_WRONG_FOR_INTENT Internal System Error.
1804 PAYMENT_REQUEST_ALREADY_FULFILLED Internal System Error.
1805 ORDER_ID_REFERENCE_ID_NOT_MATCHED Internal System Error.
1806 RECEIVER_WALLET_ID_NOT_MATCHED Internal System Error.
1807 INTENT_NOT_MATCHED Internal System Error.
1808 PAYMENT_REQUEST_DETAILS_MISSING Internal System Error.
1809 ACCOUNTING_CATEGORY_NOT_MATCHED Internal System Error.
1810 METADATA_MALFORMED Internal System Error.
1811 PAYMENT_REQUEST_NOT_FOUND Internal System Error.
1812 ORDER_ID_NOT_UNIQUE Internal System Error.
1813 SENDER_WALLET_ID_NOT_MATCHED Internal System Error.
1814 SENDER_RECEIVER_WALLET_SAME Internal System Error.
1815 PAYMENT_REQUEST_INITIATED_BUT_OTP_FAILED Internal System Error.
1816 AUTHORIZATION_NOT_REQUIRED Internal System Error.
1817 PAYMENT_REQUEST_NOT_FULFILLED Internal System Error.
1818 PAYMENT_REQUEST_ALREADY_CANCELLED Internal System Error.
1819 PAYMENT_REQUEST_NOT_IN_INITIATED_STATE Internal System Error.
1820 PAYMENT_REQUEST_WITH_PROMO_CODES_NOT_FOUND Internal System Error.
1821 BAD_CREATE_PAYMENT_REQUEST Internal System Error.
1822 EXCEEDED_PERMISSIBLE_AMOUNT Internal System Error.
1823 PAYMENT_REQUEST_EXPIRED Internal System Error.
1901 REKPON_INVALID_BANK_ACCOUNT_NUMBER Internal System Error.
1902 REKPON_INVALID_BANK_ACCOUNT_NAME Internal System Error.
2001 REFUND_REQUESTED_EXCEEDS_ORIGINAL_TRANSACTION Internal System Error.
2002 REFUND_ALREADY_PROCESSED Internal System Error.
2003 REFUND_ALREADY_EXPIRED Internal System Error.
2005 DUPLICATE_REFUND_REQUEST_FOR_SAME_ORIGINAL_TRANSACTION Refund under process. Please try again later.
2006 ORDER_IN_INVALID_STATUS_FOR_REFUND Payment not eligible for refund.
2007 PAYMENT_IN_PROGRESS Payment still processing. Please try again in later.
2100 POINTS_INVALID_EXCHANGE_REQUEST Internal System Error.
2101 INVALID_AMOUNT Internal System Error.
2103 DUPLICATE_POINTS_EXCHANGE_REQUEST Internal System Error.
2201 PROMO_NOT_APPLICABLE Internal System Error.
2202 PROMO_CODE_NOT_VALID Internal System Error.
2203 PROMO_CODE_EXPIRED Internal System Error.
2204 INVALID_PROMO_VALID_FROM Internal System Error.
2205 INVALID_PROMO_VALID_TILL Internal System Error.
2206 ACTIVE_PROMOTION_UPDATION_REQUEST Internal System Error.
2301 SERVICE_BLOCKING_INVALID_SERVICE Internal System Error.
2400 INVALID_VOUCHER_SEARCH_REQUEST Internal System Error.
2500 INVALID_ENROLLMENT Internal System Error.
2601 EXPLORE_TYPE_UNSUPPORTED Internal System Error.
2602 EXPLORE_CODE_NOT_IDENTIFIED Internal System Error.
2603 EXPLORE_INVALID_FORMAT Internal System Error.
2604 EXPLORE_MERCHANT_INFORMATION_ERROR Internal System Error.
2700 INVALID_WALLET_COUNTRY Internal System Error.
2701 MULTI_CURRENCY_TRANSACTION_NOT_SUPPORTED The currency is not supported for the country.
2800 EXCHANGE_CUTOFF_IN_PROCESS Internal System Error.
2801 EXCHANGE_SYSTEM_FAILURE Internal System Error.
2802 EXCHANGE_SIGNATURE_NOT_MATCH Internal System Error.
2803 EXCHANGE_ADDITIONAL_DATA Internal System Error.
2804 INVALID_REQUEST_TIMESTAMP Internal System Error.
2901 DUPLICATE_TRANSACTION_REQUEST Internal System Error.
3006 SENDER_WALLET_BLOCKED Sender Wallet blocked.
3007 ORDER_NOT_FOUND Payment not found. The payment ID passed is either not present or expired.
3060 ORDER_IN_CREATED_STATE Payment not captured yet. This error will only come if you're initiating a partial refund. A complete refund would have cancelled the payment.
3063 ORDER_IN_CANCELLED_STATE Order is in cancelled state.
3067 ORDER_NOT_IN_CREATED_STATE Error when trying to process/cancel order and order not in created state.
3101 TOPUP_INVALID_FIELD Invalid field during top-up request.
3102 TOPUP_REFERENCE_ID_ALREADY_EXISTS Reference ID for top up request has already been used.
3103 TOPUP_INVALID_PARTICIPANT Invalid sender or receiver.
4003 UBAC_UNAUTHORISED Transaction rejected.
4060 FRS_REJECTED Transaction rejected.
5001 AUTHORISATION_NOT_FOUND Authorization not found due to invalid or expired reference id.
5002 INVALID_AUTHORISATION_ACTION Invalid authorization.
5003 INVALID_AUTHORISATION No Matching authorization found.
5004 MULTIPLE_AUTHORISATIONS_NOT_ALLOWED Multiple authorizations not allowed.
6311 CHALLENGE_ID_NOT_FOUND Challenge ID not found.

ShopeePay Response Codes

Code Message
-2 A server dropped the connection.
-1 A server error occurred.
0 Success.
1 Request parameters error.
2 Permission denied.
4 Merchant/Store not found.
6 The user making the payment has not activated their wallet.
7 Expired.
9 User’s account is banned.
11 Duplicate request/transaction.
24 User's account is frozen.
42 Insufficient balance.
101 One of the user’s wallet limits has been exceeded.
102 One of the user’s wallet limits has been exceeded.
103 User exceeded daily payment limit. Limit will reset the next day.
104 One of the user’s wallet limits has been exceeded.
105 Authorization code is invalid.
121 Client attempts to update completed transaction.
301 Invalid payment code or QR content.
303 Merchant is trying to make payment to their own user account.
304 Refund/Void. Cannot be processed due to payment exceeding validity period. Valid refund period is set at 24 hours by default.

Transaction Status

The table given below describes the transaction_status used by Midtrans APIs.

Status Description Possible change(s)
authorize Midtrans authorizes the payment card used for the transaction. Must be captured to process the balance.
Note: This is valid for payment card only.		 capture,
cancel
capture The transaction is successful and the card balance is captured successfully. If no action is taken by you, the transaction will be successfully settled within 24 hours or within the agreed settlement time with your partner bank. The transaction status is settlement. It is safe to assume a successful payment. settlement,
cancel
settlement The transaction is successfully settled. Funds have been credited to your account. refund,
chargeback,
partial_refund,
partial_chargeback
deny The credentials used for payment are rejected by the payment provider or Midtrans Fraud Detection System (FDS). To know the reason and details for the denied transaction, see the status_message in the response. N/A
pending The transaction is created and is waiting to be paid by the customer at the payment providers like direct debit, Bank Transfer, E-wallet, and so on. settlement,
deny,
cancel,
expire
cancel The transaction is cancelled. This can be triggered by Midtrans or the partner bank. N/A
refund The transaction is marked to be refunded. Refund status is triggered by you. settlement
partial_refund The transaction is marked to be partially refunded. settlement
chargeback The transaction is marked to be charged back.
Note: Applicable for payment card only.		 settlement
partial_chargeback The transaction is marked to be partially charged back. settlement
expire The transaction is not available for processing, because the payment was delayed. N/A
failure Unexpected error occurred during transaction processing. N/A

Fraud Status

Fraud Status used by Midtrans API are given below.

Status Description
accept Transaction is safe to proceed. It is not considered as a fraud.
deny Transaction is considered as fraud. It is rejected by Midtrans.
challenge Transaction is flagged as potential fraud, but cannot be determined precisely. You can accept or deny the transaction from MAP account or by using Approve Transaction API or Deny Transaction API.
If no action is taken, the transaction is denied automatically.

Deprecation Notices

November 7, 2017

Starting on 1st February, 2018, channel parameter from Get Card Token request and Charge API request will be permanently removed. Once it is effective, any channel parameter sent to Midtrans will be disregarded. We advise you to remove channel parameter on your end immediately.

Following this announcement, we have made channel parameter as optional. However, should you choose to do a transaction via MIGS banks, you will need to send bank parameter to Midtrans. Otherwise it will return an error. A few instances where the changes may be applicable are given below.

Channel Bank Choice Recommended
No No any non-MIGS bank ✅
No MIGS specific MIGS bank ✅
No Non-MIGS specific non-MIGS bank ✅
MIGS No any MIGS bank ❌
MIGS MIGS specific MIGS bank ❌
MIGS Non-MIGS 402 Error ❌

August 31, 2017

We are improving our API to meet your security needs. Currently, Mandiri ClickPay API payload consists of full PAN number which pose a risk of leaking customer's card credentials.

We are introducing new flow for Mandiri ClickPay. This new flow will enable you to exchange customer card data for a token_id on client side. Consequently, the token_id is passed as Mandiri ClickPay parameter instead of card_number.

We highly recommend you to update your Mandiri ClickPay implementation to cater this new flow since we are going to deprecate the old implementation by 1st December, 2017. For implementation details, refer Mandiri Bill Payment.

August 3, 2017

Starting from 1st November, 2017, we are limiting the characters to make sure that order_id are URL safe. Allowed Symbols are dash(-), underscore(_), tilde (~), and dot (.). For more details, refer Transaction Details Object.

December 1, 2016

Starting from 15th January, 2017, we are going to prohibit the use of decimal value for gross_amount. Few examples of valid and invalid values are given below.

Example Validity
"10000" Valid
10000 Valid
"10000.00" Valid
"10000.01" Invalid

Invalid gross_amount will be rejected with a status_code:400 (validation error).

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

shell php javascript python go