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

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

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

{
 "virtualAccountName":"Jokul Doe",
 "virtualAccountEmail":"jokul@email.com",
 "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"
 }
}

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

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

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

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

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

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

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

{
   "partnerServiceId":"088899",
   "customerNo":"12345678901234567890",
   "virtualAccountNo":"08889912345678901234567890",
   "additionalInfo":{
       "reason":"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

PreviousSignature SNAPNextSNAP Direct Debit

Last updated