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": "41111111-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.
- Login to MAP account.
- Select Sandbox environment.
- Retrieve API access Keys.
- Create a transaction to generate an Order ID or use
SANDBOX-G710367688-806
. - 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.
- 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.
- Replace
Username
andPassword
. The BASIC AUTH format isUsername:Password
. ReplaceUsername
with Server Key and leavePassword
blank. So, this results in a string{Your_Server_Key}:
. - Encode the resulting string to Base64 format.
- 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.
Content-Type: application/json
Accept: application/json
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",
"url": "https://tokobuah.com/apple-fuji"
}]
JSON Attribute | Description | Type | Required |
---|---|---|---|
id | Item ID. | String | Optional |
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 |
url | HTTP URL of the item in the merchant site | String | Optional |
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 |
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 |
Seller Details Object
"seller_details": {
"id": "sellerId-01",
"name": "John Seller",
"email": "seller@email.com",
"url": "https://tokojohn.com",
"address": {
"first_name": "John",
"last_name": "Seller",
"phone": "081234567890",
"address": "Kemanggisan",
"city": "Jakarta",
"postal_code": "12190",
"country_code": "IDN"
}
}
JSON Attribute | Description | Type | Required |
---|---|---|---|
id | Seller's ID. | String(255) | Optional |
name | Seller's name. | String(255) | Optional |
Seller's email. | String(255) | Optional | |
url | Seller's HTTP URL. | String(255) | Optional |
address | Seller's address. | JSON Array | Optional |
Seller Address Object
JSON Attribute | Description | Type | Required |
---|---|---|---|
first_name | Seller's first name. | String(255) | Optional |
last_name | Seller's last name. | String(255) | Optional |
phone | Seller's phone number. | String(255) | Optional |
address | Seller's address. | String(255) | Optional |
city | City of the seller's address. | String(255) | Optional |
postal_code | Postal code of the seller's address. Note: Allowed characters are alphabets, numbers, dash ( - ), and space ( ). |
String(255) | Optional |
country_code | Country ID of the seller's 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.
|
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",
"bill_key" : "081211111111"
}
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 |
bill_key | Custom bill key 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.
|
String(6-12) | 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==",
"recurring": false
}
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 |
recurring | Set the value to true to mark as a recurring transaction, only allowed for authorised merchant. 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 |
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 |
Custom Expiry Object
"custom_expiry": {
"order_time": "2016-12-07 11:54:12 +0700",
"expiry_duration": 60,
"unit": "minute"
}
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) |
Handling Notifications
There's two type of notification in Midtrans, Transaction notification and Pay Account notification. Transaction notification is sent when a customer completes the transaction or when the transaction status changes. While Pay Account notification is sent when user successfully linked account or when the account is unlinked.
Merchant's notification URL can be configured on merchant dashboard, payment notification URL
for Transaction notification endpoint and pay account notification URL
for Pay Account notification endpoint.
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.
Notification Type | signature_fields |
---|---|
Transaction notification | order_id + status_code + gross_amount + merchant_server_key |
Pay Account notification | account_id + account_status + status_code + merchant_server_key |
Signature key logic
Base16(SHA512(signature_fields))
Sample code generate Transaction notification 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 for Transaction notification or get account status for Pay Account notification. The response is the similar as the notification status.
Best Practices to Handle Notification
The guidelines to handle the notifications are given below.
- Use HTTPS Endpoint
It is secure and there cannot be MITM attacks because Midtrans verifies that the name on the server certificate matches with the host name. In addition to this, do not use self-signed certificates. - Use Notification Callback URL
Use standard port (80/443) for Notification Callback URL. - Implement Notification in an Idempotent Way
In extremely rare cases, Midtrans may send multiple notifications for the same transaction event. It should not cause double entries at the merchant's end. To prevent this,order_id
oraccount_id
can be used as the key to track the entries. - Use Signature Key
Check the signature key of the notification. It confirms that the notification is actually sent by Midtrans. We encode the shared secret (server) key. Nobody else can build this signature hash. - Check the Status
Check some fields given below, to ensure that the process is successful.- Transaction notification can check this 3 fields:
status_code
: Should be 200 for successful transactions.fraud_status
: ACCEPT.transaction_status
: settlement/capture.
- Pay Account notification can check this 2 fields:
status_code
: Should be 200 forENABLED
or 204 forDISABLED
account_status
: ENABLED / DISABLED.
- Transaction notification can check this 3 fields:
- Check Current Status
We strive to send the notification immediately after the transaction occurs. But in extremely rare cases, it may get delayed because of transaction spikes. If you do not receive a notification, please use the Status API to check for current status of the transaction. - Use Status API
Use Status API to get latest status.- Transaction notification can call Status API
- Pay Account notification can call Account Status API to get the latest account status
- Reduce the Response Time
We set the HTTP timeout to fifteen seconds. Please strive to keep the response time of the the HTTP notifications under five seconds. - Ignore delayed status notifications
In extremely rare cases Midtrans may send the HTTP notifications out of order. For example, it may sendtransaction_status:"settlement"
before sending atransaction status:"pending"
. It is important that such later notifications are ignored. But again, use Midtrans status API to confirm the actual status. - Use JSON Parser
We send the notification body as JSON. Therefore, please parse the JSON with a JSON parser. New fields get added to the notification body. Parse the JSON in a non-strict format, so that when the parser sees new fields, it should not throw exception. It should gracefully ignore the new fields. This allows Midtrans to extend its notification system for newer use cases without breaking old clients. - Use the right HTTP Status code Always use the right HTTP Status code for responding to the notification. Midtrans handles retry for error cases differently based on the status code.
- for
2xx
: No retries, it is considered success. - for
500
: Retry only once. - for
503
: Retry four times. - for
400/404
: Retry two times. - for
301/302/303
: No retries. We suggest to update the Notification endpoint in Settings instead of replying to these status code. - for
307/308
: Follow the new URL with POST method and same notification body. Max redirect is five times. - for all other failures: Retry five times.
- for
- Retry at the most five times Midtrans enables retry at most five times with following policy.
- Different retry intervals from 1st time to 5th time (2m, 10m, 30m, 1.5hour, 3.5hour).
- Put a time shift for each retry based on the above interval. For example, for the first time, retry might be two minutes after the job failed. The second retry might be ten minutes after the first retry is failed and so on.
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. This is only applies for Transaction notification.
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.
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
}
}'
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.
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.
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. BRImo: 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.
- Get Card Token: Securely sends the customer’s payment card details to Midtrans server, without the merchant handling the credit card details.
- 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. |
Changes list:
- Change on token_id length from
6 first digit + "-" + 4 last digit + "-" + 36 random digit
into 8first digit + "-" + 4 last digit + "-" + 36 random digit
(e.g:481111-1114-7baba36c-5698-47cf-9170-80efd6a2e973
to48111111-1114-7baba36c-5698-47cf-9170-80efd6a2e973
) - Change on saved_token_id length from
6 first digit + 22 random digit + 4 last digit
into8 first digit + 20 random digit + 4 last digit
(e.g:481111sHdcfSakAvHvFQFEjTivUV1114
to48111111sHfSakAvHvFQFEjTivUV1114
) - Masked_card on Response, Event, log changed from
6 first digit + 4 last digit from card number
into8 first digit + 4 last digit
from a card number - Support 8 Digit bin in Aegis
- Support 8 digit bin in BIN API
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, 48111111sHfSakAvHvFQFEjTivUV1114 . |
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. | "48111111-1114-d3d690db-3e18-4edd-9fee-4d061e4eb6f3" Note: token_id is required during Card Payment Charge Transaction. |
hash | One way hashing from given card number to a random id. | "6d9df2ff-ae9c-3cee-a5ff-a063dc476077" |
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 arecapture : 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 areaccept : 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 8-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 arecapture : 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 areaccept : 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 8-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 fields
- Set custom expiry
- Add metadata The subsequent sections explain these features in detail.
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": "48111111-1114",
"bank": "bni"
}
Sample Response - Set Custom Field Notifications
{
"masked_card": "48111111-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.
-
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. -
Send Charge API request with the custom fields value.
-
The label and value of the custom fields can be checked using the Order ID of a transaction.
-
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.
- Bank Transfer: Permata Virtual Account, BCA Virtual Account, Mandiri Bill Payment, BNI Virtual Account, BRI Virtual Account
- Direct Debit: BCA KlikPay, KlikBCA, BRImo, CIMB Clicks, Danamon Online Banking, UOB Ezpay
- E-money: QRIS, GoPay, ShopeePay
- Over the Counter: Indomaret, Alfamart
- Cardless Credit: Akulaku, Kredivo
The transaction is rejected if the custom expiry exceeds the allowed maximum time.
See Custom Expiry Object for reference.
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": "48111111-1114",
"bank": "bni"
}
Sample Response - Notification
{
"masked_card": "48111111-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 or Pre-Authorized GoPay.
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" : "45111111-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 8-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 areaccept : 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" : "45111111-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 arecapture : 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 areaccept : 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 8-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" : "45111111-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 8-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 arecapture : 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 areaccept : 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.
- Bank Transfer: Permata Virtual Account, BCA Virtual Account, Mandiri Bill Payment, BNI Virtual Account, BRI Virtual Account
- Direct Debit: BCA KlikPay, KlikBCA, BRImo, CIMB Clicks, Danamon Online Banking, UOB Ezpay
- E-Money: QRIS, GoPay, ShopeePay
- Over the Counter: Indomaret, Alfamart
- Cardless Credit: Akulaku
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" : "48111111-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": "48111111-1114",
"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 8-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 arecapture : 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 areaccept : 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 arecapture : 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" : "48111111-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" : "48111111-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 arerefund : 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 arerefund : 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 Status
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" : "48111111-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",
"payment_option_type": "GOPAY_WALLET"
}
Sample Response - Success (Refund)
{
"status_code" : "200",
"status_message" : "Success, transaction found",
"transaction_id" : "249fc620-6017-4540-af7c-5a1c25788f46",
"masked_card" : "48111111-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",
"payment_option_type": "GOPAY_WALLET",
"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" : "48111111-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",
"payment_option_type": "GOPAY_WALLET",
"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 8-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 arecapture : 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 areaccept : 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 | |
payment_option_type | Type of payment that is being used, possible values are GOPAY_WALLET , PAY_LATER , GO_CICIL , GOPAY_COINS (more possible values will be added once we launch more payment option on Gopay). Only available for Gopay payment type. |
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.
per_page
is not set,page
is not set: Merchant gets F, E, D, C, B, Aper_page
is set 2,page
is not set: Merchant gets F, Eper_page
is set 2,page
is set 1: Merchant gets D, Cper_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 arecapture : 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 areaccept : 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
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": "48111111-1114"
}
JSON Attribute | Description | Type |
---|---|---|
transaction_id | Transaction ID given by Midtrans. | String |
masked_card | First 8-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 Account Request
{
"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.
-
activation-link-url
is for customer authentication in browser or WebView. This redirection is recommended for desktop. The customer needs to scan the QR code shown on this page using their Gojek app to verify the linking. Once the linking is verified, then this page is redirected back to the merchant page. For merchants with special agreement with GoPay, this page may show OTP/PIN page instead. -
activation-link-app
is for customer authentication in Gojek app (This might not be applicable for all merchants). The customer needs to input OTP/PIN from the Gojek app.
Pay Account Link Notification
Sample Notification - Pay Account Link Notification
{
"account_id": "00000269-7836-49e5-bc65-e592afafec14",
"merchant_id": "M099098",
"payment_type": "gopay",
"signature_key": "ad7ccda03d8ec6f2f415661fb511d47fcd17dcc7d7e1ade96a305dd5d3bc2bea5438a8bdfe1aeedabdefb226000338ac169fc18d5ae73788fd5e78dbac945ce4",
"status_code": "200",
"account_status": "ENABLED",
"status_message": "Midtrans account_linked notification"
}
Pay Account link notification will be sent to merchant after user have been redirected to provider app and successfully input their pin/OTP. This notification sample can be seen on the side, and you can see Handle notifications section to know how to handle the notifications.
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 |
Gopay Metadata Field | Description | Type |
---|---|---|
payment_options.active | Flag to mark if payment option is active. | Boolean |
payment_options.token | Token that need to be use on Gopay Tokenization charge request as payment_option_token . |
String |
payment_options.balance | Linked account balance for each payment options. | String |
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 |
Pay Account Unbind Notification
Sample Notification - Pay Account Unbind Notification
{
"account_id": "00000269-7836-49e5-bc65-e592afafec14",
"merchant_id": "M099098",
"payment_type": "gopay",
"signature_key": "ad7ccda03d8ec6f2f415661fb511d47fcd17dcc7d7e1ade96a305dd5d3bc2bea5438a8bdfe1aeedabdefb226000338ac169fc18d5ae73788fd5e78dbac945ce4",
"status_code": "204",
"account_status": "DISABLED",
"status_message": "Midtrans account_unlinked notification"
}
Pay Account unbind notification will be sent to merchant when user unlinked the account from merchant services/payment provider service (ex: Gojek App). This notification sample can be seen on the side, and you can see Handle notifications section to know how to handle the notifications.
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": "45563300",
"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 |
API Headers
Header Parameter | Description | Required | Example |
---|---|---|---|
Idempotency-Key | Idempotency key to safely handle retry requests. More info on Idempotent Requests | Optional | d63ae3e0-a7c5-4733-8d81-b451168d8a2c-charge |
X-Payment-Locale | Header provided to change language on any web pages rendered by specific payment type (Currently only for Gopay linking & charge). Default value is id-ID |
Optional | en-EN or id-ID |
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 the same 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 will process 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 46. 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.
Update: There will be an automated retry mechanism for failed payment. When a transaction failed to be processed, the mechanism will attempt to process the payment again after 1 hour. This mechanism will occur 3 times and if the payment still failed after that, the transaction will be arranged as inactive.
Example: There's a payment that's failed to be processed at 11 Oct 2022 15.48 WIB. Then, retry attempts will possibly occur at:
- 11 Oct 2022 16.48 WIB
- 11 Oct 2022 17.48 WIB
- 11 Oct 2022 18.48 WIB
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": "48111111sHfSakAvHvFQFEjTivUV1114",
"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. Generated order ID will contain subscription name and 10 digits of unique number. Note: Allowed symbols are dash(-), underscore(_), tilde (~), and dot (.). |
String(40) | 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": "48111111sHfSakAvHvFQFEjTivUV1114",
"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": "48111111sHfSakAvHvFQFEjTivUV1114",
"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": "48111111sHfSakAvHvFQFEjTivUV1114",
"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."
}
HTTP Notification Example
Here are some examples of possible JSON responses as HTTP notification in recurring API for:
- successful subscription creation
- successful credit card payment
- successful GoPay payment
- failed credit card payment
- failed GoPay payment
HTTP Notification - successful subscription creation
{
"token": "8447a56f-0e5e-498a-a948-eefa88265544",
"status": "active",
"schedule": {
"start_time": "2022-10-26T04:20:00.000000Z",
"next_execution_at": "2022-10-26T04:20:00.000000Z",
"interval_unit": "month",
"interval": 1,
"current_interval": 0
},
"payment_type": "credit_card",
"name": "SUBSCRIBE-1666753619",
"metadata": {
"meta": "data"
},
"merchant_id": "M099098",
"id": "a05a8d85-8e22-4a9d-80bd-1e6199aea3f3",
"customer_details": {
"first_name": "John"
},
"currency": "IDR",
"amount": "14000"
}
HTTP Notification - successful credit card payment
{
"transaction": {
"transaction_status": "capture",
"transaction_id": "2dd96707-8969-4930-9afa-74343b9e2042",
"status_code": "200",
"channel_response_message": "Approved",
"channel_response_code": "0"
},
"subscription": {
"token": "48111111JMUIocDPQoVTfKUhpNKX1114",
"status": "active",
"schedule": {
"start_time": "2022-10-26T09:59:00.000000Z",
"next_execution_at": "2022-11-26T09:59:00.000000Z",
"interval_unit": "month",
"interval": 1,
"current_interval": 1
},
"payment_type": "credit_card",
"name": "SUBSCRIBE-1666778331",
"metadata": {
"meta": "data"
},
"merchant_id": "M099098",
"id": "db516f5c-4acf-4f67-ac75-bb8428b58633",
"customer_details": {
"first_name": "John"
},
"currency": "IDR",
"amount": "14000"
},
"event_name": "subscription.charge"
}
HTTP Notification - successful GoPay payment
{
"transaction": {
"transaction_status": "settlement",
"transaction_id": "48fd27f9-284d-48fc-87d0-a799e80682c4",
"status_code": "200"
},
"subscription": {
"token": "b54264bf-1391-4951-9f05-059ab1300d3f",
"status": "active",
"schedule": {
"start_time": "2022-10-26T10:06:00.000000Z",
"next_execution_at": "2022-11-07T10:06:00.000000Z",
"interval_unit": "day",
"interval": 12,
"current_interval": 1
},
"payment_type": "gopay",
"name": "SUBSCRIBE-1666778737",
"metadata": {
"meta": "data"
},
"merchant_id": "G575825106",
"id": "7d9a7685-8437-4914-bcc1-47b11c0f3e58",
"customer_details": {
"first_name": "John"
},
"currency": "IDR",
"amount": "14000"
},
"event_name": "subscription.charge"
}
HTTP Notification - failed credit card payment
{
"transaction": {
"status_code": "411"
},
"subscription": {
"token": "8447a56f-0e5e-498a-a948-eefa88265544",
"status": "inactive",
"schedule": {
"start_time": "2022-10-26T04:50:00.000000Z",
"next_execution_at": "2022-10-26T07:50:00.000000Z",
"interval_unit": "month",
"interval": 1,
"current_interval": 0
},
"payment_type": "credit_card",
"name": "SUBSCRIBE-1666759564",
"metadata": {
"meta": "data"
},
"merchant_id": "G575825106",
"id": "6fbdf52b-a3b0-430c-bfb7-999fa1df1966",
"customer_details": {
"first_name": "John"
},
"currency": "IDR",
"amount": "14000"
},
"event_name": "subscription.charge"
}
HTTP Notification - failed GoPay payment
{
"transaction": {
"status_code": "402"
},
"subscription": {
"token": "b54264bf-1391-4951-9f05-059ab1300d3f",
"status": "inactive",
"schedule": {
"start_time": "2022-10-26T08:17:00.000000Z",
"next_execution_at": "2022-10-26T11:17:00.000000Z",
"interval_unit": "day",
"interval": 12,
"current_interval": 0
},
"payment_type": "gopay",
"name": "SUBSCRIBE-1666772200",
"metadata": {
"meta": "data"
},
"merchant_id": "M099098",
"id": "fd1d1cb3-9d13-425d-84f0-c59f9cabe847",
"customer_details": {
"first_name": "John"
},
"currency": "IDR",
"amount": "14000"
},
"event_name": "subscription.charge"
}
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.
- Get token.
- Send Charge request using the token.
- For 3D secure transactions, redirect the customer to the address specified in the response. (Optional)
- 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": "48111111-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",
"on_us": true
}
Sample Response - Error
{
"status_code": "411",
"status_message": "Token id is missing, invalid, or timed out"
}
Sample Response - Capture Notification
{
"masked_card": "48111111-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",
"on_us": false
}
Sample Response - Deny Notification
{
"masked_card": "48111111-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",
"on_us": true
}
Sample Response - Challenge Notification
{
"masked_card": "48111111-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",
"on_us": false
}
Sample Response - Settlement Notification
{
"masked_card": "48111111-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 8-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 |
on_us | Indicate whether issuing and acquiring bank is the same | Boolean |
The transaction_status
and fraud_status
attributes are the two most important details received in the JSON response.
- Transaction status
capture
and fraud statusaccept
: Transaction successful. - Transaction status
deny
and fraud statusaccept
,deny
orchallenge
: Transaction rejected by bank or by Fraud Detection System (FDS). - Transaction status
capture
and fraud statuschallenge
: Transaction is challenged. You have to make a confirmation at Merchant Administration Portal (MAP). - Transaction status
capture
and fraud statusaccept
: Customer’s card has been charged and the amount is credited to your account. At this point, the payment process of a transaction is complete. Send the transaction status to the customer and also update the respective database. For example, you can mark if the respective order_id has been paid for. Login to MAP to see the detail of the transaction and the transaction status. Alternatively, check the transaction status using Get Transaction Status.
By default, all card transactions from 00:00 until 23:59 are settled on the next day at 16:00. The transaction status is updated fromcapture
tosettlement
. If there is any unapproved transaction with fraud status aschallenge
, Midtrans cancels the transaction automatically. Midtrans also sends HTTP POST notification to the Notification URL configured on MAP.
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.
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": "48111111-1114",
"card_type": "credit",
"three_ds_version": "2",
"on_us": true
}
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": "48111111-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": "48111111-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",
"on_us": true
}
Sample Response - Capture Notification after submit OTP 3DS 2.0
{
"masked_card": "48111111-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": "48111111-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": "48111111-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": "48111111-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
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 arecapture : 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 areaccept : 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 8-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: 3D Secure 2.0 (EMV 3DS)
3D Secure 2.0 (EMV 3-D Secure) is the new authentication protocol for online card payments. 3DS 2.0 is designed to improve upon 3D Secure 1 by addressing the old protocol's pain points. Promotes frictionless consumer authentication and enables consumers to authenticate themselves with their card issuer when making card-not-present (CNP) e-commerce purchases. The additional security layer helps prevent unauthorised CNP transactions and helps protect the merchant from exposure to CNP fraud and delivering a much smoother and integrated user experience.
- Midtrans supports card payments using 3DS 2.0 with our APIs. To make the integration process as seamless as possible, please refer to Midtrans API Libraries & Plugins.
- For Merchants who don't have PCI license, please refer to Snap API for browser integration and to Mobile SDK for mobile integration.
3DS 2.0 Benefits:
- Frictonless (User friendly SCA - Less abandonment)
There is no OTP Challenge that customer needs to submit. If transaction is considered safe by Issuing bank & Principle, the transaction will be processed immediately. - More data = Less decline.
3DS 2.0 Frictionless:
- Merchant or Customer can provide additional data (such as item_details, customer_details, billing_address, and shipping_address) in the 3DS Charge request to try and achieve 3DS frictionless authentication, final decision will be determined by ACS as the Issuing Bank and the Principle. Those fields are optional, If you do not provide any additional data, Midtrans will still process 3DS even the result is frictionless or challenge.
- If sufficient data is received to verify that it is indeed the cardholder making payment, the issuer can use frictionless 3DS authentication without the cardholder needing to perform 2FA. 3DS succeeds, the payment is accepted, and the merchant benefits from chargeback liability without any additional verification step.
For Specific Item Details and Customer Details, please refer to Item Details and Customer Details
Notes on 3DS 2.0 Migration::
- In relation to 3DS 2.0 mandate from principal, we need to migrate all of existing BCA and BRI MIDs from MIGS to MPGS because MIGS BCA & BRI only support 3DS 1.0, The MID migration will affect channel_response_code and channel_response_message format.
For more details, please refer to MIGS BCA & BRI MIDs Migration - OTP Challenge on 3DS 2.0, there will be new flow that were previously Synchronous for 3DS 1.0 but for 3DS 2.0 will become Asynchronous. So after Challenge OTP, the transaction could still be Pending. Merchant needs to wait for successful notification from Midtrans or try Get Status to Midtrans several times in next minute.
- New field three_ds_challenge_completion on Charge and Status API response (Only for 3DS Challenge) to indicate whether the customer has submitted the OTP or not. Since 3DS 2.0 is Asynchronous this field may not be instantly updated due to Issuing bank or Principle having a delay when sending the callback.
- 3DS URL Changes:
- For Merchant that implements logic to close OTP Page with URL Path validation, Merchant needs to change or update the validation for 3DS 2.0
- For Merchant that implements Mobile SDK, Merchant needs to update to latest version.
- For Merchant that implements Snap API, there is no need for changes on Merchant side.
- For Merchant that implements logic to close OTP Page with URL Path validation, Merchant needs to change or update the validation for 3DS 2.0
Version | URL | Description |
---|---|---|
3DS 1.0 | {midtransHost}/v2/token/rba/redirect/{tokenId} | Redirect URL on Charge Response |
3DS 1.0 | {midtransHost}/v2/token/rba/callback/{tokenId} | Redirect URL after Input OTP |
3DS 2.0 | {midtransHost}/v2/3ds/redirect/{tokenId} | Redirect URL on Charge Response |
3DS 2.0 | {midtransHost}/v2/3ds/result-completion/{tokenId} | Redirect URL after Input OTP |
If you have any inquiries, please contact support@midtrans.com
FAQ: 3D Secure 2.0 (EMV 3DS)
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": "48111111-1114",
"bank": "bni",
"installment_term": "6",
"channel_response_code": "00",
"channel_response_message": "Approved",
"currency": "IDR",
"card_type": "credit",
"on_us": true
}
Sample Response - Online Installment Capture
{
"masked_card": "48111111-1114",
"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",
"on_us": false
}
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": "48111111-1114",
"bank": "bni",
"installment_term": "6",
"channel_response_code": "00",
"channel_response_message": "Approved",
"currency": "IDR",
"card_type": "credit",
"on_us": true
}
Sample Response - Offline Installment Notifications
{
"masked_card": "48111111-1114",
"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",
"on_us": false
}
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": "48111111-1114",
"bank": "bca",
"channel_response_code": "0",
"channel_response_message": "Approved",
"currency": "IDR",
"card_type": "credit",
"on_us": true
}
Sample Response - Pre-Authorization
{
"masked_card": "48111111-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",
"on_us": false
}
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": "48111111-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": "48111111-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 arecapture : 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 areaccept : 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 8-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": "48111111-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",
"on_us": true
}
Sample Response - Initial One Click Notification
{
"masked_card": "48111111-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",
"on_us": false
}
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": "48111111-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",
"on_us": true
}
Sample Response - Notification
{
"masked_card": "48111111-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",
"on_us": false
}
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": "48111111-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": "48111111-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",
"on_us": false
}
Sample Response - Notification
{
"masked_card": "48111111-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",
"on_us": true
}
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 Feature: 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 Merchant has a PCI license.
To better understand the integration, the transactions are categorized into the following:
Full PAN Non-3DS Integration
Send a Charge API request with payment_type
, transaction_details
, customer_details
, item_details
. Successful response returns the redirect_url
. The steps to integrate with Non-3DS are given below.
- Send the Charge request to Midtrans.
- 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 Verification Code (CVC) 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": "48111111-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",
"on_us": true
}
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": "48111111-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",
"on_us": false
}
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": "48111111-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",
"on_us": true
}
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": "48111111-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 arecapture : 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 areaccept : 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 8-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 |
on_us | Indicate whether issuing and acquiring bank is the same | Boolean |
Full PAN 3DS Integration
The steps to integrate using 3DS are given below.
- Send the Charge request to Midtrans.
- Open Redirect URL.
- 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": "48111111-1114",
"card_type": "credit",
"three_ds_version": "2",
"on_us": true
}
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": "48111111-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": "48111111-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",
"on_us": false
}
Sample Response - Capture Notification after submit OTP 3DS 2.0
{
"masked_card": "48111111-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": "48111111-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": "48111111-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": "48111111-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 areaccept : 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 8-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 |
on_us | Indicate whether issuing and acquiring bank is the same | 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
- BCA Virtual Account
- Mandiri Bill Payment
- BNI Virtual Account
- BRI Virtual Account
Permata Virtual Account
The steps to integrate with Permata Virtual Account are given below.
- Send the Charge API request to Midtrans.
- Display the virtual account number.
- 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 | Optional |
customer_details | Details of the customer. | Object | Optional |
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.
- Send the Charge API request to Midtrans.
- Display the virtual account number.
- 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 | Optional |
item_details | Details of the item(s) purchased by the customer. | Object | Optional |
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.
- Send the Charge API request to Midtrans.
- Display bill key and biller code to the customer.
- 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",
"bill_key" : "081211111111"
}
}
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 | Optional |
customer_details | Details of the customer. | Object | Optional |
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.
- Send the Charge API request to Midtrans.
- Display the virtual account number.
- 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 | Optional |
item_details | Details of the item(s) purchased by the customer. | Object | Optional |
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.
- Send the Charge API request to Midtrans.
- Display the virtual account number.
- 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 | Optional |
item_details | Details of the item(s) purchased by the customer. | Object | Optional |
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
- KlikBCA
- BRImo
- CIMB Clicks
- Danamon Online Banking (DOB)
- UOB Ezpay
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.
- Send the Charge API request to Midtrans.
- Redirect the customer to URL specified in the response.
- 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 arepending , settlement , expire . |
String |
fraud_status | Detection result by Fraud Detection System (FDS). Possible values areaccept : 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.
- Send the Charge API request to Midtrans.
- Redirect the customer to URL specified in the response.
- 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 |
BRImo
BRImo 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 BRImo payment page.
The Steps to integrate with BRImo are given below.
- Send the Charge API request to Midtrans.
- Redirect the customer to URL specified in the response.
- 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 BRImo 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 |
BRImo 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 BRImo 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 BRImo transaction. Possible values arepending , expire , settlement . |
String |
fraud_status | Detection result by Fraud Detection System (FDS). Possible values areaccept : 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 BRImo 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.
- Send the Charge API request to Midtrans.
- Redirect the customer to URL specified in the response.
- 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.
- Send the Charge API request to Midtrans.
- Redirect the customer to URL specified in the response.
- 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 areexpire , deny , accept . |
String |
fraud_status | Detection result by Fraud Detection System (FDS). Possible values areaccept : 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 |
UOB EzPay
{
"payment_type": "uob_ezpay",
"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"
}
}
UOB Ezpay is one of the internet banking payment methods that is provided by UOB Bank. This method allows the customer to perform a transaction by redirecting the customer to the UOB payment page.
Integration steps:
- Merchant send charge request to Midtrans.
- The merchant will need to open the redirection url in the
actions
to the customer.web-deeplink-redirect
to redirect to UOB web page andmobile-deeplink-redirect
to redirect to UOB mobile app. - Handle notification.
Following attributes are required to charge UOB Ezpay:
JSON Attribute | Type | Description |
---|---|---|
payment_type | String | Set UOB Ezpay payment method. Value: uob_ezpay |
transaction_details | Object | Details of the transaction will be paid by customer |
item_details | Object | Shopping item details |
customer_details | Object | Customer Details |
UOB Ezpay Charge Response and Notifications
UOB Ezpay Charge Response
{
"status_code": "201",
"status_message": "Success, UOB Ez Pay transaction is successful",
"transaction_id": "226f042f-020e-4829-8bd7-2de64b8673ce",
"order_id": "1000156414164125",
"gross_amount": "392127.00",
"payment_type": "uob_ezpay",
"transaction_time": "2016-06-19 16:41:25",
"transaction_status": "pending",
"fraud_status": "accept",
"actions": [
{
"name": "web-deeplink-redirect",
"method": "GET",
"url": "https://u-payment.uob.co.id/startup/ezpay?clientId=107b9f3e-7399-4983-8342-a3350e7b8ce0&type=JWT&signature=Jpc3MiOiIxMDdiOWYzZS03Mzk5LTQ5ODMtODM0Mi1hMzM1MGU3YjhjZTAiLCJpYXQiOjE1NjE1NUBQl"
},
{
"name": "mobile-deeplink-redirect",
"method": "GET",
"url": "https://digitalbankid.page.link/?link=https://www.tmrwbyuob.com?clientId%3D107b9f3e-7399-4983-8342-a3350e7b8ce0%26signature%3DJpc3MiOiIxMDdiOWYzZS03Mzk5LTQ5ODMtODM0Mi1hMzM1MGU3YjhjZTAiLCJpYXQiOjE1NjE1NUBQl-5gvMiOqzSq-lroACwpf83vpj2NYlExcrYckyV7Oc&type=JWT&apn=com.uob.id.digitalbank.dev&isi=1472320289&ibi=com.uob.id.digitalbank.uat"
}
]
}
UOB Ezpay Pending notification
{
"status_code": "201",
"status_message": "midtrans payment notification",
"transaction_id": "226f042f-020e-4829-8bd7-2de64b8673ce",
"order_id": "1000156414164125",
"gross_amount": "392127.00",
"payment_type": "uob_ezpay",
"transaction_time": "2016-06-19 16:41:25",
"transaction_status": "pending",
"fraud_status": "accept",
"signature_key": "666617ddc981eb096b6f08ab8ee132b93c12d3b5b3817f00a02c5d4c71bd53fd7f39d55a92b2a1f729ee070fdb241b569dc90bfa61e41de16904075238d67d55",
}
UOB Ezpay Settlement notification
{
"status_code": "200",
"status_message": "midtrans payment notification",
"transaction_id": "226f042f-020e-4829-8bd7-2de64b8673ce",
"order_id": "1000156414164125",
"gross_amount": "392127.00",
"payment_type": "uob_ezpay",
"transaction_time": "2016-06-19 16:45:21",
"transaction_status": "settlement",
"fraud_status": "accept",
"approval_code": "RB5031388093",
"signature_key": "3bcdf0700d3c8a288f279e4fe27a4012e916cb44120d541f6e4c48c83a107b605fdb063ae7c8744d15891047aeb1fc8d2e95741c0abc5f67e10e0b60244bc441"
}
UOB Ezpay Deny notification
{
"status_code": "202",
"status_message": "midtrans payment notification",
"transaction_id": "226f042f-020e-4829-8bd7-2de64b8673ce",
"order_id": "1000156414164125",
"gross_amount": "392127.00",
"payment_type": "uob_ezpay",
"transaction_time": "2016-06-19 16:44:21",
"transaction_status": "deny",
"fraud_status": "accept",
"signature_key": "b736864661f8cbf04b287ee5a9514589dbe2dc53e3949338d648144b6bad1bc77d1b495921f119e7a6bf5521b697ea5d629b5ea93f2bcda4ff13df744cfbf701"
}
UOB Ezpay Ezpay Expired notification
{
"status_code": "202",
"status_message": "midtrans payment notification",
"transaction_id": "226f042f-020e-4829-8bd7-2de64b8673ce",
"order_id": "1000156414164125",
"gross_amount": "392127.00",
"payment_type": "uob_ezpay",
"transaction_time": "2016-06-19 18:41:25",
"transaction_status": "expire",
"fraud_status": "accept",
"signature_key": "3f1ddaf45b269df7a1638d6d4080957e1323df2cbc2da83549f86a23b17c2acae0215994bb60805455daf157125990414259e5319e84c9288fd6222e655c6756"
}
JSON Attribute | Type | Description |
---|---|---|
transaction_id | String | Transaction ID given by Midtrans |
order_id | String | Order ID given by merchant |
gross_amount | String | Total amount of transaction |
payment_type | String | Transaction payment method |
transaction_time | String | Timestamp of transaction |
transaction_status | String | Transaction status of UOB Ezpay transaction, the possible value ispending |
status_code | String | Status code of transaction charge result |
status_message | String | Description of transaction charge result |
redirect_url | String | Redirect URL to UOB Ezpay payment page |
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
- GoPay
- GoPay Tokenization
- ShopeePay
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.
- GoPay
- AirPay Shopee (ShopeePay)
The steps to integrate with QRIS are given below.
- Send the Charge API request to Midtrans with the selected acquirer.
- Show the rendered QR string to the users.
- 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 | Optional |
customer_details | Details of the customer. | Object | Optional |
qris | Charge details using QRIS. | Object | Optional |
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 arepending , 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:
- 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)
- 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
Sequence Diagram for Deeplink
The steps to integrate with GoPay are given below.
- Create payment instructions for users (see example below).
- Send the Charge API request to Midtrans.
- 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).
- Handle notifications.
Instruction Example |
---|
For QR Code
![]() ![]() |
For Deeplink
|
![]() |
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 arepending , 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 |
Implementing GoPay Deeplink Callback
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.
- Set
enable_callback
parameter in the charge request totrue
. - Set
callback_url
with the deeplink URL redirecting to E-commerce apps. - 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.

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.
- Link customer account only if the customer phone number is not yet linked to GoPay.
- Fetch customer account. If the linking of customer account is successful, then the payment options available to the customer are-
GOPAY_WALLET
andPAY_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. - If the linking is already successful then the customer can proceed with the charge. Sample Charge API request is shown on the side.
- If the
status_code
in the response is 200, then the transaction is completed. If thestatus_code
is 201, then you need to open the verification URL in theactions
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: Pre-Authorization Flow
Pre-auth flow allows you to make a reservation to user's wallet balance. This will help for cases where you need to reserve user's balance instead of debit it directly, to initiate debit you can call Capture API afterwards. To use this feature, you can set pre-auth
as true on GoPay Object. By default, reserved balance will be released after 15 minutes if there is no "capture" action for that transaction. Capturing a reservation is a process to settle the customer balance into merchant account. You can customize reservation time limits by sending custom expiry time parameters on charge request
As of now, pre-auth flow feature only supports non PIN flow. To test in Sandbox, please make sure that the amount doesn’t exceed IDR 100,000.
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/",
"recurring": false
},
"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 arepending , 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 steps to integrate Gopay Tokenization Pre-Auth feature are given below.
- The linking process is exactly same as GoPay Tokenization linking process above.
- 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. - If the
status_code
in the response is 200, then the transaction is authorized. If thestatus_code
is 201, then you need to open the verification URL in theactions
to the customer. Once the verification is done, it will be redirected back to the callback URL that is set on your dashboard. - You need to call Capture API. Please note that we do not accept partial amount capture for GoPay.
- 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 arepending , 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.
- Send the Charge API request to Midtrans.
- Open the redirect url in the response to get redirected to Shopee app.
- Handle the redirect from Shopee app back to merchant app.
- 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 arepending , 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 |
Implementing Shopeepay Deeplink Callback
In addition to the standard mobile apps flow, you can implement deeplink callback to redirect customer back from Gojek to your app.
To integrate with ShopeePay Deeplink (Please look into the ShopeePay Charge API Request for sample implementation) please set callback_url
with the deeplink URL redirecting to the Ecommerce apps
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.
- Send Charge API request to Midtrans.
- Display the payment code to the customer.
- 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.
- Send Charge API request to Midtrans.
- Display the payment code to the customer.
- 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 areaccept : 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 PayLater Cardless Credit payment method only.
Akulaku PayLater
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 PayLater Cardless Credit are given below.
- Send Charge API request to Midtrans.
- Redirect the customer to the provider website.
- 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 PayLater Charge API Request
Sample Request - Akulaku PayLater 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 PayLater 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 , settlement , expire . |
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 |
Kredivo
Kredivo 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 Kredivo.
The steps to integrate with Kredivo Cardless Credit are given below.
- Send Charge API request to Midtrans.
- Redirect the customer to the provider website.
- Handle notifications.
Kredivo Charge API Request
Sample Request - Kredivo Charge
{
"payment_type": "kredivo",
"transaction_details": {
"order_id": "orderid-01",
"gross_amount": 40000,
"currency": "IDR"
},
"customer_details": {
"email": "john.baker@email.com",
"first_name": "John",
"last_name": "Baker",
"phone": "08123456789",
"shipping_address": {
"first_name": "John",
"last_name": "Baker",
"phone": "08123456789",
"address": "Jl. Kemanggisan",
"city": "Jakarta",
"postal_code": 12353,
"country_code": "IND"
}
},
"item_details": [
{
"id": "1",
"name": "Sepatu",
"price": 40000,
"category": "Fashion",
"quantity": 1,
"url": "http://toko/toko1?item=abc"
}
],
"seller_details": [
{
"id": "sellerId-01",
"name": "John Seller",
"email": "seller@email.com",
"url": "https://tokojohn.com",
"address": {
"first_name": "John",
"last_name": "Seller",
"phone": "081234567890",
"address": "Kemanggisan",
"city": "Jakarta",
"postal_code": "12190",
"country_code": "IDN"
}
}
],
"custom_expiry": {
"expiry_duration": 60,
"unit": "minute"
}
}
JSON Attribute | Description | Type | Required |
---|---|---|---|
payment_type | The Cardless Credit payment method used by the customer. Value: kredivo . Note: Currently only kredivo is supported. |
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 | Optional |
item_details | Details of the item(s) purchased by the customer. | Object | Optional |
seller_details | Details of the seller(s) where the customer purchased from. All field in the given sample are Required. Note: This field is only mandatory for marketplace merchant. |
Object | Conditional |
custom_expiry | Details of the expiry time of the specific transaction. Default value: 24 hours |
Object | Optional |
Kredivo Charge API Response and Notifications
Sample Response - Success
{
"status_code":"201",
"status_message":"Kredivo transaction is created",
"transaction_id":"c1b4e32c-fd32-4ce3-98ed-130a6faf0fef",
"order_id":"orderid-01",
"redirect_url":"https://api.sandbox.veritrans.co.id/v2/oms/redirect/c1b4e32c-fd32-4ce3-98ed-130a6faf0fef",
"merchant_id":"M099098",
"gross_amount":"40000.00",
"currency":"IDR",
"payment_type":"kredivo",
"transaction_time":"2022-04-12 13:55:34",
"transaction_status":"pending",
"fraud_status":"accept",
"channel_response_code":"OK",
"channel_response_message":"Success Create Transaction"
}
Sample Response - Pending Notification
{
"transaction_time": "2018-08-24 16:20:36",
"gross_amount": "11000.00",
"order_id": "orderid-01",
"payment_type": "kredivo",
"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": "kredivo",
"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": "kredivo",
"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": "kredivo",
"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 Kredivo 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 Kredivo transaction. Possible values are pending , deny , settlement , expire . |
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
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
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:
|
CYBERSOURCE
Banks included in this category are: BCA, BRI
Code | Message | Description |
---|---|---|
00 | Approved and completed successfully | Transaction was successful. |
01 | Refer to card issuer | The customer’s bank (Card Issuer) has indicated a problem with the payment card number. The customer should contact their bank and should |
02 | Refer to card issuer, special condition | 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 | Invalid 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 (no fraud) | 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 condition (fraud account) | 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. |
10 | Partial approval | |
11 | Approved (V.I.P) | |
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 or currency conversion field overflow | 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 account number (no such 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 such issuer | The customer’s bank (Card Issuer) does not exist. Check the payment card information and try processing the transaction again. |
19 | Re-enter 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. |
25 | Unable to locate record in 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. |
28 | File temporarily not available for update or inquiry | |
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. |
41 | Lost card, pick up (fraud account) | 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. |
43 | Stolen card, pick up (fraud account) | 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. |
51 | Not sufficient 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 checking 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 or expiration date is missing | 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 or PIN missing | 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. |
57 | Transaction 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 | Transaction not allowed at 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. |
61 | Exceeds approval amount 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 (card invalid in this region or country) | 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 (source is not correct issuer) | The customer’s bank has declined the transaction. The customer should use an alternate payment card. |
64 | Transaction does not fulfill AML requirement | 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. |
65 | Exceeds withdrawal frequency limit | |
70 | PIN data required | |
74 | Different value than that used for PIN encryption errors | |
75 | Allowable number of PIN entry 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. |
76 | Unsolicited reversal | |
78 | “Blocked, first used”—Transaction from new cardholder, and card not properly unblocked | |
79 | Already reversed (by Switch) | |
80 | No financial impact | |
81 | Cryptographic error found in PIN | |
82 | Negative CAM, dCVV, iCVV, or CVV results | |
85 | No reason to decline a request for address verification, CVV2 verification, or a credit voucher or merchandise return | |
86 | Cannot verify PIN; for example, no PVV | |
89 | Ineligible to receive financial position information (GIV) | |
91 | Issuer or switch inoperative and STIP not applicable or not available for this transaction; Time-out when no stand-in; POS Check Service: Destination unavailable; Credit Voucher and Merchandise Return Authorizations: V.I.P. sent the transaction to the issuer, but the issuer was unavailable. | |
92 | Financial institution or intermediate network facility cannot be found for routing (receiving institution ID is invalid) | |
93 | Transaction cannot be completed - violation of law | |
1A | Additional customer authentication required | |
B1 | Surcharge amount not permitted on Visa cards or EBT food stamps (U.S. acquirers only) | |
B2 | Surcharge amount not supported by debit network issuer. | |
N0 | Force STIP | Transaction failed. Customers should try using another card. |
N3 | Cash service not available | |
N4 | Cash request exceeds issuer or approved limit | |
N5 | Ineligible for resubmission | |
N7 | Decline for CVV2 failure | 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. |
N8 | Transaction amount exceeds preauthorized approval amount | |
P5 | Denied PIN unblock—PIN change or unblock request declined by issuer | |
P6 | Denied PIN change—requested PIN unsafe | |
Q1 | Card Authentication failed | |
R0 | Stop Payment Order | |
R2 | Transaction does not qualify for Visa PIN | |
R3 | Revocation of all authorizations order | |
Z3 | Unable to go online; offline-declined | 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. |
MPGS
Banks included in this category are: BCA, BRI, American Express
Code | Message | Description |
---|---|---|
APPROVED | Transaction Successful | |
UNSPECIFIED_FAILURE | Transaction could not be processed | |
DECLINED | Transaction Declined - Contact Issuing Bank | The requested operation was not successful. For example, a payment was declined by issuer or payer authentication was not able to be successfully completed. |
TIMED_OUT | Transaction Declined - No reply from Bank | |
EXPIRED_CARD | Transaction Declined - Expired Card | Transaction declined due to expired card. |
INSUFFICIENT_FUNDS | Transaction Declined - Insufficient Credit | Transaction declined due to insufficient funds. |
ACQUIRER_SYSTEM_ERROR | Transaction Declined - Bank system error | Acquirer system error occured processing the transaction. |
SYSTEM_ERROR | Payment Server Processing Error | Internal system error occurred processing the transaction, typically caused by invalid input data such as a credit card number. Processing errors can also occur. |
NOT_SUPPORTED | Transaction Declined - Transaction Type not supported | |
DECLINED_DO_NOT_CONTACT | Bank Declined Transaction (Do not contact Bank) | Transaction declined - do not contact issuer. |
ABORTED | Transaction Aborted | Transaction aborted by card holder. |
BLOCKED | Transaction Blocked | Transaction blocked due to Risk or 3D Secure blocking rules. Returned when: - the Verification Security Level has a value of '07', - The merchant has 3D-Secure blocking enabled, -the overall risk assessment result returns a 'Reject' or 'System Reject'. |
CANCELLED | Transaction Cancelled | Transaction cancelled by card holder. |
DEFERRED_TRANSACTION_RECEIVED | Deferred Transaction | Deferred transaction received and awaiting processing. |
REFERRED | Transaction Declined - Refer to card issuer | |
AUTHENTICATION_FAILED | 3D Secure Authentication Failed | |
INVALID_CSC | Card Security Code Failed | Invalid card security code. |
LOCK_FAILURE | Shopping Transaction Locked | Order locked - another transaction is in progress for this order. This indicates that there is another transaction taking place using the same shopping transaction number. |
SUBMITTED | Transaction submitted - response has not yet been received | Transaction Submitted (the transaction has been directed to the acquirer, but the Payment Server has not yet received it to complete the transaction). |
NOT_ENROLLED_3D_SECURE | Cardholder not enrolled | Cardholder not enrolled in 3DSecure (authentication only). |
PENDING | Transaction is Pending | |
EXCEEDED_RETRY_LIMIT | Retry Limits Exceeded, Transaction Not Processed | |
DUPLICATE_BATCH | Transaction Declined - Duplicate Batch | Transaction declined due to duplicate batch. |
DECLINED_AVS | Address Verification Failed | Transaction declined due to address verification. |
DECLINED_CSC | Card Security Code Failed | Transaction declined due to card security code. |
DECLINED_AVS_CSC | Address Verification and Card Security Code Failed | Transaction declined due to address verification and card security code. |
DECLINED_PAYMENT_PLAN | Transaction Declined - Payment Plan not supported | |
APPROVED_PENDING_SETTLEMENT | Transaction Approved - pending batch settlement | Approved pending settlement - Approved by a batch settlement system, but still awaiting further details from the acquirer. |
UNKNOWN | Response unknown |
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. |
2903 | INVALID_REQUEST | invalid request (most common case is whitelisting issue) |
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).
-
User-Agent
header in the HTTP notification from Midtrans will no longer be 'Veritrans'. It will be the same as the HTTP client we are using in code. Please do not use theUser-Agent
Header or depend on it. In line with the change of the name of the organization, we will also deprecate the usage ofveritrans.co.id
domain in the next 3-4 months. The changes in the domain names are listed below. -
api.veritrans.co.id
changed toapi.midtrans.com
-
vtweb2.veritrans.co.id
changed tovtweb2.midtrans.com
-
app.veritrans.co.id
changed toapp.midtrans.com
-
payments.veritrans.co.id
changed topayments.midtrans.com
Please switch to using the new host names and URL's immediately to avoid failures.
October 4, 2022
Midtrans is sanitizing order id characters for MPGS to make sure it's URL safe. Allowed symbols in order id are dash(-), underscore(_), tilde(~), and dot(.). On Midtrans MAP (Merchant Portal), order id shown will be the same with the one sent by Merchant. but order id shown on MPGS portal or Bank settlement report could be different because of order id sanitization.
For more details, refer Transaction Details Object.
Deployment Notices
June 17, 2022
Starting on 22nd July, 2022, we are going to Implement 8 Digit bin.
Changes list:
- Change on token_id length from 48 digit to 50 digit.
Stage Sample Length Description Before 481111-1114-7baba36c-5698-47cf-9170-80efd6a2e973 48 6 first digit + "-" + 4 last digit + "-" + 36 random digit After 48111111-1114-7baba36c-5698-47cf-9170-80efd6a2e973 50 8 first digit + "-" + 4 last digit + "-" + 36 random digit - Change on saved_token_id format.
Stage Sample Length Description Before 481111sHdcfSakAvHvFQFEjTivUV1114 32 6 first digit + 22 random digit + 4 last digit After 48111111sHfSakAvHvFQFEjTivUV1114 32 8 first digit + 20 random digit + 4 last digit - Change of masked_card in response body, event, and notification.
Stage Sample Length Description Before 481111-1114 11 6 first digit + 1 digit delimiter + 4 last digit After 48111111-1114 13 8 first digit + 1 digit delimiter + 4 last digit - Support 8 digit bin in Aegis.
- Support 8 digit bin in BIN API.
August 30, 2022
- The allowed maximum time of expiry for gopay is 7 days.
October 7, 2022
Starting on 7th Oct 2022, all MIGS MID has been migrated to MPGS MID.
Affected Banks:
Bank | Previous Channel | New Channel |
---|---|---|
BCA | MIGS | MPGS |
BRI | MIGS | MPGS |
if you have any inquiry, please contact support@midtrans.com
December 6, 2022 (Expiry Threshold)
Starting on January 16th 2023, we will apply minimum and maximum expiry time threshold.
Terms | Definition |
---|---|
Transaction timestamp | Timestamp at which transaction is initiated via Charge API |
Expiry timestamp | Timestamp at which the order will be expired |
Expiry time | Time between transaction timestamp and expiry timestamp |
Change list:
1. Added field `expiry_time` on charge response, get status response and notification
expiry_time in charge & status API response
{
"transaction_time":"2023-01-16 10:00:00",
"Transaction_status":"pending",
"transaction_id":"ce0a3584-5a0c-4049-ad88-5590a96be4fe",
…
"expiry_time":"2023-07-16 10:00:00"
}
expiry_time in HTTP Notification
{
"transaction_time": "2023-01-16 10:00:00",
"transaction_status": "pending",
"transaction_id": "ce0a3584-5a0c-4049-ad88-5590a96be4fe",
"status_message": "midtrans payment notification",
…
"expiry_time":"2023-07-16 10:00:00"
}
expiry_time
field will be returned in API response (charge and status API) and also HTTP notification
2. Transaction with expiry time less than 20 seconds will be rejected
Custom expiry without order_time sample
"custom_expiry": {
"expiry_duration": 10,
"unit": "second"
}
Sample scenario of Charge API with Custom Expiry object
a. charge request without order time
If merchant send the sample request (seen on right side) without order_time at 10:00:30 GMT+7, then the calculated expiry time is 10 seconds, as follow:
order_time
: not specified hence will follow transaction timetransaction_time
: 10:00:30 GMT+7expiry_duration
: 10 seconds- Expiry timestamp: 10:00:40 GMT+7
- Expiry time: 10 seconds
Therefore the transaction will be rejected.
b. charge request with order time
Custom expiry with order_time sample
"custom_expiry": {
"order_time": "2023-01-16 10:00:00 +0700",
"expiry_duration": 40,
"unit": "second"
}
If merchant send the sample request (seen on right side) with order_time at 10:00:30 GMT+7, then the calculated expiry time is 10 seconds, as follow:
order_time
: 10:00:00 GMT+7transaction_time
: 10:00:30 GMT+7expiry_duration
: 40 seconds- Expiry timestamp: 10:00:40 GMT+7
- Expiry time: 10 seconds
Therefore the transaction will be rejected.
Charge response for rejected transaction
{
"status_code": "400",
"status_message": "One or more parameters in the payload is invalid.",
"id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
"validation_messages":
[
"custom_expiry is below minimum threshold"
]
}
3. Transaction with expiry time more than 180 days will be accepted but expiry time will be trimmed to 180 days*
Custom expiry without order_time sample
"custom_expiry": {
"expiry_duration": 210,
"unit": "day"
}
Sample scenario of Charge API with Custom Expiry object
a. charge request without order time
If merchant send the sample request (seen on right side) request at 2023-01-16, then the calculated expiry time is 210 days, as follow:
order_time
: not specified hence will follow transaction timetransaction_time
: 2023-01-16 10:00:00 GMT+7expiry_duration
: 210 days (approx 7 months)- Expiry timestamp withouth trim should be: 2023-08-16 10:00:00 GMT+7
We will trim the expiry time to 180 days with new expiry timestamp: 2023-07:16 10:00:00 GMT+7.
Custom expiry with order_time sample
"custom_expiry": {
"order_time": "2023-01-15 10:00:00 +0700",
"expiry_duration": 210,
"unit": "day"
}
b. charge request with order time
If merchant send the sample request (seen on right side) request at 2023-01-16, then the calculated expiry time is 209 days, as follow:
order_time
: 2023-01-15 10:00:00 GMT+7transaction_time
: 2023-01-16 10:00:00 GMT+7expiry_duration
: 210 days (approx 7 months)- Expiry time: 209 days
- Expiry timestamp withouth trim should be: 2023-08-15 10:00:00 GMT+7
Therefore we will trim the expiry time to 180 days with new expiry timestamp: 2023-07:16 10:00:00 GMT+7.
Charge response with trimmed expiry_time
{
"transaction_time":"2023-01-16 10:00:00",
"transaction_status":"pending",
"transaction_id":"ce0a3584-5a0c-4049-ad88-5590a96be4fe",
....
"expiry_time":"2023-07-16 10:00:00"
}
December 6, 2022 (GoPay deny error)
Starting in January 2023 there will be an update on Midtrans deny error for GoPay payment channel. The transition phase will start in January upto April 2023, Please ensure that merchant's system can accommodate both behavior (before and after) within this period.
Status code 202 sample
{
"Status_code":"202",
"status_message":"GoPay transaction is denied",
"channel_response_code":"201",
"channel_response_message":"insufficient balance"
…
}
Status code 4xx sample
{
"status_code":"400",
"status_message":"One or more parameters in the payload is invalid.",
"validation_messages":[
"Gopay.account_id is required"
],
"id":"1a3fef7b-c034-4cf2-98d6-e239594976f3"
}
Status code 5xx sample
{
"status_code":"500",
"status_message":"Sorry. Our system is recovering from unexpected issues. Please retry.",
"Id":"6a782ad4-1e18-4df5-b5bd-dbf94ce15ddc"
}
Terms | Definition |
---|---|
Deny error | An error that Midtrans return back to merchant, if Midtrans got rejection from payment provider (status code 202). For this error Merchant can call Get Status API to retrieve payment provider error data |
Channel response code | Error code that Midtrans received from payment provider |
Channel response message | Error message that Midtrans received from payment provider |
4xx error | status code 4xx |
5xx error | status code 5xx |
Change list:
1. Update on behavior for the listed GoPay error
GoPay error code | GoPay error message | New status code | New HTTP code | Before | After |
---|---|---|---|---|---|
310 | Malformed data | 400 | 400 | { "Status_code":"202", "status_message":"GoPay transaction is denied", "channel_response_code":"310", "channel_response_message":"Malformed data … } |
{ "status_code": "400", "status_message": "One or more parameters in the payload is invalid.", "validation_messages": [ "Malformed data" ], "id": "f7f6463e-d46b-4b4e-9027-8d8104ac34c6" } |
2901 | Duplicate transaction | 406 | 200 | { "Status_code":"202", "status_message":"GoPay transaction is denied", "channel_response_code":"2901", "channel_response_message":"Duplicate transaction", … } |
{ "status_code":"406", "status_message":"The request could not be completed due to a conflict with the current state of the target resource, please try again", "id":"be929ec4-19cb-458b-85e4-43869ada0597" } |
2701 | The currency is not supported for the country | 400 | 400 | { "status_code":"202", "status_message":"GoPay transaction is denied", "channel_response_code":"2701", "channel_response_message":"The currency is not supported for the country", … } |
{ "status_code": "400", "status_message": "One or more parameters in the payload is invalid.", "validation_messages": [ "The currency is not supported for the country" ], "id": "f7f6463e-d46b-4b4e-9027-8d8104ac34c6" } |
4060 | Fraud validation | 202 | 200 | { "Status_code":"202", "status_message":"GoPay transaction is denied", "channel_response_code":"4060", "channel_response_message":"Fraud validation error", … "fraud_status":"accept" } |
{ "status_code": "202", "status_message": "GoPay transaction is rejected by FDS", "transaction_id": "171dba71-6d5c-4bb8-8fd7-3ad44fdeb8fb", ... "fraud_status": "deny" } |
303 | Field cannot be blank | 402 | 200 | { "Status_code":"202", "status_message":"GoPay transaction is denied", "channel_response_code":"303", "channel_response_message":"Field cannot be blank" … } |
{ "status_code":"402", "status_message":"Missing GoPay merchant setting data", "id":"363a8d7f-92d5-4232-9c2d-7e6de2dafa33" } |
112 | User Blocked | 402 | 200 | { "Status_code":"202", "status_message":"GoPay transaction is denied", "channel_response_code":"112", "channel_response_message":"User Blocked" … } |
{ "status_code":"402", "status_message":"GoPay user is blocked", "id":"363a8d7f-92d5-4232-9c2d-7e6de2dafa33" } |
1703 | Midtrans merchant not active | 402 | 200 | { "Status_code":"202", "status_message":"GoPay transaction is denied", "channel_response_code":"1703", "channel_response_message":"Midtrans merchant not active", … } |
{ "status_code":"402", "status_message":"GoPay merchant is not active.", "id":"363a8d7f-92d5-4232-9c2d-7e6de2dafa33" } |
153 | The token is invalid for the payment | 400 | 400 | { "status_code":"202","status_message":"GoPay transaction is denied", "channel_response_code":"153", "channel_response_message":"The token is invalid for the payment", … } |
{ "status_code": "400", "status_message": "One or more parameters in the payload is invalid.", "validation_messages": [ "GoPay token is invalid for the payment" ], "id": "f7f6463e-d46b-4b4e-9027-8d8104ac34c6" } |
5009 | Auth token already expired | 400 | 400 | { "Status_code":"202", "status_message":"GoPay transaction is denied", "channel_response_code":"5009", "channel_response_message":"Auth token already expired", … } |
{ "status_code": "400", "status_message": "One or more parameters in the payload is invalid.", "validation_messages": [ "GoPay challenge token is already expired" ], "id": "f7f6463e-d46b-4b4e-9027-8d8104ac34c6" } |
110 | Unauthorized | 402 | 200 | { "status_code":"202", "status_message":"GoPay transaction is denied", "channel_response_code":"110", "channel_response_message":"Unauthorized", … } |
{ "status_code":"402", "status_message":"GoPay merchant is unauthorized.", "id":"363a8d7f-92d5-4232-9c2d-7e6de2dafa33", } |
132 | Transaction in progress | 406 | 200 | { "Status_code":"202", "status_message":"GoPay transaction is denied", "channel_response_code":"132", "channel_response_message":"Transaction in progress", … } |
{ "status_code":"406", "status_message":"The request could not be completed due to a conflict with the current state of the target resource, please try again", "id":"be929ec4-19cb-458b-85e4-43869ada0597" } |
2903 | Invalid Request | 402 | 200 | { "Status_code":"202", "status_message":"GoPay transaction is denied", "channel_response_code":"2903", "channel_response_message":"Invalid Request", … } |
{ "status_code":"402", "status_message":"Missing GoPay merchant setting data", "id":"363a8d7f-92d5-4232-9c2d-7e6de2dafa33" } |
902 | Malformed JSON | 413 | 200 | { "Status_code":"202", "status_message":"GoPay transaction is denied", "channel_response_code":"902", "channel_response_message":"Malformed JSON", … } |
{ "status_code": "413", "status_message": "The request cannot be processed due to malformed syntax in the request body" } |
101 | Wallet not found | 404 | 200 | { "Status_code":"202", "status_message":"GoPay transaction is denied", "channel_response_code":"101", "channel_response_message":"Wallet not found", … } |
{ "status_code": "404", "status_message": "GoPay Wallet doesn't exist.", "id": "7d17e7e6-4272-42ac-be95-f728a42c6b78" } |
900 | Internal server error | either 500 or 202 | 200 | { "status_code":"202", "status_message":"GoPay transaction is denied", "channel_response_code":"900", "channel_response_message":"Internal server error", … } |
500: { "status_code":"500", "status_message":"Sorry. Our system is recovering from unexpected issues. Please retry.", "id":"6a782ad4-1e18-4df5-b5bd-dbf94ce15ddc" } 202: { "status_code":"202", "status_message":"GoPay transaction is denied", "channel_response_code":"900", "channel_response_message":"Internal server error", "transaction_id":"c4f05215-1044-4740-b1b9-6154a73fc433", "order_id":"893016743", "merchant_id":"G253339736", "gross_amount":"61499.00", "currency":"IDR", "payment_type":"gopay", "transaction_time":"2022-11-22 09:30:29", "transaction_status":"deny","fraud_status":"accept" } |