Payment Method: QRIS

📘

Both GoPay QRIS and ShopeePay QRIS are available on SNAP-based flow.

In QRIS flow, merchant will receive QRIS code which can be paid by users. Users can scan the QRIS code using e-wallet app that already is QRIS compatible, such as GoPay, ShopeePay, etc.

This section will explain how merchants can initiate GoPay QRIS transactions using SNAP-based CoreAPI specification.


Creating GoPay/ShopeePay QRIS transaction


Path/{version}/qr/qr-mpm-generate
HTTP MethodPOST
Versionv1.0
SNAP Service Code47

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 response.
X-PARTNER-ID String M Unique identifier for caller (client_id)
X-EXTERNAL-ID String M Alphanumeric string. Preferably UUID. 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:BMRI
X-EXTERNAL-ID:12345678901234567890
CHANNEL-ID:12345

Request Body

Field Name Field Type Mandatory Field Description
partnerReferenceNo String(64) O Merchant order id
amount Object O Amount object
amount.value String(16,2) M Transaction amount
amount.currency String(3) M Transaction currency
merchantId String(64) O Merchant identifier that is unique per each merchant
subMerchantId String(32) O Sub merchant id
storeId String(64) O Unique shop id on the merchant side.
validityPeriod String(25) O The time when the QRIS will automatically expire. The time when the payment will be automatically expired. The format is defined by ISO 8601.

(Maximum value : 180 days from trx time, Minimum value : 20 second, default value : 15 min)

terminalId String(16) O Merchant terminal id
additionalInfo Object O Additional information
additionalInfo.acquirer String O Acquirer name, possible value for now: GOPAY, AIRPAY SHOPEE. If not given, default value is GOPAY
{
  "partnerReferenceNo": "2020102900000000000001",
  "amount": {
    "value": "12345678.00",
    "currency": "IDR"
  },
  "merchantId": "00007100010926",
  "terminalId": "213141251124",
  "validityPeriod": "2009-07-03T12:08:56-07:00",
  "additionalInfo": {
    "acquirer": "gopay",
    "items": [
      {
        "id": "susumaniskaleng",
        "price": {
          "value": "5000",
          "currency": "IDR"
        },
        "quantity": "1",
        "name": "HOLYCOW 1KG T-bone",
        "brand": "Makan makan 1OMS ",
        "category": "Food",
        "merchantName": ""
      }
    ],
    "customerDetails": {
      "email": "[email protected]",
      "firstName": "Budi",
      "lastName": "Utomo",
      "phone": "081223323423"
    },
    "metadata": {
    },
    "countryCode": "ID",
    "locale": "id_ID"
  }
}

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

Response Body

Field Name Field Type Mandatory Field Description
responseCode String (7) M Response Code (HTTP status code + service code + case code)
responseMessage String (150) M Description of charge result response.
referenceNo String (64) O Transaction identifier on service provider system.
partnerReferenceNo String (64) O Transaction identifier on service consumer system
qrContent String(512) C QR String MPM.

If qrContent is null, then qrUrl or qrImage must be filled.

qrUrl String(256) O QR URL for download QR Image
qrImage String O base64 from image QRIS.

Max length is unlimited.

redirectUrl String(512) O Redirect URL to go to PJSP page to process the payment.
merchantName String(25) O Merchant name
storeId String(64) O unique shop id on the merchant side.
terminalId String(16) O Merchant terminal id
additionalInfo Object O Additional information
additionalInfo.acquirer Object O Acquirer chosen from request
{
  "responseCode": "2004700",
  "responseMessage": "Request has been processed successfully",
  "referenceNo": "2020102977770000000009",
  "partnerReferenceNo": "2020102900000000000001",
  "qrContent": "xxxxxxxxxxxxxxxx",
  "qrUrl": "https: //qrurl?img=12345",
  "qrImage": "TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5vdCBvbmx5IGJ5IGhpcyByZWFzb24sIGJ1dCAuLi4=",
  "redirectUrl": "https://test.psjp.id/redirect/qris?x=238490324092",
  "merchantName": "Baso Malang",
  "storeId": "abcd",
  "terminalId": "213141251124",
  "additionalInfo": {
    "createdAt": {
      "dateTime": "2023-07-10T02:50:45.623789",
      "offset": {
        "totalSeconds": 0
      },
      "zone": {
        "totalSeconds": 0
      }
    },
    "amount": {
      "value": 5000,
      "currency": "IDR"
    },
    "transactionType": "MERCHANT_TRANSACTION",
    "recurring": false,
    "merchantCrossRefId": "a78b46f8-cef0-4294-8f9c-5f1bff6a9995"
    "acquirer": "gopay"
  }
}

List of Response code

Response Code HTTP Status Description
2004700 200 Successful
2024700 202 Transaction still on process
4004700 400 General request failed error, including message parsing failed.
4004701 400 Invalid format
4004702 400 Missing or invalid format on mandatory field
4014700 401 General unauthorized error (No Interface Def, API is Invalid, Oauth Failed, Verify Client Secret Fail, Client Forbidden Access API, Unknown Client, Key not Found)
4014701 401 Token found in request is invalid (Access Token Not Exist, Access Token Expiry)
4014703 401 Token not found in the system. This occurs on any API that requires token as input parameter
4034700 403 Transaction expired
4034701 403 This merchant is not allowed to call Direct Debit APIs
4034702 403 Exceeds Transaction Amount Limit
4034703 403 Suspected Fraud
4034704 403 Too many request, Exceeds Transaction Frequency Limit
4034705 403 Account or User status is abnormal
4034706 403 Cut off In Progress
4034709 403 The account is dormant
4034714 403 Insufficient Funds
4034715 403 Transaction Not Permitted
4034716 403 Suspend Transaction
4034718 403 Indicates inactive account
4034719 403 Merchant is suspended from calling any APIs
4034720 403 Merchant aggregated purchase amount on that day exceeds the agreed limit
4034721 403 Set limit not allowed on particular token
4034722 403 The token limit desired by the merchant is not within the agreed range between the merchant and the Issuer
4034723 403 Account aggregated purchase amount on that day exceeds the agreed limit
4044700 404 Invalid transaction status
4044701 404 Transaction not found
4044702 404 Invalid Routing
4044704 404 Transaction is cancelled by customer
4044708 404 Merchant does not exist or status abnormal
4044710 404 Invalid API transition within a journey
4044713 404 The amount doesn't match with what supposed to
4044716 404 Partner number can't be found
4044717 404 Terminal does not exist in the system
4044718 404 Inconsistent request parameter
4054700 405 Requested function is not supported
4054701 405 Requested operation to cancel/refund transaction Is not allowed at this time.
4094700 409 Cannot use same X-EXTERNAL-ID in same day
4094701 409 Transaction has previously been processed indicates the same partnerReferenceNo already success
4294700 429 Maximum transaction limit exceeded
5004700 500 General Error
5004701 500 Unknown Internal Server Failure, Please retry the process again
5004702 500 Backend system failure, etc
5044700 504 timeout from the issuer

Additional APIs

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