Card Payment - Token Storage

Background

Tokenization is proven to be able to increase the conversion rate and convenience of doing payments. It also appeals to returning customers who pays using credit cards, as they are not required to fill in their card information with each consecutive payment.

This document outlines how merchants can utilize Midtrans’ two-clicks and one-click functionality on Snap by leveraging the token storage feature. There are two prime scenarios that will be covered in this document:

First time Checkout: First time users will be asked to register their credit card on Snap and as identifier for the credit card that is registered in Snap, merchant will send parameter/information of user_id; and
Returning Checkout: Merchants do not have to save the tokenized card details, simply send the returning user’s user_id and we will pre-fill the user’s credit card information based on that user_id.

First Time Checkout

When checking out for the first time, merchant will send a parameter that lets Snap know to allow shoppers to save their credit card details with Midtrans, this is accompanied by the user_id information as an identifier for token retrieval.

Should the customer choose to save their card information, Midtrans will save the card in the form of a token and return the generated card token on the HTTP post payment notification after the payment is successful. Merchants are not required to store the token, instead storing the user_id will suffice. This approach enables shoppers to save more than one cards, while merchants only have to store a single user_id as the identifier.

Page Flow

Get Snap Token

Valid Scenario

To utilise this feature, merchants should provide the save_card parameter with it’s value set to true within the credit_card parameter block. To allow tracking of the user’s token, you should also provide a unique user_id in the request. This will enable the save card toggle button on the Snap popup for the user to check on later during payment.

{
  "transaction_details": {
    "gross_amount": 10000,
    "order_id": "test-123"
  },
  "credit_card": {
    "secure": true,
    "save_card": true
  },
  "user_id": "customer-01"
}
```

The response of the above request will be a Snap Token (for pop up method) or a redirection URL (for redirection method):

{
  "token": "e5624efe-8095-4aca-8d3a-aadbc824437d",
  "redirect_url": "https://app.sandbox.veritrans.co.id/snap/v2/vtweb/e5624efe-8095-4aca-8d3a-aadbc824437d"
}

This will enable the "save card" toggle button on Snap’s UI, as illustrated bellow:

Invalid Scenario

Invalid Scenario 1: Merchant sends request to get redirect URL without option to save card:

{
  "transaction_details": {
    "gross_amount": 10000,
    "order_id": "test-123"
  },
  "credit_card": {
    "secure": true,
    "save_card": false
  },
  "user_id": "customer"
}

Midtrans will respond with a token/redirection URL:

{
  "token": "e5624efe-8095-4aca-8d3a-aadbc824437d",
  "redirect_url": "https://app.sandbox.veritrans.co.id/snap/v2/vtweb/e5624efe-8095-4aca-8d3a-aadbc824437d"
}

Although the request is successful and the response is valid, there will be no toggle button to save the credit card information on the UI. By default, the save_card parameter is set to false.

Invalid Scenario 2: Merchant sends request to get redirect URL with invalid JSON Body:

{
  "transaction_details": {
    "gross_amount": 10000,
    "order_id": "test-123"
  },
  "credit_card": {
    "secure": true,
    "save_card": yes
  },
  "user_id": 001
}

Midtrans will respond with error message:

{
  "status_code": "413",
  "status_message": "The request cannot be processed due to malformed syntax in the request body",
  "id": "56d58264-2127-4cd5-94ec-7407dfcbd61e"
}

Example of HTTP Post Payment Notification

Scenario 1: Customer selects option to save card and transaction was successful (accept by bank and by Fraud engine)

Response from Midtrans:

{
    "status_code": "200",
    "status_message": "Success, Credit Card 3D Secure transaction is successful",
    "transaction_id": "f50c0aef-b629-4a5b-957b-4c52f45e2e63",
    "order_id": "A87550",
    "payment_type": "credit_card",
    "transaction_time": "2014-08-25 11:21:48",
    "transaction_status": "capture",
    "fraud_status": "accept",
    "masked_card": "481111-1114",
    "saved_token_id": "4811117d16c884-2cc7-4624-b0a8-10273b7f6cc8",
    "saved_token_id_expired_at": "2024-08-25 11:21:48",
    "approval_code": "1408940508666",
    "gross_amount": "145000.00",
    "eci": "05"
}

If the customer chose to save the card information and the transaction was successful, we will send 2 additional parameters in the HTTP notification. This is for informative purpose only, merchants will not need to save these parameters:

saved_token_id: the actual token that was generated by Midtrans
saved_token_id_expired_at: Datetime when the token is set to expire (this data refers to the Credit Card’s Expiration Date)

Scenario 2: Customer selects option to save card and transaction failed (denied by bank but accepted by FDS)

If the customer chose to save the card information, but the transaction was unsuccessful (due to decline by banks or by our Fraud Detection System), the card information will not be stored.

Response from Midtrans:

{
  "transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "order_id": "C17551",
  "gross_amount": "145000.00",
  "payment_type": "credit_card",
  "transaction_time": "2014-08-24 15:39:22",
  "transaction_status": "deny",
  "fraud_status": "accept",
  "masked_card": "481111-1114",
  "status_code": "202",
  "bank": "bni",
  "status_message": "Veritrans payment notification",
  "approval_code": "1408869563148",
  "eci": "05"
}

Scenario 3: Customer selects option to save card and transaction failed(accepted by bank but denied by FDS)

Response from Midtrans:

{
  "transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "order_id": "C17551",
  "gross_amount": "145000.00",
  "payment_type": "credit_card",
  "transaction_time": "2014-08-24 15:39:22",
  "transaction_status": "accept",
  "fraud_status": "deny",
  "masked_card": "481111-1114",
  "status_code": "202",
  "bank": "bni",
  "status_message": "Veritrans payment notification",
  "approval_code": "1408869563148",
  "eci": "05"
}

Scenario 4: Customer selects option to save card and transaction is set to challenge(accepted by bank but challenged by FDS)

Response from Midtrans:

{
  "transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "order_id": "C17551",
  "gross_amount": "145000.00",
  "payment_type": "credit_card",
  "transaction_time": "2014-08-24 15:39:22",
  "transaction_status": "accept",
  "fraud_status": "challenge",
  "masked_card": "481111-1114",
  "status_code": "201",
  "bank": "bni",
  "status_message": "Veritrans payment notification",
  "approval_code": "1408869563148",
  "eci": "05"
}

Scenario 5: Customer doesn't select option to save card and transaction was successful

Response from Midtrans:

{
  "transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "order_id": "C17550",
  "gross_amount": "145000.00",
  "payment_type": "credit_card",
  "transaction_time": "2014-08-24 15:39:22",
  "transaction_status": "capture",
  "fraud_status": "accept",
  "masked_card": "481111-1114",
  "status_code": "200",
  "bank": "bni",
  "status_message": "Success, Credit Card 3D Secure transaction is successful",
  "approval_code": "1408869563148",
  "eci": "05"
}

If at this point the customer does not chose to save the card information and the transaction was successful, we will send the usual HTTP Post payment notification without the additional params for 2-clicks.

Returning Checkout

For returning checkouts, the merchant will only need to provide the user_id params and Midtrans will fetch all saved card token details and populate them when shoppers open up the Snap payment page.

Page Flow

For returning checkouts, merchant will send a card token parameter that will enable Snap to preload the card information associated with that particular token, the page flow will be as follow:

Get Snap Token

Valid Scenario

Merchant sends API request to get redirection URL with a valid card token:

{
  "transaction_details": {
    "gross_amount": 10000,
    "order_id": "test-123"
  },
  "credit_card": {
    "secure": true,
    "save_card": true
  },
  "user_id": "customer"
}

Midtrans will respond with a token and a redirection URL:

{
  "token": "d190d83d-4f02-4510-85b9-30dd32aecb4a",
  "redirect_url": "https://app.sandbox.veritrans.co.id/snap/v2/vtweb/d190d83d-4f02-4510-85b9-30dd32aecb4a"
}

Snap will pre load all credit card information that is associated with that particular user_id and merchant_id.

Note: The saved credit card information is not shared to other merchants who also uses the Snap platform. The credit card tokens and user_id are unique by merchant_id

Example of HTTP Post Payment Notification

Scenario 1: Transaction successful(accepted by bank and by Fraud Detection System)

Response:

{
  "transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "order_id": "C17551",
  "gross_amount": "145000.00",
  "payment_type": "credit_card",
  "transaction_time": "2014-08-24 15:39:22",
  "transaction_status": "capture",
  "fraud_status": "accept",
  "masked_card": "481111-1114",
  "status_code": "200",
  "bank": "bni",
  "status_message": "Success, Credit Card 3D Secure transaction is successful",
  "approval_code": "1408869563148",
  "eci": "05"
}

Scenario 2: Transaction failed(accepted by Fraud Detection System but denied by bank)

Response:

{
  "transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "order_id": "C17551",
  "gross_amount": "145000.00",
  "payment_type": "credit_card",
  "transaction_time": "2014-08-24 15:39:22",
  "transaction_status": "deny",
  "fraud_status": "accept",
  "masked_card": "481111-1114",
  "status_code": "202",
  "bank": "bni",
  "status_message": "Veritrans payment notification",
  "approval_code": "1408869563148",
  "eci": "05"
}

Scenario 3: Transaction failed(accepted by bank but denied by Fraud Detection System)

Response from Midtrans :

{
  "transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "order_id": "C17551",
  "gross_amount": "145000.00",
  "payment_type": "credit_card",
  "transaction_time": "2014-08-24 15:39:22",
  "transaction_status": "accept",
  "fraud_status": "deny",
  "masked_card": "481111-1114",
  "status_code": "202",
  "bank": "bni",
  "status_message": "Veritrans payment notification",
  "approval_code": "1408869563148",
  "eci": "05"
}

Scenario 4: Transaction got challenged(accepted by bank but challenged by Fraud Detection System)

Response:

{
  "transaction_id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
  "order_id": "C17551",
  "gross_amount": "145000.00",
  "payment_type": "credit_card",
  "transaction_time": "2014-08-24 15:39:22",
  "transaction_status": "accept",
  "fraud_status": "challenge",
  "masked_card": "481111-1114",
  "status_code": "201",
  "bank": "bni",
  "status_message": "Veritrans payment notification",
  "approval_code": "1408869563148",
  "eci": "05"
}