SNAP QRIS

API Services

Header

Header Request

Header parameters for transaction request.

Field	Attribute	Type	Description
Content-Type	Mandatory	String	String represents indicate the media type of the resource (e.g. application/json, application/pdf)
X-TIMESTAMP	Mandatory	String	Client's current local time in yyyy-MMddTHH:mm:ssTZD format
X-SIGNATURE	Mandatory	String	Represents signature of a request. Signature Type used: Asymetric-Signature : SHA256withRSA (Private_Key, stringToSign) dengan formula stringToSign = HTTPMethod +”:“+ EndpointUrl +":“+ Lowercase(HexEncode(SHA256(minify(RequestBody)))) + ":“ + TimeStamp
ORIGIN	Optional	String	Origin Domain www.yourdomain.com
X-PARTNER-ID	Mandatory	String (5)	Unique ID for a partner. merchant_id mapped here
X-EXTERNAL- ID	Mandatory	String (36)	Numeric String. Reference number that should be unique in the same day
CHANNEL-ID	Mandatory	String (5)	Faspay’s channel id Device identification on which the API services is currently being accessed by the end user (customer)

Header Response

Header parameters for transaction response.

Field	Attribute	Type	Description
Content-Type	Mandatory	String	application/json
X-TIMESTAMP	Mandatory	String	Client's current local time in yyyy-MMddTHH:mm:ssTZD format

Header Request Sample

Content-type: application/json  
X-TIMESTAMP: 2020-12-17T10:55:00+07:00  
X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5  
ORIGIN: www.hostname.com  
X-PARTNER-ID: 82150  
X-EXTERNAL-ID: 41807553358950093184162180797837  
CHANNEL-ID: 88001  

Header Response Sample

Content-type: application/json
X-TIMESTAMP: 2020-12-21T10:30:34+07:00  Content-type: application/json  
X-TIMESTAMP: 2020-12-17T10:55:00+07:00  
X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5  
ORIGIN: www.hostname.com  
X-PARTNER-ID: 82150  
X-EXTERNAL-ID: 41807553358950093184162180797837  
CHANNEL-ID: 88001  

Body

Generate QRIS

POST /{version}/qr/qr-mpm-generate

The generate QRIS API is used for generating QRIS code payment.

Service Code: 47

Notes: - *is required

- Current version: v1.0

URL Path

Sandbox: https://debit-sandbox.faspay.co.id/v1.0/qr/qr-mpm-generate Production: https://web.faspay.co.id/v1.0/qr/qr-mpm-generate

Request Body

Name	Type	Description
partnerReferenceNo*	String (32)	Transaction identifier on service consumer system
amount	Object	An object that contains information about an amount or value within a specific context.
value*	String (16,2)	Net amount of the transaction. If it's IDR then value includes 2 decimal digits. e.g. IDR 10.000,- will be placed with 10000.00 with 2 decimal (ISO4217)
currency*	String (3)	Currency
merchantId*	String (5)	Merchant identifier that is unique per each merchant
validityPeriod*	String (25)	The time when the QRIS valid. (ISO-860)
additionalInfo	Object	Merchant identifier that is unique per each merchant
billDate*	String (25)	Transaction/ Order Date. (ISO-8601)
billDescription*	String (128)	Bill description
channelCode*	String (32)	Payment Channel Code List Channel Code: 715 Linkaja QRIS 711 ShopeePay QRIS

Response Parameters Generate QRIS

Parameter	M/O/C	Type	Length	Description
responseCode	M	String	7	Response code
responseMessage	M	String	150	Response description
referenceNo	M	String	16	Transaction identifier on service provider system. Must be filled upon successful transaction
partnerReferenceNo	M	String	32	Transaction identifier on service consumer system
qrUrl	C	String	256	QR URL for download QR Image Will be returned only for direct merchant.
additionalInfo	O	Object		Additional information
qrImageUrl	M		256	Redirect URL to display QR Image in Faspay page.
merchantId	M	String	5	Merchant identifier that is unique per each merchant
amount	M	Object		An object that contains information about an amount or value within a specific context.
value	M	String	16,2	Net amount of the transaction. If it's IDR then value includes 2 decimal digits. e.g. IDR 10.000,- will be placed with 10000.00 with 2 decimal (ISO4217)
currency	M	String	3	Currency

QRIS Payment Request Sample

{
    "partnerReferenceNo": "2020102900000000000001",
    "amount":
    {
        "value": "1000.00",
        "currency": "IDR"
    },
    "merchantId": "99999",
    "validityPeriod": "2023-10-03T23:00:00+07:00",
    "additionalInfo":
    {
        "billDate": "2023-10-03T17:00:00+07:00",
        "billDescription": "Payment #12345678",
        "channelCode": "711"
    }
}

QRIS Payment Response Sample

{
    "responseCode": "2004700",
    "responseMessage": "Request has been processed successfully",
    "referenceNo": "1999971176208743",
    "partnerReferenceNo": "2020102900000000000001",
    "qrUrl":"https://debit-staging.faspay.co.id/__assets/qr/99999-1999971176208743.png",
    "additionalInfo":
    {
        "qrImageUrl":"https://debit-   staging.faspay.co.id/pws/100003/0830000010100000/a32c3d417ec84d6e977484ab02192d26fd58563a?trx_id=1999971176208743&merchant_id=99999&bill_no=2020102900000000000001",
        "merchantId": "99999",
        "amount":
        {
            "value": "1000.00",
            "currency": "IDR"
        }
    }
}

Query Payment

POST /{version}/qr/qr-mpm-query

The query payment API is used to check the transaction status.

Service Code: 51

Notes: - *is required

- Current version: v1.0

URL Path

Sandbox: https://debit-sandbox.faspay.co.id/v1.0/qr/qr-mpm-query Production: https://web.faspay.co.id/v1.0/qr/qr-mpm-query

Request Body

Name	Type	Description
originalReferenceNo*	String(16)	Original transaction identifier on service provider system
channelCode*	String(32)	Payment Channel Code List Channel Code: 715 Linkaja QRIS 711 ShopeePay QRIS
additionalInfo	Object	Additional information
merchantId*	String(5)	Merchant identifier that is unique per each merchant
serviceCode*	String(2)	Transaction type indicator (service code of the original transaction request)
originalPartnerReferenceNo*	String(32)	Original transaction identifier on service consumer system

200: OK

Response Parameters Query Payment

Parameter	M/O/C	Type	Length	Description
responseCode	M	String	7	Response code
responseMessage	M	String	150	Response description
originalReferenceNo	M	String	16	Original transaction identifier on service provider system. Must be filled upon successful transaction
paidTime	C	DateTime	25	Transaction date (yyyyMMddHHmmss) ISO-8601. Notes: Mandatory when payment Happened
amount	O	Object		An object that contains information about an amount or value within a specific context.
value	C	String	16,2	Amount of customer payment. If it's IDR then value includes 2 decimal digits. e.g. IDR 10.000,- will be placed with 10000.00. Notes: Mandatory when payment Happened (ISO4217)
currency	C	String	3	Currency
originalPartnerReferenceNo	M	String	32	Original transaction identifier on service consumer system
serviceCode	M	String	2	Transaction type indicator (service code of the original transaction request)
latestTransactionStatus	M	String	2	Status code list: 00 - Success 01 - Initiated 03 - Pending 04 - Refunded 05 - Canceled 06 - Failed 07 - Not found 07 - Expired
transactionStatusDesc	M	String	32	Description status transaction
additionalInfo	O	Object		Additional information
paymentReff	C	String	16	Payment Reff (from Payment Channel). Mandatory when payment Happened
merchantId	M	String	5	Merchant identifier that is unique per each merchant

Query Payment Request Sample

{
    "originalReferenceNo":"1999971176208743",
    "originalPartnerReferenceNo":"2020102900000000000001",
    "serviceCode":"47",
    "merchantId":"99999",
    "additionalInfo":{
        "channelCode":"711"
    }
}

Query Payment Response Sample

{
    "responseCode": "2005100",
    "responseMessage": "Request has been processed successfully",
    "originalReferenceNo": "1999971176208743",
    "originalPartnerReferenceNo": "2020102900000000000001",
    "serviceCode": "47",
    "latestTransactionStatus": "00",
    "transactionStatusDesc": "Success",
    "paidTime":"2023-10-03 14:21:03",
    "amount":{
        "value":"1000.00",
        "currency":"IDR"
    }
    "additionalInfo": {
        "paymentReff":"158745496507764240"
        "merchantId": "99999"
    }
}

Payment Notification

Payment notification from Faspay to merchant backend will also be triggered an event of transaction status getting updated, to ensure merchant is securely informed. Please provide the URL and make sure it's already registered on Faspay system.

The detailed API reference can be found here

Integration Requirement

Integration need API & Credential Key.

Response Code

Response status consists of 2 components, the code (response code) and the description (response message).

Component	Type	Length	Description
responseCode	String	7	response code = HTTP status code + service code + case code
responseMessage	String	150

Response Code List

Category	HTTP Code	Service Code	Case Code	Response Message	Description
Success	200	any	0	Successful	Successful
Success	202	any	0	Request In Progress	Transaction still on process
System	400	any	0	Bad Request	General request failed error, including message parsing failed.
Message	400	any	1	Invalid Field Format {field name}	Invalid format
Message	400	any	2	Invalid Mandatory Field {field name}	Missing or invalid format on mandatory field
System	401	any	0	Unauthorized. [reason]	General unauthorized error (No Interface Def, API is Invalid, Oauth Failed, Verify Client Secret Fail, Client Forbidden Access API, Unknown Client, Key not Found)
System	401	any	1	Invalid Token (B2B)	Token found in request is invalid (Access Token Not Exist, Access Token Expiry)
System	401	any	2	Invalid Customer Token	Token found in request is invalid (Access Token Not Exist, Access Token Expiry)
System	401	any	3	Token Not Found (B2B)	Token not found in the system. This occurs on any API that requires token as input parameter
System	401	any	4	Customer Token Not Found	Token not found in the system. This occurs on any API that requires token as input parameter
Business	403	any	0	Transaction Expired	Transaction expired
System	403	any	1	Feature Not Allowed [Reason]	This merchant is not allowed to call Direct Debit APIs
Business	403	any	2	Exceeds Transaction Amount Limit	Exceeds Transaction Amount Limit
Business	403	any	3	Suspected Fraud	Suspected Fraud
Business	403	any	4	Activity Count Limit Exceeded	Too many request, Exceeds Transaction Frequency Limit
Business	403	any	5	Do Not Honor	Account or User status is abnormal
System	403	any	6	Feature Not Allowed At This Time. [reason]	Cut off In Progress
Business	403	any	7	Card Blocked	The payment card is blocked
Business	403	any	8	Card Expired	The payment card is expired
Business	403	any	9	Dormant Account	The account is dormant
Business	403	any	10	Need To Set Token Limit	Need to set token limit
System	403	any	11	OTP Blocked	OTP has been blocked
System	403	any	12	OTP Lifetime Expired	OTP has been expired
System	403	any	13	OTP Sent To Cardholer	initiates request OTP to the issuer
Business	403	any	14	Insufficient Funds	Insufficient Funds
Business	403	any	15	Transaction Not Permitted.[reason]	Transaction Not Permitted
Business	403	any	16	Suspend Transaction	Suspend Transaction
Business	403	any	17	Token Limit Exceeded	Purchase amount exceeds the token limit set prior
Business	403	any	18	Inactive Card/Account/Customer	Indicates inactive account
Business	403	any	19	Merchant Blacklisted	Merchant is suspended from calling any APIs
Business	403	any	20	Merchant Limit Exceed	Merchant aggregated purchase amount on that day exceeds the agreed limit
Business	403	any	21	Set Limit Not Allowed	Set limit not allowed on particular token
Business	403	any	22	Token Limit Invalid	The token limit desired by the merchant is not within the agreed range between the merchant and the Issuer
Business	403	any	23	Account Limit Exceed	Account aggregated purchase amount on that day exceeds the agreed limit
Business	404	any	0	Invalid Transaction Status	Invalid transaction status
Business	404	any	1	Transaction Not Found	Transaction not found
System	404	any	2	Invalid Routing	Invalid Routing
System	404	any	3	Bank Not Supported By Switch	Bank not supported by switch
Business	404	any	4	Transaction Cancelled	Transaction is cancelled by customer
Business	404	any	5	Merchant Is Not Registered For Card Registration Services	Merchant is not registered for Card Registration services
System	404	any	6	Need To Request OTP	Need to request OTP
System	404	any	7	Journey Not Found	The journeyID cannot be found in the system
Business	404	any	8	Invalid Merchant	Merchant does not exist or status abnormal
Business	404	any	9	No Issuer	No issuer
System	404	any	10	Invalid API Transition	Invalid API transition within a journey
Business	404	any	11	Invalid Card/Account/Customer [info]/Virtual Account	Card information may be invalid, or the card account may be blacklisted, or Virtual Account number maybe invalid.
Business	404	any	12	Invalid Bill/Virtual Account [Reason]	The bill is blocked/ suspended/not found. Virtual account is suspend/not found.
Business	404	any	13	Invalid Amount	The amount doesn't match with what supposed to
Business	404	any	14	Paid Bill	The bill has been paid
System	404	any	15	Invalid OTP	OTP is incorrect
Business	404	any	16	Partner Not Found	Partner number can't be found
Business	404	any	17	Invalid Terminal	Terminal does not exist in the system
Business	404	any	18	Inconsistent Request	Inconsistent request parameter found for the same partner reference number/transaction id It can be considered as failed in transfer debit, but it should be considered as success in transfer credit. Considered as success: '- Transfer credit = (i) Intrabank transfer; (ii) Interbank transfer; (iii) RTGS transfer; (iv) SKNBI transfer; '- Virtual account = (i) Payment VA; (ii) Payment to VA; '- Transfer debit = (i) Refund payment; (ii) Void; Considered as failed: '- Transfer credit = (i) Transfer to OTC; '- Transfer debit = (i) Direct debit payment; (ii) QR CPM payment; (iii) Auth payment; (iv) Capture;
Business	404	any	19	Invalid Bill/Virtual Account	The bill is expired. Virtual account is expired.
System	405	any	0	Requested Function Is Not Supported	Requested function is not supported
Business	405	any	1	Requested Opearation Is Not Allowed	Requested operation to cancel/refund transaction Is not allowed at this time.
System	409	any	0	Conflict	Cannot use same XEXTERNAL-ID in same day
System	409	any	1	Duplicate partnerReferenceNo	Transaction has previously been processed indicates the same partnerReferenceNo already success
System	429	any	0	Too Many Requests	Maximum transaction limit exceeded
System	500	any	0	General Error	General Error
System	500	Any	1	Internal Server Error	Unknown Internal Server Failure, Please retry the process again
System	500	Any	2	External Server Error	Backend system failure, etc
System	504	any	0	Timeout	timeout from the issuer