Payment Method: GoPay Tokenization (non Pre-Auth)

This section will explain how merchant can initiate GoPay Tokenization (non Pre-Auth) transactions using SNAP-based CoreAPI specification.

  1. In order to do GoPay Tokenization transaction, merchant should link the customer's GoPay account first by initiating the Account Linking API.
  2. Once linked, merchant can create a transaction by calling Direct Debit Payment API.
  3. Merchant can also do other subsequent actions such as Cancel, Refund, and Get Status.
  4. To receive payment notification from Midtrans, merchant will need to also implement Payment Notification API.

Creating GoPay Tokenization transaction


GoPay Tokenization - Direct Debit Payment API

Path/{version}/debit/payment-host-to-host
HTTP MethodPOST
Versionv1.0
SNAP service code54

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.
Authorization-CustomerStringMRepresents access_token of a request; string starts with keyword “Bearer ” followed by access_token from Binding API response
X-PARTNER-IDStringMUnique identifier for partner. Merchant can send any value.
X-EXTERNAL-IDStringMNumeric string. Preferably UUID. Reference number that should be unique in the same day or 1 day idempotency key. In case of timeout, merchant can do:
1. Use this value in get status API to get status transaction or

2. Retry this request with the same X-EXTERNAL-ID and request body to avoid creating duplicate transaction
CHANNEL-IDStringMChannel ID Device identification on which the API services are currently being accessed by the end user. Given by BI
X-DEVICE-IDStringMDevice identification on which the API services are currently being accessed by the end user (customer).
Content-type:application/json
X-TIMESTAMP:2020-01-01T00:00:00+07:00
X-SIGNATURE: da1fa417c72d6b91c257e01e54fac824
Authorization: Bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CupvIJbU1Mmu4a11MNDZ7Sg5u9a
Authorization-Customer: Bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CupvIJbU1Mmu4a11MNDZ7Sg5u9a
X-PARTNER-ID: BMRI
X-DEVICE-ID: 0987ADCASA
X-EXTERNAL-ID:12345678901234567890
CHANNEL-ID:12345

Request Body

Field Name Field Type Mandatory Field Description
partnerReferenceNo String (64) M Merchant order id

Only used for debugging purpose in server side

chargeToken String M The account token used to represent the account binding between merchant and GoPay.

We are not sharing accountToken/accessToken with Merchants. Merchant needs to call the Binding Inquiry API to fetch the accountToken/accessToken.

urlParam Array of Object O Merchant redirect URL.

After completing payment, user will be redirected back to this URL

urlParam.url String(512) M URL value (need to be whitelisted as part of GoPay Tokenization onboarding process)
urlParam.type String(32) M Possible value : PAY_RETURN
urlParam.isDeeplink String(1) M Is Deeplink or not (Y/N)
validUpTo String(25) O The time when the payment will be automatically expired. Using ISO 8601 format

(Maximum value: 180 days from transaction time, minimum value: 20 seconds, default value: 15 minutes)

payOptionDetails Array of Object M Payment option that will be used for this payment

Currently only accept 1 payOptions

payOptionDetails.payMethod String (64) M Payment method. e.g. CREDIT_CARD, GOPAY
payOptionDetails.payOption String (64) M Payment option which shows the provider of this payment

e.g. GOPAY_WALLET, GOPAY_COINS, etc

(Value can be acquired from additionalInfo.paymentOptions.name in Binding Inquiry API response)

payOptionDetails.transAmount Object O Payment transaction amount
payOptionDetails.transAmount.value String (16,2) M Transaction amount that will be paid using this payment method. If it's IDR then value includes 2 decimal digits.

e.g. IDR 10.000 will be placed as 10000.00

Minimum value: 1.00

Maximum value : 99999999999.00

payOptionDetails.transAmount.currency String (3) M IDR
payOptionDetails.additionalInfo Object M Additional information field which merchants need to pass to support current API contracts.
payOptionDetails.additionalInfo.recurring String O Recurring flag

Possible value : Y/N

If recurring: Y then we will treat this transaction as recurring transaction and bypass PIN challenge. Only applies if recurring feature has already been enabled, please talk to your Midtrans sales representative to have this feature enabled.

payOptionDetails.additionalInfo.promotionIds Array of String O List of promotion ID

Promotion ID can be obtained from Get Promotion API.

payOptionDetails.additionalInfo.paymentoptiontoken String M paymentOptionToken
additionalInfo Object O Additional Information
additionalInfo.customerDetails Object O Customer detail information
additionalInfo.customerDetails.phone String(15) O Customer phone number
additionalInfo.customerDetails.email String(255) O Customer email
additionalInfo.customerDetails.firstName String(255) O Customer first name
additionalInfo.customerDetails.lastName String(255) O Customer last name
additionalInfo.customerDetails.billingAddress Object O
additionalInfo.customerDetails.billingAddress.firstName String(255) O Billing address first name
additionalInfo.customerDetails.billingAddress.lastName String(255) O Billing address last name
additionalInfo.customerDetails.billingAddress.phone String(15) O Billing address phone number
additionalInfo.customerDetails.billingAddress.address String(255) O Billing address detail
additionalInfo.customerDetails.billingAddress.city String(255) O Billing address city
additionalInfo.customerDetails.billingAddress.postalCode String(255) O Billing address postal code
additionalInfo.customerDetails.billingAddress.countryCode String(15) O Billing address country code
additionalInfo.customerDetails.shippingAddress Object O
additionalInfo.customerDetails.shippingAddress.firstName String(255) O Shipping address first name
additionalInfo.customerDetails.shippingAddress.lastName String(255) O Shipping address last name
additionalInfo.customerDetails.shippingAddress.phone String(15) O Shipping address phone number
additionalInfo.customerDetails.shippingAddress.address String(255) O Shipping address detail
additionalInfo.customerDetails.shippingAddress.city String(255) O Shipping address city
additionalInfo.customerDetails.shippingAddress.postalCode String(255) O Shipping address postal code
additionalInfo.customerDetails.shippingAddress.countryCode String(15) O Shipping address country code
additionalInfo.items Array Of Object O
additionalInfo.items.id String(32) O Item ID

Shall merchant intent to apply SKU based promotion, merchant should pass the agreed item ID value for promotion.

additionalInfo.items.price Object M
additionalInfo.items.price.value String (ISO4217) M Item price value
additionalInfo.items.price.currency String M Item price currency
additionalInfo.items.quantity String(16) M Item quantity
additionalInfo.items.name String(64) M Item name
additionalInfo.items.merchantName String(64) O Name of the merchant selling the item
additionalInfo.items.brand String(64) O Brand name of the item
additionalInfo.items.category String(64) O Category of the item
additionalInfo.metadata Object O Transaction metadata
{
    "partnerReferenceNo": "merchant-order-id",
    "chargeToken": “accessToken",
    "validUpTo": “2023-07-03T10:36:17+07:00",
    "payOptionDetails": [
        {
            "payMethod": "Gopay",
            "payOption": "Coins",
            "transAmount": {
                "value": "12345678.00",
                "currency": "IDR"
            },
            "additionalInfo": {
                "paymentOptionToken": "aGoPayWalletToken / aPayLaterToken / aGoPayCoinsToken",
                "challengeId": "aChallengeID",
                "paymentToken": "aPaymentToken"
            }
        }
    ],
    "urlParam": 
        {
            "url": "www.merchant.com",
            "type": "PAY_RETURN",
            "isDeeplink": “Y/N”
            },
    "additionalInfo": {
          "customerDetails": {
                "phone": "81234532422",
                "firstName": "farz",
                "lastName": "zsasa",
                "email": "[email protected]",
                "billingAddress": {
                        "firstName": "billingFirstName",
                        "lastName": "billingLastName",
                        "phone": "billingPhone",
                        "address": "billingAddress",
                        "city": "billingCity",
                        "postalCode": "12790",
                        "countryCode": "CZH"
                 },
                "shippingAddress": {
                        "firstName": "shippingFirstName",
                        "lastName": "shippingLastName",
                        "phone": "shippingPhone",
                        "address": "shippingAddress",
                        "city": "shippingCity",
                        "postalCode": "12790",
                        "countryCode": "CZH"
                 
                 },
            },
          "items": [
                  {
                          "id": "8za1ieleavwusxn6u5re60ri",
                          "price":  {
                                     "value": "12345678.00",
                                     "currency": "IDR"
                          },
                          "quantity": “1”,
                          "name": "subscription ",
                          "brand": "brand ",
                          "category": "Subsciption ",
                          "merchantName": "amazon prime"
                  }
                 ],
          "metadata": {}
    }
}

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: 2020-01-01T00:00:00+07:00

Response Body

Field Name Field Type Mandatory Field Description
responseCode String (7) M Error code to specify the error returned.
responseMessage String (150) M Debug message to provide more information.
referenceNo String (256) M Transaction unique identifier on service provider system. For e.g : GopayOrderId

(Only filled if transaction created successfully)

partnerReferenceNo String (32) O Transaction identifier on service consumer system (Merchant order ID)
webRedirectUrl String (2048) M Returns a universal link to GoPay PIN page. Use this link to redirect user to GoPay PIN page for them to complete payment. This can be open via webview / app redirection depending on which flow the merchant is onboarded.
additionalInfo Object O Additional information
additionalInfo.gross_amount Object M
additionalInfo.gross_amount.value String (ISO4217) M Gross amount value
additionalInfo.gross_amount.currency String M Gross amount currency
additionalInfo.payOptionDetails Array of Object M Payment option detail
additionalInfo.payOptionDetails.payMethod String M Gopay
additionalInfo.payOptionDetails.payOptions String M Gopay payment option used
additionalInfo.transactionTime String O Timestamp of transaction in ISO 8601 format. Time zone: GMT+7.
additionalInfo.transactionStatus String O Transaction status

Possible Values:

  • 00 - Success
  • 03 - Pending
  • 04 - Refunded
  • 05 - Canceled
  • 06 - Failed
additionalInfo.fraudStatus String O Fraud status
additionalInfo.validUpTo String(25) O The time when the payment will be automatically expired. Using ISO 8601 format
{
   "responseCode":"20054000",
   "responseMessage":"Request has been processed successfully",
   "referenceNo":"Gopay-order-id",
   "partnerReferenceNo":"merchant-order-id",
   "webRedirectUrl":"https://pjsp.com/universal?bizNo=REF993883&...",
   "additionalInfo":{
      "grossAmount":{
              "value": "12345678.00",
              "currency": "IDR"
       },
      "currency":"IDR",
     “payOptionDetails” : [{
          "payMethod":"Gopay",
            "payOption": "Coins"
        }], 
       "transactionTime":"",
      "transactionStatus":"settlement",  
      "fraudStatus":"some-fraud-status"  ,
    "validUpTo":"2023-07-03T10:36:17+07:00"
   }
}
{
   "responseCode":"4001001",
   "responseMessage":"There is some issue with the transaction request",
   "originalExternalId": "merchant-order-id",
}

List of response code

Response Code HTTP Status Code Response Message
4005402 400 Invalid Mandatory Field chargeToken , partnerReferenceNo
4015400 401 Unauthorized. Auth token required
4015401 401 Invalid Token (B2B)
4015402 401 Invalid Customer Token
4035403 403 Suspected Fraud
4035414 403 Insufficient Funds
4035415 403 Transaction Not Permitted. Url not whitelisted.
5005401 500 Internal Server Error
5045400 504 Timeout

Additional APIs

  1. Refund API
  2. Cancel API
  3. Get Transaction Status API
  4. Payment Notification API