Pre-requirement

server_key : required for requests made from Merchant server-side

Authentication
a) Method
Token Based Authotication.
b) Midtrans HTTP Header

Key Value

Content-Type application/json

Accept application/json

Authorization Basic
base64_encode(server_key+':')

Base URL
Development Environment : https://api.sandbox.midtrans.com/v2
Production Environment : https://api.midtrans.com/v2

API
Get Token Credit Card
● Description
This request is sent on purpose to tokenize user’s Credit Card data and
acquire token_id essential in Credit Card Payment Type during Charge
Transaction.
● URL
BASE_URL/token
● Method
POST
● URL Params
client_key : String, acquired from Merchant Administration Portal =>
Setting => Access Key
gross_amount : String (Integer formatted)
card_number : String, Valid format 16 - 19 (including 3 white space
between 4 group number)
card_exp_month: String (Integer formatted), e.g. “12”
card_exp_year : String (Integer formatted), e.g. “2020”
 cvv : String (Integer formatted), e.g. “123”
secure : [true, false]
● Data params
None
● Request Example
https://api.sandbox.midtrans.com/v2/token?client_key=SB-Mid-client-
uo0Gl_0JcvwNKBa9&gross_amount=10000&card_number=4811 1111 1111
1114&card_exp_month=12&card_exp_year=24&card_cvv=123&secure=true
● Success Response
{
“status_code”: 200
“status_message”: The message of the status code
“token_id”: The token id used for charge process
“eci”: The 3DS status indicator
}
● Error and Failed Response
{
“status_code”: 400
“status_message”: The message of the status code
“validation_message”: The validation errors
}

Charge
● Description
Charge a transaction with a unique data according to the merchant's need
● URL
BASE_URL/charge
● URL Params
None
● Data Params
Must be a JSON Object
Required:
● payment_type : String [ ‘bank_transfer’, credit_card‘’ ,
’telkomsel_cash’, etc ]
● transaction_details : JSON Object containing { “order_id”
[String], “gross_amount” [String] }
Optional:
● custom_field : String (the key name can be set on MAP)
● custom_expiry : JSON Object containing { “order_time”
[e.g. “2016-12-07 11:54:12 +0700", “expiry_duration” [e.g. 60],
“unit” [e.g. "minute”] }
● metadata : customizable JSON Object
● item_details : Array of JSON Object
● costumer_details : JSON Object
 Bank Transfer:
● bank_transfer : JSON Object containing { “bank” [string],
“va_number” [string], corresponding bank info [object] }
Credit Card:
● credit_card : JSON Object containing { "token_id" [string],
“bank” [string], "installment_term” [‘3’, ‘6’, ‘12’], “bins”
[string] , "type” [‘authorize’, null], "save_token_id" [bool] }
Telkomsel Cash:
● telkomsel_cash : JSON Object containing { “customer” [String] }
● Request Example
Bank Transfer
Permata
{
"payment_type": "bank_transfer",
"bank_transfer": {
"bank": "permata",
"permata": {
"recipient_name": "SUDARSONO"
}
},
"transaction_details": {
"order_id": "H17550",
"gross_amount": 145000
}
}
BCA
{
"payment_type": "bank_transfer",
"bank_transfer":{
"bank": "bca",
"va_number": "111111",
"free_text": { => BCA ONLY
"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"
}
},
"transaction_details": {
"order_id": "H17550",
"gross_amount": 145000
}
}
Mandiri
{
"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"
}
}
Credit Card Payment
{
"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": "[email protected]",
"phone": "+628123456",
"billing_address": {
"first_name": "BUDI",
"last_name": "UTOMO",
"email": "[email protected]",
"phone": "081 2233 44-55",
"address": "Sudirman",
"city": "Jakarta",
"postal_code": "12190",
"country_code": "IDN"
},
"shipping_address": {
"first_name": "BUDI",
"last_name": "UTOMO",
"email": "[email protected]",
"phone": "0 8128-75 7-9338",
"address": "Sudirman",
"city": "Jakarta",
"postal_code": "12190",
"country_code": "IDN"
}
}
}
E-wallet (Telkomsel Cash)
{
"customer_details": {
 "first_name": "Budi",
"phone": "0812332423",
"email": "[email protected]",
"last_name": "Utomo"
},
"item_details": [
{
"id": "2964101",
"price": 25000,
"name": "Telkomsel REG 25000",
"quantity": 1
}
],
"transaction_details": {
"gross_amount": 25000,
"order_id": "order01"
},
"telkomsel_cash": {
"promo": false,
"is_reversal": 0,
"customer": "9932710273"
},
"payment_type": "telkomsel_cash"
}
● Success Response Example
Bank Transfer
Permata
{
"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"
}
BCA, BNI
{
"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"
}
Mandiri
{
"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"
}
Credit Card
{
"transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
"order_id": "C17550",
"gross_amount": "145000.00",
"payment_type": "credit_card",
"transaction_time": "2014-08-24 15:39:22",
"transaction_status": "capture",
"fraud_status": "accept",
"masked_card": "481111-1114",
"status_code": "200",
"bank": "bni",
 "status_message": "Success, Credit Card 3D Secure transaction is
successful",
"approval_code": "1408869563148",
"eci": "05",
"channel_response_code": "00",
"channel_response_message": "Approved",
"currency": "IDR"
}
E-wallet (Telkomsel Cash)
{
"status_code": "200",
"status_message": "Success, T-Cash transaction is successful",
"transaction_id": "0528d852-76be-466a-993e-787241cc5d90",
"order_id": "order01",
"gross_amount": "25000.00",
"payment_type": "telkomsel_cash",
"transaction_time": "2016-06-19 16:08:09",
"transaction_status": "settlement"
}
● Error and Failed Response Example
{
"status_code": 411
"status_message": “Token id is missing, invalid, or timed out”
}

Notification Handling
● Endpoint Setup
Midtrans Server sends request feedback to Merchant’s Notification Endpoint
Url
Can be set on MAP => Setting => Configuration
● Signature Key
Notifications sent to Merchant’s Endpoint by Midtrans contains Signature
Key formatted as
SHA512(order_id+status_code+gross_amount+serverkey)
● Success Transaction
A successful transaction can be determined by these parameters
○ status code: Should be 200 for successful transactions
○ fraud status: ACCEPT
○ transaction status : settlement/capture
● Notification Object
Credit Card Payment Capture
{
"masked_card": "481111-1114",
"approval_code": "T58755",
"bank": "bni",
"eci": "05",
"transaction_time": "2014-08-24 15:39:22",
"gross_amount": "145000.00",
"order_id": "C17550",
"payment_type": "credit_card",
"signature_key":
"8d22a6b625f395a1a2cf0e62497e20be433cbad3e8a8ff36bf6b40dbd47308125c
cda93546eab8a3acd91390155082658ac25b10a6294c6660642e43a5edc8bb",
"status_code": "200",
"transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
"transaction_status": "capture",
"fraud_status": "accept",
"status_message": "Veritrans payment notification",
"channel_response_code": "00",
"channel_response_message": "Approved"
}
Credit Card Payment Settlement
{
"masked_card": "481111-1114",
"approval_code": "131755",
"bank": "bni",
"eci": "05",
"transaction_time": "2014-08-24 15:39:22",
"gross_amount": "145000.00",
"order_id": "C17550",
"payment_type": "credit_card",
"signature_key":
"49e158a0c3f1913eae0902875324075c562daa39b2824b865db2242adea247a228
960d2f1002392fdbc29c3271c2bc78ba72e588db9047a82932d0615ddc811f",
"status_code": "200",
"transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
"transaction_status": "settlement",
"fraud_status": "accept",
"status_message": "Veritrans payment notification",
"channel_response_code": "00",
 "channel_response_message": "Approved"
}
Credit Card Payment Deny
{
"masked_card": "481111-1114",
"approval_code": "338016",
"bank": "bni",
"eci": "06",
"transaction_time": "2014-08-24 15:39:22",
"gross_amount": "145000.00",
"order_id": "C17550",
"payment_type": "credit_card",
"signature_key":
"763713b31cf59c886d3cc4a0c654a060a8e990080fe29fca75ae9e4ff9de804809
c4e20977829844dac01a7ac1464a4eb095ad32482048398918987295dc5022",
"status_code": "202",
"transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
"transaction_status": "deny",
"fraud_status": "accept",
"status_message": "Veritrans payment notification",
"channel_response_code": "05",
"channel_response_message": "Do not honor"
}
Bank Transfer
Permata
Pending
{
"status_code": "201",
"status_message": "Veritrans payment notification",
"transaction_id": "6fd88567-62da-43ff-8fe6-5717e430ffc7",
"order_id": "H17550",
"gross_amount": "145000.00",
"payment_type": "bank_transfer",
"transaction_time": "2016-06-19 13:42:29",
"transaction_status": "pending",
"fraud_status": "accept",
"permata_va_number": "8562000087926752",
"signature_key":
"66aa11a65b18e9ee5da966ed18d5d2163812000eee37824ceb59aba1ded00
 5e992e05a7dfac39098ebdb0e2c8b484e140b586246d34b4ca313c690cc6ea
e48cf"
}
Settlement
{
"status_code": "200",
"status_message": "Veritrans payment notification",
"transaction_id": "6fd88567-62da-43ff-8fe6-5717e430ffc7",
"order_id": "H17550",
"gross_amount": "145000.00",
"payment_type": "bank_transfer",
"transaction_time": "2016-06-19 18:23:21",
"transaction_status": "settlement",
"fraud_status": "accept",
"permata_va_number": "8562000087926752",
"signature_key":
"0c0df82489931602577d9e434966c0540249b7c0aeaae2b718305af89a11e
2bf9b4008aba07d1b3b248b15b4fbecdd15e81dbb2648b974efc4e0656e8c9
76094"
}

Expire
{
"status_code": "202",
"status_message": "Veritrans payment notification",
"transaction_id": "6fd88567-62da-43ff-8fe6-5717e430ffc7",
"order_id": "H17550",
"gross_amount": "145000.00",
"payment_type": "bank_transfer",
"transaction_time": "2016-06-20 13:42:30",
"transaction_status": "expire",
"fraud_status": "accept",
"permata_va_number": "8562000087926752",
"signature_key":
"f1066b06ec8a4b7d6ffb941fd9772f6df304618e15e02cf17c2914cec1279
3e19c71653042f7f617b027eae6ecb6759529c67eca9af55264b736408d8b4
df2b9"
}
BCA
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":
"74d9b6f4cc36585d74e06c9dba360331e455171bcec35df60cf28a786436f
8f96e6afcc1f091d6cb61411aec246ac28ba30b76d9b2c1cdb6409c0a70fcc
1fe47",
"status_code": "201",
"transaction_id": "a9aed5972-5b6a-401e-894b-a32c91ed1a3a",
"transaction_status": "pending",
"fraud_status": "accept",
"status_message": "Veritrans payment notification"
}
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":
"fe5f725ea770c451017e9d6300af72b830a668d2f7d5da9b778ec2c4f9177
efe5127d492d9ddfbcf6806ea5cd7dc1a7337c674d6139026b28f49ad0ea1c
e5107",
"status_code": "200",
 "transaction_id": "9aed5972-5b6a-401e-894b-a32c91ed1a3a",
"transaction_status": "settlement",
"fraud_status": "accept",
"status_message": "Veritrans payment notification"
}
Expired
{
"status_code": "202",
"status_message": "Veritrans payment notification",
"transaction_id": "9aed5972-5b6a-401e-894b-a32c91ed1a3a",
"order_id": "1466323342",
"gross_amount": "20000.00",
"payment_type": "bank_transfer",
"transaction_time": "2016-06-20 15:02:23",
"transaction_status": "expire",
"signature_key":
"e4e829a5d9a1e342daf181c5fd750afa64dd5a5c9a6e0cfb636e7966295b2
613fda22b4dc52b01c30618a50ff3524f57ec661a9dced249df93f163138a0
df6b0"
}