API References
Create AccountSubmit FeedbackAI Assist (BETA)
Start typing to search…

Get Auth Code API

Path/{version}/get-auth-code
HTTP MethodGET
Versionv1.0
SNAP service code10
📘

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 NameField TypeMandatoryField Description
Content-typeStringMMedia type of the resource, i.e. application/json.
X-TIMESTAMPStringMClient’s current local time in ISO-8601 format.
X-SIGNATUREStringMCreated using symmetric signature HMAC_SHA512 algorithm.
AuthorizationStringMRepresents 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-IDStringMUnique identifier for merchant. Provided by Midtrans.
X-EXTERNAL-IDStringMAlphanumeric string. We suggest merchant to use UUID format. Reference number that should be unique in the same day or 1 day idempotency key.
CHANNEL-IDStringMMandatory 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 NameField TypeMandatoryField Description
Content-typeStringMMedia type of the resource, i.e. application/json
X-TIMESTAMPStringMClient’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.

GoPay may add/change GoPay redirection URL from time to time. To ensure merchant can always support GoPay flow at all times, we highly suggest merchant to not do explicit URL whitelisting.

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.

GoPay may add/change GoPay URL from time to time. To ensure merchant can always support GoPay flow at all times, we highly suggest merchant to not do explicit URL whitelisting.

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 flowApp type/versionSuccess scenarioFailure scenario
Webview-redirectUrl?authCode=xxx&state=yyy&success=trueredirectUrl?errorCode=xxx&errorDesc=yyy
App redirectionGoPay (all version)redirectUrl?authCode=xxx&state=yyy&result=successredirectUrl?authCode=null&state=yyy&result=abort/failure
Gojek < 4.95redirectUrl?authCode=xxx&state=yyy&result=successredirectUrl?authCode=xxx&state=yyy&result=abort/failure
Gojek >= 4.95redirectUrl?authCode=xxx&state=yyy&result=successredirectUrl?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 result value to know whether linking is successful from the user side (on Gojek app) before calling the Bind Account API.

Response Body

Field NameField TypeMandatoryField Description
responseCodeString(7)MCode to specify the response returned.
responseMessageString (150)MDebug message to provide more information.
referenceNoString (256)CDebug 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 CodeResponse Message
4001001Already authorized
4001002Invalid Mandatory Field mobileNumber
4011000Unauthorized. Auth token required
4011001Invalid Token (B2B)
4041012Invalid Bill/Virtual Account Not Found
This error is due to phone number is not registered on GoPay
5001001Internal Server Error
5041000Timeout