Direct API

Direct Debit

Direct Debit is a payment method done automatically and is usually used for recurring payments. The funds in your account will be automatically deducted according to the agreed schedule. Espay Payment Gateway provides integration services that can help you meet your needs through Autodebit. There are three services that you need to integrate:

Account Binding
Binding Notify
Autodebit

Before Integration

Make sure you have received the credentials from the Espay team.

Integration Steps

You can use the following steps to integrate with Direct API – Direct Debit.

1. Display Payment Method

Inquiry Merchant Info is a service that helps find active bank and product codes. This service allows you to customize the user interface (UI) when selecting a payment method. Learn Inquiry Merchant Info

2. Generate Signature Asymmetric

Every request you send will be validated by the Espay Payment Gateway using the signature parameters you have created. Learn how to make a Signature Asymmetric

Preparing the Header for Each Service

The header is a section always present in every request and response. Ensure that each service you use has a header with the correct format.

Name	Type	Mandatory	Description
Content-Type	String	Y	Content of your request body. Example: application/json
X-TIMESTAMP	String (25)	Y	Customer's current local date and time. Format: yyyy-MM-ddThh:mi:ssTZD (ISO 8601) Example: 2024-03-14T07:49:28+07:00
X-SIGNATURE	String (255)	Y	Code used to validate transactions. Learn Signatures Asymmetric
X-EXTERNAL-ID	String (32)	Y	Numeric String. Reference number that should be unique on the same day.
X-PARTNER-ID	String (50)	Y	Merchant Code from Espay team. Example: SGWYESSISHOP
CHANNEL-ID	String (5)	Y	Channel id. Value: Espay
Authorization-Customer	String (150)	C	Access Token B2B2C. Espay -> Bank

Y: Yes, O: Optional, C: Conditional

Registering an Account (Account Binding)

To connect with Direct Debit, you need to register the data of customers who will use the service. The data will then be verified and validated to ensure its accuracy.

Type	Value
Service Code	07
Name	API Account Binding
HTTP Method	POST

Flow

You send the required parameters to make a request, and Espay Payment Gateway will respond in JSON format.

Environment

Environment	URL
Sandbox Port of HTTPS (443)	https://sandbox-api.espay.id/apidirectdebit/v1.0/debit/registra tion-account-binding
Production Port of HTTPS (443)	https://api.espay.id/apidirectdebit/v1.0/debit/registra tion-account-binding

Request Parameters

Parameter	Type	Mandatory	Description
partnerReferenceNo	String (64)	Y	Original merchant order id / payment id.
merchantId	String (64)	Y	Partner code. Value: "ESPAY"
phoneNo	String (13)	Y	Customer phone number. Format: 62xxxxxxxxxxxx
authCode	String (128)	Y	Auth Code from Get auth code service.
additionalInfo	Object
productCode	String (16)	Y	Product code. Click here
accountToken	String (64)	Y	Registered Customer id.
ktpFile	base64encoded	C	KTP / ID Card image. Format: Base64 encoded. The maximum compression limit is up to 50kb.
npwpFile	base64encoded	C	NPWP image. Format: Base64 encoded. The maximum compression limit is up to 50kb.
pdfFile	base64encoded	C	File PDF. Format: Base64 encoded.
amount	String (16.2)	C
value	String (16.2)	C	Amount binding. Format: Decimal .00 (ISO 4217) Example: 150000.00
currency	String (3)	C	Transaction currency code. Format: Rupiah: IDR
customerAccountNumber	String (24)	C	Account Number Customer for Binding
customerName	String (100)	C	Account Name Customer for Binding.
debitType	String (1)	C	Tipe debit. Format: Fix: F If debitType = F, then amount “nominal transaksi”. Variable: V JIf debitType = V, then amount “0”.

Y: Yes, O: Optional, C: Conditional

Response Parameters

Parameter	Type	Mandatory	Description
responseCode	String (7)	Y	Response Code. Format: HTTP Code + Service Code + Error Code Example: 200+07+00 = 2000700.
responseMessage	String (150)	Y	Response description.
accessTokenInfo	Object	Y
accessToken	String (128)	Y	Access Token
expiresIn	String (25)	Y	Access Token Expired. Format: yyyy-MM-ddThh:mi:ssTZD (ISO 8601) Example: 2024-03-14T07:49:28+07:00
refreshToken	String (128)	Y	Refresh Token.
reExpiresIn	String (25)	Y	Refresh Token Expired. Format: yyyy-MM-ddThh:mi:ssTZD (ISO 8601) Example: 2024-03-14T07:49:28+07:00
tokenStatus	String (64)	O	Token status. Format: Active: Active Non Active: INACTIVE
AdditionalInfo	Object
accountInfo
accountType	String (64)	O	Account Type.
accountId	String (64)	O	Account Number.
linkId	String (64)	O	Link/Binding Id.
accountToken	String (64)	O	Registered Customer id.
redirectUrl	String (255)	O	Web form Redirect Url.

Y: Yes, O: Optional, C: Conditional

Receiving Registration Notifications (Binding Notify)

Type	Value
Service Code	56
Name	Binding Notify
HTTP Method	POST

Flow

Each time you register through Account Binding, Espay will send a request to your server via the Binding Notify URL that you have registered. You are required to respond in JSON format using the provided structure.

Environment

URL Merchant	Endpoint	Description
https://yourdomain.com	.../apidirectdebit/v1.0/debit/notify	Merchant domain URL. Port of HTTPS (443). TLS 1.2

Request Parameters

Parameter	Type	Mandatory	Description
originalPartnerReferenceNo	String (64)	Y	Merchant Reference No from Autodebit / Registration / Payment.
originalReferenceNo	String (64)	Y	ReferenNo from Espay.
merchantId	String (28)	Y	Merchant code from Espay team. Example: SGWYESSISHOP
amount	Object	Y
value	String (16.2)	Y	Amount registration. Format: Desimal .00 (ISO 4217) Example: 150000.00
currency	String (3)	Y	Transaction currency code. Format: Rupiah: IDR
latestTransactionStatus	String (2)	Y	Latest Transaction Status. Format: Success / Approve: 00 Failed / Reject: 06
additionalInfo	Object
accountToken	String (64)	Y	Account Token Registration / Binding.
productCode	String (64)	Y	Product code. Click here
statusRegistration	String (5)	Y	Status Registration for Autodebit Registration. Format: Approve: A Reject: R
reason	String (100)	Y	Reason Registration.

Y: Yes, O: Optional, C: Conditional

Response Parameters

Parameter	Type	Mandatory	Description
responseCode	String (7)	Y	Response Code. Format: HTTP Code + Service Code + Error Code Example: 200+56+00 = 2000700.
responseMessage	String (150)	Y	Response description.
approvalCode	String (20)	O	Approval Code.

Y: Yes, O: Optional, C: Conditional

Payment Process (Autodebit)

Type	Value
Service Code	54
Name	Direct Debit Payment
HTTP Method	POST

Flow

You send the required parameters to make a request, and Espay Payment Gateway will respond in JSON format.

Environment

Environment	URL
Sandbox Port of HTTPS (443)	https://sandbox-api.espay.id/apidirectdebit/v1.0/debit/payment-host-to-host
Production Port of HTTPS (443)	https://api.espay.id/apidirectdebit/v1.0/debit/payment-host-to-host

Request Parameters

Parameter	Type	Mandatory	Description
partnerReferenceNo	String (32)	Y	Merchant Reference No.
merchantId	String (28)	Y	Merchant code from Espay team. Example: SGWYESSISHOP
amount	Object	Y
value	String (16.2)	Y	Paid amount. Format: Desimal .00 (ISO 4217) Example: 150000.00
currency	String (3)	Y	Transaction currency code. Format: Rupiah: IDR
urlParam	Object
url	String (255)	Y	Callback URL to merchant page (Thank you page).
type	String (32)	Y	URL type. Value: PAY_RETURN
isDeeplink	String (1)	Y	Deeplink Status. The only supported value for SNAP is N (No). Format: Yes: Y No: N
payOptionDetails	Object
payMethod	String (64)	Y	Bank code. Click here
payOption	String (64)	Y	Bank product. Click here
transAmount	Object
value	String (16.2)	Y	Paid amount. Format: Desimal .00 (ISO 4217) Example: 150000.00
currency	String (3)	Y	Transaction currency code. Format: Rupiah: IDR
feeAmount	Object
value	String (16.2)	Y	Transaction fee. Format: Desimal .00 (ISO 4217) Example: 4400.00
currency	String (3)	Y	Transaction currency code. Format: Rupiah: IDR
additionalInfo	Object
productCode	String (20)	Y	Product code. Click here
accountName	String (20)	Y	Account Bank Name Customer.
payType	String (64)	Y	Pay Type. Value: AUTODEBIT
debitType	String (64)	Y	Debit Type. Format: Fix: F Variable: V

Y: Yes, O: Optional, C: Conditional

Response Parameters

Parameter	Type	Mandatory	Description
responseCode	String (7)	Y	Response Code. Format: HTTP Code + Service Code + Error Code Example: 200+54+00 = 2005400.
responseMessage	String (150)	Y	Response description.
partnerReferenceNo	String (64)	Y	Merchant Reference No.
originalReferenceNo	String (2048)	O	Original Reference No.
referenceNo	String (2048)	O	Reference No.
approvalCode	String (64)	Y	Approval Code from ESPAY.

Y: Yes, O: Optional, C: Conditional

5. After Payment

Espay Payment Gateway provides an optional API that you can use to support other payment needs.

Direct Debit – Cancel
Direct Debit – Check Status
Direct Debit – Account Unbinding

Sample Headers


Content-Type:application/json
X-TIMESTAMP:2024-03-14T07:49:28+07:00
X-SIGNATURE:B0VF16Vjsxxb/rUcgZM401XH7Z9cB5mhmYnfMdkblq84akTybh9Bakmb9nJD/ttrADmUbDJDW7s6E7yYTEATCdbjPs3+xEgA53gdcM7aJP9qPcfe79GankZrRvROcICdxuN2rjYZOuzvJ9SrfG/llmGic1bM627Eiz/G4pf7e8r6MOfsBRoUqH+moBGcw+/Xh2V8hqfb64hIzb7JZNZnVV7fQN6NZ8VAWLzjmo8PFLjg390wL3Fybr0GJwHohCaxBhv6P0nxVP+P9psnljKWt8EYHHWizgSVinUa9kncRq2MEpvLwujGcSG/MteZhcKXXYNGbCO5u7qato19fWwxaw==
X-EXTERNAL-ID:6b13fe32-0a63-4af2-911b-e6c9a0f9c7f4
X-PARTNER-ID:SGWYESSISHOP
CHANNEL-ID:ESPAY

Sample Request - Account Binding


{
    "partnerReferenceNo": "156436436456544",
    "merchantId": "ESPAY",
    "phoneNo": "087888XXXXX",
    "authCode": "YT1Ex4UGXzAcxw5Ve8l4QNLH2GmGPN",
    "additionalInfo": {
        "productCode": "DANAMONDIRECTDEBIT",
        "accountToken": "ESP230929094046rRD5mCT1IZkrBhJb5",
        "ktpFile":"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAP//////////////////////////////////////////////////////////////////////////////////////2wBDAf//////////////////////////////////////////////////////////////////////////////////////wAARCADqATkDASIAAhEBAxEB/8QAFwABAQEBAAAAAAAAAAAAAAAAAAECA//EACQQAQEBAAIBBAMBAQEBAAAAAAABESExQQISUXFhgZGxocHw/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAH/xAAWEQEBAQAAAAAAAAAAAAAAAAAAEQH/2gAMAwEAAhEDEQA/AMriLyCKgg1gQwCgs4FTMOdutepjQak+FzMSVqgxZdRdPPIIvH5WzzGdBriphtTeAXg2ZjKA1pqKDUGZca3foBek8gFv8Ie3fKdA1qb8s7hoL6eLVt51FsAnql3Ut1M7 AWbflLMDkEMX/F6/YjK/pADFQAUNA6alYagKk72m/j9p4Bq2fDDSYKLNXPNLoHE/NT6RYC31cJxZ3yWVM+aBYi/S2ZgiAsnYJx5D21vPmqrm3PTfpQQwyAC8JZvSKDni41ZrMuUVVl+Uz9 w9v/1QWrZsZ5nFPHYH+JZyureQSF5M+fJ0CAfwRAVRBQA1DAWVUayoJUWoDpsxntPsueBV4 +Vxhd+IusqCrv5ZEUVOk1RuJfwSLOOkGFi4XPCoYYrNiKauosBGi9ICstM1UAAAAAAFQ0Vc TBAXUGgIqGoKhKAzRRUQUAwxoSrGRpkQA/qiosOL9oJptMRRVZa0VUqSiChE6BqMgCwqKqI ogAIAqKCKgKoogg0lBFuIKgAAAKNRlf2gqsftsEtZWoAAqAACKoMqAAeSoqp39kL2AqLOlE 8rEBFQARYALhigrNC9gGmooLp4TweEQFFBFAECgIoAu0ifIAqAAA//9k=",
        "npwpFile:"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD/2wBD AP//////////////////////////////////////////////////////////////////////////////////////2wBDAf/////////////////////////////////////////////////////////////////////////////////////wAARCADqATkDASIAAhEBAxEB/8QAFwABAQEBAAAAAAAAAAAAAAAAAAECA//EACQQAQEBAAIBBAMBAQEBAAAAAAABESExQQISUXFhgZGxocHw/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAH/xAAWEQEBAQAAAAAAAAAAAAAAAAAAEQH/2gAMAwEAAhEDEQA/AMriLyCKgg1gQwCgs4FTMOdutepjQak+FzMSVqgxZdRdPPIIvH5WzzGdBriphtTeAXg2ZjKA1pqKDUGZca3foBek8gFv8Ie3fKdA1qb8s7hoL6eLVt51FsAnql3Ut1M7A WbflLMDkEMX/F6/YjK/pADFQAUNA6alYagKk72m/j9p4Bq2fDDSYKLNXPNLoHE/NT6RYC31cJxZ3yWVM+aBYi/S2ZgiAsnYJx5D21vPmqrm3PTfpQQwyAC8JZvSKDni41ZrMuUVVl+Uz9w 9v/1QWrZsZ5nFPHYH+JZyureQSF5M+fJ0CAfwRAVRBQA1DAWVUayoJUWoDpsxntPsueBV4+ AgL0CAAAALiANCKioNLgM1CrLihmTafkt1EF3SZ5ZVUW4mnIKvAi5fhEURVDWVQBRAAAAAA AAQFRVyAyulgAqCKlF8IqLsEgC9mGoC+IusqCrv5ZEUVOk1RuJfwSLOOkGFi4XPCoYYrNiK auosBGi9ICstM1UAAAAAAFQ0VcTBAXUGgIqGoKhKAzRRUQUAwxoSrGRpkQA/qiosOL9oJpt MRRVZa0VUqSiChE6BqMgCwqKqIogAIAqKCKgKoogg0lBFuIKgAAAKNRlf2gqsftsEtZWoAA qAACKoMqAAeSoqp39kL2AqLOlE8rEBFQARYALhigrNC9gGmooLp4TweEQFFBFAECgIoAu0ifIAqAAA//9k=",
        "pdfFile": "data:application/pdf;base64,JVBERi0xLjcNCiW1tbW1DQoxID Agb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFIvTGFuZyhlbikgL1N0cnVjdFRyZ WVSb290IDE1IDAgUi9NYXJrSW5mbzw8L01hcmtlZCB0cnVlPj4vTWV0YWRhdGEgMjcgMCBS L1ZpZXdlclByZWZlcmVuY2VzIDI4IDAgUj4+DQplbmRvYmoNCjIgMCBvYmoNCjw8L1R5cGU +PDg4Q0RCRTBCODY2MDkzNDZBRTc1MzE3RTExNTgyNUNBPl0gPj4NCnN0YXJ0eHJlZg0KMT UwNzYNCiUlRU9GDQp4cmVmDQowIDANCnRyYWlsZXINCjw8L1NpemUgMzAvUm9vdCAxIDAgU i9JbmZvIDE0IDAgUi9JRFs8ODhDREJFMEI4NjYwOTM0NkFFNzUzMTdFMTE1ODI1Q0E+PDg4 Q0RCRTBCODY2MDkzNDZBRTc1MzE3RTExNTgyNUNBPl0gL1ByZXYgMTUwNzYvWFJlZlN0bSA xNDc2OD4+DQpzdGFydHhyZWYNCjE1ODMzDQolJUVPRg==",
        "amount": {
            "value": "150000.00",
            "currency": "IDR"
        },
        "customerAccountNumber": "108909378902",
        "customerName": "Jhon Doe",
        "debitType": "V"
    }
}

Sample Response - Account Binding


{
    "responseCode": "2000700",
    "responseMessage": "Successful",
    "accessTokenInfo": {
        "accessToken": "YO6BtqyI2bkIWpMQDgG4WDoPTBM3VUVf1VkowOlVtf1ysELS1pDcCA46",
        "expiresIn": "2024-03-29T21:41:08+07:00",
        "refreshToken": "YSpvPZkpyDw60wLs40wDJwuTY3DvULZtO4ZPsGBDGOOtM4",
        "reExpiresIn": "2024-03-29T21:41:07+07:00",
        "tokenStatus": "ACTIVE"
    },
    "additionalInfo": {
        "accountInfo": {
            "accountType": "ACCOUNT",
            "accountId": "00******0812"
        }
    },
    "linkId": "83d5fa51aec3dc8",
    "accountToken": "ESP230929094046rRD5mCT1IZkrBhJb5",
    "redirectUrl": "https://google.com"
}

Sample Request - Binding Notify


{
    "originalPartnerReferenceNo ": "PARTNERREF0897698723467831",
    "originalReferenceNo": "99114163520190507",
    "merchantId": "SGWXXXXXXX",
    "amount": {
        "value": "100000.00",
        "currency": "IDR"
    },
    "latestTransactionStatus": "00",
    "additionalInfo": {
        "accountToken": "ESP24080910131954477298813129094",
        "productCode": "BCAAUTODEBIT",
        "statusRegistration": "A",
        "reason": "approve"
    }
}

Sample Response - Binding Notify


{
    "responseCode": "2005600", 
    "responseMessage": "Successful",
    "approvalCode": "89047849509183746"
}

Sample Request - Autodebit


{
    "partnerReferenceNo": "PARTNERREF0897698723467831",
    "merchantId": "SGWXXXXXXX",
    "amount": {
        "value": "10000.00",
        "currency": "IDR"
    },
    "urlParam": {
        "url": "https://google.com/merchantlogo ",
        "type": "MERCHANT_LOGO",
        "isDeeplink": "N"
    },
    "payOptionDetails": [
        {
            "payMethod": "014",
            "payOption": "BCAAUTODEBIT",
            "transAmount": {
                "value": "10000.00",
                "currency": "IDR"
            },
            "feeAmount": {
                "value": "10000.00",
                "currency": "IDR"
            }
        }
    ],
    "additionalInfo": {
        "productCode": "BCAAUTODEBIT",
        "accountName": "Jhon Doe",
        "payType": "AUTODEBIT",
        "debitType": "F"
    }
}

Sample Response - Binding Notify


{
    "responseCode": "2025400",
    "responseMessage": "Request In Process",
    "partnerReferenceNo": "PARTNERREF0897698723467833",
    "originalReferenceNo": null,
    "referenceNo": null,
    "approvalCode": "306637984686232"
}

CURL


curl --location 'https://sandbox-api.espay.id/apimerchant/v1.0/debit/payment-host-to-host' \
--header 'X-TIMESTAMP: 2024-03-14T07:49:28+07:00' \
--header 'X-SIGNATURE: B0VF16Vjsxxb/rUcgZM401XH7Z9cB5mhmYnfMdkblq84akTybh9Bakmb9nJD/ttrADmUbDJDW7s6E7yYTEATCdbjPs3+xEgA53gdcM7aJP9qPcfe79GankZrRvROcICdxuN2rjYZOuzvJ9SrfG/llmGic1bM627Eiz/G4pf7e8r6MOfsBRoUqH+moBGcw+/Xh2V8hqfb64hIzb7JZNZnVV7fQN6NZ8VAWLzjmo8PFLjg390wL3Fybr0GJwHohCaxBhv6P0nxVP+P9psnljKWt8EYHHWizgSVinUa9kncRq2MEpvLwujGcSG/MteZhcKXXYNGbCO5u7qato19fWwxaw==' \
--header 'X-EXTERNAL-ID: 76d1c963-9cd6-4f15-abf7-64ebb71db1a3' \
--header 'X-PARTNER-ID: SGWYESSISHOP' \
--header 'CHANNEL-ID: ESPAY' \
--header 'Content-Type: application/json' \
--data-raw '{
"partnerReferenceNo": "DIGORDER000001",
"merchantId": "SGWYESSISHOP",
"subMerchantId": "fd322d0f036c8443d6904973c1a329bd", 
"amount": {
  "value": "10000.00",
  "currency": "IDR"
},
"urlParam": {
  "url": "https://yourthankyoupage.com",
  "type": "PAY_RETURN",
  "isDeeplink": "N"
},
"validUpTo": "2023-12-23T07:44:11+07:00",
"pointOfInitiation": "Website",
"payOptionDetails": {
  "payMethod": "014",
  "payOption": "BCAATM",
  "transAmount": {
    "value": "10000.00",
    "currency": "IDR"
  },
  "feeAmount": {
    "value": "10000.00",
    "currency": "IDR"
  }
},
"additionalInfo": {
  "payType": "REDIRECT",
  "userId": "425666",
  "userName": "Agung Setiadi Putra",
  "userEmail": "[email protected]",
  "userPhone": "082231838297",
  "buyerId": "12345678"
}
}
'

What can I help you find?

Direct API

Direct Debit

Before Integration

Integration Steps

1. Display Payment Method

2. Generate Signature Asymmetric

Preparing the Header for Each Service

Registering an Account (Account Binding)

Flow

Environment

Request Parameters​

Response Parameters

Receiving Registration Notifications (Binding Notify)

Flow

Environment

Request Parameters​

Response Parameters

Payment Process (Autodebit)

Flow

Environment

Request Parameters​

Response Parameters

5. After Payment

Request Parameters

Request Parameters

Request Parameters