Collection of JSON objects that are used in Create Snap Token parameter.
Note: More JSON objects exists for each specific payment channels.
Transaction Details Object
"transaction_details": {
"order_id": "ORDER-101",
"gross_amount": 10000
}
| Parameter | Description |
|---|---|
| transaction_details.order_id (required) String(50) for Snap Checkout String (36) for Payment Link | Unique transaction ID. A single ID could be used only once by a Merchant. NOTE: Allowed Symbols are dash(-), underscore(_), tilde (~), and dot (.) |
| transaction_details.gross_amount Integer (required) | Amount to be charged |
Item Details Object
"item_details": [{
"id": "ITEM1",
"price": 10000,
"quantity": 1,
"name": "Midtrans Bear",
"brand": "Midtrans",
"category": "Toys",
"merchant_name": "Midtrans",
"url": "https://tokobuah.com/apple-fuji"
}]
| Parameter | Description |
|---|---|
| id String(50) (optional) | Item ID |
| price Integer (required) | Price of the item NOTE: Don't add decimal |
| quantity Integer (required) | Quantity of the item NOTE: Must be greater than or equal 1 |
| name String(50) (required) | Name of the item |
| brand String(50) (optional) | Brand of the item |
| category String(50) (optional) | Category of the item |
| merchant_name String(50) (optional) | Merchant selling the item |
| url String(50) (optional) | HTTP URL of the item in the merchant site |
- Subtotal (item price multiplied by quantity) of all the item details needs to be exactly the same as the gross_amount inside transaction_details object
- Please avoid using vertical line (
|) for Alfamart payment type- item_details field is required for Akulaku payment type and does not allow duplicate item IDs (item_details.id) in one request
Tips
You can actually make an item with minus price to be presented as discount
Customer Details Object
"customer_details": {
"first_name": "TEST",
"last_name": "MIDTRANSER",
"email": "[email protected]",
"phone": "+628123456",
"billing_address": {
"first_name": "TEST",
"last_name": "MIDTRANSER",
"email": "[email protected]",
"phone": "081 2233 44-55",
"address": "Sudirman",
"city": "Jakarta",
"postal_code": "12190",
"country_code": "IDN"
},
"shipping_address": {
"first_name": "TEST",
"last_name": "MIDTRANSER",
"email": "[email protected]",
"phone": "0 8128-75 7-9338",
"address": "Sudirman",
"city": "Jakarta",
"postal_code": "12190",
"country_code": "IDN"
}
}
Tips
Customer Details object is mandatory to be passed for Akulaku Paylater, if not passed, transaction will fail.
Address Object
"billing_address": {
"first_name": "TESTER",
"last_name": "MIDTRANSER",
"email": "[email protected]",
"phone": "081 2233 44-55",
"address": "Sudirman",
"city": "Jakarta",
"postal_code": "12190",
"country_code": "IDN"
}
"shipping_address": {
"first_name": "TESTER",
"last_name": "MIDTRANSER",
"email": "[email protected]",
"phone": "081 2233 44-55",
"address": "Sudirman",
"city": "Jakarta",
"postal_code": "12190",
"country_code": "IDN"
}
| Parameter | Description |
|---|---|
| first_name String(255) (optional) | |
| last_name String(255) (optional) | |
| email String(255) (optional) | |
| phone String(255) (optional) | |
| address String(255) (optional) | |
| country_code String(10) (optional) | |
| postal_code String(10) (optional) | |
| city String(100) (optional) |
Credit Card Object
"credit_card": {
"save_card": true,
"secure": true,
"channel": "migs",
"bank": "maybank",
"installment": {
"required": false,
"terms": {
"bni": [3, 6, 12],
"mandiri": [3, 6, 12],
"cimb": [3],
"bca": [3, 6, 12],
"offline": [6, 12]
}
},
"whitelist_bins": [
"48111111",
"41111111",
"bni"
],
"dynamic_descriptor": {
"merchant_name" : "Fuji Apple Inc",
"city_name": "Jakarta",
"country_code": "ID"
}
}
| Parameter | Description |
|---|---|
| secure Boolean (optional) | Use 3D-Secure authentication when using credit card. Default: false |
| bank String (optional) | Acquiring bank. Options: bca, bni, mandiri, cimb, bri, danamon, maybank, mega |
| channel String (optional) | Acquiring channel. Options: migs |
| type String (optional) | Credit card transaction type. Options: authorize, authorize_capture. Default: "authorize_capture" |
| whitelist_bins Array (optional) | Allowed credit card BIN numbers. The bin value can be either a prefix(upto 8 digits) of card number or the name of a bank, in which case all the cards issued by that bank will be allowed. The supported bank names are bni bca mandiri cimb bri and maybank. Default: allow all cards |
| installment.required Boolean (optional) | Force installment when using credit card. Default: false |
| installment.terms Object (optional) | Available installment terms |
| dynamic_descriptor.merchant_name String(25) (optional) | First 25 digit on customer's billing statement. Mostly used to show the merchant or product name. Only works for BNI. |
| dynamic_descriptor.city_name String(13) (optional) | Next 13 digit on customer's billing statement. It works as secondary metadata on the statement. Mostly used to show city name or region. Only works for BNI. |
| dynamic_descriptor.country_code String(2) (optional) | Last 2 digit on customer's billing statement. Mostly used to show country code. The format is ISO 3166-1 alpha-2. Only works for BNI. |
BCA Virtual Account Object
"bca_va": {
"va_number": "12345678911",
"sub_company_code": "00000",
"free_text": {
"inquiry": [
{
"en": "text in English",
"id": "text in Bahasa Indonesia"
}
],
"payment": [
{
"en": "text in English",
"id": "text in Bahasa Indonesia"
}
]
}
}
| Parameter | Description |
|---|---|
| va_number String (optional) | Custom virtual account number. Length should be within 6 to 11. |
| sub_company_code String (optional) | BCA sub company code directed for this transactions. NOTE: Default is 00000 |
| free_text FreeText (optional) |
Free Text
| Parameter | Description |
|---|---|
| inquiry Array of FreeTextItem (optional) | Size should not exceed 10. |
| payment Array of FreeTextItem (optional) | Size should not exceed 10. |
Free Text Item
| Parameter | Description |
|---|---|
| en String (required) | Size should not exceed 50 chars. |
| id String (required) | Size should not exceed 50 chars. |
Permata Virtual Account Object
"permata_va": {
"va_number": "1234567890",
"recipient_name": "SUDARSONO"
}
| Parameter | Description |
|---|---|
| va_number String (optional) | Custom virtual account number. Length should be 10. Only supported for b2b transactions. |
| recipient_name String (optional) | Recipient name shown on the on the bank's payment prompt. It is shown as 20 character uppercase string. Anyting over 20 character will be truncated. NOTE: Default is merchant name |
BNI Virtual Account Object
"bni_va": {
"va_number": "12345678"
}
| Parameter | Description |
|---|---|
| va_number String (optional) | Custom virtual account number. Length should be within 1 to 8. |
Mandiri Bill Object
"echannel" : {
"bill_info1" : "Payment:",
"bill_info2" : "Grocery Items",
}
| JSON Attribute | Description | Type | Required |
|---|---|---|---|
| bill_info1 | Label 1. Mandiri allows only 10 characters. Exceeding characters will be truncated. | String(255) | Optional |
| bill_info2 | Value for Label 1. Mandiri allows only 30 characters. Exceeding characters will be truncated. | String(255) | Optional |
BRI Virtual Account Object
"bri_va": {
"va_number": "12345678"
}
| Parameter | Description |
|---|---|
| va_number String (optional) | Custom virtual account number. Length should be within 1 to 13. |
CIMB Virtual Account Object
"cimb_va": {
"va_number": "12345678"
}
| Parameter | Description |
|---|---|
| va_number String (optional) | Custom virtual account number. Length should be within 1 to 12. |
GoPay Object
"gopay": {
"enable_callback": true,
"callback_url": "http://gopay.com",
"tokenization": true,
"phone_number": "8123456789",
"country_code": "62"
}
| Parameter | Description |
|---|---|
| enable_callback Boolean (optional) | Enable redirect back to merchant from GoJek apps. Default: false |
| callback_url String (optional) | Determine where should customer be redirected from GoJek apps. It supports both HTTP and deeplink. Default: same value as finish url |
| tokenization String (optional) | Determine whether gopay tokenization feature is enabled or not. Default: false |
| phone_number String (optional) | Determine the phone number that will be used on gopay tokenization. Default: null |
| country_code String (optional) | Determine the country code that will be used on gopay tokenization. Default: same value as finish url. Default: null |
ShopeePay Object
"shopeepay": {
"callback_url": "http://midtrans.com/finish-url?order_id=order-123"
}
| Parameter | Description |
|---|---|
| callback_url String (optional) | The URL to redirect the customer back from the ShopeePay app. It supports both HTTP and deeplink. Default: same value as finish url. If it's also empty, value is the finish URL and configured on your Snap Preferences. |
Cstore (Over the Counter) Object
"cstore": {
"alfamart_free_text_1" : "qwerty",
"alfamart_free_text_2" : "asdfg",
"alfamart_free_text_3" : "zxcvb"
}
| Parameter | Description |
|---|---|
| alfamart_free_text_1 String(40) (optional) | First row of printed receipt description |
| alfamart_free_text_2 String(40) (optional) | Second row of printed receipt description |
| alfamart_free_text_3 String(40) (optional) | Third row of printed receipt description |
Note : Indomaret doesn't use Cstore object.
Callbacks Object
"callbacks": {
"finish" : "https://example.com/",
"error": "https://example1.com"
}
| Parameter | Description |
|---|---|
| finish String(255) (optional) | Redirect URL after transaction is successfully paid. Applicable for all payments that will redirect from payment partner app/web back to Midtrans. Can also be set via Snap Settings menu in your dashboard. For GoPay, use the finish parameter in the GoPay object. |
| error String(255)(optional) | Redirect URL after transaction failed to be paid by customer. Applicable for all payments that will redirect from payment partner app/web back to Midtrans (except for BNPL and GoPay payment method). Can also be set via Snap Settings menu in your dashboard. |
Expiry Object
"expiry": {
"start_time": "2018-12-13 18:11:08 +0700",
"unit": "minutes",
"duration": 1
}
| Parameter | Description |
|---|---|
| start_time String(255) (optional) | Timestamp in yyyy-MM-dd HH:mm:ss Z format. If not specified, transaction time will be used as start time (when customer charge) |
| duration Integer (required for expiry) | Expiry duration |
| unit String (required for expiry) | Expiry unit. Options: day, hour, minute (plural term also accepted) |
If this parameter is not sent, the default expiry will use expiry setting on Snap preferences on merchant dashboard. Furthermore, if only
unitanddurationis given,start_timewill equal the timestamp of the transaction time (when customer charge).The Maximum expiry for the Snap token is 7 days. If the expiry sent is more than 7 days after the token is created. The Snap token will still expire 7 days after creation.
The minimum expiry for the Snap token is 20 seconds. If the expiry sent is less than 20 seconds. The Snap will respond to validation errors.
See this guide for more details.
Page Expiry Object
...
"page_expiry": {
"duration": 3,
"unit": "hours"
}
...
| Parameter | Description | Type | Required |
|---|---|---|---|
duration | Page expiry duration in numbers | Integer | Required |
unit | Expiry unit. Options: day, hour, minute (plural terms also accepted). | String | Required |
Note :
If not specified, default is 24 hours. See this guide for more details.
Recurring/Subscription Object
Use this object to show a dedicated recurring flow UI in Snap - differences include card will be automatically saved without having user manually tick the checkbox and adjusted copy to better suit recurring payments. Snap will then return the information passed here back in HTTP notification, for you to utilize when calling the Subscription API.
Use this object in conjunction with Subscription API - add this object to alter the Snap customer UI, then convert the transaction to recurring payments using Subscription API. Make sure to also have the prerequisites to accept Subscription (e.g. One Click feature) - otherwise transactions might fail.
Note that if you do choose to pass the start_time and interval_unit within the object, make sure to use the same information when calling the Subscription API - otherwise, information presented to user and actual subscription charge schedule will be different, which might result in chargeback.
...
"recurring": {
"required": true,
"start_time": "2024-06-09 15:07:00 +0700",
"interval_unit": "week"
}
...
| Parameter | Description | Type | Required |
|---|---|---|---|
required | Specify the intent whether payment will be utilizing recurring payments or not. | Integer | Required (if recurring object is passed) |
start_time | Start of the subscription schedule. Passed information will be shown in Snap Checkout UI & returned in HTTP Notification. | String | Optional |
interval_unit | Subscription charge internal unit | String | Optional |