Create Checkout Token API

This API can be used to create a checkout token which is used to open a checkout page where a transaction happens. Details regarding the transaction can be passed here, such as list of enabled payments on checkout page, transaction expiry time, callback URL from checkout page, and some more which can be seen below.

Endpoints: /api/v1/checkout/transactions

HTTP Method: POST

Request Body

{
  "transaction_details": {
    "order_id": "ORDER-101",
    "gross_amount": 10000
  }
}

{
  "transaction_details": {
    "order_id": "ORDER-101",
    "gross_amount": 10000
  },
  "item_details": [{
    "id": "ITEM1",
    "price": 10000,
    "quantity": 1,
    "name": "Midtrans Bear",
    "brand": "Midtrans",
    "category": "Toys",
    "merchant_name": "Midtrans",
    "url": "http://toko/toko1?item=abc"
  }],
  "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"
    }
  },
  "enabled_payments": ["credit_card", "cimb_clicks",
    "bca_klikbca", "bca_klikpay", "bri_epay", "echannel", "permata_va",
    "bca_va", "bni_va", "bri_va","cimb_va", "other_va", "gopay", "indomaret",
    "danamon_online", "akulaku", "shopeepay", "kredivo", "uob_ezpay","other_qris" ],
  
  "credit_card": {
    "secure": true,
    "channel": "migs",
    "bank": "bca",
    "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"
    ],
    "dynamic_descriptor": {
      "merchant_name" : "Fuji Apple Inc",
      "city_name": "Jakarta",
      "country_code": "ID"
    }
  },
  "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"
        }
      ]
    }
  },
  "bni_va": {
    "va_number": "12345678"
  },
  "bri_va": {
    "va_number": "1234567891234"
  },
  "cimb_va": {
    "va_number": "1234567891234567"
  },  
  "permata_va": {
    "va_number": "1234567890",
    "recipient_name": "SUDARSONO"
  },
  "shopeepay": {
    "callback_url": "http://shopeepay.com"
  },
  "gopay": {
    "enable_callback": true,
    "callback_url": "http://gopay.com"
  },
  "callbacks": {
    "finish": "https://demo.midtrans.com"
  },
  "expiry": {
    "start_time": "2018-12-13 18:11:08 +0700",
    "unit": "minutes",
    "duration": 1
  },
  "page_expiry": {
      "duration": 3,
      "unit": "hours"
  },
  "custom_field1": "custom field 1 content",
  "custom_field2": "custom field 2 content",
  "custom_field3": "custom field 3 content"
}

Field	Type	Attribute	Description
transaction_details Transaction Details	Object	Mandatory	Specific information regarding the transaction
item_details Array of Item Details	Object	Mandatory	Shopping item details will be paid by customer
customer_details Customer Details	Object	Mandatory	Specific information regarding the customer
enabled_payments	Array of String	Optional	List of payment types that should be enabled. If `enabled_payments:` field is not passed, all active payment types are included. Card Payment: `credit_card`. VA: `echannel` (Mandiri Bill Payment), `permata_va`, `bca_va`, `bni_va`, `bri_va`, `cimb_va`. E-wallets: `gopay`, and `shopeepay`. Other QRIS: `other_qris` Aliasing refers to a list of payment types. Passing an alias is the equivalent of passing all the the payment types it refers to. Supported aliases**: `bank_transfer` => e.g. `permata_va`, `bca_va`, `bni_va`. If you want to use `other_va`, either `permata_va` or `bni_va` or `bri_va` because Midtrans handles other bank transfer as either Permata or BNI VA or BRI VA.
credit_card CreditCard	Object	Optional	Card payment method
bca_va BCA Virtual Account	Object	Optional	BCA Virtual Account payment method
permata_va Permata Virtual Account	Object	Optional	Permata Virtual Account payment method
bni_va BNI Virtual Account	Object	Optional	BNI Virtual Account payment method
cimb_va CIMB Virtual Account	Object	Optional	CIMB Virtual Account payment method
bri_va BRI Virtual Account	Object	Optional	BRI Virtual Account payment method
other_va Other Banks Virtual Account	Object	Optional	Other Banks payment method. See Other Bank page for more details on how it works.
gopay GoPay	Object	Optional	GoPay e-wallet & GoPay QRIS payment methods.
shopeepay ShopeePay	Object	Optional	ShopeePay & ShopeePay QRIS payment methods.
callbacks Callbacks	Object	Optional	Redirect URL after transaction is successfully paid (can be overridden by JS callback). Can also be set via Snap Preference menu in your dashboard. Partner merchant (multi-outlet) can use cross auth to access merchant dashboard and configure this.
expiry Expiry	Object	Optional	Custom payment method expiry
page_expiry Page Expiry	Object	Optional	Customize Checkout page expiry
custom_field1	String	Optional	Custom field 1 for custom parameter from merchant
custom_field2	String	Optional	Custom field 2 for custom parameter from merchant
custom_field3	String	Optional	Custom field 3 for custom parameter from merchant

📘
Specifying payment methods via API using enabled_payments
Other than from Snap Preference settings in Dashboard, you can also specify which payment method to show in Snap via API using enabled_payments. This is useful if you want to maintain your own payment list; you can then bind each payment method list in your checkout page with individual Snap checkout page containing the specified payment method. See Supported Payment Channels page for more details on the param value for each payment channel.

Sample Curl

curl --location 'https://partner-api.stg.midtrans.com/api/v1/checkout/transactions' \
--header 'x-partner-id: 370' \
--header 'x-merchant-id: G167720338' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic key' \
--data '{
    "transaction_details": {
        "order_id": "order-1720773628",
        "gross_amount": 50000
    }
}'

Response Body

Success

{
  "token": "d379aa71-99eb-4dd1-b9bb-eefe813746e9",
  "redirect_url": "https://app.sandbox.midtrans.com/snap/v3/redirection/071e0c3d-dade-4148-a1b5-296ee8735b79"
}

Field	Type	Description
token	String(36)	Snap token for opening the Snap popup
redirect_url	String(75)	URL for redirection

Failed

{
  "error_messages": [
    "transaction_details.gross_amount is not equal to the sum of item_details"
  ]
}

{
  "error_messages": [
    "transaction_details.order_id has been paid and utilized, please use another order ID"
  ]
}

{
  "error_messages": [
    "Access denied due to unauthorized transaction, please check client or server key",
    "Visit https://snap-docs.midtrans.com/#request-headers for more details"
  ]
}

{
  "error_messages": [
    "Sorry, we encountered internal server error. We will fix this soon."
  ]
}

Field	Type	Description
error_messages	Array of String	Error messages