Advanced Features

Core API has various optional parameters that can be utilized to integrate with more advanced use cases.

General


Recommended Parameters


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.

{
  "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"
    }
  }
}
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
email 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
email 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


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.

...
  "custom_expiry": {
      "order_time": "2016-12-07 11:54:12 +0700",
      "expiry_duration": 60,
      "unit": "minute"
  }
...
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
ParameterDescriptionTypeNote
order_timeThe 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_durationThe duration for which the transaction is valid.String (50)--
unitThe unit of expiry_duration.String (50)Valid values are second, minute, hour or day.
Default value is minute.

Custom Fields


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.

...
  "custom_field1": "this is custom text defined by merchant",
  "custom_field2": "order come from web",
  "custom_field3": "customer selected blue color variant"
...
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
ParameterDescriptionType
custom_field1You can write custom details about the transaction.String (255)
custom_field2You can write custom details about the transaction.String (255)
custom_field3You can write custom details about the transaction.String (255)

Metadata


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.

...
  "metadata": {
	"you": "can",
	"put": "any",
	"parameter": "you like"
   }
...
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
ParameterDescriptionType
metadataObject containing the metadata parametersObject


Credit Card


3 Domain Secure (3DS)


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 your Midtrans's Sales PIC or Support team to allow disabling 3DS.

...
  "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 '{
  "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
ParameterDescriptionTypeValues
authenticationFlag to enable the 3DS authentication.Booleantrue to enable 3DS.
false to disable 3DS.

Routing Transactions to Specific Acquiring Bank


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.

{
  "transaction_details": {
    "order_id": "CustOrder-102",
    "gross_amount": 9000
  },
  "credit_card": {
    "token_id": "<token_id from Get Card Token Step>",
    "authentication": true,
	"bank": "bca"
  }
}
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
ParameterDescriptionTypeValues
bankName of the preferred Acquiring Bank.Stringmandiri, bni, cimb, bca, maybank, bri or mega.

BIN (Bank Identification Number) Filter


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.

{
  "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"]
  }
}
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.


Installment Payment


Online Installment

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.

{
  "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
  }
}
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
ParameterDescriptionType
token_idRepresents customer's credit card information acquired from Get Card Token Response.String
authenticationFlag to enable the 3DS authentication.Boolean
bankThe name of the Card Issuing Bank or Acquiring Bank.
Else, it will be treated as Offline Installment.
String
installment_termThe tenor of installment.Integer

Offline Installment

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 your Midtrans Sales PIC or Support 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.

{
  "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"
  }
}
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
ParameterDescriptionType
token_idRepresents customer's credit card information acquired from Get Card Token Response.String
authenticationFlag to enable the 3D secure authentication.Boolean
installment_termThe tenor of installment.Integer
binsList of credit card's BIN (Bank Identification Number) that is allowed for transaction.Array

Pre-Authorization Payment


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.

{
  "transaction_details": {
    "order_id": "CustOrder-102",
    "gross_amount": 9000
  },
  "credit_card": {
    "secure": true,
    "authentication": true,
    "type": "authorize"
  }
}
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
ParameterTypeDescriptionNote
token_idStringRepresents customer's credit card information acquired from Get Card Token Response.--
authenticationBooleanFlag to enable the 3D secure authentication.--
typeStringAttribute to enable the pre-authorization feature.Valid value authorize.


Credit Card - Save Card (Tokenization)

📘

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.


Two Clicks Transaction


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.


Retrieving the token_id

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.


Charge API Request for the First Transaction

The token_id retrieved is added as an attribute in credit_card object in the Request Body during Charge API Request.

{
  "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
  }
}
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
  }
}'
{
    "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 for First Transaction

The transaction_status is Pending.


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 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
ParameterDescriptionType
saved_token_idToken ID of a credit card to be charged for recurring transactions from the customer.String
saved_token_id_expired_atExpiry date of the Token IDString

Getting Card Token For Future Transactions

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.


Recurring/One Click Transaction

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.


Retrieving the token_id

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.


Charge API Request for first transaction

Additional attributes token_id and save_token_id are added in credit_card object in the Request Body during Charge API Request.

{
  "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
  }
}
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
  }
}'
{
    "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.


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.

Success Callback & HTTP Notification of First Transaction

{
  "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
ParameterDescriptionTypeNote
saved_token_idToken ID of a credit card to be charged for recurring transactions.String--
saved_token_id_expired_atExpiry date and time of the Token ID. It is in the format YYYY-MM-DD HH:MM:SSString--

You will receive saved_token_id & saved_token_id_expired_at from the response (also in the HTTP notification's JSON Body ). 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


Charge API Request for Recurring Transactions

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.

{
  "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
  }
}
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>",
  }
}'

Charge API Response and Notifications for Recurring Transactions

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.


Recurring Transaction with Register Card API


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:


Register Card via MidtransNew3ds JS


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.


Register API Request Details

MethodAPI Endpoint
GEThttps://api.sandbox.midtrans.com/v2/card/register

Query Parameters

ParameterDescriptionTypeNote
card_numberThe card number of the customer.String--
card_exp_monthThe month of expiry on the card.StringIt is in MM format
card_exp_yearThe year of expiry on the card.StringIt is in YYYY format.
client_keyYour Client Key.StringIt can be retrieved from your MAP account.

Sample Request and Response

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'
"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.


Getting Card Token for the First Transaction

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.


Sending Transaction Data to Charge API for the First Transaction

Charge API request is sent from merchant backend to acquire redirect_url, required to open 3DS authentication page.

{
  "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.

RequirementDescription
Server KeyThe server key. For more details, refer to Retrieving API Access Keys.
order_idThe order_id of the transaction.
gross_amountThe total amount of transaction.
token_idRepresents customer's card information acquired from Getting Card Token for the first transaction.
authenticationFlag to enable the 3D secure authentication.

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.


Charge API Request for Future Transactions

For any future transaction using the same card credentials, retrieve saved_token_id saved on the database from Registering the Card step.

{
  "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>"
  }
}
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>"
  }
}'

Recurring Transaction with Subscriptions API


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.



Credit Card - Full PAN


Please see Credit Card - Full PAN API Reference.



GoPay


Redirecting Customer from the Gojek App


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.

{
  "payment_type": "gopay",
  "transaction_details": {
    "order_id": "CustOrder-102",
    "gross_amount": 9000
  },
  "gopay": {
    "enable_callback": true,
    "callback_url": "https://tokoecommerce.com/gopay_finish"
  }
}
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
ParameterDescriptionTypeValues
enable_callbackFlag to enable or disable callback_urlBooleantrue to enable.
false to disable.
callback_urlThe URL to which the customer is redirectedStringUse 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 ParameterDescriptionType
order_idOrder ID sent on the Charge Request.String
resultResult 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.


GoPay Recurring/Subscription


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.



Bank Transfer/VA


Specifying Custom VA Number and VA Description


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.

JSON Parameters in Request Body

...
   "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
     }
   }
...
...
  "bank_transfer":{
     "bank": "bni",
     "va_number": "111111"
  }
...
...
  "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"
}
...
...
	"bank_transfer":{
	  "bank": "permata",
	  "va_number": "0123456789",
	  "permata": {
	    "recipient_name": "SUDARSONO"
	  }
	}
...
POST Body JSON Attribute Description for BCA
ParameterDescriptionTypeNote
bankThe name of the bank which processes the transaction.String (255)--
va_numberCustom VA number assigned by you.StringMinimum Length: 1
Maximum length: 11
inquiryTexts to be displayed on ATM when the customer attempts to enquire the VA number.Array (10)--
IdText message in Bahasa Indonesia.String (50)--
EnText message in English.String (50)--
paymentTexts to be displayed on ATM when the customer attempts to make payments.Array (10)--
sub_company_codeBCA sub company code directed for this transactions. NOTE: Don't send this field unless BCA give you sub company codeStringDefault value is 00000.
POST Body JSON Attribute Description for BNI
ParameterDescriptionTypeNote
bankThe name of the bank which processes the transaction using Bank Transfer payment method.String (255)--
va_numberCustom VA number assigned by merchant.String (255)Minimum length:1
Maximum length:8
POST Body JSON Attribute Description for Mandiri Bill
ParameterDescriptionTypeNote
bill_info1Label 1StringMaximum length: 10.
Exceeding characters will be truncated.
bill_info2Value for Label 1StringMaximum length: 30
Exceeding characters will be truncated.
bill_info3Label 2StringMaximum length: 10
Exceeding characters will be truncated.
bill_info4Value for Label 2StringMaximum length: 30
Exceeding characters will be truncated.
bill_info5Label 3StringMaximum length: 10
Exceeding characters will be truncated.
bill_info6Value for Label 3StringMaximum length: 30
Exceeding characters will be truncated.
bill_info7Label 4StringMaximum length: 10
Exceeding characters will be truncated.
bill_info8Value for Label 4StringMaximum length: 30
Exceeding characters will be truncated.
bill_keyCustom bill key assigned by youStringMaximum length: 12
If longer than maximum then Midtrans will trim the remaining least significant bits.
POST Body JSON Attribute Description
ParameterDescriptionTypeNote
bankThe name of the bank which processes the Bank Transfer transaction.String (255)--
va_numberCustom VA number assigned by the merchant.String (10)Length should be equal to 10.
Only supported for B2B VA type.
recipient_nameThe 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 NumberCompany NumberUnique 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.



Consideration and Limitations

There are a few limitations to consider while using Midtrans API. These limitations are given below.


Maximum Request Size Limit


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.


Card Token ID Expiry Time


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.