Get Token

Token ID is a unique value that is associated with the customer’s credit card information during a transaction. The GET Token method sends the credit card information via Midtrans.min.js to Midtrans server and returns the Token ID to you.

To utilize Midtrans JavaScript library, add the code given below in your payment page inside the <head> tag.


<script id= "midtrans-script" src="https://api.midtrans.com/v2/assets/js/midtrans-new-3ds.min.js" data-environment="<production|sandbox>" data-client-key="<INSERT CLIENT KEY HERE>" type="text/javascript"></script>

📘

Note

The GET Token method and its features are applicable only for card transactions. Read more here for API references on various card features to be used in conjuction with this guide.



Midtrans JavaScript Library

Midtrans JavaScript library consists of two functions as given below.

  1. Get Card Token: Securely sends the customer’s payment card details to Midtrans server, without the merchant handling the credit card details.
  2. Redirect: Redirects the customer to 3DS authentication page.

❗️

Secure token only support 3DS 1.0, need to implement 3DS 2.0 refer Card Feature: 3D Secure (3DS)

3D Secure 2.0 is an authentication protocol that aims to reduce fraud and enhance security in online card payments.

AttributeDescription
data-environmentThe environment which the request is pointing to. Possible values are production and sandbox.
data-client-keyYour Client key. For more details, refer Retrieving API Access Keys.

❗️

8 Digit Bin

With the oncoming mandates from Visa and other principals, Midtrans will start supporting 8-digit BIN's for card transaction processing flows.
The 8-digit bin changes on CoreAPI and will impact the length of token_id and format of saved_token_id.

Changes list:

  1. Change on token_id length from 6 first digit + "-" + 4 last digit + "-" + 36 random digit into 8 first digit + "-" + 4 last digit + "-" + 36 random digit (e.g: 481111-1114-7baba36c-5698-47cf-9170-80efd6a2e973 to 48111111-1114-7baba36c-5698-47cf-9170-80efd6a2e973)
  2. Change on saved_token_id length from 6 first digit + 22 random digit + 4 last digit into 8 first digit + 20 random digit + 4 last digit (e.g: 481111sHdcfSakAvHvFQFEjTivUV1114 to 48111111sHfSakAvHvFQFEjTivUV1114)
  3. Masked_card on response, event, log changed from 6 first digit + 4 last digit from card number into 8 first digit + 4 last digit from a card number
  4. Support 8 Digit bin in Midtrans Fraud Detection System (for Aegis's users)
  5. Support 8 digit bin in Bin API


Getting Card Token

GET Card Token Request

The card object attributes are given below. Depending on the token type, some parameters are conditional.

// Create the card object with the required fields
var card = {
  card_number: "4811111111111114",
  card_cvv: "123",
  card_exp_month: "12",
  card_exp_year: "2025"
}

var options = {
  onSuccess: function(response) {
      // Implement success handling here
  },
  onFailure: function(response) {
      // Implement error handling here
  }
}

MidtransNew3ds.getCardToken(card, options);
JSON AttributeDescriptionNormalTwo ClicksRemarks
card_numberThe 16 digits Credit Card number.RequiredConditionalSpace( ) is allowed.
For example, 4111 1111 1111 1111 or 4111111111111111 both are valid.
card_cvvThe CVV number printed on the card.RequiredRequiredFor example, 123.
card_exp_monthThe card expiry month in MM format.RequiredConditionalFor example, 12.
card_exp_yearThe card expiry year in YYYY format.RequiredConditionalFor example, 2022.
token_idThe token ID of credit card saved previously. Its value is same as the saved_token_id retrieved from initial Charge response.ConditionalRequiredFor example, 48111111sHfSakAvHvFQFEjTivUV1114.

GET Card Token Response

Callback response object attributes are listed below.

JSON AttributeDescriptionRemarks
status_codeStatus code of transaction charge result."200" for success, "400" when validation error.
status_messageStatus message describing the result of the API request."OK, success request new token".
validation_messagesThe message describing the error.“card_exp_year must be greater than this year”, "card_exp_month must be greater than this year's month”.
token_idThe token id of the card."48111111-1114-d3d690db-3e18-4edd-9fee-4d061e4eb6f3"
Note: token_id is required during Card Payment Charge Transaction.
hashProduced from one-way hashing of the given card number. This value is irreversible and will always be consistent for each card number."6d9df2ff-ae9c-3cee-a5ff-a063dc476077"

Available options are given below.

NameDescription
onSuccessThis function is called only when get token responds with status code 200.
onFailureThis function is called for all the other status codes except 200.


Redirecting to 3DS Page (3DS 2.0 Compatible)

After proceeding card transaction to Charge API request, if the transaction needs 3DS authentication, you will receive redirect_url in the response. You can optionally use built-in MidtransNew3ds.redirect function to redirect the customer.

After 3DS process is completed, the customer is redirected back to the website specified in callbackUrl or the Finish Redirect URL configured on your MAP account.
This final redirect is HTTP POST method. It contains JSON string encapsulated as value of response key of the POST form-data.

Callback response object attributes are listed below.

var options = {
    // In case, Merchant needs to override for each transactions
    callbackUrl = "<ANY LINK>"
}

MidtransNew3ds.redirect(redirect_url, options);
<form id="veritrans" method="post" action="<callbackUrl>">
    <input type="hidden" name="response" value="<JSON FORMAT CALLBACK OBJECT>"/>
</form>
JSON AttributeDescriptionType
transaction_idTransaction ID given by Midtrans.String
order_idOrder ID specified by you.String
gross_amountTotal amount of transaction in IDR.String
payment_typeThe payment method used by the customer.String
transaction_timeTimestamp of transaction in ISO 8601 format. Time Zone: GMT+7.String
transaction_statusTransaction status after charge credit card transaction. Possible values are
capture : Transaction is accepted by the bank and ready for settlement.
deny: transaction is denied by the bank or FDS.
authorize: Credit card is authorized in pre-authorization feature.
pending: Credit card is pending and you will need to rely on the http notification webhook to receive the final transaction status..
String
fraud_statusDetection result by Fraud Detection System (FDS). Possible values are
accept : Approved by FDS.
challenge: Questioned by FDS. Note: Approve transaction to accept it or transaction gets automatically canceled during settlement.
deny: Denied by FDS. Transaction automatically failed.
String
masked_cardFirst 8-digits and last 4-digits of customer's credit card number.String
status_codeStatus code of transaction charge result.String
bankThe name of the acquiring bank.String
status_messageStatus message describing the result of the API request.String
approval_codeApproval code. It can be used for refund. This does not exist on denied transaction.String
eciThe 3D secure ECI Code.String
channel_response_codeResponse code from payment channel provider.String
channel_response_messageResponse message from payment channel provider.String
currencyISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.
String
card_typeType of card used for the transaction. Possible values are credit, debit.String
three_ds_version3DS Version that used for transaction (This field only present for 3DS Transaction). Possible values are 1, 2String
three_ds_challenge_completion3DS Challenge completion state to indicate the customer has submit the OTP or not(it doesn't matter if the OTP is valid or not). Possible values are true, falseBoolean

📘

Note

If you receive pending transaction_status, you will need to rely on the http notification webhook to receive the final transaction status


Optional parameter is given below.

NameDescriptionRequired
callbackUrlTo override where the customer gets redirected after 3DS authentication is done.Optional


Opening 3DS Page via iFrame (3DS 2.0 Compatible)

Optionally, you can use MidtransNew3ds.performAuthentication function to open redirect_url as iFrame. It is a substitute to the redirection scheme.

After 3DS process is completed by a customer, your website receives JSONP callback containing the transaction result.

Callback response object attributes are listed below.

// Open 3DSecure dialog box
function openDialog(url) {
    // make sure to load fancybox in a script tag
    $.fancybox.open({
        href: url,
        type: 'iframe',
        autoSize: false,
        width: 400,
        height: 420,
        closeBtn: false,
        modal: true
    });
}

// Close 3DSecure dialog box
function closeDialog() {
    $.fancybox.close()
}

var options = {
  performAuthentication: function(url) {
    openDialog(url)
  },
  onSuccess: function(response) {
    // Successful handling
    closeDialog()
  },
  onPending: function(response) {
    // Pending handling
    closeDialog()
  },
  onFailure: function(response) {
    // Failure handling
    closeDialog()
  }
}

MidtransNew3ds.authenticate(redirect_url,options)
JSON AttributeDescriptionType
transaction_idTransaction ID given by Midtrans.String
order_idOrder ID specified by you.String
gross_amountTotal amount of transaction in IDR.String
payment_typeThe payment method used by the customer.String
transaction_timeTimestamp of transaction in ISO 8601 format. Time Zone: GMT+7.String
transaction_statusTransaction status after charge credit card transaction. Possible values are
capture : Transaction is accepted by the bank and ready for settlement.
deny: transaction is denied by the bank or FDS.
authorize: Credit card is authorized in pre-authorization feature.
pending: Credit card is pending and you will need to rely on the http notification webhook to receive the final transaction status.
String
fraud_statusDetection result by Fraud Detection System (FDS). Possible values are
accept : Approved by FDS.
challenge: Questioned by FDS. Note: Approve transaction to accept it or transaction gets automatically canceled during settlement.
deny: Denied by FDS. Transaction automatically failed.
String
masked_cardFirst 8-digits and last 4-digits of customer's credit card number.String
status_codeStatus code of transaction charge result.String
bankThe acquiring bank of the transaction.String
status_messageDescription of transaction charge result.String
approval_codeApproval code. It can be used for refund. This does not exist on denied transaction.String
eciThe 3D secure ECI Code.String
channel_response_codeResponse code from payment channel provider.String
channel_response_messageResponse message from payment channel provider.String
currencyISO-4217 representation of three-letter alphabetic currency code. Value: IDR.
Note: Currently only IDR is supported.
String
card_typeType of card used for the transaction. Possible values are credit, debit.String
three_ds_version3DS Version that used for transaction (This field only present for 3DS Transaction). Possible values are 1, 2String

📘

Note

If you receive pending transaction_status, you will need to rely on the http notification webhook to receive the final transaction status


Available options are given below.

NameDescription
performAuthenticationImplementation to open redirect URL in iFrame.
onSuccessHandle to receive successful callback response.
onPendingHandle to receive callback response. Only applicable when merchant applied for async endpoint.
onFailureHandle to receive failure response.
Language
Click Try It! to start a request and see the response here!