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.
- Get Card Token: Securely sends the customer’s payment card details to Midtrans server, without the merchant handling the credit card details.
- 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.
| Attribute | Description |
|---|---|
| data-environment | The environment which the request is pointing to. Possible values are production and sandbox. |
| data-client-key | Your 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:
- Change on token_id length from
6 first digit + "-" + 4 last digit + "-" + 36 random digitinto 8first digit + "-" + 4 last digit + "-" + 36 random digit(e.g:481111-1114-7baba36c-5698-47cf-9170-80efd6a2e973to48111111-1114-7baba36c-5698-47cf-9170-80efd6a2e973) - Change on saved_token_id length from
6 first digit + 22 random digit + 4 last digitinto8 first digit + 20 random digit + 4 last digit(e.g:481111sHdcfSakAvHvFQFEjTivUV1114to48111111sHfSakAvHvFQFEjTivUV1114) - Masked_card on response, event, log changed from
6 first digit + 4 last digit from card numberinto8 first digit + 4 last digitfrom a card number - Support 8 Digit bin in Midtrans Fraud Detection System (for Aegis's users)
- 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 Attribute | Description | Normal | Two Clicks | Remarks |
|---|---|---|---|---|
| card_number | The 16 digits Credit Card number. | Required | Conditional | Space( ) is allowed. For example, 4111 1111 1111 1111 or 4111111111111111 both are valid. |
| card_cvv | The CVV number printed on the card. | Required | Required | For example, 123. |
| card_exp_month | The card expiry month in MM format. | Required | Conditional | For example, 12. |
| card_exp_year | The card expiry year in YYYY format. | Required | Conditional | For example, 2022. |
| token_id | The token ID of credit card saved previously. Its value is same as the saved_token_id retrieved from initial Charge response. | Conditional | Required | For example, 48111111sHfSakAvHvFQFEjTivUV1114. |
GET Card Token Response
Callback response object attributes are listed below.
| JSON Attribute | Description | Remarks |
|---|---|---|
| status_code | Status code of transaction charge result. | "200" for success, "400" when validation error. |
| status_message | Status message describing the result of the API request. | "OK, success request new token". |
| validation_messages | The 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_id | The token id of the card. | "48111111-1114-d3d690db-3e18-4edd-9fee-4d061e4eb6f3" Note: token_id is required during Card Payment Charge Transaction. |
| hash | Produced 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.
| Name | Description |
|---|---|
| onSuccess | This function is called only when get token responds with status code 200. |
| onFailure | This 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 Attribute | Description | Type |
|---|---|---|
| transaction_id | Transaction ID given by Midtrans. | String |
| order_id | Order ID specified by you. | String |
| gross_amount | Total amount of transaction in IDR. | String |
| payment_type | The payment method used by the customer. | String |
| transaction_time | Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. | String |
| transaction_status | Transaction status after charge credit card transaction. Possible values arecapture : 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_status | Detection result by Fraud Detection System (FDS). Possible values areaccept : 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_card | First 8-digits and last 4-digits of customer's credit card number. | String |
| status_code | Status code of transaction charge result. | String |
| bank | The name of the acquiring bank. | String |
| status_message | Status message describing the result of the API request. | String |
| approval_code | Approval code. It can be used for refund. This does not exist on denied transaction. | String |
| eci | The 3D secure ECI Code. | String |
| channel_response_code | Response code from payment channel provider. | String |
| channel_response_message | Response message from payment channel provider. | String |
| currency | ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.Note: Currently only IDR is supported. | String |
| card_type | Type of card used for the transaction. Possible values are credit, debit. | String |
| three_ds_version | 3DS Version that used for transaction (This field only present for 3DS Transaction). Possible values are 1, 2 | String |
| three_ds_challenge_completion | 3DS 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, false | Boolean |
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.
| Name | Description | Required |
|---|---|---|
| callbackUrl | To 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 Attribute | Description | Type |
|---|---|---|
| transaction_id | Transaction ID given by Midtrans. | String |
| order_id | Order ID specified by you. | String |
| gross_amount | Total amount of transaction in IDR. | String |
| payment_type | The payment method used by the customer. | String |
| transaction_time | Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. | String |
| transaction_status | Transaction status after charge credit card transaction. Possible values arecapture : 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_status | Detection result by Fraud Detection System (FDS). Possible values areaccept : 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_card | First 8-digits and last 4-digits of customer's credit card number. | String |
| status_code | Status code of transaction charge result. | String |
| bank | The acquiring bank of the transaction. | String |
| status_message | Description of transaction charge result. | String |
| approval_code | Approval code. It can be used for refund. This does not exist on denied transaction. | String |
| eci | The 3D secure ECI Code. | String |
| channel_response_code | Response code from payment channel provider. | String |
| channel_response_message | Response message from payment channel provider. | String |
| currency | ISO-4217 representation of three-letter alphabetic currency code. Value: IDR.Note: Currently only IDR is supported. | String |
| card_type | Type of card used for the transaction. Possible values are credit, debit. | String |
| three_ds_version | 3DS Version that used for transaction (This field only present for 3DS Transaction). Possible values are 1, 2 | String |
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.
| Name | Description |
|---|---|
| performAuthentication | Implementation to open redirect URL in iFrame. |
| onSuccess | Handle to receive successful callback response. |
| onPending | Handle to receive callback response. Only applicable when merchant applied for async endpoint. |
| onFailure | Handle to receive failure response. |