QRIS

SNAP API

QRIS Integration

QRIS (Quick Response Code Indonesian Standard) is the national standard QR Code payment method in Indonesia. Winpay provides integration for both dynamic and static QRIS MPM (Merchant Presented Mode) in real-time via SNAP API.

QRIS Transaction

1. Generate QRIS MPM

POST/v1.0/qr/qr-mpm-generateService Code: 47

This service is used to create QRIS using the Merchant Presented Mode (MPM) method.

Payload Create QRIS Payment

Parameters	Data Type	Mandatory	Description
partnerReferenceNo	String	Y	Transaction number merchant Length: 5-50 Allowed Chars: a-z A-Z 0-9 - _
terminalId	String	C	ID terminal Length: 3-16 Allowed Chars: a-z A-Z 0-9 - _
subMerchantId	String	C	ID merchant winpay from submerchant
amount	Object	Y	Object amount
value	String	Y	Transaction value Length: 1-14 Allowed Chars: numeric
currency	String	Y	Currency code Length: 3 Allowed Value: IDR
validityPeriod	String	C	Transaction time ends Format: YYYY-MM-DDTHH:mm:ssZ (ISO8601) Mandatory if additionalInfo.isStatic = false Must be more than 1 minute and a maximum of 3 months from the time of request
additionalInfo	Object	Y	Object additionalInfo
isStatic	Boolean	Y	Status QRIS true = Static false = Dynamic

{
  "partnerReferenceNo": "ref00000000001",
  "amount": {
    "value": "50000.00",
    "currency": "IDR"
  },
  "validityPeriod": "2023-09-06T23:08:56+07:00",
  "additionalInfo": {
    "isStatic": false
  }
}

Response Create QRIS Payment

Parameters	Data Type	Description
responseCode	String	Response COde
responseMessage	String	Message response
partnerReferenceNo	String	Merchant Transaction Number
qrContent	Null/String	If the merchant is only ISO, the QRIS will display ISO text
qrUrl	String	QR Image Url
terminalId	String	ID terminal
additionalInfo	Object	Object additionalInfo
contractId	String	Generated transaction identifier in Winpay system
expiredAt	String	Transaction expiration time in ISO8601 string Format
isStatic	Boolean	Status QRIS

{
  "responseCode": "2004700",
  "responseMessage": "Success",
  "partnerReferenceNo": "ref00000000001",
  "qrContent": null,
  "qrUrl": "https://sandbox-payment.winpay.id/scqr/get_image_qr?payid=1309cd8ceef30410ed1664c8c8c0bb76",
  "terminalId": "TERM GIGIH",
  "additionalInfo": {
    "contractId": "qr2300a3fe-68b8-414b-bf00-8f44ce1cf5d3",
    "expiredAt": "2023-09-06T23:08:56+07:00",
    "isStatic": false
  }
}

List Response Code Create Payment QRIS

Response Code	Response Message	Description
2004700	Success
4004700	Bad Request	General request failed error, including message parsing failed.
4004701	Invalid field format { field name }
4004702	Invalid mandatory field {field name}
4014700	Invalid signature	X-Signature wrong
4044716	Partner not found	X-Partner-ID not registered
4094700	Cannot use same X-EXTERNAL-ID in same day	X-External-ID have been used on the same day
4094701	Duplicate partnerReferenceNo	partnerReferenceNo already used
5004700	General Error	General Error.
5004701	Internal Server Error	Unknown Internal Server Failure, Please retry the process again.

---

2. Query Payment

POST/v1.0/qr/qr-mpm-queryService Code: 51

This service is used to check the payment status of QRIS.

Payload Query Payment

Field Name	Data Type	Mandatory	Description
originalPartnerReferenceNo	String	Y	Transaction number according to the field partnerReferenceNo at the time of create payment Length: 5-50 Allowed Characters: letters (a-z, A-Z), numbers (0-9), underscores (_) and hyphens (-)
serviceCode	String	Y	Code service Create QRIS Payment
additionalInfo	Object	Y	Object additionalInfo
additionalInfo.contractId	String	Y	Generated transaction identifier in Winpay system

{
  "originalPartnerReferenceNo": "gigih-00000081",
  "serviceCode": "47",
  "additionalInfo": {
    "contractId": "qr1906dc67-2e28-4d8a-9546-7cb30d73db2c"
  }
}

Response Query Payment

Parameters	Data Type	Description
responseCode	String	Response Code
responseMessage	String	Message Response
originalPartnerReferenceNo	String	Transaction ID on the Merchant's system.
serviceCode	String	Create QRIS Payment service code
latestTransactionStatus	String	00 - Success, 01 - Initiated, 02 - Paying, 03 - Pending, 04 - Refunded, 05 - Canceled, 06 - Failed, 07 - Not found.
amount	Object
value	String	The total amount of the transaction amount.
currency	String	Currency.
feeAmount	Object
value	String	The nominal amount of admin.
currency	String	Currency.
terminalId	String	NMID code from QRIS merchant.
additionalInfo	Object	Additional information.
issuer	String	Brand Name issuer.
rrn	String	Kode rrn from issuer.
buyerRef	String	Username from issuer.

{
  "responseCode": "2005100",
  "responseMessage": "Success",
  "originalPartnerReferenceNo": "gigih-00000081",
  "serviceCode": "47",
  "latestTransactionStatus": "00",
  "transactionStatusDesc": "Success",
  "paidTime": "2023-08-24T17:03:33+07:00",
  "amount": {
    "value": "2000.00",
    "currency": "IDR"
  },
  "feeAmount": {
    "value": "14.00",
    "currency": "IDR"
  },
  "terminalId": "",
  "additionalInfo": {
    "issuer": "Dana",
    "rrn": "810534941939",
    "buyerReff": "Winpay"
  }
}

List Response Code Query Payment QRIS

Response Code	Response Message	Description
2005100	Success
4005100	Bad Request	General request failed error, including message parsing failed.
4005101	Invalid field format { field name }
4005102	Invalid mandatory field {field name}
4015100	Invalid signature	X-Signature wrong
4045116	Partner not found	X-Partner-ID not registered
4095100	Cannot use same X-EXTERNAL-ID in same day	X-External-ID have been used on the same day
4095101	Duplicate partnerReferenceNo	partnerReferenceNo already used
5005100	General Error	General Error.
5005101	Internal Server Error	Unknown Internal Server Failure, Please retry the process again.

---

3. Cancel Payment

POST/v1.0/qr/qr-mpm-cancelService Code: 77

This service is used to cancel the payment of QRIS.

Payload Cancel Payment

Field Name	Data Type	Mandatory	Description
originalPartnerReferenceNo	String	Y	Transaction ID on the Merchant's system Length: 5-50 Allowed Characters: letters (a-z, A-Z), numbers (0-9), underscores (_) and hyphens (-)
reason	String	Y	Reason to cancel the payment
additionalInfo	Object	Y	Object additionalInfo
additionalInfo.contractId	String	Y	Generated transaction identifier in Winpay system

{
  "originalPartnerReferenceNo": "abctoxfzxctpww",
  "reason": "Gagal",
  "additionalInfo": {
    "contractId": "qre9162f14-b282-4325-a72b-25c755db7322"
  }
}

Response Cancel Payment

Parameter	Data Type	Description
responseCode	String	Response Code
responseMessage	String	Response Message
originalPartnerReferenceNo	String	Transaction ID on the Merchant's system
cancelTime	String	Cancelation time
additionalInfo	Object	Object additionalInfo
additionalInfo.contractId	String	Generated transaction identifier in Winpay system

{
  "responseCode": "2007700",
  "responseMessage": "Request has been processed successfully",
  "originalPartnerReferenceNo": "abctoxfzxctpww",
  "cancelTime": "2024-05-30T18:08:05+07:00",
  "additionalInfo": {
    "contractId": "qre9162f14-b282-4325-a72b-25c755db7322"
  }
}

List Response Code Cancel Payment QRIS

Response Code	Response Message	Description
2007700	Success
4007700	Bad Request	General request failed error, including message parsing failed.
4007701	Invalid field format { field name }
4007702	Invalid mandatory field {field name}
4017700	Invalid signature	X-Signature wrong
4047716	Partner not found	X-Partner-ID not registered
4097700	Cannot use same X-EXTERNAL-ID in same day	X-External-ID have been used on the same day
4097701	Duplicate partnerReferenceNo	partnerReferenceNo already used
5007700	General Error	General Error.
5007701	Internal Server Error	Unknown Internal Server Failure, Please retry the process again.

---

Terminal ID Registration

Merchants can use the Terminal ID feature according to merchant needs with a note that the Terminal ID sent has been registered with Winpay. For Terminal ID registration, you can fill in the following documents: [link]

---

Handle Payment Callback

After the customer makes a payment, Winpay will send a callback to the merchant to notify the payment status. Merchants must implement services to receive callbacks from Winpay.

We will send a callback to the merchant 3x until the merchant responds with the expected response. However, when the first callback attempt is appropriate, we will not send any more callbacks.

Callback Info

POST{yoururl}/v1.0/qr/qr-mpm-notifyService Code: 52

QRIS payment callback service sent by the Winpay system to the Merchant server.

Header Structure

Header	Value	Description
Content-Type	application/json
X-Timestamp	2023-08-24T17:07:05+07:00	ISO8601 String
X-Partner-ID	{partnerId}
X-Signature	{signature}
X-External-ID	{externalId}
Channel-ID	{channelId}

Callback Payload

Parameters	Data Type	Description
originalReferenceNo	String	The transaction ID on the service provider system.
originalPartnerReferenceNo	String	Transaction ID on the Merchant's system.
latestTransactionStatus	String	00 - Success 01 - Initiated 02 - Paying 03 - Pending 04 - Refunded 05 - Canceled 06 - Failed 07 - Not found.
amount	Object
value	String	The total amount of the transaction amount.
currency	String	Currency.
additionalInfo	Object	Additional information.
channel	String	The bank code of the bank to which you want to pay.
contractId	String	The reference code for the corresponding request.
brandName	String	Brand Name issuer.
rrn	String	Kode rrn from issuer.
buyerRef	String	Username from issuer.
nmid	String	NMID Code from QRIS merchant.
terminalId	String	NMID Code from QRIS merchant.
feeAmount	String	Winpay admin fee
nettAmount	String	Total value received by merchants

{
  "originalReferenceNo": "54083",
  "originalPartnerReferenceNo": "abctoxfzxctpq",
  "latestTransactionStatus": "00",
  "amount": {
    "value": "10002.00",
    "currency": "IDR"
  },
  "additionalInfo": {
    "channel": "QRIS",
    "contractId": "qrabf1e3e0-7e30-4ebf-a38f-8cc5d4453fb7",
    "brandName": "DANA",
    "rrn": "527420057612",
    "buyerRef": "WINPAY",
    "terminalId": "A01",
    "feeAmount": "70.01",
    "nettAmount": "9931.99"
  }
}

Expected Results

The expected response from the merchant is as follows:

{
  "responseCode": "2005200",
  "responseMessage": "success"
}