Core API has various optional parameters that can be utilized to integrate with more advanced use cases.
You can include more information such as customer_details, item_details, and so on along side transaction_details. While sending API requests, it is recommended to send more details regarding the transaction, so that these details will be captured on the transaction record. Which can be viewed on the Midtrans Dashboard.
The JSON parameters added in the Request Body of a Charge API Request, to include more details of the transaction, are shown below.
{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "order102",
"gross_amount": 13000
},
"credit_card": {
"token_id": "<token_id from Get Card Token Step>",
"authentication": true,
},
"item_details": [
{
"id": "a01",
"price": 7000,
"quantity": 1,
"name": "Apple"
},
{
"id": "b02",
"price": 3000,
"quantity": 2,
"name": "Orange"
}
],
"customer_details": {
"first_name": "Budi",
"last_name": "Susanto",
"email": "[email protected]",
"phone": "+628123456789",
"billing_address": {
"first_name": "Budi",
"last_name": "Susanto",
"email": "[email protected]",
"phone": "08123456789",
"address": "Sudirman No.12",
"city": "Jakarta",
"postal_code": "12190",
"country_code": "IDN"
},
"shipping_address": {
"first_name": "Budi",
"last_name": "Susanto",
"email": "[email protected]",
"phone": "0812345678910",
"address": "Sudirman",
"city": "Jakarta",
"postal_code": "12190",
"country_code": "IDN"
}
}
}The JSON objects item_details, customer_details, and shipping_address are included in the sample Charge API Request shown below.
curl -X POST \
https://api.sandbox.midtrans.com/v2/charge \
-H 'Accept: application/json'\
-H 'Authorization: Basic <YOUR SERVER KEY ENCODED in Base64>' \
-H 'Content-Type: application/json' \
-d '{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "order102",
"gross_amount": 13000
},
"credit_card": {
"token_id": "<token_id from Get Card Token Step>",
"authentication": true,
},
"item_details": [
{
"id": "a01",
"price": 7000,
"quantity": 1,
"name": "Apple"
},
{
"id": "b02",
"price": 3000,
"quantity": 2,
"name": "Orange"
}
],
"customer_details": {
"first_name": "Budi",
"last_name": "Susanto",
"email": "[email protected]",
"phone": "+628123456789",
"billing_address": {
"first_name": "Budi",
"last_name": "Susanto",
"email": "[email protected]",
"phone": "08123456789",
"address": "Sudirman No.12",
"city": "Jakarta",
"postal_code": "12190",
"country_code": "IDN"
},
"shipping_address": {
"first_name": "Budi",
"last_name": "Susanto",
"email": "[email protected]",
"phone": "0812345678910",
"address": "Sudirman",
"city": "Jakarta",
"postal_code": "12190",
"country_code": "IDN"
}
}
}'POST Body JSON Attribute Description
For general use, the JSON parameters recommended to be included in the Charge API request are described in the table given below.
| Parameter | Description | Type | |
|---|---|---|---|
| item_details | The details of the item purchased. | Object | |
| id | The id of the item purchased. | String | |
| price | The price of the item. | String | |
| quantity | The number of items purchased. | String | |
| name | The name of the item purchased. | String | |
| customer_details | The details of the customer. | Object | |
| first_name | The first name of the payer. | String | |
| last_name | The last name of the payer. | String | |
| The email address of the payer. | String | ||
| phone | The phone number of the payer. | String | |
| address | The postal address of the payer. | String | |
| city | The city of payer. | String | |
| postal_code | The postal code of the payer. | String | |
| country_code | The country code of the payer. | String | |
| shipping_address | The address to which the item is to be shipped. | String | |
| first_name | The first name of the customer. | String | |
| last_name | The last name of the customer | String | |
| The email address of the customer. | String | ||
| phone | The phone number of the customer. | String | |
| address | The postal address. | String | |
| city | The name of the city. | String | |
| postal_code | The postal code. | String | |
| country_code | The country code. | String | |
For more details, refer to JSON Object.
You can also add fee, tax, discount, etc. to item_details if you need.
Custom transaction expiry can be configured for all payment methods except for Credit Card payment methods. You can configure expiry time for the payment of a transaction with the Transaction Status : Pending. After the expiry time is elapsed, the customer will not be able to make a payment for the transaction.
The JSON parameter added in the Request Body of a Charge API Request, to configure custom transaction expiry, is shown below.
...
"custom_expiry": {
"order_time": "2016-12-07 11:54:12 +0700",
"expiry_duration": 60,
"unit": "minute"
}
...The JSON object custom_expiry included in the sample Charge API Request is shown below.
curl -X POST \
https://api.sandbox.midtrans.com/v2/charge \
-H 'Accept: application/json'\
-H 'Authorization: Basic <YOUR SERVER KEY ENCODED in Base64>' \
-H 'Content-Type: application/json' \
-d '{
"payment_type": "gopay",
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 13000
},
"custom_expiry": {
"order_time": "2016-12-07 11:54:12 +0700",
"expiry_duration": 60,
"unit": "minute"
}
}'POST Body JSON Attribute Description
The JSON attributes recommended to be included in the Charge API request, to configure custom transaction expiry, are described in the table given below.
| Parameter | Description | Type | Note |
|---|---|---|---|
| order_time | The date and time at which the item was ordered. If not specified, transaction time (the time at which the payment method was confirmed) will be used as order_ time. |
String (50) | It is in the format, YYYY-MM-DD HH:MM:SS. Time zone: Western Indonesian Time (GMT+7) |
| expiry_duration | The duration for which the transaction is valid. | String (50) | -- |
| unit | The unit of expiry_duration. | String (50) | Valid values are second, minute, hour or day. Default value is minute. |
Custom Fields is a feature that enables you to include any specific details about the transaction. These details will be sent to the Core API. These will be included in the HTTP notification sent from Midtrans to the merchant backend. These custom details will also be displayed on the Dashboard under order details.
The JSON parameters added in the Request Body of a Charge API Request, to include custom fields, are shown below.
...
"custom_field1": "this is custom text defined by merchant",
"custom_field2": "order come from web",
"custom_field3": "customer selected blue color variant"
...The JSON objects custom_field1, custom_field2, custom_field3 included in the sample Charge API Request are shown below.
curl -X POST \
https://api.sandbox.midtrans.com/v2/charge \
-H 'Accept: application/json'\
-H 'Authorization: Basic <YOUR SERVER KEY ENCODED in Base64>' \
-H 'Content-Type: application/json' \
-d '{
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 13000
},
"custom_field1": "this is custom text defined by merchant",
"custom_field2": "order come from web",
"custom_field3": "customer selected blue color variant"
}'POST Body JSON Attribute Description
The JSON parameters recommended to be included in the Charge API request, to configure custom transaction expiry, are described in the table given below.
| Parameter | Description | Type |
|---|---|---|
| custom_field1 | You can write custom details about the transaction. | String (255) |
| custom_field2 | You can write custom details about the transaction. | String (255) |
| custom_field3 | You can write custom details about the transaction. | String (255) |
Metadata is similar to Custom Fields which enables you to put free-form JSON object instead of String. You can use this metadata as a transaction tag and retrieve it using Get Status or Notification Payload. Additionally, you can also configure fraud detection rules based on the metadata fields.
The JSON parameters added in the Request Body of a Charge API Request, to include metadata, is shown below.
...
"metadata": {
"you": "can",
"put": "any",
"parameter": "you like"
}
...The JSON object metadata, included in the sample Charge API Request is shown below.
curl -X POST \
https://api.sandbox.midtrans.com/v2/charge \
-H 'Accept: application/json'\
-H 'Authorization: Basic <YOUR SERVER KEY ENCODED in Base64>' \
-H 'Content-Type: application/json' \
-d '{
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 13000
},
"metadata": {
"you": "can",
"put": "any",
"parameter": "you like"
}
}'POST Body JSON Attribute Description
The JSON parameter recommended to be included in the Charge API request, to configure metadata, is described in the table given below.
| Parameter | Description | Type |
|---|---|---|
| metadata | Object containing the metadata parameters | Object |
Three Domain Secure (3DS) feature can be enabled/disabled for a specific transaction. By default, you should always enable 3DS. Please understand the risks involved in disabling 3DS. This will require you to have agreement and approval by the Acquiring Bank. Consult Midtrans Activation team to allow disabling 3DS.
The JSON parameters added in the Request Body of a Charge API Request, to enable 3DS, is shown below.
...
"credit_card": {
"token_id": "<token_id from Get Card Token Step>",
"authentication": true
}
...The JSON attribute authentication, included in the sample Charge API Request is shown below.
curl -X POST \
https://api.sandbox.midtrans.com/v2/charge \
-H 'Accept: application/json'\
-H 'Authorization: Basic <YOUR SERVER KEY ENCODED in Base64>' \
-H 'Content-Type: application/json' \
-d '{
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 9000
},
"credit_card": {
"token_id": "<token_id from Get Card Token Step>",
"authentication": true
}
}'POST Body JSON Attribute Description
The JSON parameter recommended to be included in the Charge API request, to enable/disable 3DS authentication, is described in the table given below.
| Parameter | Description | Type | Values |
|---|---|---|---|
| authentication | Flag to enable the 3DS authentication. | Boolean | true to enable 3DS.false to disable 3DS. |
You can specify a preferred Acquiring Bank for a specific transaction. Specify the bank name inside bank parameter. The transaction fund will be routed to that specific Acquiring Bank. Consult Midtrans Activation team to get information about the availability of the Acquiring Bank.
The JSON parameter added in the Request Body of a Charge API Request, to route the transaction fund to a specific Acquiring Bank, is shown below.
{
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 9000
},
"credit_card": {
"token_id": "<token_id from Get Card Token Step>",
"authentication": true,
"bank": "bca"
}
}The JSON attribute bank, included in the sample Charge API Request is shown below.
curl -X POST \
https://api.sandbox.midtrans.com/v2/charge \
-H 'Accept: application/json'\
-H 'Authorization: Basic <YOUR SERVER KEY ENCODED in Base64>' \
-H 'Content-Type: application/json' \
-d '{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 9000
},
"credit_card": {
"token_id": "<token_id from Get Card Token Step>",
"authentication": true,
"bank": "bca"
}'POST Body JSON Attribute Description
| Parameter | Description | Type | Values |
|---|---|---|---|
| bank | Name of the preferred Acquiring Bank. | String | mandiri, bni, cimb, bca, maybank, bri or mega. |
BIN (Bank Identification Number) filter is a feature that allows the merchant to accept only Credit Cards within specific set of BIN numbers. It is useful for certain bank promo/discount payment by accepting only credit cards issued by that bank. BIN (Bank Identification Number) is the first 1-8 digits of a card number, which identifies the bank that issues the card. A bank generally has more than one BIN.
To use this feature, accumulate the list of BIN that accepts the promotion or uses the issuing bank's name. This transaction can be performed exclusively by using the credit card that is included in the BIN list or BIN under the particular defined issuing bank.
The JSON parameters added in the Request Body of a Charge API Request to allow BIN filter, are shown below.
{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 120000
},
"credit_card": {
"token_id": "<token_id from Get Card Token Step>",
"authentication": true,
"bank": "bni",
"bins": ["48111111", "bni", "5"]
}
}The JSON attributes bank and bins included in the sample Charge API Request are shown below.
curl -X POST \
https://api.sandbox.midtrans.com/v2/charge \
-H 'Accept: application/json'\
-H 'Authorization: Basic <YOUR SERVER KEY ENCODED in Base64>' \
-H 'Content-Type: application/json' \
-d '{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 120000
},
"credit_card": {
"token_id": "<token_id from Get Card Token Step>",
"authentication": true,
"bank": "bni",
"bins": ["48111111", "bni", "5"]
}
}'?> Note: By default, Midtrans populates BIN number for BNI, Mandiri, CIMB, BCA, and other partner banks. You can add the bank name as bins value.
Online Installment is the type of payment where Card Issuing Bank used for making an installment payment and the Acquiring Bank are the same. For example, a customer makes an installment payment using BNI Card and the Acquiring Bank is also BNI.
For online installments, the bank will issue special MID for installment. This installment MID is used to automatically convert the transaction into installments. To activate the installment feature, you are required to have agreement with the bank. Please consult Midtrans Activation Team for installment MID. If MID is ready, merchant simply needs to add installment_term and bank parameter.
The JSON parameter added in the Request Body of a Charge API Request to allow Online Installment, is shown below.
{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 120000
},
"credit_card": {
"token_id": "<token_id from Get Card Token Step>",
"authentication": true,
"bank": "bni",
"installment_term": 3
}
}The JSON attribute installment_term & bank, included in the sample Charge API Request is shown below.
curl -X POST \
https://api.sandbox.midtrans.com/v2/charge \
-H 'Accept: application/json'\
-H 'Authorization: Basic <YOUR SERVER KEY ENCODED in Base64>' \
-H 'Content-Type: application/json' \
-d '{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 120000
},
"credit_card": {
"token_id": "<token_id from Get Card Token Step>",
"authentication": true,
"bank": "bni",
"installment_term": 3
}
}'POST Body JSON Attribute Description
| Parameter | Description | Type |
|---|---|---|
| token_id | Represents customer's credit card information acquired from Get Card Token Response. | String |
| authentication | Flag to enable the 3DS authentication. | Boolean |
| bank | The name of the Card Issuing Bank or Acquiring Bank. Else, it will be treated as Offline Installment. |
String |
| installment_term | The tenor of installment. | Integer |
Offline Installment is the type of payment where Card Issuing Bank used for making an installment payment and the Acquiring Bank need not be the same. For example, a customer makes an installment payment using BNI Card and the Acquiring Bank is Mandiri.
To allow installment feature with banks which do not issue Installment MID, merchant can use offline installment feature. With offline installment feature, the transaction will initially be charged in full amount and will be converted into installment later. To activate the installment feature, you are required to have agreement with the bank. Please consult Midtrans Activation Team for installment MID.
You have to add the installment parameter with combination of bins filter feature. The purpose of BIN filter is to allow only certain acceptable cards to proceed with offline installment payment, based on the agreement between you and issuing banks.
Usually you will also need to add bank parameter to specify which card acquirer bank should be used for the offline installment payment.
The JSON parameters added in the Request Body of a Charge API Request to allow Offline Installment, are shown below.
{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 120000
},
"credit_card": {
"token_id": "<token_id from Get Card Token Step>",
"authentication": true,
"installment_term": 12,
"bins": ["48111111", "3111", "5"],
"bank": "mandiri"
}
}The JSON attribute installment with bins filter feature included in the Charge API Request, are shown below. The purpose of bins filter is to limit certain cards from being allowed to do offline installment, based on the agreement between you and issuing banks.
curl -X POST \
https://api.sandbox.midtrans.com/v2/charge \
-H 'Accept: application/json'\
-H 'Authorization: Basic <YOUR SERVER KEY ENCODED in Base64>' \
-H 'Content-Type: application/json' \
-d '{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 120000
},
"credit_card": {
"token_id": "<token_id from Get Card Token Step>",
"authentication": true,
"installment_term": 12,
"bins": ["48111111", "3111", "5"],
"bank": "mandiri"
}
}'POST Body JSON Attribute Description
| Parameter | Description | Type |
|---|---|---|
| token_id | Represents customer's credit card information acquired from Get Card Token Response. | String |
| authentication | Flag to enable the 3D secure authentication. | Boolean |
| installment_term | The tenor of installment. | Integer |
| bins | List of credit card's BIN (Bank Identification Number) that is allowed for transaction. | Array |
Pre-Authorization payment feature will temporarily block the fund from the customer's account. The fund is not immediately deducted after the transaction. You can initiate "capture" action through Capture API. By default, fund reservation will be released after 7 days if there is no "capture" action for that transaction.
The JSON parameters added in the Request Body of a Charge API Request to pre-authorize a payment, is shown below.
{
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 9000
},
"credit_card": {
"secure": true,
"authentication": true,
"type": "authorize"
}
}The JSON attribute type is included in the sample Charge API Request is shown below.
curl -X POST \
https://api.sandbox.midtrans.com/v2/charge \
-H 'Accept: application/json'\
-H 'Authorization: Basic <YOUR SERVER KEY ENCODED in Base64>' \
-H 'Content-Type: application/json' \
-d '{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 9000
},
"credit_card": {
"token_id": "<token_id from Get Card Token Step>",
"authentication": true,
"type": "authorize"
}
}'POST Body JSON Attribute Description
| Parameter | Type | Description | Note |
|---|---|---|---|
| token_id | String | Represents customer's credit card information acquired from Get Card Token Response. | -- |
| authentication | Boolean | Flag to enable the 3D secure authentication. | -- |
| type | String | Attribute to enable the pre-authorization feature. | Valid value authorize. |
?> This feature is also known as Card Tokenization. Which simply means a method to replace sensitive information value (card credentials) with a token (a placeholder) value, but also allowing it to still be associated with the actual value. Generally to keep sensitive information safely kept within secure environments, but still accessible for authorized parties.
You can allow customer to save their card credentials, for easier and faster future transactions. Two Clicks means there will be additional step which require customer to input CVV (and also conditionally 3DS/OTP process). Which basically means abput two-step away to trigger the payment: input CVV, and then initiate payment.
Midtrans saves the card credentials securely on Midtrans side, and give you the token associated to that card. You need to store and associate each customer with a unique saved_token_id that will be retrieved from the first Charge API Response.
?> Note: This feature requires no additional MID from acquiring bank, this utilize your regular card MID. If you already integrate with regular card payment on Midtrans, then you are eligible to use this feature.
Sequence Diagram
The Two Clicks end-to-end payment process is illustrated in following sequence diagram:
To configure Two Clicks transaction for a customer, follow the steps given below.
The token_id is a representation of customer's card information used for the transaction. The token_id is retrieved using MidtransNew3ds JS library on merchant frontend. Merchant frontend JavaScript securely transmits card information to Midtrans Core API in exchange of the card token_id. This avoids the risk of card information being transmitted to merchant backend.
For more details, refer to Getting the Card Token.
The token_id retrieved is added as an attribute in credit_card object in the Request Body during Charge API Request.
The JSON parameter added in the Request Body of a Charge API Request to allow Two-Click transaction, is shown below.
{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 10000
},
"credit_card": {
"token_id": "<token_id from Get Card Token Step>",
"authentication": true,
"save_token_id": true // <-- To flag that token is saved during First charge response
}
}The JSON attribute save_token_id, included in the sample Charge API Request is shown below.
curl -X POST \
https://api.sandbox.midtrans.com/v2/charge \
-H 'Accept: application/json'\
-H 'Authorization: Basic <YOUR SERVER KEY ENCODED in Base64>' \
-H 'Content-Type: application/json' \
-d '{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 10000
},
"credit_card": {
"token_id": "<token_id from Get Card Token Step>",
"authentication": true,
"save_token_id": true
}
}'The Charge API response includes the redirect_url.
{
"status_code": "201",
"status_message": "Success, Credit Card transaction is successful",
"transaction_id": "47df99ca-f997-41bd-864e-8598ccf2fc27",
"order_id": "Order-123-1578978260",
"redirect_url": "https://api.sandbox.veritrans.co.id/v2/token/rba/redirect/48111111-1114-47df99ca-f997-41bd-864e-8598ccf2fc27",
"merchant_id": "G816197673",
"gross_amount": "10000.00",
"currency": "IDR",
"payment_type": "credit_card",
"transaction_time": "2020-01-14 12:04:20",
"transaction_status": "pending",
"fraud_status": "accept",
"masked_card": "48111111-1114",
"bank": "mandiri",
"card_type": "credit"
}?>Note: The transaction_status is Pending.
To open 3DS authentication page on merchant frontend, display the redirect_url retrieved from Charge API Response for the First Transaction. The redirect URL is displayed using MidtransNew3ds.authenticate or MidtransNew3ds.redirect function in MidtransNew3DS JS library.
When the customer completes the transaction, the Transaction Status changes from Pending to Capture.
For more details, refer to Open 3DS Authenticate Page JS Implementation.
Midtrans notifies the merchant backend with the new transaction status and saved_token_id.
{
"status_code": "200",
"status_message": "Success, Credit Card transaction is successful",
"transaction_id": "0cc39431-4f74-4605-8b6c-4363822fb398",
"order_id": "1578977094",
"merchant_id": "G816197673",
"gross_amount": "200000.00",
"currency": "IDR",
"payment_type": "credit_card",
"transaction_time": "2020-01-14 11:44:55",
"transaction_status": "capture",
"fraud_status": "accept",
"approval_code": "1578977095472",
"eci": "05",
"masked_card": "48111111-1114",
"bank": "mandiri",
"card_type": "credit",
"saved_token_id":"481111xDUgxnnredRMAXuklkvAON1114",
"saved_token_id_expired_at": "2020-12-31 07:00:00",
"channel_response_code": "00",
"channel_response_message": "Approved",
}?>Note: The Transaction Status is updated to Capture.
Store the saved_token_id to your database.
POST Body JSON Attribute Description
| Parameter | Description | Type |
|---|---|---|
| saved_token_id | Token ID of a credit card to be charged for recurring transactions from the customer. | String |
| saved_token_id_expired_at | Expiry date of the Token ID | String |
The saved_token_id from the previous step, is used in this step.
To retrieve card token_id, use MidtransNew3ds.getCardToken function. Implement the following JavaScript on payment page.
// card data from customer input, for example
var cardData = {
"token_id": <saved_token_id from Two Clicks first transaction response>,
"card_cvv": 123,
};
// callback functions
var options = {
onSuccess: function(response){
// Success to get card token_id, implement as you wish here
console.log('Success to get card token_id, response:', response);
var token_id = response.token_id;
console.log('This is the card token_id:', token_id);
},
onFailure: function(response){
// Fail to get card token_id, implement as you wish here
console.log('Fail to get card token_id, response:', response);
}
};
// trigger `getCardToken` function
MidtransNew3ds.getCardToken(cardData, options);?>Note: You need saved_token_id retrieved from database.
For successful transactions,the token_id is received inside onSuccess callback function. It will be used as one of the JSON parameters for Charge API request.
You can allow the customer to save their card credentials, for future transactions. One Click means there will be no additional step like inputting CVV or 3DS/OTP process presented to the customer. Which basically means only need one-step away to trigger the payment. Whether it is initiated by you (as merchant) or the customer.
This adds to a better customer experience. Midtrans saves the card credentials securely on Midtrans side, and give you the token associated to that card. You need to store and associate each customer with a unique saved_token_id that will be retrieved from the first Charge API Response.
?> Note: This feature requires special MID from acquiring bank, this utilize what bank usually call as "recurring MID". Which may means additional business agreement with the acquiring bank, you should consult Midtrans Activation team to activate this feature.
Sequence Diagram
The Recurring/One Click end-to-end payment process can be illustrated in following sequence diagram.
token_id is retrieved from Getting the Card Token. token_id is a representation of customer's card information used for the transaction. Merchant frontend JavaScript securely transmits card information to Midtrans Core API in exchange of card token_id. token_id should be retrieved using MidtransNew3ds JS library. on merchant frontend. This avoids the risk of card information being transmitted to merchant backend.
For more details, refer to Getting the Card Token.
Additional attributes token_id and save_token_id are added in credit_card object in the Request Body during Charge API Request.
The JSON parameters added in the Request Body of a Charge API Request, to enable One Click transaction, is shown below.
{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 10000
},
"credit_card": {
"token_id": "<token_id from Get Card Token Step>",
"authentication": true,
"save_token_id": true // <-- To indicate that token should be saved during first charge
}
}The JSON attribute save_token_id, included in the sample Charge API Request is shown below.
curl -X POST \
https://api.sandbox.midtrans.com/v2/charge \
-H 'Accept: application/json'\
-H 'Authorization: Basic <YOUR SERVER KEY ENCODED in Base64>' \
-H 'Content-Type: application/json' \
-d '{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 9000
},
"credit_card": {
"token_id": "<token_id from Get Card Token Step>",
"authentication": true,
"save_token_id": true
}
}'The sample Charge API response for the first transaction is shown below.
{
"status_code": "201",
"status_message": "Success, Credit Card transaction is successful",
"transaction_id": "47df99ca-f997-41bd-864e-8598ccf2fc27",
"order_id": "Order-123-1578978260",
"redirect_url": "https://api.sandbox.veritrans.co.id/v2/token/rba/redirect/48111111-1114-47df99ca-f997-41bd-864e-8598ccf2fc27",
"merchant_id": "G816197673",
"gross_amount": "10000.00",
"currency": "IDR",
"payment_type": "credit_card",
"transaction_time": "2020-01-14 12:04:20",
"transaction_status": "pending",
"fraud_status": "accept",
"masked_card": "48111111-1114",
"bank": "mandiri",
"card_type": "credit"
}?> Note: The transaction_status is Pending.
The redirect_url received in the response is used in Opening 3DS Authentication Page for the First Transaction.
To open 3DS authentication page on merchant frontend, display the redirect_url retrieved from Charge API response. The redirect URL is displayed using MidtransNew3ds.authenticate or MidtransNew3ds.redirect function in MidtransNew3DS JS library.
For more details, refer to Open 3DS Authentication Page JS Implementation.
?>Note: When the customer completes the transaction on the page, the Transaction Status changes from Pending to Capture.
{
"status_code": "200",
"status_message": "Success, Credit Card transaction is successful",
"transaction_id": "0cc39431-4f74-4605-8b6c-4363822fb398",
"order_id": "1578977094",
"merchant_id": "G816197673",
"gross_amount": "200000.00",
"currency": "IDR",
"payment_type": "credit_card",
"transaction_time": "2020-01-14 11:44:55",
"transaction_status": "capture",
"fraud_status": "accept",
"approval_code": "1578977095472",
"eci": "05",
"masked_card": "48111111-1114",
"bank": "mandiri",
"card_type": "credit",
"saved_token_id":"481111xDUgxnnredRMAXuklkvAON1114",
"saved_token_id_expired_at": "2020-12-31 07:00:00",
"channel_response_code": "00",
"channel_response_message": "Approved"
}Response Body JSON Attribute Description
| Parameter | Description | Type | Note |
|---|---|---|---|
| saved_token_id | Token ID of a credit card to be charged for recurring transactions. | String | -- |
| saved_token_id_expired_at | Expiry date and time of the Token ID. It is in the format YYYY-MM-DD HH:MM:SS | String | -- |
You will receive saved_token_id & saved_token_id_expired_at from the response (it also available in the JSON of HTTP notification). saved_token_id is unique for each customer's card. Store this saved_token_id in your database and associate that card token to your customer.
!> Important: Be sure to store the card's saved_token_id_expired_at. When that date time has been surpassed, the card's saved_token_id will be no longer usable, it means the card is expired. In that case you will need to ask your customer to re-do the card saving process with their re-newed card.
For recurring transactions by the customer, use saved_token_id retrieved previously (or from your database) as the value of token_id attribute, while sending Charge API Request.
The JSON parameters added in the Request Body of a Charge API Request to allow One Click transaction, is shown below.
{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "CustOrder-103",
"gross_amount": 10000
},
"credit_card": {
"token_id": "481111xDUgxnnredRMAXuklkvAON1114" // <-- saved_token_id from One Click first Transaction Response
}
}The JSON attribute token_id included in the sample Charge API Request is shown below.
curl -X POST \
https://api.sandbox.midtrans.com/v2/charge \
-H 'Accept: application/json'\
-H 'Authorization: Basic <YOUR SERVER KEY ENCODED in Base64>' \
-H 'Content-Type: application/json' \
-d '{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "CustOrder-103",
"gross_amount": 10000
},
"credit_card": {
"token_id": "<saved_token_id from One Click First Transaction Response>",
}
}'The Charge API response for recurring transaction on the card is identical with Card Payment Charge Response. Successful One Click transaction is flagged as "transaction_status": "capture" and is ready for settlement.
{
"status_code": "200",
"status_message": "Success, Credit Card transaction is successful",
"transaction_id": "139c7a0f-204e-4c88-9c8c-63348b545b99",
"order_id": "Order-123-1578977940",
"merchant_id": "G816197673",
"gross_amount": "10000.00",
"currency": "IDR",
"payment_type": "credit_card",
"transaction_time": "2020-01-14 11:58:59",
"transaction_status": "capture",
"fraud_status": "accept",
"approval_code": "1578977940108",
"masked_card": "48111111-1114",
"bank": "bni",
"card_type": "credit",
"channel_response_code": "00",
"channel_response_message": "Approved"
}For more use-cases, refer to One Click, Two click and Recurring Transactions.
You can allow the customer to save their card credentials, then it requires no CVV input and 3DS/OTP for future transactions. Midtrans saves the card credentials securely on Midtrans side, and give you the token associated to that card. You need to store and associate each customer with a unique saved_token_id that will be retrieved from Register Card API Response.
?> Note: This feature requires special MID from acquiring bank, this utilize what bank usually call as "recurring MID". Which may means additional business agreement with the acquiring bank, you should consult Midtrans Activation team to activate this feature.
Sequence Diagram
The overall Register Card API end-to-end payment process can be illustrated in following sequence diagram:
To save card credentials on Midtrans and retrieve card's saved_token_id, use MidtransNew3ds.registerCard through MidtransNew3ds JS library. Implement the following JavaScript on the payment page.
// Create the card object with the required fields
var cardData = {
card_number: "4811111111111114",
card_cvv: "123",
card_exp_month: "12",
card_exp_year: "2025"
};
var options = {
onSuccess: function(response) {
// Implement success handling here, save the `saved_token_id` to your database
console.log('Saved Token ID:',response.saved_token_id);
},
onFailure: function(response) {
// Implement error handling here
console.log('Fail to get saved card token',response.status_message);
}
}
MidtransNew3ds.registerCard(cardData, options);Frontend implementation via JS is used to ensure card credentials is securely passed from customer browser directly to Midtrans API.
Alternative: via API Request
Alternatively via API request. You should not pass card credentials from your backend unless you are authorized to do so, or PCI/DSS certified. To avoid security risks.
| Method | API Endpoint |
|---|---|
| GET | https://api.sandbox.midtrans.com/v2/card/register |
| Parameter | Description | Type | Note |
|---|---|---|---|
| card_number | The card number of the customer. | String | -- |
| card_exp_month | The month of expiry on the card. | String | It is in MM format |
| card_exp_year | The year of expiry on the card. | String | It is in YYYY format. |
| client_key | Your Client Key. | String | It can be retrieved from your MAP account. |
Sample Register API request is given below.
curl -X GET \
'https://api.sandbox.midtrans.com/v2/card/register?card_number=5211111111111117&card_exp_month=12&card_exp_year=2021&client_key=<YOUR CLIENT KEY HERE>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'Sample Register API response is given below.
{
"status_code": "200",
"saved_token_id": "521111nHlLvTuKywNOOLhTlHZcab1117",
"transaction_id": "cbd3ff55-2ead-43e9-84c5-5c3b7a8a1814",
"masked_card": "52111111-1117"
}Store saved_token_id received in the response body, to your database.
Using saved_token_id from step above, the token_id is retrieved using MidtransNew3ds.getCardToken through MidtransNew3ds JS library. Implement the following JavaScript on the payment page.
// card data from customer input, for example
var cardData = {
"token_id": <saved_token_id from Register Card API Response Step>,
"card_cvv": 123,
};
// callback functions
var options = {
onSuccess: function(response){
// Success to get card token_id, implement as you wish here
console.log('Success to get card token_id, response:', response);
var token_id = response.token_id;
console.log('This is the card token_id:', token_id);
},
onFailure: function(response){
// Fail to get card token_id, implement as you wish here
console.log('Fail to get card token_id, response:', response);
}
};
// trigger `getCardToken` function
MidtransNew3ds.getCardToken(cardData, options);For successful transactions, token_id is received inside onSuccess callback function. It is used as one of the JSON parameters for Charge API request.
Charge API request is sent from merchant backend to acquire redirect_url, required to open 3DS authentication page.
The JSON parameters added in the Request Body of a Charge API Request are shown below.
{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "order102",
"gross_amount": 789000
},
"credit_card": {
"token_id": "<token_id from Get Card Token Step>",
"authentication": true,
}
}curl -X POST \
https://api.sandbox.midtrans.com/v2/charge \
-H 'Accept: application/json'\
-H 'Authorization: Basic <YOUR SERVER KEY ENCODED in Base64>' \
-H 'Content-Type: application/json' \
-d '{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "order102",
"gross_amount": 789000
},
"credit_card": {
"token_id": "<token_id from Get Card Token Step>",
"authentication": true,
}
}'The parameters that are required for the API Charge request are given below.
| Requirement | Description |
|---|---|
| Server Key | The server key. For more details, refer to Retrieving API Access Keys. |
order_id |
The order_id of the transaction. |
gross_amount |
The total amount of transaction. |
token_id |
Represents customer's card information acquired from Getting Card Token for the first transaction. |
authentication |
Flag to enable the 3D secure authentication. |
To open 3DS authentication page on merchant frontend, display the redirect_url retrieved from Charge API response. The redirect URL is displayed using MidtransNew3ds.authenticate or MidtransNew3ds.redirect function in MidtransNew3DS JS library.
For more details, refer to Open 3DS Authentication Page JS Implementation.
For any future transaction using the same card credentials, retrieve saved_token_id saved on the database from Registering the Card step.
The JSON parameters added in the Request Body of a Charge API Request is shown below.
{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 10000
},
"credit_card": {
"token_id": "<saved_token_id from Get Card Token Step>"
}
}The JSON attribute token_id, included in the Charge API Request is shown below.
curl -X POST \
https://api.sandbox.midtrans.com/v2/charge \
-H 'Accept: application/json'\
-H 'Authorization: Basic <YOUR SERVER KEY ENCODED in Base64>' \
-H 'Content-Type: application/json' \
-d '{
"payment_type": "credit_card",
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 10000
},
"credit_card": {
"token_id": "<token_id from Get Card Token Step>"
}
}'Note that the One Click feature mentioned above is relying on your system/backend to schedule and trigger the recurring charges. Additionally, Midtrans also support automatically charge recurring for you based on your specified schedule. Which is described on this section.
Follow the same implementation as mentioned above, to the point your system retrieved the saved_token_id. Then you can proceed with Core API's Recurring API feature here. To specify the schedule of when Midtrans should charge recurringly to your customer.
?> Note: This feature requires special MID from acquiring bank, this utilize what bank usually call as "recurring MID". Which may means additional business agreement with the acquiring bank, you should consult Midtrans Activation team to activate this feature.
After completing payment using GoPay payment method, by default, the customer will remain on Gojek app. They need to manually close Gojek app to switch back to merchant website or application. gopay.callback_url parameter will allow customers to be automatically redirected from the Gojek app to the merchant website/application.
The JSON parameters added in the Request Body of a Charge API Request, to redirect the customer is shown below.
{
"payment_type": "gopay",
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 9000
},
"gopay": {
"enable_callback": true,
"callback_url": "https://tokoecommerce.com/gopay_finish"
}
}The JSON attribute callback_url included in the sample Charge API Request is shown below.
curl -X POST \
https://api.sandbox.midtrans.com/v2/charge \
-H 'Accept: application/json'\
-H 'Authorization: Basic U0ItTWlkLXNlcnZlci1UT3ExYTJBVnVpeWhoT2p2ZnMzVV7LZU87' \
-H 'Content-Type: application/json' \
-d '{
"transaction_details": {
"order_id": "CustOrder-102",
"gross_amount": 9000
},
"gopay": {
"enable_callback": true,
"callback_url": "https://tokoecommerce.com/gopay_finish"
}
}'POST Body JSON Attribute Description
| Parameter | Description | Type | Values |
|---|---|---|---|
| enable_callback | Flag to enable or disable callback_url | Boolean | true to enable.false to disable. |
| callback_url | The URL to which the customer is redirected | String | Use http/https URL protocol for websites, or Deeplink protocol for mobile applications. |
The final redirect URL will be appended with query parameter like ?order_id=xxx&result=xxx. For example the final redirect URL might look like this:
https://tokoecommerce.com/gopay_finish/?order_id=CustOrder-102123123&
result=success
| Query Parameter | Description | Type |
|---|---|---|
| order_id | Order ID sent on the Charge Request. | String |
| result | Result of the transaction to decide what kind of page to show to customer. Possible values: success or failure. |
String |
?> Note: You may use the information to display custom message to your customer on your finish URL.
Core API support linking customer's GoPay account to your web/app/business, to allow charging customer in recurring or subscription manner. Follow the documentation of GoPay Recurring via Tokenization here.
Requires additional agreement & approval. Consult Midtrans Activation team to have this feature activated for your merchant account.
Midtrans creates random VA number for transactions using Bank Transfer payment method. In some cases, you can customize the VA number. You can do that with the following parameters.
The JSON parameters added in the Request Body of a Charge API Request, are shown below.
...
"bank_transfer":{
"bank": "bca",
"va_number": "111111",
"free_text": {
"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" // NOTE: Don't send this field unless BCA give you sub company code
}
}
...POST Body JSON Attribute Description
| Parameter | Description | Type | Note |
|---|---|---|---|
| bank | The name of the bank which processes the transaction. | String (255) | -- |
| va_number | Custom VA number assigned by you. | String | Minimum Length: 1 Maximum length: 11 |
| inquiry | Texts to be displayed on ATM when the customer attempts to enquire the VA number. | Array (10) | -- |
| Id | Text message in Bahasa Indonesia. | String (50) | -- |
| En | Text message in English. | String (50) | -- |
| payment | Texts to be displayed on ATM when the customer attempts to make payments. | Array (10) | -- |
| sub_company_code | BCA sub company code directed for this transactions. NOTE: Don't send this field unless BCA give you sub company code | String | Default value is 00000. |
The JSON parameters added in the Request Body of Charge API Request, are shown below.
...
"bank_transfer":{
"bank": "bni",
"va_number": "111111"
}
...POST Body JSON Attribute Description
| Parameter | Description | Type | Note |
|---|---|---|---|
| bank | The name of the bank which processes the transaction using Bank Transfer payment method. | String (255) | -- |
| va_number | Custom VA number assigned by merchant. | String (255) | Minimum length:1 Maximum length:8 |
The JSON parameters added in the Request Body of Charge API Request, are shown below.
...
"echannel": {
"bill_info1": "Payment For:",
"bill_info2": "Tuition fee",
"bill_info3": "Name:",
"bill_info4": "Budi Utomo",
"bill_info5": "Class:",
"bill_info6": "Computer Science",
"bill_info7": "ID:",
"bill_info8": "VT-12345",
"bill_key": "081211111111"
}
...POST Body JSON Attribute Description
| Parameter | Description | Type | Note |
|---|---|---|---|
| bill_info1 | Label 1 | String | Maximum length: 10. Exceeding characters will be truncated. |
| bill_info2 | Value for Label 1 | String | Maximum length: 30 Exceeding characters will be truncated. |
| bill_info3 | Label 2 | String | Maximum length: 10 Exceeding characters will be truncated. |
| bill_info4 | Value for Label 2 | String | Maximum length: 30 Exceeding characters will be truncated. |
| bill_info5 | Label 3 | String | Maximum length: 10 Exceeding characters will be truncated. |
| bill_info6 | Value for Label 3 | String | Maximum length: 30 Exceeding characters will be truncated. |
| bill_info7 | Label 4 | String | Maximum length: 10 Exceeding characters will be truncated. |
| bill_info8 | Value for Label 4 | String | Maximum length: 30 Exceeding characters will be truncated. |
| bill_key | Custom bill key assigned by you | String | Maximum length: 12 If longer than maximum then Midtrans will trim the remaining least significant bits. |
The JSON parameters added in the Request Body of a Charge API Request, are shown below.
...
"bank_transfer":{
"bank": "permata",
"va_number": "0123456789",
"permata": {
"recipient_name": "SUDARSONO"
}
}
...POST Body JSON Attribute Description
| Parameter | Description | Type | Note |
|---|---|---|---|
| bank | The name of the bank which processes the Bank Transfer transaction. | String (255) | -- |
| va_number | Custom VA number assigned by the merchant. | String (10) | Length should be equal to 10. Only supported for B2B VA type. |
| recipient_name | The name of the recipient shown in the payment details. |
String (20) | Default value is your name. |
Virtual Account number displayed to customer contains two parts; the company-prefix-number and the second part is a unique-va-number. The table given below, explains this with an example.
| Virtual Account Number | Company Number | Unique VA Number |
|---|---|---|
{91012}{12435678} |
{91012} |
{12435678} |
The unique code can be customized.
Rules for customizing Virtual Account number is given below.
- Only digits are allowed.
- Different banks have different specifications for their custom VA numbers. Please go through the documentation of the respective banks. Note: for Permata, only B2B VA type support custom VA numbers, so by default your sandbox account may not support Permata custom VA, please contact us if you wish to have this feature.
- If the number provided is currently active for another order, then a different unique number will be used instead.
- If the number provided is longer than required, then the unnecessary digits in the end will be trimmed.
- If the number provided is shorter than required, then the number will be prefixed with zeros.
?>Note: In Production environment, not every bank may support custom VA number (e.g. Permata) as the default state. It depends on the type of VA configured for your merchant account & your business agreement with the bank. Please consult Midtrans Activation team for further information.
There are a few limitations to consider while using Midtrans API. These limitations are given below.
Midtrans API allows a maximum size of 16kb or 16000 total characters per request. Please try to keep it under the limit to avoid request failures.
?>Tips: Limit the number of item_details from your request, or group it into fewer item_details.
For regular card transactions, the token_id (for non-recurring, non-one-click, non-two-click token) and the 3DS redirect_url expires in 10 minutes.
For security reasons, it is designed to generate a unique token_id for each transaction. Please make sure to complete the card transaction within the time limit to avoid expired token_id.