SNAP Virtual Account

API Services

Header

The header for transaction request

Parameter	M/O/C	Data 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-MM-ddTHH:mm:ssTZD format
X-SIGNATURE	Mandatory	String	Represents signature of a request. Signature details here.
ORIGIN	Optional	String	Origin Domain www.yourdomain.com
X-PARTNER-ID	Mandatory	String (36)	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)	Channel identifier using Faspay’s API Service (77001)

Header Response

Parameter	M/O/C	Data Type	Description
Content-Type	Mandatory	String	application/json
X-TIMESTAMP	Mandatory	String	Client's current local time in yyyy-MM-ddTHH: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

Create Virtual Account (VA)

POST /{version}/transfer-va/create-va

The API Virtual Account service creates a VA number for transactions.

Service code: 27

Current version: v1.0

*is required

URL Path

Sandbox: https://debit-sandbox.faspay.co.id/v1.0/transfer-va/create-va

Request Body

Parameter	Data Type	Description
virtualAccountName*	String (128)	Customer name
virtualAccountEmail	String (128)	Customer email
virtualAccountPhone	String (30)	Customer's phone number. Format: 62xxxxxxxxxxxxx
trxId*	String (32)	Transaction ID in Partner system
totalAmount	Object
value*	String (16,2)	Transaction Amount. Total Amount with 2 decimal
currency*	String (3)	Currency = IDR
expiredDate	String (25)	Expiration date for Virtual Account. ISO-8601
additionalInfo	Object	Additional Information
billDate*	Datetime (25)	Transaction/ Order Date. local time in yyyy-MM-ddTHH:mm:ssTZD format
channelCode*	Numeric (32)	Payment Channel Code VA ONLY refer to here
billDescription*	String (18)	Bill description

This API Service is available for this channel code:

• 402 -> Permata VA (Dynamic)

• 408 -> Maybank VA (Dynamic)

• 702 -> BCA VA (Dynamic)

• 706 -> Indomaret Payment point (Dynamic)

• 707 -> Alfagroup (Dynamic)

• 708 -> Danamon VA (Dynamic)

• 718 -> BNC VA (Static & Dynamic)

• 800 -> BRI VA (Dynamic)

• 801 -> BNI VA (Static & Dynamic)

• 802 -> Mandiri VA (Dynamic)

• 818 -> Sinarmas VA (Dynamic)

• 825 -> CIMB VA (Dynamic)

• 837 -> BTN VA (Static & Dynamic)

Response

Parameter	Data Type	Descriptions
responseCode*	String (7)	Response code
responseMessage*	String (150)	Response description
virtualAccountData*	Object
partnerServiceId*	String (8)	Derivative of X-PARTNER-ID , similar to company code, 8 digit left padding space
customerNo*	String (20)	Unique number (up to 20 digits)
virtualAccountNo*	String (28)	partnerServiceId (8 digit left padding space) + customerNo (up to 20 digits)
virtualAccountName*	String (128)	Customer name
virtualAccountEmail	String (128)	Customer email
virtualAccountPhone	String (30)	Customer's phone number. Format: 62xxxxxxxxxxxxx
trxId*	String (32)	From create VA request
totalAmount	Object
value*	String (ISO4217) (16,2)	Transaction amount. The total amount with 2 decimals.
currency*	String (3)	Currency. Currency of amount based on ISO 4217.
expiredDate*	String (25)	Expiration date for Virtual Account. ISO-8601
additionalInfo	Object	Additional Information for custom use
billDate*	Datetime (25)	Transaction/ order date
channelCode*	Numeric (32)	Payment channel code VA ONLY
billDescription*	String (18)	Bill description
redirectUrl	String	Merchant call back URL

Create VA - Sample Request

{
 "virtualAccountName":"Jokul Doe",
 "virtualAccountEmail":"[e-mail]",
 "virtualAccountPhone":"6281828384858",
 "trxId":"abcdefgh1234",
 "totalAmount":{
     "value":"12345678.00",
     "currency":"IDR"
 },
 "expiredDate":"2020-12-31T23:59:59-07:00",
 "additionalInfo":{
     "billDate":"2020-12-31T23:59:59-07:00",
     "channelCode":"402",
     "billDescription":"Maintenance"
 }
}

Create VA-Sample Response

{
   "responseCode":"2002500",
   "responseMessage":"Success",
   "virtualAccountData":{
      "partnerServiceId":" 088899",
      "customerNo":"12345678901234567890",
      "virtualAccountNo":"08889912345678901234567890",
      "virtualAccountName":"Jokul Doe",
      "virtualAccountEmail":"[e-mail]",
      "virtualAccountPhone":"6281828384858",
      "trxId":"abcdefgh1234",
      "totalAmount":{
         "value":"12345678.00",
         "currency":"IDR"
      },
      "expiredDate":"20201231T235959Z",
         "additionalInfo":{
            "billDate":"2020-12-31T23:59:59-07:00",
            "channelCode":"402",
            "billDescription":"Maintenance",
            "redirectUrl":"https://dev.faspay.co.id/pws/100003/0830000010100000/5807a17ccd950904ec0a303725fa8a4b36c89e2f?trx_id=9876530200004184&merchant_id=98765&bill_no=98765123456789"
   }
}

Inquiry

POST /{version}/transfer-va/inquiry

The API Virtual Account Inquiry is used to forward user requests to inquire about specific VA information.

Service Code: 24

Notes: - * is required

- Current version: v1.0

URL Path: urlmerchant + /v1.0/transfer-va/inquiry

(example: merchantkita-sandbox.com/v1.0/transfer-va/inquiry)

Request Body

Parameter	Data Type	Description
partnerServiceId*	String (8)	Derivative of X-PARTNER-ID, similar to company code,8 digit left padding space
customerNo*	String (20)	Unique number (up to 20 digits).
virtualAccountNo*	String (28)	partnerServiceId (8 digit left padding space) + customerNo (up to 20 digits)
inquiryRequestId*	String (32)	Unique identifier for this Inquiry. Generated by Faspay.

This API service is available for channel code:

• 402 -> Permata VA (Static)

• 408 -> Maybank VA (Static)

• 702 -> BCA VA (Static)

• 706 -> Indomaret Payment point (Static)

• 707 -> Alfagroup (Static)

• 708 -> Danamon VA (Static)

• 800 -> BRI VA (Static)

• 802 -> Mandiri VA (Static)

• 818 -> Sinarmas VA (Static)

• 825 -> CIMB VA (Static)

Inquiry Response Parameter

Parameter	Data Type	M/O/C	Description
responseCode	String (7)	Mandatory	Response Code
responseMessage	String (150)	Mandatory	Response Description
virtualAccountData	Object	Mandatory
partnerServiceId	String (8)	Mandatory	Derivative of X-PARTNER-ID , similar to company code, 8 digit left padding space
customerNo	String (20)	Mandatory	Unique number. (up to 20 digits)
virtualAccountNo	String (28)	Mandatory	partnerServiceId (8 digit left padding space) + customerNo (up to 20 digits)
virtualAccountName	String (50)	Mandatory	Customer name
virtualAccountEmail	String (255)	Mandatory	Customer email
virtualAccountPhone	String (30)	Mandatory	Customer's phone number. Format: 62xxxxxxxxxxxxx
inquiryRequestId	String (128)	Mandatory	From Inquiry Request
totalAmount	Object	Mandatory
value	String (ISO4217) (16,2)	Mandatory	Transaction Amount. Total Amount with 2 decimal
currency	String (3)	Mandatory	Currency

Inquiry-Sample Request

{
   "partnerServiceId":"  88899",
   "customerNo":"12345678901234567890",
   "virtualAccountNo":"  08889912345678901234567890",
   "inquiryRequestId":"abcdef-123456-abcdef"
}

Inquiry-Sample Response

{
   "responseCode":"2002400",
   "responseMessage":"Success",
   "virtualAccountData":{
      "partnerServiceId":"  088899",
      "customerNo":"12345678901234567890",
      "virtualAccountNo":"  08889912345678901234567890",
      "virtualAccountName":"Johnny Suh",
      "virtualAccountEmail":"[e-mail]",
      "virtualAccountPhone":"6281828384858",
      "inquiryRequestId":"abcdef-123456-abcdef",
      "totalAmount":{
         "value":"12345678.00",
         "currency":"IDR"
      },
   }	
}

Payment

POST /{version}/transfer-va/payment

This service is used to notify payment confirmation for specific VA that has been paid.

Service Code: 25

Notes: - * is required

- Current version: v1.0

URL Path: urlmerchant+/v1.0/transfer-va/payment

(example: merchantkita-sandbox.com/v1.0/transfer-va/payment)

Request Body

Parameter	Data Type	Description
partnerServiceId*	String (8)	Derivative of X-PARTNER-ID, similar to company code, 8 digit left padding space
customerNo*	String (20)	Unique number. (up to 20 digits)
virtualAccountNo*	String (28)	partnerServiceId (8 digit left padding space) + customerNo (up to 20 digits)
paymentRequestId*	String (128)	Unique identifier generated by Faspay. If Payment comes from the Inquiry process, this value must be the same with inquiryRequestId.
paidAmount*	Object
value*	String (16,2)	Paid Amount with 2 decimal
currency*	String (3)	Currency
trxDateTime*	Date (25)	PJP internal system datetime with timezone, which follows the ISO-8601 standard
referenceNo*	String (16)	Transaction ID (Issued/generated by Faspay (Media Indonusa))

This API service is available for channel code:

• 402 -> Permata VA (Static)

• 408 -> Maybank VA (Static)

• 702 -> BCA VA (Static)

• 706 -> Indomaret Payment point (Static)

• 707 -> Alfagroup (Static)

• 708 -> Danamon VA (Static)

• 800 -> BRI VA (Static)

• 802 -> Mandiri VA (Static)

• 818 -> Sinarmas VA (Static)

• 825 -> CIMB VA (Static)

Payment Response Parameter

Parameter	Data Type	Description
responseCode*	String (7)	Response Code
responseMessage*	String (150)	Response Description
virtualAccountData*	Object
partnerServiceId*	String (8)	Derivative of X-PARTNER-ID , similar to company code, 8 digit left padding space
customerNo*	String (20)	Unique number. (up to 20 digits)
virtualAccountNo*	String (28)	partnerServiceId (8 digit left padding space) + customerNo (up to 20 digits)
virtualAccountName*	String (255)	Customer name
paymentRequestId*	String (128)	From Payment Request
paidAmount*	Object
value*	String (ISO4217) (16,2)	Transaction Amount. From Payment Request
currency*	String (3)	Currency

Payment-Sample Request

{
   "partnerServiceId":"  088899",
   "customerNo":"12345678901234567890",
   "virtualAccountNo":"  08889912345678901234567890",
   "paymentRequestId":"abcdef-123456-abcdef",
   "paidAmount":{
      "value":"12345678.00",
      "currency":"IDR"
   },
   "trxDateTime":"20201231T235959Z"
   "referenceNo":"123456789012345"
}

Payment-Sample Response

{
   "responseCode":"2002500",
   "responseMessage":"Success",
   "virtualAccountData":{
      "partnerServiceId":" 088899",
      "customerNo":"12345678901234567890",
      "virtualAccountNo":"  08889912345678901234567890",
      "virtualAccountName":"Johnny Suh",
      "paymentRequestId":"abcdef-123456-abcdef",
      "paidAmount":{
         "value":"12345678.00",
         "currency":"IDR"
      }
   }
}

Inquiry Status

POST /{version}/transfer-va/status

Merchants use this service to check the status of transfers made.

Service code: 26

Current version: v1.0

*is required

URL Path

Sandbox: https://debit-sandbox.faspay.co.id/v1.0/transfer-va/status

Request Body

Parameter	Data Type	Descriptions
partnerServiceId*	String (8)	Derivative of X-PARTNER-ID, similar to company code, 8 digit left padding space
customerNo*	String (20)	Unique number (up to 20 digits)
virtualAccountNo*	String (28)	partnerServiceId (8 digit left padding space) + customerNo (up to 20 digits)
inquiryRequestId	String (32)	Unique identifier from Inquiry (Conditional parameter)
additionalInfo*	Object
channelCode*	Sring (32)	Payment Channel Code VA ONLY refer to here
trxId	String (32)	Transaction ID in Partner system (Conditional parameter) Notes : Mandatory if the transaction from Create VA

Inquiry Status Response Parameter

Parameter	Data Type	M/O/C	Description
responseCode	String (7)	Mandatory	Response Code
responseMessage	String (150)	Mandatory	Response Description
virtualAccountData	Object	Mandatory
paymentFlagReason	Object	Mandatory	Reason for Payment Status multi language
english	String (32)	Mandatory	Reason for Payment Status in English
partnerServiceId	String (8)	Mandatory	Derivative of X-PARTNER-ID , similar to company code, 8 digit left padding space
customerNo	String (20)	Mandatory	Unique number (up to 20 digits)
virtualAccountNo	String (28)	Mandatory	partnerServiceId (8 digit left padding space) + customerNo (up to 20 digits)
inquiryRequestId	String (128)	Conditional	Unique identifier from Inquiry
paymentRequestId	String (16)	Conditional	Unique identifier for this Payment from Faspay. Mandatory if Payment happened.
paidAmount	Object	Mandatory
value	String (ISO4217) (16,2)	Mandatory	Paid Amount with 2 decimal
currency	String (3)	Mandatory	Currency. Currency of amount based on ISO 4217
transactionDate	Date (25)	Conditional	Mandatory when the payment happened
paymentFlagStatus	String (2)	Mandatory	Status for Payment Flag
additionalInfo	Object	Mandatory
channelCode	String (32)	Mandatory	Payment Channel Code VA ONLY

Status Code List

Status Code	Status Reason
00	Success
01	Paying
03	Pending
04	Refunded
05	Canceled
06	Failed
07	Expired
07	Not Found

Inquiry Status-Request Sample

{
 "partnerServiceId":"088899",
 "customerNo":12345678901234567890,
 "virtualAccountNo":"08889912345678901234567890",
 "inquiryRequestId":"abcdef-123456-abcdef",
 "additionalInfo":{
      "channelCode":"402",
      "trxId":"9876540000001115"
 }
}

Inquiry Status-Response Sample

{
   "responseCode":"2002600",
   "responseMessage":"Success",
   "virtualAccountData":{
      "paymentFlagReason":{
         "english":"Success",
      },
      "partnerServiceId":"  088899",
      "customerNo":"12345678901234567890",
      "virtualAccountNo":"  08889912345678901234567890",
      "inquiryRequestId":"abcdef-123456-abcdef",
      "paymentRequestId":"abcdef-123456-abcdef",
      "paidAmount":{
          "value":"12345678.00",
          "currency":"IDR"
       },
      "transactionDate":"20201231T235959Z",
      "paymentFlagStatus":"00",
      "additionalInfo":{
          "channelCode":"402"
   }
}
}

Delete Virtual Account

DELETE /{version}/transfer-va/delete-va

This service is used to delete the VA number permanently.

Service code: 31

Current version: v1.0

*is required

URL Path

Sandbox: https://debit-sandbox.faspay.co.id/v1.0/transfer-va/delete-va

Request Body

Parameter	Data Type	Descriptions
partnerServiceId*	String (8)	Derivative of X-PARTNER-ID, similar to company code,8 digit left padding space
customerNo*	String (20)	A Unique number (up to 20 digits).
virtualAccountNo*	String (28)	partnerServiceId (8 digit left padding space) + customerNo (up to 20 digits)
additionalInfo	Object	From inquiry responses
reason*	String (50)	Payment Cancel Reason's Message
trxId*	String (32)	Transaction ID in Partner system

Delete VA Response Parameter

Parameter	Data Type	M/O/C	Description
responseCode	String (7)	Mandatory	Response Code
responseMessage	String (150)	Mandatory	Response Description
virtualAccountData	Object	Mandatory
partnerServiceId	String (8)	Mandatory	Derivative of X-PARTNER-ID, similar to company code, 8 digit left padding space
customerNo	String (20)	Mandatory	Unique number (up to 20 digits)
virtualAccountNo	String (28)	Mandatory	partnerServiceId (8 digit left padding space) + customerNo (up to 20 digits)
additionalInfo	Object (unlimited)	Optional	From Inquiry Response
billNo	String (32)	Mandatory	Bill number from partner
trxStatusCode	String (5)	Mandatory	Transaction Status
trxStatusDesc	String (32)	Mandatory	Transaction Status Description

Delete VA-Request Sample

{
   "partnerServiceId":"088899",
   "customerNo":"12345678901234567890",
   "virtualAccountNo":"08889912345678901234567890",
   "additionalInfo":{
       "reason":"Order Canceled"
   }
}

Delete VA-Response Sample

{
   "responseCode":"2003100",
   "responseMessage":"Success",
   "virtualAccountData":{
      "partnerServiceId":"088899",
      "customerNo":"12345678901234567890",
      "virtualAccountNo":"08889912345678901234567890",
      "additionalInfo":{
          "billNo":"98765123456789",
          "trxStatusCode":"3",
          "trxStatusDesc":"Order Canceled"
      }
   }
}

Payment Notification

Payment notification from Faspay to the merchant backend will also trigger an event of transaction status updating to ensure the 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

Response Code

Component	Data 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 ToCardholer	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 X-EXTERNAL-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	Time	timeout from the issuer