GoPay Tokenizations mode is available for both Snap and Core API integration. To read about GoPay Tokenization in Snap checkout, go here.
GoPay Tokenization allows you to link your customer GoPay account. The flow is similar to card tokenization where you can use the linked customer account for transaction authorization.
Send a Charge API request with the details of the transaction such as payment_type
, gopay
, and transaction_details
. Successful request returns a status_code:200
.
The steps to integrate with GoPay Tokenization are given below.
- Link customer account only if the customer phone number is not yet linked to GoPay.
- Fetch customer account. If the linking of customer account is successful, then the payment options available to the customer are-
GOPAY_WALLET
andPAY_LATER
. Customer can select any of these options. From metadata, store the token of the payment option. You can also use this API to fetch the customer balance. - If the linking is already successful then the customer can proceed with the charge. Sample Charge API request is shown on the side.
- Ensure to have proper handling of various status codes that you've received from Midtrans - for example, if the
status_code
in the response is 200, then the transaction is completed. If thestatus_code
is 201, then you need to open the verification URL in theactions
to the customer. Once the verification is done, it will redirect back to the callback URL that is set on your dashboard.
Use the following two redirection URLs only :
verification-link-url
is for transaction verification in browser or webview. This redirection is recommended for desktop. The customer will receive a push notification from their Gojek app. Once the customer verifies the transaction on the app, it will be automatically redirected to the merchant page. For merchants with special agreement with GoPay, this page may also show OTP/PIN page.verification-link-app
is for transaction verification in Gojek app. This might not be applicable for all merchants. The customer will need to input OTP/PIN from the Gojek app.
GoPay Tokenization Charge API Request
{
"payment_type": "gopay",
"gopay": {
"account_id": "00000269-7836-49e5-bc65-e592afafec14",
"payment_option_token": "eyJ0eXBlIjogIkdPUEFZX1dBTExFVCIsICJpZCI6ICIifQ==",
"callback_url": "https://midtrans.com/",
"recurring": false,
"promotion_ids": [
"CASHBACK|acbec7d4-b30b-44ac-9c42-f5d767419a72|8bb3c041-c71e-40f3-892b-688fda2ec979||2021-02-22|2021-02-23"
]
},
"transaction_details": {
"gross_amount": 100000,
"order_id": "order-1234"
}
}
The attributes to be sent to charge GoPay Tokenization are given below.
JSON Attribute | Description | Type | Required |
---|---|---|---|
payment_type | Set GoPay payment method. Value: gopay . | String | Required |
gopay | Charge details using GoPay. | Object | Required |
transaction_details | The details of the specific transaction such as order_id and gross_amount . | Object | Required |
callback_url | Please make sure callback_url is the same URL submitted during the onboarding process. If callback_url is not specified by merchant, we will use merchant's finish redirect URL that is set on Midtrans Administration Portal, please make sure these URLs are also submitted during onboarding process. | String | Optional |
GoPay Tokenization Charge Response and Notifications
{
"status_code": "200",
"status_message": "Success, GoPay transaction is successful",
"transaction_id": "00000269-7836-49e5-bc65-e592afafec14",
"order_id": "order-1234",
"gross_amount": "100000.00",
"currency": "IDR",
"payment_type": "gopay",
"transaction_time": "2016-06-28 09:42:20",
"transaction_status": "settlement",
"fraud_status": "accept",
}
{
"status_code": "201",
"status_message": "GoPay transaction is created. Action(s) required",
"transaction_id": "00000269-7836-49e5-bc65-e592afafec14",
"order_id": "order-1234",
"gross_amount": "100000.00",
"currency": "IDR",
"payment_type": "gopay",
"transaction_time": "2016-06-28 09:42:20",
"transaction_status": "pending",
"fraud_status": "accept",
"actions": [
{
"name": "verification-link-url",
"method": "GET",
"url": "http://api.midtrans.com/v2/gopay/redirect/gppr_6123269-1425-21e3-bc44-e592afafec14/charge"
},
{
"name": "verification-link-app",
"method": "GET",
"url": "http://api.midtrans.com/v2/gopay/redirect/gppd_6123269-1425-21e3-bc44-e592afafec14/charge"
}
]
}
{
"status_code": "202",
"status_message": "GoPay transaction is denied",
"transaction_id": "a8a91ece-24f9-427d-a588-b9a2428acda0",
"order_id": "order-1234",
"gross_amount": "100000.00",
"currency": "IDR",
"payment_type": "gopay",
"transaction_time": "2016-06-28 09:42:20",
"transaction_status": "deny",
"fraud_status": "accept",
}
JSON Attribute | Description | Type |
---|---|---|
status_code | Status code of transaction charge result. | String |
status_message | Description of transaction charge result. | String |
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 | Transaction payment method. | String |
transaction_time | Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. | String |
transaction_status | Status of GoPay transaction. Possible values arepending , settlement , expire , deny . | String |
actions | Actions which can be performed with this transaction. Use verification-link-url or verification-link-app to do the verification and to redirect the customer to callback URL. These links have an expiry time of 5 minutes. | Array(Object) |
currency | ISO-4217 representation of three-letter alphabetic currency code. Value: IDR .Note: Currently only IDR is supported. | String |
GoPay Tokenization Features: Pre-Authorization
Merchant that enables GoPay Tokenization could opt to do pre-auth transactions. Pre-auth allows merchant to reserve the customer balance before the goods or services are delivered.
Pre-auth flow allows you to make a reservation to user's wallet balance. This will help for cases where you need to reserve user's balance instead of debit it directly, to initiate debit you can call Capture API afterwards. To use this feature, you can set pre-auth
as true on GoPay Object. By default, reserved balance will be released after 15 minutes if there is no "capture" action for that transaction. Capturing a reservation is a process to settle the customer balance into merchant account. You can customize reservation time limits by sending custom expiry time parameters on charge request
As of now, pre-auth flow feature only supports non PIN flow. To test in Sandbox, please make sure that the amount doesn’t exceed IDR 100,000.
GoPay Tokenization Features: Pre-Authorization Flow
The steps to integrate Gopay Tokenization Pre-Auth feature are given below.
- The linking process is exactly same as GoPay Tokenization linking process above.
- If the linking is already successful then the customer can proceed with the charge. The only difference is that merchant needs to pass
pre_auth
: "true" parameter. See example on the side. - Ensure to have proper handling of various status codes that you've received from Midtrans - for example, if the
status_code
in the response is 200, then the transaction is authorized. If thestatus_code
is 201, then you need to open the verification URL in theactions
to the customer. Once the verification is done, it will be redirected back to the callback URL that is set on your dashboard. - You need to call Capture API. Please note that we do not accept partial amount capture for GoPay.
- As an option, you can also cancel the authorization by calling the Cancel API.
Send a Charge API request with the details of the transaction and pre_auth:true
. Successful request returns a status_code:200
.
Pre-Auth Charge API Request
{
"payment_type": "gopay",
"gopay": {
"account_id": "00000269-7836-49e5-bc65-e592afafec14",
"payment_option_token": "eyJ0eXBlIjogIkdPUEFZX1dBTExFVCIsICJpZCI6ICIifQ==",
"pre_auth": true, // the default value is false
},
"transaction_details": {
"gross_amount": 100000,
"order_id": "order-1234"
}
}
Pre-Auth Charge Response and Notifications
{
"status_code": "200",
"status_message": "Success, GoPay transaction is successful",
"transaction_id": "00000269-7836-49e5-bc65-e592afafec14",
"order_id": "order-1234",
"gross_amount": "100000.00",
"currency": "IDR",
"payment_type": "gopay",
"transaction_time": "2016-06-28 09:42:20",
"transaction_status": "authorize",
"fraud_status": "accept",
"channel_response_code": "0",
"channel_response_message": "Process service request successfully."
}
{
"status_code": "201",
"status_message": "GoPay transaction is created. Action(s) required",
"transaction_id": "00000269-7836-49e5-bc65-e592afafec14",
"order_id": "order-1234",
"gross_amount": "100000.00",
"currency": "IDR",
"payment_type": "gopay",
"transaction_time": "2016-06-28 09:42:20",
"transaction_status": "pending",
"fraud_status": "accept",
"actions": [
{
"name": "verification-link-url",
"method": "GET",
"url": "http://api.midtrans.com/v2/gopay/redirect/gppr_6123269-1425-21e3-bc44-e592afafec14/charge"
},
{
"name": "verification-link-app",
"method": "GET",
"url": "http://api.midtrans.com/v2/gopay/redirect/gppd_6123269-1425-21e3-bc44-e592afafec14/charge"
}
]
}
{
"status_code": "202",
"status_message": "GoPay transaction is denied",
"transaction_id": "a8a91ece-24f9-427d-a588-b9a2428acda0",
"order_id": "order-1234",
"gross_amount": "100000.00",
"currency": "IDR",
"payment_type": "gopay",
"transaction_time": "2016-06-28 09:42:20",
"transaction_status": "deny",
"fraud_status": "accept",
}
JSON Attribute | Description | Type |
---|---|---|
status_code | Status code of transaction charge result. | String |
status_message | Description of transaction charge result. | String |
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 | Transaction payment method. | String |
transaction_time | Timestamp of transaction in ISO 8601 format. Time Zone: GMT+7. | String |
transaction_status | Status of GoPay transaction. Possible values arepending , settlement , expire , deny . | String |
actions | Actions which can be performed with this transaction. Use verification-link-url or verification-link-app to do the verification and to redirect the customer to callback URL. | Array(Object) |
channel_response_code | Response code from payment channel provider. | String |
channel_response_message | Response message from payment channel provider. | String |
signature_key | Combination of parameters such as order_id , status_code , gross_amount , server_key to verify integrity of payload/response. | String |
currency | ISO-4217 representation of three-letter alphabetic currency code. Value: IDR .Note: Currently only IDR is supported. | String |