| Path | /{version}/get-auth-code |
|---|---|
| HTTP Method | GET |
| Version | v1.0 |
| SNAP service code | 10 |
To simplify the integration, we highly recommends merchant to call this Get Auth Code API directly from merchant's front end.
We are deprecating request and respone header from the Get Auth Code API. Moving forward merchant is not required to pass request header as part of the Get Auth Code API call.
For merchant that has already passed the headers, we will maintain the backward compatibality and process the API call as is.
Request Header
| Field Name | Field Type | Mandatory | Field Description |
|---|---|---|---|
| Content-type | String | M | Media type of the resource, i.e. application/json. |
| X-TIMESTAMP | String | M | Client’s current local time in ISO-8601 format. |
| X-SIGNATURE | String | M | Created using symmetric signature HMAC_SHA512 algorithm. |
| Authorization | String | M | Represents access_token of a request; string starts with keyword “Bearer ” followed by access_token. Can get this token from Access Token B2B API response. |
| X-PARTNER-ID | String | M | Unique identifier for merchant. Provided by Midtrans. |
| X-EXTERNAL-ID | String | M | Alphanumeric string. We suggest merchant to use UUID format. Reference number that should be unique in the same day or 1 day idempotency key. |
| CHANNEL-ID | String | M | Mandatory field from Bank Indonesia that can take any value with correct format 5 digits numeric string |
Content-type:application/json
X-TIMESTAMP:2024-03-19T14:30:00+07:00
X-SIGNATURE: da1fa417c72d6b91c257e01e54fac824
Authorization: Bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CupvIJbU1Mmu4a11MNDZ7Sg5u9a
X-PARTNER-ID: G123456
X-EXTERNAL-ID:12345678901234567890
CHANNEL-ID:12345
Query Parameter
| Field Name | Field Type | Mandatory | Field Description |
|---|---|---|---|
| redirectURL | String (256) | M | Merchant callback URL after success get auth code. Need to be whitelisted from GoPay side (part of GoPay Tokenization onboarding process). |
| scopes | List of String (256) | M | Access scope from authorization. Possible value = DEFAULT. |
| state | String (32) | M | Random string for CSRF. |
| merchantId | String (64) | M | Merchant payment handle, merchant identifier in UUID format. Provided by Midtrans. Note: this value is not Midtrans Merchant ID, but a different value, here's the sample format: 303b4f89-xxxx-xxxx-xxxx-62a8ffaefaf3 The value on staging and production is different. Please make sure that you are sending the correct value based on the environment that you are using. |
| lang | String(2) | M | Language code for service Possible values: en, id. |
| seamlessData | String (512) | M | Data to speed up the validation and verification process. |
| seamlessData.mobileNumber | String | M | Mobile number to be linked (format should be country code (without "+") + phone number. Example: 62812345678). |
| seamlessData.paymentType | String | M | Payment type to be linked. Possible value: gopay. |
| seamlessSign | String (512) | M | Signature from seamlessData. |
/get-auth-code?state=<RANDOM_UNIQUE>&merchantId=<merchant-id>&lang=id&scopes=DEFAULT&redirectUrl=<MERCHANT_OAUTH_CALLBACK_URL>&seamlessData=<SEAMLESS_DATA>&seamlessSign=<SIGNATURE>
| Seamless Data Format |
|---|
| seamlessData = URLEncode("mobileNumber=62822999999&paymentType=gopay") |
| Seamless Sign Format |
|---|
| seamlessSign = URLEncode(Base64(SHA256withRSA(privateKey, seamlessData)) |
Note: Merchant need to use their private key to encrypt seamless sign
Response Header
| Field Name | Field Type | Mandatory | Field Description |
|---|---|---|---|
| Content-type | String | M | Media type of the resource, i.e. application/json |
| X-TIMESTAMP | String | M | Client’s current local time in ISO-8601 format |
Content-type: application/json
X-TIMESTAMP: 2024-03-19T14:30:00+07:00
Redirection Response Header
| Field Name | Field Type | Mandatory | Field Description |
|---|---|---|---|
| Location | String | M | GoPay PIN/OTP page URL - Webview: Redirect user to GoPay PIN/OTP page in webview - App redirection: Redirect user to GoPay PIN page in Gojek/GoPay app |
| Origin | String | O | Only will be returned if merchant is using App redrection flow. Will contains linking QR flow. User will need to scan QR using Gojek/GoPay app to continue linking |
HTTP/1.1 302 Found
Location: https://www.integration-gws-app.gopayapi.com/app/authorize?referenceId=19352694-0ef6-4439-8ad1-b1dfb8bbb85f
HTTP/1.1 302
Location:merchantRedirectURL?responseCode=4001002&responseMessage=Invalid Mandatory Field mobileNumber
In case of a successful API request call (merchant successfully calls the Get Auth Code API), Midtrans will return Location in header with the GoPay PIN/OTP page URL. But if the call fails, Midtrans will return Location in header with the merchant's redirect URL and the error responseCode and responseMessage.
Response Query Parameter (After redirection)
| Field Name | Field Type | Mandatory | Field Description |
|---|---|---|---|
| authCode | String (256) | C | Auth code used to exchange with access token. Please refer to the section below for the detailed explanation on authCode |
| state | String (32) | C | Random string for CSRF (Merchant can validate to check if this is the same as state sent on request). |
| success | String | C | Indicating whether user has successfully completed linking on GoPay page Will be returned if merchant is onboarded on webview flow |
| result | String | C | Indicating whether user has successfully completed linking on GoPay page Will be returned if merchant is onboarded on app redirection flow |
| errCode | String | C | Indicating the error code in case user fails to successfully linked on GoPay page Will be returned if merchant is onboarded on webview flow |
| errDesc | String | C | Indicating the error mesage in case user fails to successfully linked on GoPay page Will be returned if merchant is onboarded on webview flow |
Response query parameter (after redirection) behavior
(will be live in prod on August 26, 2024)
Please refer to the table below for the redirect url format for each of the Tokenization flow.
Tokenization flow App type/version Success scenario Failure scenario Webview - redirectUrl?authCode=xxx&state=yyy&success=true redirectUrl?errorCode=xxx&errorDesc=yyy App redirection GoPay (all version) redirectUrl?authCode=xxx&state=yyy&result=success redirectUrl?authCode=null&state=yyy&result=abort/failure Gojek < 4.95 redirectUrl?authCode=xxx&state=yyy&result=success redirectUrl?authCode=xxx&state=yyy&result=abort/failure Gojek >= 4.95 redirectUrl?authCode=xxx&state=yyy&result=success redirectUrl?authCode=null&state=yyy&result=abort/failure
Things to note
- In the case where user is using Gojek app < 4.95 and they have failed to complete linking on the app, Midtrans will still return authCode value on redirect url query parameters.
- When merchant call the Bind Account API with that authCode, Midtrans will return an error and linking cannot be confirmed/successful.
- It is highly recommended that merchant reads the
resultvalue to know whether linking is successful from the user side (on Gojek app) before calling the Bind Account API.
Response Body
| Field Name | Field Type | Mandatory | Field Description |
|---|---|---|---|
| responseCode | String(7) | M | Code to specify the response returned. |
| responseMessage | String (150) | M | Debug message to provide more information. |
| referenceNo | String (256) | C | Debug id to provide more information |
{
"responseCode":"2001001",
"responseMessage":"Successful"
}
{
"responseCode":"5001001",
"responseMessage":"Internal Server Error",
"referenceNo":"19352694-0ef6-4439-8ad1-b1dfb8bbb85f"
}
List of Response Code
| Response Code | Response Message |
|---|---|
| 3021000 | |
| 4001001 | Already authorized |
| 4001002 | Invalid Mandatory Field mobileNumber |
| 4011000 | Unauthorized. Auth token required |
| 4011001 | Invalid Token (B2B) |
| 4041012 | Invalid Bill/Virtual Account Not Found This error is due to phone number is not registered on GoPay |
| 5001001 | Internal Server Error |
| 5041000 | Timeout |