This section will explain how merchants can initiate bank transfer (virtual account) transactions using BI-SNAP-based CoreAPI specification.
Creating bank transfer (virtual account) transaction
Path | /{version}/transfer-va/create-va |
---|---|
HTTP Method | POST |
Version | v1.0 |
SNAP version code | 27 |
Request Header
Field Name | Field Type | Mandatory | Field Description |
---|---|---|---|
Content-Type | String | M | Media type of the resource, i.e. application/json |
X-TIMESTAMP | String | M | Client’s current local time in ISO-8601 format |
Authorization | String | M | Represents access_token of a request; string starts with keyword “Bearer ” followed by access_token. Can get this from Access Token B2B API response. |
X-SIGNATURE | String | M | Created using symmetric signature HMAC_SHA512 algorithm |
X-PARTNER-ID | String | M | Unique identifier for caller (merchant_id) |
CHANNEL-ID | String | M | Mandatory field from Bank Indonesia that can take any value with correct format 5 digits numeric string |
X-EXTERNAL-ID | String | M | Alphanumeric string. Preferably UUID. Reference number that should be unique across 3 months. The value should also be the same as request_body.trxId It’s recommended that the merchant appends the said value with their client_id (client_key) |
Content-type:application/json
X-TIMESTAMP:2020-01-01T00:00:00+07:00
X-SIGNATURE:da1fa417c72d6b91c257e01e54fac824
Authorization:Bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CupvIJbU1Mmu4a11MNDZ7Sg5u9a
X-PARTNER-ID:G12345678
X-EXTERNAL-ID:midtrans-testing-001
CHANNEL-ID:12345
Request Body
Field Name | Field Type | Mandatory | Field Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
partnerServiceId | String(8) | M | This field will be shared by Midtrans during the onboarding process. This will be associated with the bank's company code.
The value should be left-padded with spaces until it’s 8 characters long. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customerNo | String(20) | M | Merchant-defined number. The value will be used to generate the VA number. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
virtualAccountNo | String(28) | M | This field will be the combination of partnerServiceId + customerNo
Please refer to the "Custom VA Number" below this section if you're looking to define your own VA number for your customers. If you want to randomize your VA number, please refer to the additionalInfo.flags.shouldRandomizeVaNumber field |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
virtualAccountName | String(255) | M | The customer name | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
virtualAccountEmail | String(255) | O | The customer’s email | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
virtualAccountPhone | String(30) | O | The customer’s phone number | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
trxId | String(36) | M | Alphanumeric string. Preferably UUID. Reference number that should be unique across 3 months. This value should be filled with the same value as X-EXTERNAL-ID | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
totalAmount | Object | M | For Multi-use VA with flexible amount, merchant should fill the totalAmount field with a totalAmount.value of at least 1.00 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
totalAmount.value | String (16, 2) | M | The numeric string of the amount up to two decimal places | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
totalAmount.currency | String (3) | M | The currency of the value paid. Should be IDR | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
expiredDate | String (25) | O | Indicate the deadline the virtual account should be paid at the latest. Beyond the specified time it will be marked as expired.
For Multi-use VA, this value will be ignored and the expiry time will always be 6 months after creation for the first payment and indefinite for the next payments |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo | Object | M | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.bank | String | M | Indicates the bank chosen to create the VA at. The banks that can be used will differ based on the banks chosen by the merchant during the onboarding process. Possible values are
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.merchantId | String(10) | M | This will be the merchantId shared during the onboarding process | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.subCompanyCode | String | O | This field can be used if the VA being created is BCA. It can filled with BCA’s sub company code value
Note: Default is 00000. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.freeText | Array of Objects | O | Will be used by the bank to show to the consumer in the bank app
Note: Right now only used for BCA VA. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.freeText.inquiry | Object | O | Will be used by the bank to show to the consumer at the inquiry process | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.freeText.inquiry.english | String | O | English description of the inquiry text | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.freeText.inquiry.indonesia | String | O | Bahasa Indonesia version of the inquiry text | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.freeText.payment | Object | O | Will be used by the bank to show to the consumer after the payment process | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.freeText.payment.english | String | O | English description of the payment text | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.freeText.payment.indonesia | String | O | Bahasa Indonesia version of the payment text | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.mandiri | Array of Objects | C | Array of Mandiri bill description. (this will become mandatory , if Mandiri is chosen as the VA method - additionalInfo.bank = "mandiri") |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.mandiri.billInfo1 | String (10) | C | Label 1. Mandiri allows only 10 characters. Exceeding characters will be truncated. (this will become mandatory , if Mandiri is chosen as the VA method - additionalInfo.bank = "mandiri") |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.mandiri.billInfo2 | String (30) | C | Value for Label 1. Mandiri allows only 30 characters. Exceeding characters will be truncated. (this will become mandatory , if Mandiri is chosen as the VA method - additionalInfo.bank = "mandiri") |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.mandiri.billInfo3 | String (10) | O | Label 2. Mandiri allows only 10 characters. Exceeding characters will be truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.mandiri.billInfo4 | String (30) | O | Value for Label 2. Mandiri allows only 30 characters. Exceeding characters will be truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.mandiri.billInfo5 | String (10) | O | Label 3. Mandiri allows only 10 characters. Exceeding characters will be truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.mandiri.billInfo6 | String (30) | O | Value for Label 3. Mandiri allows only 30 characters. Exceeding characters will be truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.mandiri.billInfo7 | String (10) | O | Label 4. Mandiri allows only 10 characters. Exceeding characters will be truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.mandiri.billInfo8 | String (30) | O | Value for Label 4. Mandiri allows only 30 characters. Exceeding characters will be truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customField | Object | O | A collection of up to three fields that can be customized by the merchant. These fields will be sent by Midtrans on the HTTP notification. It will also be displayed on the Dashboard under “order detail” | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customField1 | String(255) | O | First field that contains the custom data set by the merchant | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customField2 | String(255) | O | Second field that contains the custom data set by the merchant | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customField3 | String(255) | O | Third field that contains the custom data set by the merchant | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails | Object | O | Customer Detail Information | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.phone | String(15) | O | Customer Phone number | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.email | String(255) | O | Customer email | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.firstName | String(255) | O | Customer First Name
Will be shown to user during inquiry |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.lastName | String(255) | O | Customer Last Name
Will be shown to user during inquiry |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.billingAddress | Object | O | Customer billing address | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.billingAddress.firstName | String(255) | O | Billing address first name | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.billingAddress.lastName | String(255) | O | Billing address last name | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.billingAddress.phone | String(15) | O | Billing address phone | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.billingAddress.address | String(255) | O | Billing address detail | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.billingAddress.city | String(255) | O | Billing address city | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.billingAddress.postalCode | String(255) | O | Billing address postal code | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.billingAddress.countryCode | String(15) | O | Billing address country code | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.shippingAddress | Object | O | Customer shipping address | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.shippingAddress.firstName | String(255) | O | Shipping address first name | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.shippingAddress.lastName | String(255) | O | Shipping address last name | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.shippingAddress.phone | String(15) | O | Shipping address phone | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.shippingAddress.address | String(255) | O | Shipping address detail | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.shippingAddress.city | String(255) | O | Shipping address city | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.shippingAddress.postalCode | String(255) | O | Shipping address postal code | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.customerDetails.shippingAddress.countryCode | String(15) | O | Shipping address country code
Note: Currently only IDN is supported. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.items | Array Of Object | C | Item Details
Mandatory for Mandiri B2B VA only |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.items[x].id | String(32) | O | Item ID | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.items[x].price | Object | M | Price of the item in IDR. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.items[x].price.value | String (16,2) | M | The numeric string of the amount up to two decimal places | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.items[x].price.currency | String(3) | M | Item Price currency. Should be IDR. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.items[x].quantity | Number | M | Quantity of the item purchased by the customer. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.items[x].name | String(64) | O | Name of the item. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.items[x].merchantName | String(64) | O | Name of the merchant selling the item. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.items[x].brand | String(64) | O | Brand name of the item. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.items[x].category | String(64) | O | Category of the item. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.items[x].url | String(64) | O | HTTP URL of the item in the merchant site | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.flags | Object | O | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
additionalInfo.flags.shouldRandomizeVaNumber | Boolean | O | When this field is set to true, then the VA number suffix (customerNo) will be randomized. We also suggest to fill customerNo with "0000000000" and virtualAccountNo with partnerServiceId + "0000000000". If this value is not sent, Midtrans will acknowledge that merchant do not want to randomize the VA number. |
Note: this is an exhaustive list, please read the API specification above on how to use it.
Custom VA Number
As per mentioned above, this field will be the combination of partnerServiceId + customerNo , there's some rules that needs to be followed if we want to define our own VA number for our customer :
General Rules
- Only digits are allowed.
- Different banks have different specs on their custom VA numbers. (Please refer to the "Additional Rules" below this section)
- If the number provided is already utilized for another order, then a different unique number will be used instead.
- If the number provided is longer than the maximum character (MaxChar), then the unnecessary digits in the end will be trimmed.
- If the number provided is shorter than the minimum character (MinChar), then customerNo will be prefixed with zeros.
Additional Rules
These additional rules need to be implemented because each bank have their own accepted format and some of them have unique logic that we need to follow, so the VA number that we create could be accepted by the respective banks.
- CIMB : MaxChar = 16 ; MinChar = 16
- BCA : MaxChar = 23 ; MinChar = partnerServiceId + 6
- BRI : MaxChar = 18 ; MinChar = 18
- Mandiri : MaxChar = partnerServiceId + 12 ; MinChar = partnerServiceId + 6
- Permata : MaxChar = 16 ; MinChar = 16 ; partnerServiceId will always be suffixed with 2 random char sequence number.
BNI VA Unique rules
For BNI, partnerServiceId will be altered first, and then MinChar & MaxChar logic will be adjusted using the result of altered partnerServiceId
If partnerServiceId == 3 char, partnerServiceId will prefixed by "8", other than that, it'll be prefixed with "988"
For
Prefix = "8" , then MaxChar = partnerServiceId + 12 ; MinChar = partnerServiceId + 12
Prefix = "988" , then MaxChar = parterServiceId + 8 ; MinChar = partnerServiceId + 8
*When you see MaxChar having an equals value with MinChar, that means any exceeding number will be trimmed, and any deficient number will be left padded with 0.
{
"partnerServiceId": " 70012",
"customerNo": "6280123456",
"virtualAccountNo": " 700126280123456",
"virtualAccountName": "Jokul Doe",
"virtualAccountEmail": "[email protected]",
"virtualAccountPhone": "6281828384858",
"trxId": "midtrans-testing-001",
"totalAmount": {
"value": "10000.00",
"currency": "IDR"
},
"additionalInfo": {
"merchantId": "G059876677",
"bank": "mandiri",
"flags": {
"shouldRandomizeVaNumber": false
},
"mandiri": {
"billInfo1": "bank_name",
"billInfo2": "mandiri",
"billInfo3": "Name:",
"billInfo4": "Budi Utomo",
"billInfo5": "Class:",
"billInfo6": "Computer Science",
"billInfo7": "ID:",
"billInfo8": "VT-12345"
},
"customerDetails": {
"firstName": "Jokul",
"lastName": "Doe",
"email": "[email protected]",
"phone": "+6281828384858",
"billingAddress": {
"firstName": "Jukul",
"lastName": "Doe",
"address": "Kalibata",
"city": "Jakarta",
"postalCode": "12190",
"phone": "+6281828384858",
"countryCode": "IDN"
},
"shippingAddress": {
"firstName": "Jukul",
"lastName": "Doe",
"address": "Kalibata",
"city": "Jakarta",
"postalCode": "12190",
"phone": "+6281828384858",
"countryCode": "IDN"
}
},
"customField": {
"1": "custom-field-1",
"2": "custom-field-2",
"3": "custom-field-3"
},
"items": [
{
"id": "a1",
"price": {
"value": "1000.00",
"currency": "IDR"
},
"quantity": 3,
"name": "Apel",
"brand": "Fuji Apple",
"category": "Fruit",
"merchantName": "Fruit-store"
},
{
"id": "a2",
"price": {
"value": "1000.00",
"currency": "IDR"
},
"quantity": 7,
"name": "Apel Malang",
"brand": "Fuji Apple",
"category": "Fruit",
"merchantName": "Fruit-store"
}
]
}
}
Response Header
Field Name | Field Type | Mandatory | Field Description |
---|---|---|---|
Content-Type | String | M | Media type of the resource, i.e application/json |
X-TIMESTAMP | String | M | Client's current local time in ISO-8601 |
Content-type:application/json
X-TIMESTAMP:2020-01-01T00:00:00+07:00
Response Body
Field Name | Field Type | Mandatory | Field Description | |
responseCode | String(7) | M | Status code of transaction charge result. | |
responseMessage | String(150) | M | Description of transaction charge result. | |
virtualAccountData | M | Object | ||
virtualAccountData.partnerServiceId | M | String(8) | Company code - will be shared by Midtrans during the onboarding process. Will be left-padded up to 8 characters long | |
virtualAccountData.customerNo | M | String(20) | Suffix of the VA number. The value will either be randomized or contains the customerNo sent in the request as a substring. Maximum length depends on the bank. | |
virtualAccountData.virtualAccountNo | M | String(28) | Number generated using the partnerServiceId and the given
customerNo in the request.
Note: The VA number generated will not always be the request.partnerServiceid + request.customerNo. Please use this field as the source of truth for VA number. |
|
virtualAccountData.virtualAccountName | M | String (255) | The customer name | |
virtualAccountData.virtualAccountEmail | String(255) | O | The customer’s email | |
virtualAccountData.virtualAccountPhone | String(30) | O | The customer’s phone number | |
virtualAccountData.trxId | String(36) | M | The identifier for the merchant to use for
inquiryRequestId in Inquiry Status API.
This value will be the same as the request’s trxId and X-EXTERNAL-ID |
|
virtualAccountData.totalAmount | O | Object | ||
virtualAccountData.totalAmount.value | M | String (16,2) | Total Amount up to 2 decimal places based with ISO 4217 format | |
virtualAccountData.totalAmount.currency | M | String(3) | Currency of amount based on ISO 4217 | |
virtualAccountData.expiryDate | O | String(25) | ISO 8601 Datetime when the VA will be expired if not paid
Notes: Multi Use VA will not have this field |
|
additionalInfo | Object | M | ||
additionalInfo.bank | String | M | Indicates the bank chosen to create the VA at. The banks
that can be used will differ based on the banks chosen by the merchant during
the onboarding process. Possible values are
|
|
additionalInfo.merchantId | String(10) | M | This will be the merchantId shared during the onboarding process | |
additionalInfo.subCompanyCode | String | O | This field can be used if the VA being created is BCA. It can filled with BCA’s sub company code value | |
additionalInfo.freeText | Array of Objects | O | Will be used by the bank to show to the consumer in the bank app | |
additionalInfo.freeText[x].inquiry | Object | O | Will be used by the bank to show to the consumer after the inquiry process | |
additionalInfo.freeText[x].inquiry.english | String | O | English description of the inquiry text | |
additionalInfo.freeText[x].inquiry.indonesia | String | O | Bahasa Indonesia version of the inquiry text | |
additionalInfo.freeText[x].payment | Object | O | Will be used by the bank to show to the consumer after the payment process | |
additionalInfo.freeText[x].payment.english | String | O | English description of the payment text | |
additionalInfo.freeText[x].payment.indonesia | String | O | Bahasa Indonesia version of the payment text | |
additionalInfo.mandiri | Object | O | Array of Mandiri bill description | |
additionalInfo.mandiri.billInfo1 | String | O | Label 1. Mandiri allows only 10 characters. Exceeding characters will be truncated. | |
additionalInfo.mandiri.billInfo2 | String | O | Value for Label 1. Mandiri allows only 30 characters. Exceeding characters will be truncated. | |
additionalInfo.mandiri.billInfo3 | String | O | Label 2. Mandiri allows only 10 characters. Exceeding characters will be truncated. | |
additionalInfo.mandiri.billInfo4 | String | O | Value for Label 2. Mandiri allows only 30 characters. Exceeding characters will be truncated. | |
additionalInfo.mandiri.billInfo5 | String | O | Label 3. Mandiri allows only 10 characters. Exceeding characters will be truncated. | |
additionalInfo.mandiri.billInfo6 | String | O | Value for Label 3. Mandiri allows only 30 characters. Exceeding characters will be truncated. | |
additionalInfo.mandiri.billInfo7 | String | O | Label 4. Mandiri allows only 10 characters. Exceeding characters will be truncated. | |
additionalInfo.mandiri.billInfo8 | String | O | Value for Label 4. Mandiri allows only 30 characters. Exceeding characters will be truncated. | |
additionalInfo.customerDetails | Object | O | Customer Detail Information | |
additionalInfo.customerDetails.phone | String(15) | O | Customer Phone number | |
additionalInfo.customerDetails.email | String(255) | O | Customer email | |
additionalInfo.customerDetails.firstName | String(255) | O | Customer First Name | |
additionalInfo.customerDetails.lastName | String(255) | O | Customer Last Name | |
additionalInfo.customerDetails.billingAddress | Object | O | Customer billing address | |
additionalInfo.customerDetails.billingAddress.firstName | String(255) | O | Billing address first name | |
additionalInfo.customerDetails.billingAddress.lastName | String(255) | O | Billing address last name | |
additionalInfo.customerDetails.billingAddress.phone | String(15) | O | Billing address phone | |
additionalInfo.customerDetails.billingAddress.address | String(255) | O | Billing address detail | |
additionalInfo.customerDetails.billingAddress.city | String(255) | O | Billing address city | |
additionalInfo.customerDetails.billingAddress.postalCode | String(255) | O | Billing address postal code | |
additionalInfo.customerDetails.billingAddress.countryCode | String(15) | O | Billing address country code | |
additionalInfo.customerDetails.shippingAddress | Object | O | Customer shipping address | |
additionalInfo.customerDetails.shippingAddress.firstName | String(255) | O | Shipping address first name | |
additionalInfo.customerDetails.shippingAddress.lastName | String(255) | O | Shipping address last name | |
additionalInfo.customerDetails.shippingAddress.phone | String(15) | O | Shipping address phone | |
additionalInfo.customerDetails.shippingAddress.address | String(255) | O | Shipping address detail | |
additionalInfo.customerDetails.shippingAddress.city | String(255) | O | Shipping address city | |
additionalInfo.customerDetails.shippingAddress.postalCode | String(255) | O | Shipping address postal code | |
additionalInfo.customerDetails.shippingAddress.countryCode | String(15) | O | Shipping address country code | |
additionalInfo.items | Array Of Object | O | Item Details | |
additionalInfo.items[x].id | String(32) | O | Item ID | |
additionalInfo.items[x].price | Object | M | Price of the item in IDR. | |
additionalInfo.items[x].price.value | String (ISO4217) | M | Item Price value | |
additionalInfo.items[x].price.currency | String(3) | M | Item Price currency | |
additionalInfo.items[x].quantity | String(16) | M | Quantity of the item purchased by the customer. | |
additionalInfo.items[x].name | String(64) | O | Name of the item. | |
additionalInfo.items[x].merchantName | String(64) | O | Name of the merchant selling the item. | |
additionalInfo.items[x].brand | String(64) | O | Brand name of the item. | |
additionalInfo.items[x].category | String(64) | O | Category of the item. | |
additionalInfo.items[x].url | String(64) | O | HTTP URL of the item in the merchant site |
{
"responseMessage": "Successful",
"virtualAccountData": {
"partnerServiceId": " 70012",
"customerNo": "6280123456",
"virtualAccountNo": " 700126280123456",
"expiryDate": "2024-01-27T14:04:54+07:00",
"virtualAccountEmail": "[email protected]",
"totalAmount": {
"value": "10000.00",
"currency": "IDR"
},
"virtualAccountPhone": "6281828384858",
"additionalInfo": {
"merchantId": "G059876677",
"bank": "mandiri",
"mandiri": {
"billInfo1": "bank_name",
"billInfo2": "mandiri",
"billInfo3": "Name:",
"billInfo4": "Budi Utomo",
"billInfo5": "Class:",
"billInfo6": "Computer Science",
"billInfo7": "ID:",
"billInfo8": "VT-12345"
},
"customerDetails": {
"firstName": "Jokul",
"lastName": "Doe",
"email": "[email protected]",
"phone": "+6281828384858",
"billingAddress": {
"firstName": "Jukul",
"lastName": "Doe",
"address": "Kalibata",
"city": "Jakarta",
"postalCode": "12190",
"phone": "+6281828384858",
"countryCode": "IDN"
},
"shippingAddress": {
"firstName": "Jukul",
"lastName": "Doe",
"address": "Kalibata",
"city": "Jakarta",
"postalCode": "12190",
"phone": "+6281828384858",
"countryCode": "IDN"
}
},
"customField": {
"1": "custom-field-1",
"2": "custom-field-2",
"3": "custom-field-3"
},
"items": [
{
"id": "a1",
"price": {
"value": "1000.00",
"currency": "IDR"
},
"quantity": 3,
"name": "Apel",
"brand": "Fuji Apple",
"category": "Fruit",
"merchantName": "Fruit-store",
"url": "https://www.google.com/search?q=apel"
},
{
"id": "a2",
"price": {
"value": "1000.00",
"currency": "IDR"
},
"quantity": 7,
"name": "Apel Malang",
"brand": "Fuji Apple",
"category": "Fruit",
"merchantName": "Fruit-store",
"url": "https://www.google.com/search?q=apel-malang"
}
]
},
"virtualAccountName": "Jokul Doe",
"trxId": "midtrans-testing-001"
},
"responseCode": "2002700"
}
List Response Code
Response Code | HTTP Status Code | Response Message |
2002700 | 200 | Success |
4012700 | 401 | Unauthorized. Signature |
5002700 | 500 | Internal Server Error |
4002700 | 400 | Bad Request |
4042713 | 404 | Invalid Amount |
4002701 | 400 | Invalid Field Format X-TIMESTAMP |
4092700 | 409 | Conflict |
Inquiry Status - Single Use VA
Path | /{version}/transfer-va/status |
---|---|
HTTP Method | POST |
Version | v1.0 |
SNAP version code | 26 |
Request Header
Field Name | Field Type | Mandatory | Field Description |
---|---|---|---|
Content-Type | String | M | Media type of the resource, i.e. application/json |
X-TIMESTAMP | String | M | Client’s current local time in ISO-8601 format |
Authorization | String | M | Represents access_token of a request; string starts with keyword “Bearer ” followed by access_token. Can get this from Access Token B2B API response. |
X-SIGNATURE | String | M | Created using symmetric signature HMAC_SHA512 algorithm |
X-PARTNER-ID | String | M | Unique identifier for caller (merchant_id) |
CHANNEL-ID | String | M | Mandatory field from Bank Indonesia that can take any value with correct format 5 digits numeric string |
X-EXTERNAL-ID | String | M | Alphanumeric string. Preferably UUID. Reference number that should be unique across 3 months. The value should also be the same as request_body.trxId It’s recommended that the merchant appends the said value with their client_id (client_key) |
Content-type:application/json
X-TIMESTAMP:2020-01-01T00:00:00+07:00
X-SIGNATURE:da1fa417c72d6b91c257e01e54fac824
Authorization:Bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CupvIJbU1Mmu4a11MNDZ7Sg5u9a
X-PARTNER-ID:G12345678
X-EXTERNAL-ID:midtrans-testing-001
CHANNEL-ID:12345
Request Body
Field Name | Field Type | Mandatory | Field Description | |
partnerServiceId | M | String(8) | partnerServiceId from Create VA Response | |
customerNo | M | String(20) | customerNo from Create VA Response | |
virtualAccountNo | M | String(28) | virtualAccountNo from Create VA Response | |
inquiryRequestId | M | String(128) | The trxId from createVA response. | |
additionalInfo | Object | |||
additionalInfo.merchantId | String(10) | M | This is the merchantId shared by Midtrans during the onboarding process |
{
"inquiryRequestId": "midtrans-testing-001",
"partnerServiceId": " 70012",
"customerNo": "6280123456",
"virtualAccountNo": " 700126280123456",
"additionalInfo": {
"merchantId": "G059876677"
}
}
Response Header
Field Name | Field Type | Mandatory | Field Description |
---|---|---|---|
Content-Type | String | M | Media type of the resource, i.e application/json |
X-TIMESTAMP | String | M | Client's current local time in ISO-8601 |
Content-type:application/json
X-TIMESTAMP:2020-01-01T00:00:00+07:00
Response Body
Field Name | Field Type | Mandatory | Field Description | |
responseCode | String(7) | M | Status code of transaction charge result. | |
responseMessage | String(150) | M | Description of transaction charge result. | |
virtualAccountData | M | Object | ||
virtualAccountData.paymentFlagReason | O | Object | ||
virtualAccountData.paymentFlagReason.english | O | String(200) | Reason for Payment Status in English | |
virtualAccountData.partnerServiceId | M | String(8) | customerNo from Create VA Response | |
virtualAccountData.customerNo | M | String(20) | virtualAccountNo from Create VA Response | |
virtualAccountData.virtualAccountNo | M | String(28) | The trxId from createVA response | |
virtualAccountData.inquiryRequestId | M | String(128) | Identifier to be used for performing inquiry This will be the same value as the request.inquiryRequestId |
|
virtualAccountData.paymentRequestId | C | String(128) | Unique identifier for this Payment from Midtrans.
This value will exist if the payment has been completed |
|
virtualAccountData.totalAmount | O | Object | ||
virtualAccountData.totalAmount.value | M | String (16,2) | Total Amount up to 2 decimal places based with ISO 4217 format | |
virtualAccountData.totalAmount.currency | M | String(3) | Currency of amount based on ISO 4217 | |
virtualAccountData.trxDateTime | O | Date(25) | ISO-8601 datetime in GMT+7 when the VA is created | |
virtualAccountData.transactionDate | O | Date(25) | ISO-8601 datetime in GMT+7 when the VA was paid
This field will exist if the VA has been paid |
|
virtualAccountData.paymentFlagStatus | O | String(2) | Status for Payment Flag
00 - Success 01 - Initiated 02 - Paying 03 - Pending 04 - Refunded 05 - Canceled 06 - Failed 07 - Not found 08 - Expired 09 - Denied |
|
virtualAccountData.paymentFlagReason | O | Object | Contains explanation for the payment flag status in different languages | |
virtualAccountData.paymentFlagReason.english | O | String | Explanation for payment flag status in English | |
additionalInfo | O | Object | ||
additionalInfo.merchantId | M | String (10) | This is the merchantId shared by Midtrans during the onboarding process |
{
"additionalInfo": {
"merchantId": "G059876677"
},
"responseMessage": "Successful",
"virtualAccountData": {
"partnerServiceId": " 70012",
"customerNo": "6280123456",
"virtualAccountNo": " 700126280123456",
"totalAmount": {
"currency": "IDR",
"value": "10000.00"
},
"paymentFlagReason": {
"english": "settlement"
},
"paymentFlagStatus": "00",
"trxDateTime": "2024-04-19T15:18:13+07:00",
"transactionDate": "2024-04-19T15:19:09+07:00",
"inquiryRequestId": "midtrans-testing-001",
"paymentRequestId": "A120240419081813bceyKQUK3iID"
},
"responseCode": "2002600"
}
List Response Code
Response Code | HTTP Status Code | Response Message |
2002600 | 200 | Success |
4012600 | 401 | Unauthorized. Signature |
4012600 | 401 | Unauthorized. Merchant does not have access |
4042601 | 404 | Transaction Not Found |
4002602 | 400 | Invalid Mandatory Field |
5002600 | 500 | Internal Server Error |
Inquiry Status - Multi Use VA
Path | /{version}/transfer-va/status |
---|---|
HTTP Method | POST |
Version | v1.0 |
SNAP version code | 26 |
Request Header
Field Name | Field Type | Mandatory | Field Description |
---|---|---|---|
Content-Type | String | M | Media type of the resource, i.e. application/json |
X-TIMESTAMP | String | M | Client’s current local time in ISO-8601 format |
Authorization | String | M | Represents access_token of a request; string starts with keyword “Bearer ” followed by access_token. Can get this from Access Token B2B API response. |
X-SIGNATURE | String | M | Created using symmetric signature HMAC_SHA512 algorithm |
X-PARTNER-ID | String | M | Unique identifier for caller (merchant_id) |
CHANNEL-ID | String | M | Mandatory field from Bank Indonesia that can take any value with correct format 5 digits numeric string |
X-EXTERNAL-ID | String | M | Alphanumeric string. Preferably UUID. Reference number that should be unique across 3 months. The value should also be the same as request_body.trxId It’s recommended that the merchant appends the said value with their client_id (client_key) |
Content-type:application/json
X-TIMESTAMP:2020-01-01T00:00:00+07:00
X-SIGNATURE:da1fa417c72d6b91c257e01e54fac824
Authorization:Bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CupvIJbU1Mmu4a11MNDZ7Sg5u9a
X-PARTNER-ID:G12345678
X-EXTERNAL-ID:midtrans-testing-001
CHANNEL-ID:12345
Request Body
partnerServiceId | String(8) | M | partnerServiceId from Create VA Response | |
customerNo | String(20) | M | customerNo from Create VA Response | |
virtualAccountNo | String(28) | M | virtualAccountNo from Create VA Response | |
inquiryRequestId | String(128) | M | The trxId from createVA response. | |
additionalInfo | Object | |||
additionalInfo.merchantId | String(10) | M | This is the merchantId shared by Midtrans during the onboarding process | |
additionalInfo.page | String | O | Index of the search. Default is 0. Min page is 0. | |
additionalInfo.pageSize | String | O | Number of transactions displayed per page. Default is 10.
Max page_size is 15. Min page_size is 1.
Example : Merchant has five transactions created under a certain order_id. The transactions are A, B, C, D, E, F (ordered to the latest). Below are the examples on how merchants can use page and pageSize parameters. pageSize is not set, page is not set: Merchant gets F, E, D, C, B, A pageSize is set 2, page is not set: Merchant gets F, E pageSize is set 2, page is set 1: Merchant gets D, C pageSize is set 3, page is set 1: Merchant gets C, B, A |
{
"inquiryRequestId": "midtrans-testing-001",
"partnerServiceId": " 70012",
"customerNo": "6280123456",
"virtualAccountNo": " 700126280123456",
"additionalInfo": {
"merchantId": "G059876677",
"page": "0",
"pageSize": "2"
}
}
Response Body
Field Name | Field Type | Mandatory | Field Description | |
responseCode | String(7) | M | Status code of transaction charge result. | |
responseMessage | String(150) | M | Description of transaction charge result. | |
virtualAccountData | Object | M | ||
virtualAccountData.partnerServiceId | String(8) | M | Derivative of X- PARTNER- ID, similar to company code, 8 digit left padding space. | |
virtualAccountData.customerNo | String(20) | M | Unique number (up to 20 digits). | |
virtualAccountData.virtualAccountNo | String(28) | M | partnerServiceId (8 digit left padding 0) + customerNo (up to 20 digits). | |
virtualAccountData.inquiryRequestId | String(128) | M | trxId sent in Create VA | |
additionalInfo | ||||
additionalInfo.merchantId | String | M | This is the merchantId shared by Midtrans during the onboarding process | |
additionalInfo.recurringPaymentDetail | Object | O | ||
additionalInfo.recurringPaymentDetail.recurringOrders | Array of Objects | M | All payments related to the parent order trxId | |
additionalInfo.recurringPaymentDetail.recurringOrders[0].totalAmount | Object | M | ||
additionalInfo.recurringPaymentDetail.recurringOrders[0].totalAmount.value | String(ISO 4217) (16,2) | M | Total Amount with 2 decimal | |
additionalInfo.recurringPaymentDetail.recurringOrders[0].totalAmount.currency | String(3) | M | Currency of amount based on ISO 4217 | |
additionalInfo.recurringPaymentDetail.recurringOrders[0].paymentFlagReason | Object | M | ||
additionalInfo.recurringPaymentDetail.recurringOrders[0].paymentFlagReason.english | String | M | Reason for Payment Status in English | |
additionalInfo.recurringPaymentDetail.recurringOrders[0].paymentRequestId | String | M | Midtrans order id | |
additionalInfo.recurringPaymentDetail.recurringOrders[0].paymentFlagStatus | String | M | Status for Payment Flag
00 - Success 01 - Initiated 02 - Paying 03 - Pending 04 - Refunded 05 - Canceled 06 - Failed 07 - Not found 08 - Expired 09 - Denied |
|
additionalInfo.recurringPaymentDetail.recurringOrders[0].trxDateTime | String | M | Datetime when the order created in GMT+7. ISO-8601 | |
additionalInfo.recurringPaymentDetail.recurringOrders[0].transactionDate | String | M | Datetime when the payment happened in GMT+7. ISO-8601 | |
additionalInfo.recurringPaymentDetail.recurringOrders[0].trxId | String | M | trxId, appended with randomly generated identifier for
second payment and so on
Sample first payment: merchant_order_id Sample: merchant_order_id-030424072903549oVvY |
|
additionalInfo.recurringPaymentDetail.paginationMetadata | Object | M | Pagination of the orders | |
additionalInfo.recurringPaymentDetail.paginationMetadata.total | String | M | Total orders related to the trxId | |
additionalInfo.recurringPaymentDetail.paginationMetadata.pageSize | String | M | Number of transactions displayed per page. | |
additionalInfo.recurringPaymentDetail.paginationMetadata.page | String | M | Index of the search. |
{
"responseCode": "2002600",
"responseMessage": "Successful"
"virtualAccountData": {
"partnerServiceId": " 70012",
"customerNo": "6280123456",
"virtualAccountNo": " 700126280123456"
},
"additionalInfo": {
"merchantId": "G12345463",
"recurringPaymentDetail": {
"recurringOrders": [
{
"totalAmount": {
"currency": "IDR",
"value": "150000.00"
},
"paymentFlagReason": {
"english": "settlement"
},
"paymentRequestId": "A120240403072903E6HgHZoE3bID",
"paymentFlagStatus": "00",
"trxDateTime": "2024-04-03T14:29:03+07:00",
"transactionDate": "2024-04-03T14:29:03+07:00",
"trxId": "midtrans-testing-001-030424072903549oVvY"
},
{
"totalAmount": {
"currency": "IDR",
"value": "5000.00"
},
"paymentFlagReason": {
"english": "settlement"
},
"paymentRequestId": "A120240403072821jJ3pwMIFEyID",
"paymentFlagStatus": "00",
"trxDateTime": "2024-04-03T14:28:21+07:00",
"transactionDate": "2024-04-03T14:28:49+07:00",
"trxId": "midtrans-testing-001"
}
],
"paginationMetadata": {
"total": "4",
"pageSize": "2",
"page": "1"
}
}
}
Delete VA
Path | /{version}/transfer-va/delete-va |
---|---|
HTTP Method | POST |
Version | v1.0 |
SNAP version code | 31 |
Request Header
Field Name | Field Type | Mandatory | Field Description |
---|---|---|---|
Content-Type | String | M | Media type of the resource, i.e. application/json |
X-TIMESTAMP | String | M | Client’s current local time in ISO-8601 format |
Authorization | String | M | Represents access_token of a request; string starts with keyword “Bearer ” followed by access_token. Can get this from Access Token B2B API response. |
X-SIGNATURE | String | M | Created using symmetric signature HMAC_SHA512 algorithm |
X-PARTNER-ID | String | M | Unique identifier for caller (merchant_id) |
CHANNEL-ID | String | M | Mandatory field from Bank Indonesia that can take any value with correct format 5 digits numeric string |
X-EXTERNAL-ID | String | M | Alphanumeric string. Preferably UUID. Reference number that should be unique across 3 months |
Content-type:application/json
X-TIMESTAMP:2020-01-01T00:00:00+07:00
X-SIGNATURE:da1fa417c72d6b91c257e01e54fac824
Authorization:Bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CupvIJbU1Mmu4a11MNDZ7Sg5u9a
X-PARTNER-ID:G12345678
X-EXTERNAL-ID:12345678901234567890
CHANNEL-ID:12345
Request Body
Field Name | Field Type | Mandatory | Field Description | |
partnerServiceId | String(8) | M | partnerServiceId from Create VA Response | |
customerNo | String(20) | M | customerNo from Create VA Response | |
virtualAccountNo | String(28) | M | virtualAccountNo from Create VA Response | |
trxId | String(64) | M | This value will be the trxId used in the create VA request. | |
additionalInfo | Object | O | ||
additionalInfo.merchantId | String(10) | M | This is the merchantId shared by Midtrans during the onboarding process |
{
"partnerServiceId": " 70012",
"customerNo": "6280123456",
"virtualAccountNo": " 700126280123456",
"trxId": "midtrans-testing-001",
"additionalInfo": {
"merchantId": "G059876677"
}
}
Response Header
Field Name | Field Type | Mandatory | Field Description |
---|---|---|---|
Content-Type | String | M | Media type of the resource, i.e application/json |
X-TIMESTAMP | String | M | Client's current local time in ISO-8601 |
Content-type:application/json
X-TIMESTAMP:2020-01-01T00:00:00+07:00
Response Body
Field Name | Field Type | Mandatory | Field Description | |
responseCode | String(7) | M | Response code | |
responseMessage | String(150) | M | Response description | |
virtualAccountData | Object | M | ||
virtualAccountData.partnerServiceId | String(8) | M | partnerServiceId from Create VA Response | |
virtualAccountData.customerNo | String(29) | M | customerNo from Create VA Response | |
virtualAccountData.virtualAccountNo | String (28) | M | virtualAccountNo from Create VA Response | |
virtualAccountData.trxId | String(64) | M | The identifier used by the merchant during create VA. This will be the same as the trxId in the create VA process | |
additionalInfo.merchantId | String(10) | M | This is the merchantId shared by Midtrans during the onboarding process |
{
"responseMessage": "Successful",
"virtualAccountData": {
"partnerServiceId": " 70012",
"customerNo": "6280123456",
"virtualAccountNo": " 700126280123456",
"additionalInfo": {
"merchantId": "G059876677"
},
"trxId": "midtrans-testing-001"
},
"responseCode": "2003100"
}
List Response Code
Response Code | HTTP Status Code | Response Message |
2003100 | 200 | Success |
4003102 | 400 | Invalid Mandatory Field |
4013100 | 401 | Unauthorized. |
5003101 | 500 | Internal Server Error |
5043100 | 504 | Timeout |