Direct API

Direct Debit

Direct Debit adalah metode pembayaran yang dilakukan secara otomatis, biasanya digunakan untuk pembayaran berulang. Dana dalam rekening Anda akan secara otomatis dipotong sesuai dengan jadwal yang telah disepakati. Espay Payment Gateway menyediakan layanan integrasi yang dapat membantu Anda untuk memprovide kebutuhan secara Autodebit. Ada 3 layanan yang harus Anda integrasikan :

Account Binding
Binding Notify
Autodebit

Sebelum Integrasi

Pastikan Anda sudah menerima kredensial dari tim Espay.

Setelah Integrasi

Berikut ini merupakan langkah-langkah yang dapat Anda gunakan untuk integrasi dengan Direct Debit.

Menampilkan Metode Pembayaran

Inquiry Merchant Info adalah layanan yang dapat Anda gunakan untuk mengetahui kode bank dan produk yang aktif. Dengan layanan ini, Anda dapat menyesuaikan antarmuka pengguna (UI) saat memilih metode pembayaran. Pelajari Inquiry Merchant Info

Generate Signature Asymmetric

Setiap permintaan yang Anda kirim, akan divalidasi oleh Espay Payment Gateway menggunakan parameter signature yang telah Anda buat. Pelajari pembuatan Signature Asymmetric.

Menyiapkan Header untuk setiap layanan

Header adalah bagian yang selalu ada dalam setiap permintaan dan respons. Pastikan bahwa setiap layanan yang Anda gunakan sudah memiliki header dengan format yang sesuai.

Nama	Tipe	Mandatory	Keterangan
Content-Type	String	Y	Isi konten permintaan Anda. Contoh: application/json
X-TIMESTAMP	String (25)	Y	Tanggal dan waktu lokal customer saat ini. Format: yyyy-MM-ddThh:mi:ssTZD (ISO 8601) Contoh: 2024-03-14T07:49:28+07:00
X-SIGNATURE	String (255)	Y	Kode yang digunakan untuk melakukan validasi transaksi. Pelajari Signature Asymmetric
X-EXTERNAL-ID	String (32)	Y	String Numerik. Kode referensi yang bersifat unik pada hari yang sama.
X-PARTNER-ID	String (50)	Y	Merchant code yang diberikan oleh tim Espay.
CHANNEL-ID	String (5)	Y	Kode channel. Value: ESPAY
Authorization-Customer	String (150)	C	Kode token B2B2C. Khusus Espay -> Bank.

Y: Yes, O: Optional, C: Conditional

Mendaftarkan Akun (Account Binding)

Untuk terhubung dengan Direct Debit, Anda perlu mendaftarkan data customer yang akan menggunakan layanan tersebut. Data tersebut kemudian akan diverifikasi dan divalidasi untuk memastikan keakuratannya.

Tipe	Value
Kode Layanan	07
Nama	API Account Binding
HTTP Method	POST

Flow

Anda melakukan permintaan dengan mengirimkan parameter yang dibutuhkan, dan Espay Payment Gateway akan memberikan respons dalam bentuk JSON.

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

Parameter Permintaan

Parameter	Tipe	Mandatory	Keterangan
partnerReferenceNo	String (64)	Y	...
merchantId	String (64)	Y	Kode partner. Value: "ESPAY"
phoneNo	String (13)	Y	No handphone customer.
authCode	String (128)	Y	....
additionalInfo	Object
productCode	String (16)	Y	Kode produk. Lihat disini
accountToken	String (64)	Y	....
ktpFile	base64encoded	C	KTP atau Kartu Identitas dalam bentuk gambar. Format: Base64 encoded. Batas maksimal compress sampai 50kb).
npwpFile	base64encoded	C	NPWP dalam bentuk gambar. Format: Base64 encoded. Batas maksimal compress sampai 50kb).
pdfFile	base64encoded	C	File PDF. Format: Base64 encoded.
amount	String (16.2)	C
value	String (16.2)	C	...
currency	String (3)	C	Kode mata uang transaksi. Format: Rupiah: IDR
customerAccountNumber	String (24)	C	Nomor rekening customer untuk binding.
customerName	String (100)	C	Nama akun customer.
debitType	String (1)	C	Tipe debit. Format: Fix: F Jika debitType = F, maka jumlah “nominal transaksi”. Variable: V Jika debitType = V, maka jumlah “0”.

Y: Yes, O: Optional, C: Conditional

Parameter Respons

Parameter	Tipe	Mandatory	Keterangan
responseCode	String (7)	Y	Kode respons. Format: Kode HTTP + Kode Layanan + Kode Error Contoh: 200+07+00 = 2000700.
responseMessage	String (150)	Y	Deskripsi respons.
accessTokenInfo	Object	Y
accessToken	String (128)	Y	Token akses.
expiresIn	String (25)	Y	Tanggal dan waktu kedaluwarsa token. Format: yyyy-MM-ddThh:mi:ssTZD (ISO 8601) Contoh: 2024-03-14T07:49:28+07:00
refreshToken	String (128)	Y	Refresh Token.
reExpiresIn	String (25)	Y	Tanggal dan waktu kedaluwarsa refresh token. Format: yyyy-MM-ddThh:mi:ssTZD (ISO 8601) Contoh: 2024-03-14T07:49:28+07:00
tokenStatus	String (64)	O	Status token. Format: Aktif: Active Tidak Aktif: INACTIVE
AdditionalInfo	Object
accountInfo
accountType	String (64)	O	Tipe akun.
accountId	String (64)	O	ID akun.
linkId	String (64)	O	ID link.
accountToken	String (64)	O	....
redirectUrl	String (255)	O	...

Y: Yes, O: Optional, C: Conditional

Menerima Notifikasi Pendaftaran (Binding Notify)

Tipe	Value
Kode Layanan
Nama
HTTP Method	POST

Flow

Setiap kali Anda mendaftarkan melalui Account Binding, Espay akan mengirimkan permintaan ke server Anda melalui URL Binding Notify yang telah Anda daftarkan. Anda diminta untuk memberikan respon dalam bentuk JSON menggunakan format yang disediakan.

Environment

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

Parameter Permintaan

Parameter	Tipe	Mandatory	Keterangan
originalPartnerReferenceNo	String (64)	Y	....
originalReferenceNo	String (64)	Y	Kode referensi dari Espay.
merchantId	String (28)	Y	Merchant code yang diberikan oleh tim Espay. Contoh: SGWYESSISHOP
amount	Object	Y
value	String (16.2)	Y	....
currency	String (3)	Y	Kode mata uang transaksi. Format: Rupiah: IDR
latestTransactionStatus	String (2)	Y	Status transaksi terbaru. Format: Berhasil / disetujui: 00 Gagal / ditolak: 06
additionalInfo	Object
accountToken	String (64)	Y	...
productCode	String (64)	Y	Kode produk. Lihat disini
statusRegistration	String (5)	Y	Status pendaftaran Autodebit. Format: Disetuji: A Ditolak: R
reason	String (100)	Y	Catatan pendaftaran.

Y: Yes, O: Optional, C: Conditional

Parameter Respons

Parameter	Tipe	Mandatory	Keterangan
responseCode	String (7)	Y	Kode respons. Format: Kode HTTP + Kode Layanan + Kode Error Contoh: 200+56+00 = 2000700.
responseMessage	String (150)	Y	Deskripsi respons.
approvalCode	String (20)	O	....

Y: Yes, O: Optional, C: Conditional

Proses Pembayaran (Autodebit)

Tipe	Value
Kode Layanan	54
Nama	Direct Debit Payment
HTTP Method	POST

Flow

Anda melakukan permintaan dengan mengirimkan parameter yang dibutuhkan, dan Espay Payment Gateway akan memberikan respons dalam bentuk JSON.

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

Parameter Permintaan

Parameter	Tipe	Mandatory	Keterangan
partnerReferenceNo	String (32)	Y	...
merchantId	String (28)	Y	Merchant code yang diberikan oleh tim Espay. Contoh: SGWYESSISHOP
amount	Object	Y
value	String (16.2)	Y	Total pembayaran. Format: Desimal .00 (ISO 4217) Contoh: 150000.00
currency	String (3)	Y	Kode mata uang transaksi. Format: Rupiah: IDR
urlParam	Object
url	String (255)	Y	URL yang mengarahkan ke halaman merchant (callback).
type	String (32)	Y	Tipe URL. Value: PAY_RETURN
isDeeplink	String (1)	Y	Status Deep Link. Khusus SNAP value yang didukung hanya N (Tidak). Format: Ya: Y Tidak: N
payOptionDetails	Object
payMethod	String (64)	Y	Kode bank. Lihat disini.
payOption	String (64)	Y	Nama produk. Lihat disini.
transAmount	Object
value	String (16.2)	Y	Total pembayaran. Format: Desimal .00 (ISO 4217) Contoh: 150000.00
currency	String (3)	Y	Kode mata uang transaksi. Format: Rupiah: IDR
feeAmount	Object
value	String (16.2)	Y	Biaya transaksi. Format: Desimal .00 (ISO 4217) Contoh: 4400.00
currency	String (3)	Y	Kode mata uang transaksi. Format: Rupiah: IDR
additionalInfo	Object
productCode	String (20)	Y	Kode produk. Lihat disini
accountName	String (20)	Y	Nama akun customer.
payType	String (64)	Y	Tipe pembayaran. Value: AUTODEBIT
debitType	String (64)	Y	Tipe debit. Format: Fix: F Variable: V

Y: Yes, O: Optional, C: Conditional

Parameter Respons

Parameter	Tipe	Mandatory	Keterangan
responseCode	String (7)	Y	Kode respons. Format: Kode HTTP + Kode Layanan + Kode Error Contoh: 200+54+00 = 2005400.
responseMessage	String (150)	Y	Deskripsi respons.
partnerReferenceNo	String (64)	Y	.....
originalReferenceNo	String (2048)	O	......
referenceNo	String (2048)	O	....
approvalCode	String (64)	Y	.....

Y: Yes, O: Optional, C: Conditional

5. Setelah Pembayaran

Espay Payment Gateway menyediakan API Opsional yang dapat Anda gunakan untuk mendukung kebutuhan pembayaran lainnya.

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

Try It!

Anda bisa coba masukkan data sesuai dengan input yang telah disediakan. Setelah itu Anda submit dan lihat hasilnya!

Request

Paramter

Value

Header

X-TIMESTAMP

X-SIGNATURE

X-EXTERNAL-ID

X-PARTNER-ID

CHANNEL-ID

Body

Response

Output

Contoh Header


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

Contoh Permintaan 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"
    }
}

Contoh Respons 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"
}

Contoh 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"
    }
}

Contoh Response Binding Notify


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

Contoh 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"
    }
}

Contoh Response Autodebit


{
    "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"
}
}
'

Apa yang mau anda cari?

Direct API

Direct Debit

Sebelum Integrasi

Setelah Integrasi

Menampilkan Metode Pembayaran

Generate Signature Asymmetric

Menyiapkan Header untuk setiap layanan

Mendaftarkan Akun (Account Binding)

Flow

Environment

Parameter Permintaan

Parameter Respons

Menerima Notifikasi Pendaftaran (Binding Notify)

Flow

Environment

Parameter Permintaan

Parameter Respons

Proses Pembayaran (Autodebit)

Flow

Environment

Parameter Permintaan

Parameter Respons

5. Setelah Pembayaran

Try It!

Request

Response