SNAP Direct Debit

API Services

Header

Header Request

Header parameters for transaction request.

Parameter	M/O/C	Data Type	Description
Content-Type	M	String	String represents indicate the media type of the resource (e.g. application/json, application/pdf)
X-TIMESTAMP	M	String	Client's current local time in yyyy-MM-ddTHH:mm:ss TZD format
X-SIGNATURE	M	String	Represents signature of a request. Signature details here.
ORIGIN	O	String	Origin Domain www.yourdomain.com
X-PARTNER-ID	M	String (36)	Unique ID for a partner. merchant_id mapped here
X-EXTERNAL- ID	M	String (36)	Numeric String. Reference number that should be unique in the same day
CHANNEL-ID	M	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.

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

Body

Direct Debit Payment

POST /{version}/debit/payment-host-to-host

This API service is used for payment using direct debit.

Service Code: 54

Notes: - *is required

- Current version: v1.0

URL Path

Sandbox: https://debit-sandbox.faspay.co.id/v1.0/debit/payment-host-to-host

Request Body

Parameter	Data Type	Description
partnerReferenceNo*	String(32)	Transaction identifier on service consumer system
bankCardToken	String(560)	Card token for payment (Conditional parameter) Notes: Mandatory for payment channel BRI Direct Debit
validUpTo*	String(25)	The time when the payment will be automatically expired. (ISO8601)
currency*	String(3)	Currency
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 (ISO4217)
amount	Object	An object that contains information about an amount or value within a specific context.
merchantId*	String(5)	Merchant identifier that is unique per each merchant
billDate*	String(25)	Transaction/Order Date (ISO 8601)
channelCode*	String(32)	Payment Channel Code List Channel Code: 814: Maybank2U 704: SAKUKU 714: BRI Direct Debit 713: Shopeepay App 716: Linkaja App 812: OVO 819: DANA 700: CIMB Clicks 701: D-Bank Pro 401: BRI E-PAY 405: BCA KlikPay 302: LinkAja 722: DANA Subs 720: OVO OpenAPI
additionalInfo	Object	Additional Information
items	Object(50)	List item product
email	String(128)	Customer email (Conditional parameter) Notes: Mandatory for payment channel OVO Tokenized
phoneNo	String(30)	Customer Phone Number (Conditional parameter) Notes: Mandatory for payment channel OVO Tokenized
customerName	String(128)	Customer name (Conditional parameter) Notes: Mandatory for payment channel Dana Subs
billDescription*	String(128)	Bill description
externalGoodsId	String(10)	Item code
subscriptionIntervalValue	String(1)	Determine how many months/week (e.g 1/2/3/4)
subscriptionIntervalType	String(10)	Determine months/week (e.g MONTHLY/WEEKLY)
subscriptionMessage	String(50)	Product Subscription detail
product	String(50)	Product name
items	Object(50)	List item product (Conditional parameter) Notes: Mandatory for payment channel LinkAja
amount	Object	An object that contains information about an amount or value within a specific context.(Conditional parameter) Notes: Mandatory for payment channel LinkAja
product	String(50)	Product Name (Conditional parameter) Notes: Mandatory for payment channel LinkAja
id	String(32)	Product Id (Conditional parameter) Notes: Mandatory for payment channel LinkAja
currency	String(3)	Currency (Conditional parameter) Notes: Mandatory for payment channel LinkAja
value	String(16,2)	Net amount of the transaction (Conditional parameter) If it's IDR then value includes 2 decimal digits. e.g. IDR 10.000,- will be placed with 10000.00 (ISO4217) Notes: Mandatory for payment channel LinkAja
quantity	String(32)	Item Quantity (Conditional parameter) Notes: Mandatory for payment channel LinkAja
	String	Items parameters for Dana Subs payment channel (channel code: 722)

Please take note of request parameters there are specific parameters exclusively utilized for particular payment channels, such as for payment channels Dana Subs, LinkAja, and BRI Direct Debit.

Response Parameters Direct Debit Payment

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
appRedirectUrl	C	String	256	Returns an URL scheme to PJP AIS payment page in native app.
webRedirectUrl	C	String	256	Returns a universal link to PJP AIS Payment page. This link is recommended when the Client is unable to implement a check for whether PJP AlS app is installed on the user's device before redirect.
additionalInfo	O	Object		Additional information
merchantId	M	String	5	Merchant identifier that is unique per each merchant
webUrl	C	String	256	The redirect url for the next process, available only on JSON format
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 (ISO4217)
currency	M	String	3	Currency

DD Payment Request Sample

{
    "partnerReferenceNo":"2020102900000000000008",
    "merchantId":"99999",
    "amount":{
        "value":"100.00",
        "currency":"IDR"
    },
    "validUpTo":"2023-03-31T23:00:00+07:00",
    "additionalInfo":{
        "channelCode":"722",
        "billDate":"2023-03-31T23:00:00+07:00",
        "billDescription":"SNAP Transaction",
        "phoneNo":"081274657847",
    }
}

DD Payment Request Sample(Dana Subs)

{
    "partnerReferenceNo": "2020102900000000000001",
    "merchantId": "99999",
    "amount":
    {
        "value": "2000.00",
        "currency": "IDR"
    },
    "validUpTo": "2023-10-12T23:00:00+07:00",
    "additionalInfo":
    {
        "channelCode": "722",
        "billDate": "2023-10-12T14:30:00+07:00",
        "billDescription": "SNAP Transaction",
        "customerName": "John Dokul",
        "phoneNo": "081382826301",
        "email": "[e-mail]",
        "items":
        {
            "product": "Black and white",
            "subscriptionMessage": "box office",
            "subscriptionIntervalType": "MONTHLY",
            "subscriptionIntervalValue": "1",
            "externalGoodsId": "cart-123"
        }
    }
}

DD Payment Request Sample(LinkAja)

{
    "partnerReferenceNo": "2020102900000000000001",
    "merchantId": "99999",
    "amount":
    {
        "value": "2000.00",
        "currency": "IDR"
    },
    "validUpTo": "2023-10-12T23:00:00+07:00",
    "additionalInfo":
    {
        "channelCode": "302",
        "billDate": "2023-10-12T14:30:00+07:00",
        "billDescription": "SNAP Transaction",
        "customerName": "John Dokul",
        "phoneNo": "081382826301",
        "email": "[e-mail]",
        "items":
        {
            "id": "1",
            "product": "Black and white",
            "amount":
            {
                "value": "1000.00",
                "currency": "IDR"
            },
            "quantity": "2",
        }
    }
}

DD Payment Request Sample(BRI Direct Debit)

{
    "bankCardToken":"card_.eyJpYXQiOjE2OTYyMzA2MTIsImlzcyI6IkJhbmsgQlJJIC0gRENFIiwianRpIjoiOWJlNDE3MWYtNTljNS00MzJiLWI5ODktNmQyYWUzNDVhNGIxIiwicGFydG5lcklkIjoi77-9Iiwic2VydmljZU5hbWUiOiJERF9FWFRFUk5BTF9TRVJWSUNFIn0.rJBUCGvNqIuCcvQo_gih9rLEMRBqu74YzWOJU6kt-E3rlXWcUTwFA66dWDxIBUbMMtVT3FbPD3jICSYJ75ULopT8ibUrecafTg4XzYf2-mGglUBCd9KCC3xdo9pccZwG_VYIWeH8gk7cqw-jKs440WYX4Znf5R2-CE7-P13yDqS9-xfoggM4E0H5jvqSrBTswQ5MgfryX5FtdJ0TV0pNPmEZ5p7V_qzQnUFxgZxL6ueYaAF5EfG3bQcBRhHuXJ_YDnhEuH4oGFET5esbM_wT-R40X0flXEBC4JDqripwGt0-KqaTAtfp4zZ0udj-08RmkMPFCJGfNSz1-r3BRGYzcw",
    "partnerReferenceNo":"2020102900000000000001",
    "merchantId":"99999",
    "amount":{
        "value":"1000.00",
        "currency":"IDR"
    },
    "validUpTo":"2023-10-27T23:00:00+07:00",
    "additionalInfo":{
        "channelCode":"714",
        "billDate":"2023-10-27T14:00:00+07:00",
        "billDescription":"SNAP Transaction",
        "customerName":"John Dokul",
        "phoneNo":"081382826301",
        "email":"[e-mail]"
    }
}

DD Payment Request Sample(OVO Tokenized)

{
    "partnerReferenceNo": "2020102900000000000001",
    "merchantId": "99999",
    "amount":
    {
        "value": "2000.00",
        "currency": "IDR"
    },
    "validUpTo": "2023-10-23T23:00:00+07:00",
    "additionalInfo":
    {
        "channelCode": "720",
        "billDate": "2023-10-23T16:30:00+07:00",
        "billDescription": "SNAP Transaction",
        "customerName": "John Dokul",
        "phoneNo": "081382826301",
        "email": "[e-mail]"
    }
}

DD Payment Response Sample

{
    "responseCode": "2005400",
    "responseMessage": "Request has been processed successfully",
    "referenceNo": "9999972270967929",
    "partnerReferenceNo": "2020102900000000000008",
    "webRedirectUrl":"https://debit-staging.faspay.co.id/pws/100003/0830000010100000/f6b92da317d40ffbc40c98ffa80cc924d7b35dd5?trx_id=9999972270967929&merchant_id=99999&bill_no=2020102900000000000008",
    "additionalInfo":
    {
        "merchantId": "99999",
        "amount":
        {
            "value": "100.00",
            "currency": "IDR"
        }
    }
}

To use the OVO Tokenized payment channel, users need to initially activate their phone numbers

Direct Debit Payment Status

POST /{version}/debit/status

This API service is used to check the direct debit payment status.

Service Code: 55

Notes: - *is required

- Current version: v1.0

URL Path

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

Request Body

Parameter	Data Type	Description
originalPartnerReferenceNo*	String(32)	Original transaction identifier on service consumer system
originalReferenceNo*	String(16)	Original transaction identifier on service provider system
serviceCode*	String(2)	Transaction type indicator (service code of the original transaction request)
merchantId*	String(5)	Merchant identifier that is unique per each merchant
additionalInfo	Object	Additional Information
channelCode*	String(32)	Payment Channel Code List Channel Code: 814: Maybank2U 704: SAKUKU 714: BRI Direct Debit 713: Shopeepay App 716: Linkaja App 812: OVO 819: DANA 700: CIMB Clicks 701: D-Bank Pro 401: BRI E-PAY 405: BCA KlikPay 302: LinkAja 722: DANA Subs 720: OVO OpenAPI

Response Parameters Direct Debit Payment Status

Parameter	M/O/C	Data Type	Length	Description
responseCode	M	String	7	Response code
responseMessage	M	String	150	Response description
originalPartnerReferenceNo	M	String	32	Original transaction identifier on service consumer system
originalReferenceNo	M	String	16	Original transaction identifier on service provider system. Must be filled upon successful transaction
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
paidTime	C	String	25	Transaction date : ISO 8601. Notes: Mandatory when payment Happened
additionalInfo	O	Object		Additional information
merchantId	M	String	5	Merchant identifier that is unique per each merchant
amount	C	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
paymentReff	C	String	16	Payment Reff (from Payment Channel). Notes: Mandatory when payment Happened

DD Payment Status Request Sample

{
    "originalPartnerReferenceNo": "2020102900000000000001",
    "originalReferenceNo": "7139999985808445",
    "serviceCode": "55",
    "merchantId": "99999",
    "additionalInfo":
    {
        "channelCode": "713"
    }
}

DD Payment Status Response Sample

{
    "responseCode": "2005500",
    "responseMessage": "Request has been processed successfully",
    "originalPartnerReferenceNo": "2020102900000000000001",
    "originalReferenceNo": "7139999985808445",
    "serviceCode": "55",
    "latestTransactionStatus": "00",
    "transactionStatusDesc": "Success",
    "paidTime": "2023-10-17 15:22:43",
    "additionalInfo":
    {
        "merchantId": "99999",
        "amount":
        {
            "value": "1000.00",
            "currency": "IDR"
        },
        "paymentReff": "164897256163543860"
    }
}

Direct Debit Payment Cancel

POST /{version}/debit/cancel

The Direct Debit Payment Cancel API is used when there are cancelation of the payment.

Service Code: 57

Notes: - *is required

- Current version: v1.0

URL Path

Sandbox: https://debit-sandbox.faspay.co.id/v1.0/debit/cancel

Request Body

Parameter	Data Type	Description
originalpartnerReferenceNo*	String(32)	Transaction identifier on service consumer system
originalReferenceNo*	String(16)	Original transaction identifier on service provider system
merchantId*	String(5)	Merchant identifier that is unique per each merchant
reason*	String(50)	Cancellation reason.
additionalInfo	String	Additional information
channelCode*	String(32)	Payment Channel Code List Channel Code: 814: Maybank2U 704: SAKUKU 714: BRI Direct Debit 713: Shopeepay App 716: Linkaja App 812: OVO 819: DANA 700: CIMB Clicks 701: D-Bank Pro 401: BRI E-PAY 405: BCA KlikPay 302: LinkAja 722: DANA Subs 720: OVO OpenAPI

Response Parameters Direct Debit Payment Cancel

Parameter	M/O/C	Data Type	Length	Description
responseCode	M	String	7	Response code
responseMessage	M	String	150	Response description
originalPartnerReferenceNo	M	String	32	Original transaction identifier on service consumer system
originalReferenceNo	M	String	16	Original transaction identifier on service provider system
cancelTime	C	String	25	Cancel time (ISO-8601). Must be filled if cancelled transaction success
additionalInfo	O	Object		Additional information
merchantId	M	String	5	Unique identifier of merchant in client system.
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	Transaction Status Description

DD Payment Cancel Request Sample

{ 
   "originalPartnerReferenceNo":"2020102900000000000001", 
   "originalReferenceNo":"1653473625364758", 
   "merchantId":"99999", 
   "reason":"Network timeout", 
   "additionalInfo":{ 
       "channelCode":"302" 
   } 
} 

DD Payment Cancel Response Sample

{
    "responseCode": "2005700",
    "responseMessage": "Request has been processed successfully",
    "originalPartnerReferenceNo": "2020102900000000000001",
    "originalReferenceNo": "7139999910232541",
    "cancelTime": "2023-03-21T10:42:40+07:00",
    "additionalInfo":
    {
        "merchantId": "99999",
        "latestTransactionStatus": "05",
        "transactionStatusDesc": "Cancelled"
    }
}

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	Successfull	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	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