API Card Binding BTN

Registration Card Binding

API ini digunakan oleh merchant untuk melakukan registrasi kartu pelanggan ke sistem penyelenggara pembayaran, seperti BTN. Merchant perlu mengirimkan data kartu yang terenkripsi untuk proses binding yang aman.

• Method: POST
• Type: application/json
• Path: /api/v1.0/registration-card-bind
• Service Code: 01

Header Registration Card Binding

Parameter	Tipe	Mandatori	Keterangan	Contoh
Content-Type	string	✓	Jenis konten permintaan	application/json
X-TIMESTAMP	string	✓	Timestamp dalam format ISO-8601	2025-05-05T13:57:57+07:00
X-SIGNATURE	string	✓	Signature terenkripsi, lihat bagian Authentication	WDcJOiayTD1St7bhI+6...
X-PARTNER-ID	string	✓	ID partner Doitpay	01J20VM8TNRK9VBMGJAQDBSF8X
X-EXTERNAL-ID	string(64)	✓	ID permintaan unik dari merchant	804346
CHANNEL-ID	string	✓	Nilai tetap DOITPAY	DOITPAY
Authorization	string	✓	Token akses menggunakan format Bearer token	Bearer eyJhbGc...

Request Body Registration Card Binding

Parameter	Tipe	Mandatori	Keterangan	Contoh
custIdMerchant	string	✓	ID unik referensi transaksi dari merchant	01JTFKSCPE94ERTKVVCBHK3PKG
phoneNo	string	✓	Nomor telepon pelanggan	+6287722728028
cardData	string	✓	Data kartu yang terenkripsi	UIdFgZi9BhWx9Scbz/YK+...
additionalInfo	object	✓	Metadata channel pembayaran, lihat tabel di bawah

additionalInfo

Parameter	Tipe	Mandatori	Keterangan	Contoh
paymentChannel	string	✓	Channel pembayaran, misalnya BTN, CIMB	BTN
paymentMethod	string	✓	Jenis metode pembayaran BANK	BANK

Example Request

{
  "custIdMerchant": "01JTFKSCPE94ERTKVVCBHK3PKG",
  "phoneNo": "+6287722728028",
  "cardData": "UIdFgZi9BhWx9Scbz/YK+JiMsPiKyhAFDaIRQe0wxMZY...",
  "additionalInfo": {
    "paymentMethod": "BANK",
    "paymentChannel": "BTN"
  }
}

Response Body

{
  "responseCode": "2000100",
  "responseMessage": "Successful",
  "referenceNo": "01JTFKSD339DJJ9WDWNDFFNC63",
  "partnerReferenceNo": "01JTFKSCPE94ERTKVVCBHK3PKG",
  "chargeToken": "abcd63617264746f6b656e",
  "tokenExpiryTime": "2025-05-05T14:00:00+07:00",
  "additionalInfo": {
    "paymentMethod": "BANK",
    "paymentChannel": "BTN",
    "authCode": "MBntChzFOrBtZSSsd7wpgJ8yF8QQiofJBLJB7700",
    "status": "NEED_APPLY_TOKEN"
  }
}

Card Binding Inquiry

API ini digunakan untuk mengetahui status kartu yang sudah didaftarkan.

• Method: POST
• Type: application/json
• Path: /api/v1.0/registration-card-inquiry
• Service Code: 03

Request Body

Parameter	Tipe	Mandatori	Keterangan	Contoh
custIdMerchant	string	✓	ID customer merchant	8a95f0026d2860f301

Response Body

{
  "responseCode": "2000300",
  "responseMessage": "Successful",
  "referenceNo": "01JTFM51KRJJDCE6GDFZQ6JYZQ",
  "partnerReferenceNo": "01JTFM51FR3Y130R3G1AGMAE8E",
  "accountCurrency": "IDR",
  "additionalInfo": {
    "paymentMethod": "BANK",
    "paymentChannel": "BTN",
    "status": "NEED_APPLY_TOKEN",
    "authCode": "MBntChzFOrBtZSSsd7wpgJ8yF8QQiofJBLJB7700",
    "chargeToken": "MBntChzFOrBtZSSsd7wpgJ8yF8QQiofJBLJB7700"
  }
}

OTP Verification

API ini digunakan untuk verifikasi OTP dalam proses card binding.

• Method: POST
• Type: application/json
• Path: /api/v1.0/otp-verification
• Service Code: 04

Request Body

Parameter	Tipe	Mandatori	Keterangan	Contoh
originalPartnerReferenceNo	string	✓	Partner reference no dari registrasi	01JTFKSCPE94ERTKVVCBHK3PKG
originalReferenceNo	string	✓	Reference no dari response registrasi	01JTFKSD339DJJ9WDWNDFFNC63
otp	string	✓	Kode OTP 6 digit	123456
type	string	✓	Tipe proses (BINDING atau PAYMENT)	BINDING

Example Request

{
  "originalPartnerReferenceNo": "01JTFKSCPE94ERTKVVCBHK3PKG",
  "originalReferenceNo": "01JTFKSD339DJJ9WDWNDFFNC63",
  "otp": "123456",
  "type": "BINDING"
}

Response Body

{
  "responseCode": "2000400",
  "responseMessage": "Successful",
  "originalReferenceNo": "01JTFKSD339DJJ9WDWNDFFNC63",
  "originalPartnerReferenceNo": "01JTFKSCPE94ERTKVVCBHK3PKG"
}

Card Set Limit

API ini digunakan untuk mengatur limit transaksi pada kartu yang sudah di-bind.

• Method: POST
• Type: application/json
• Path: /api/v1.0/registration-card-bind-limit
• Service Code: 02

Request Header

Parameter	Tipe	Mandatori	Keterangan	Contoh
Content-Type	string	✓	Jenis konten permintaan	application/json
X-TIMESTAMP	string	✓	Timestamp dalam format ISO-8601	2025-05-05T13:57:57+07:00
X-SIGNATURE	string	✓	Signature terenkripsi, lihat bagian Authentication	WDcJOiayTD1St7bhI+6...
X-PARTNER-ID	string	✓	ID partner Doitpay	01J20VM8TNRK9VBMGJAQDBSF8X
X-EXTERNAL-ID	string(64)	✓	ID permintaan unik dari merchant	804346
CHANNEL-ID	string	✓	Nilai tetap DOITPAY	DOITPAY
Authorization	string	✓	Token akses menggunakan format Bearer token	Bearer eyJhbGc...

Request Body

Parameter	Tipe	Mandatori	Keterangan	Contoh
partnerReferenceNo	string	✓	Reference no baru	01JTFKSCPE94ERTK...
bankCardToken	string	✓	Token kartu dari response bind	6d7963617264746f...
limit	string	✓	Limit transaksi harian	1000000
additionalInfo	object	✗	Informasi tambahan

Example Request

{
  "partnerReferenceNo": "01JTFKSCPE94ERTKVVCBHK3PKH",
  "bankCardToken": "6d7963617264746f6b656e",
  "limit": "1000000",
  "additionalInfo": {
    "paymentMethod": "BANK",
    "paymentChannel": "BTN"
  }
}

Response Body

{
  "responseCode": "2000200",
  "responseMessage": "Successful",
  "referenceNo": "01JTFKSD339DJJ9WDWNDFFNC64",
  "partnerReferenceNo": "01JTFKSCPE94ERTKVVCBHK3PKH",
  "additionalInfo": {
    "paymentMethod": "BANK",
    "paymentChannel": "BTN",
    "status": "ACTIVE"
  }
}

Card Unbinding

API ini digunakan untuk membatalkan binding kartu.

• Method: POST
• Type: application/json
• Path: /api/v1.0/registration-card-unbind
• Service Code: 05

Request Body

Parameter	Tipe	Mandatori	Keterangan	Contoh
partnerReferenceNo	string	✓	Reference no baru untuk unbinding	01JTFKSCPE94ERTKVVCBHK3PKI
token	string	✓	Token kartu yang akan di-unbind	6d7963617264746f6b656e
additionalInfo	object	✗	Informasi tambahan

Example Request

{
  "partnerReferenceNo": "01JTFKSCPE94ERTKVVCBHK3PKI",
  "token": "6d7963617264746f6b656e",
  "additionalInfo": {
    "paymentMethod": "BANK",
    "paymentChannel": "BTN"
  }
}

Response Body

{
  "responseCode": "2000500",
  "responseMessage": "Successful",
  "referenceNo": "01JTFKSD339DJJ9WDWNDFFNC65",
  "partnerReferenceNo": "01JTFKSCPE94ERTKVVCBHK3PKI",
  "additionalInfo": {
    "paymentMethod": "BANK",
    "paymentChannel": "BTN",
    "status": "UNBOUND"
  }
}

Access Token (B2B2C)

API ini digunakan untuk mendapatkan token akses (access token) dan token refresh untuk melakukan proses otorisasi transaksi Debit Card setelah pengguna melakukan binding dan mendapatkan authCode.

• Method: POST
• Type: application/json
• Path: /auth/v1.0/access-token/b2b2c
• Service Code: 74

Header Access Token

Parameter	Tipe	Mandatori	Keterangan	Contoh
Content-Type	string	✓	Jenis konten permintaan	application/json
X-TIMESTAMP	string	✓	Timestamp dalam format ISO-8601	2025-05-05T14:08:31+07:00
X-SIGNATURE	string	✓	Signature terenkripsi, lihat bagian Authentication	DhSIDkF6gHFkzbdx...
X-CLIENT-KEY	string	✓	Client key dari Doitpay	01J20VM8W11EP9M6KBHHJZMHPW

Request Body Access Token

Parameter	Tipe	Mandatori	Keterangan	Contoh
authCode	string	✓	Kode otorisasi yang didapat dari proses binding account	MBntChzFOrBtZSSsd7wpgJ8yF8QQ...
grantType	string	✓	Jenis grant yang digunakan (authorization_code atau refresh_token)	authorization_code
refreshToken	string	✗	Token refresh jika grantType = refresh_token
additionalInfo	object	✗	Tambahan informasi jika diperlukan

Example Request

{
  "additionalInfo": {},
  "authCode": "MBntChzFOrBtZSSsd7wpgJ8yF8QQiofJBLJB7700",
  "grantType": "authorization_code",
  "refreshToken": ""
}

Response Body

{
  "responseCode": "2007400",
  "responseMessage": "Successful",
  "accessToken": "<access_token_jwt>",
  "tokenType": "BearerToken",
  "accessTokenExpiryTime": "1296000",
  "refreshToken": "<refresh_token_jwt>",
  "refreshTokenExpiryTime": "5184000",
  "additionalInfo": null
}

Debit Payment Host-to-Host

API ini digunakan untuk melakukan permintaan pembayaran langsung dari merchant ke penyelenggara (contoh: BTN) secara host-to-host. Diperlukan access token pengguna dan informasi pembayaran.

• Method: POST
• Path: /api/v1.0/debit/payment-host-to-host
• Content-Type: application/json
• Service Code: 54

Header Payment Host-to-Host

Parameter	Tipe	Mandatori	Keterangan
Content-Type	string	✓	application/json
X-TIMESTAMP	string	✓	Timestamp format ISO-8601
X-SIGNATURE	string	✓	Signature terenkripsi
X-PARTNER-ID	string	✓	Partner ID dari dashboard Doitpay
X-EXTERNAL-ID	string	✓	ID unik permintaan
CHANNEL-ID	string	✓	DOITPAY
Authorization	string	✓	Bearer token merchant
Authorization-Customer	string	✓	Bearer token customer (hasil binding access token)

Request Body Payment Host-to-Host

{
  "additionalInfo": {
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "channel": "BTN"
  },
  "amount": {
    "currency": "IDR",
    "value": "13000.00"
  },
  "partnerReferenceNo": "01JTFNSMTWYMTH49S90VM02WBP",
  "urlParam": [
    {
      "isDeeplink": "N",
      "type": "PAY_NOTIFY",
      "url": "https://andikawhy.free.beeceptor.com/debit card"
    },
    {
      "isDeeplink": "N",
      "type": "PAY_RETURN",
      "url": "https://doitpay.co"
    }
  ],
  "validUpTo": "2025-05-05T15:03:02+07:00"
}

Response Body

{
  "responseCode": "2005400",
  "responseMessage": "Successful",
  "partnerReferenceNo": "01JTFNSMTWYMTH49S90VM02WBP",
  "additionalInfo": {
    "originalReferenceNo": "01JTFNSMYWZFMMM10NB2F4PESG",
    "channelCode": "BTN",
    "status": "ACTIVE"
  }
}

Response Field Description

Parameter	Tipe	Keterangan
responseCode	string	Kode hasil response dari sistem
responseMessage	string	Pesan respon
partnerReferenceNo	string	ID transaksi yang dikirimkan merchant
appRedirectUrl	string	URL redirect ke aplikasi
webRedirectUrl	string	URL redirect ke halaman web pembayaran
additionalInfo	object	Metadata tambahan

additionalInfo

Parameter	Tipe	Keterangan
originalReferenceNo	string	Referensi transaksi sebelumnya
channelCode	string	Channel kode pembayaran

Check Payment Status Debit Card

API Check Payment Status Debit Card adalah layanan API yang dapat digunakan oleh Merchant untuk mengetahui status pembayaran dari Debit Card menggunakan ID transaksi.

• Method: POST
• Type:application/json
• Path: /api/v1.0/debit/status
• Service Code: 55

Header Check Payment

Parameter	Tipe	Mandatori	Keterangan	Contoh
Content-Type	string	✓	string yang menunjukkan jenis media.	application/json
X-TIMESTAMP	string	✓	ISO-8601	2022-09-16T13:00:00+07:00
X-SIGNATURE	string	✓	Lihat bagian symmetric signature
X-PARTNER-ID	string	✓	Merchant Ref dari dashboard Doitpay	01JP4QP4R908GVK9X5KN7YCJEG
X-EXTERNAL-ID	string(64)	✓	Request ID yang unik.
CHANNEL-ID	string	✓	Nilai seharusnya DOITPAY
Authorization	string	✓	Otentikasi dengan bearer token ,Lihat pada bagian access token	Bearer ZGMyNDA3NWQtNmM4Ny00NGNiLTQ2NTAtMDhkYWMxNTAzNzY0

Request Body Check Payment

Parameter	Tipe	Mandatori	Keterangan	Contoh
originalPartnerReferenceNo	string	✓	Referensi transaksi asli	ORDER12345678 9
additionalInfo	object	✓	Informasi tambahan query	Lihat additionalInfo

additionalInfo Check Payment

Parameter	Tipe	Keterangan	Contoh
originalReferenceNo	string	Nomor referensi payment	EW123456789
channelCode	string	Kode kanal payment	BTN

Example Check Payment

{
  "originalPartnerReferenceNo": "ORDER123456789",
  "additionalInfo": {
    "originalReferenceNo": "EW123456789",
    "channelCode": "BTN"
  }
}

Response Body Check Payment

Parameter	Tipe	Keterangan	Contoh
responseCode	string	Kode respons API	2005500
responseMessage	string	Deskripsi respons	Successful
originalPartnerReferenceNo	string	Referensi transaksi asli	ORDER123456789
serviceCode	string	Kode tipe layanan untuk service yang digunakan, untuk debit card diisi 54	54
latestTransactionStatus	string	Status transaksi terkini	00
additionalInfo	object	Informasi tambahan respons	Lihat additionalInfo

amount Response Body Check Payment

Parameter	Tipe	Keterangan	Contoh
value	string	ISO4217 dengan 2 desimal	1000.00
currency	string	Kode mata uang, hanya menerima IDR.	IDR

additionalInfo Response Body Check Payment

Parameter	Tipe	Keterangan	Contoh
originalReferenceNo	string	Nomor referensi payment	EW123456789

Debit Card Payment Notification (callback)

• Method: POST
• Type:application/json
• Path: https://yourdomain.com/v1.0/debit/notify
• Service Code: 56

Symmetric Signature Payment Notification

Saat menerima notifikasi pembayaran, API anda perlu melakukan validasi signature untuk menjamin proses keamanan data. Berikut penjelasannya:

Formula :

stringToSign = HttpMethod + “:” + Endpoint + “:” + MerchantRef + “:” +
LowerCase(HexEncode(SHA-256(Minify(RequestBody)))) + “:” + Timestamp
hash = HMAC_SHA512(stringToSign, secretKey)

Buatlah sebuah variabel stringToSign.

1. HttpMethod adalah string nama metode yang sedang digunakan. Bisa saja POST, PUT, atau DELETE.

2. Endpoint adalah relative URL atau full path URL yang mana tanpa host atau domainnya.

3. MerchantRef adalah nilai token yang Anda dapatkan dari Merchant Reference.

4. RequestBody adalah payload yang ingin Anda kirim.

5. Timestamp menggunakan ISO-8601.

6. secretKey adalah Merchant Reference.

Hash stringToSign menggunakan HMAC_SHA512 cryptographic dan secret key (nama lain saat ini adalah API key). Kemudian, encode dengan Base 64.

Masukkan nilainya ke X-SIGNATURE.

Header Payment Notification

Parameter	Tipe	Mandatori	Keterangan	Contoh
X-TIMESTAMP	string	✓	ISO-8601	2022-09-16T13:00:00+07:00
X-SIGNATURE	string	✓	Lihat Symmetric Signature Payment Notification
X-PARTNER-ID	string	✓	Merchant Ref dari dashboard Doitpay	01JP4QP4R908GVK9X5KN7YCJEG
X-EXTERNAL-ID	string(64)	✓	Request ID yang unik.
CHANNEL-ID	string	✓

Request Body Payment Notification

Parameter	Tipe	Mandatori	Keterangan	Contoh
originalPartnerReferenceNo	string	✓	Referensi transaksi asli	ORDER123456789
originalReferenceNo	string	✓	Nomor referensi payment	EW123456789
latestTransactionStatus	string	✓	Status akhir transaksi	00
amount	object	✓	Detail jumlah transaksi	Lihat amount
additionalInfo	object	✓	Informasi tambahan notifikasi	Lihat additionalInfo

amount Request Body Payment Notification

Parameter	Tipe	Keterangan	Contoh
value	string	ISO4217 dengan 2 desimal. Menunjukkan nominal pembayaran.	1000.00
currency	string	Kode mata uang, hanya menerima IDR.	IDR

additionalInfo Request Body Payment Notification

Parameter	Tipe	Keterangan	Contoh
channelCode	string	Kode kanal payment	BTN

Response Body

Parameter	Tipe	Keterangan	Contoh
responseCode	string	Kode response, lihat bagian daftar Response Code di bawah	2005600
responseMessage	string	Penjelasan terhadap response code yang diterima	Successful

Response Code Payment Notification

Kode	Keterangan
200XX00	Berhasil membuat request. Dimana XX adalah service code untuk setiap API Debit Card.
409XX00	Conflict external ID saat membuat debit card. Dimana XX adalah service code untuk setiap API Debit Card.
400XX01	Invalid field format. Dimana XX adalah service code untuk setiap API Debit Card.
400XX02	Missing mandatory field. Dimana XX adalah service code untuk setiap API Debit Card.
401XX00	Unauthorized Signature. Dimana XX adalah service code untuk setiap API Debit Card.
401XX01	Invalid Access Token. Dimana XX adalah service code untuk setiap API Debit Card.
500XX00	Terjadi kesalahan sistem di doitpay, mohon dibantu menghubungi doitpay untuk mendapatkan detail. Dimana XX adalah service code untuk setiap API Debit Card