Create AccountSubmit FeedbackAI Assist (BETA)

JSON Objects

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
}
ParameterDescription
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"
}]
ParameterDescription
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


📘

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"
  }
}
ParameterDescription
first_name
String(255) (optional)
last_name
String(255) (optional)
email
String(255) (optional)
phone
String(255) (optional)
billing_address
Address (optional)
shipping_address
Address (optional)

📘

Tips

You can use theese parameters as rules in our Fraud Detection System



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"
}
ParameterDescription
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"
  }
}
ParameterDescription
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"
      }
    ]
  }
}
ParameterDescription
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


ParameterDescription
inquiry
Array of FreeTextItem (optional)		Size should not exceed 10.
payment
Array of FreeTextItem (optional)		Size should not exceed 10.

Free Text Item


ParameterDescription
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"
}
ParameterDescription
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"
}
ParameterDescription
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 AttributeDescriptionTypeRequired
bill_info1Label 1. Mandiri allows only 10 characters. Exceeding characters will be truncated.String(255)Optional
bill_info2Value 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"
}
ParameterDescription
va_number
String (optional)		Custom virtual account number. Length should be within 1 to 13.


CIMB Virtual Account Object


"cimb_va": {
  "va_number": "12345678"
}
ParameterDescription
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"
}
ParameterDescription
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"
}
ParameterDescription
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"
}
ParameterDescription
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/"
}
ParameterDescription
finish
String(255) (optional)		Redirect URL after transaction is successfully paid (Overriden by JS callback). 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
}
ParameterDescription
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 unit and duration is given, start_time will 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"
}
...
ParameterDescriptionTypeRequired
durationPage expiry duration in numbersIntegerRequired
unitExpiry unit. Options: day, hour, minute (plural terms also accepted).StringRequired

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"
}
...
ParameterDescriptionTypeRequired
requiredSpecify the intent whether payment will be utilizing recurring payments or not.IntegerRequired (if recurring object is passed)
start_timeStart of the subscription schedule. Passed information will be shown in Snap Checkout UI & returned in HTTP Notification.StringOptional
interval_unitSubscription charge internal unitStringOptional