Skip to main content

Payment Link

API Create Payment Link adalah layanan API yang dapat digunakan oleh Merchant untuk menerima pembayaran melalui channel Payment Link. Merchant nantinya akan menerima link checkout dari Doitpay untuk diakses pelanggan.

  • Method: POST
  • Type:application/json
  • Path: /payment-link/v1.0/debit/payment-host-to-host
  • Service Code: 54
ParameterTipeMandatoriKeteranganContoh
Content-Typestring✓string yang menunjukkan jenis media.application/json
X-TIMESTAMPstring✓ISO-86012022-09-16T13:00:00+07:00
X-SIGNATUREstring✓Lihat bagian symmetric signature
X-PARTNER-IDstring✓Merchant Ref dari dashboard Doitpay01JP4QP4R908GVK9X5KN7YCJEG
X-EXTERNAL-IDstring(64)✓Request ID yang unik.
CHANNEL-IDstring✓Nilai seharusnya DOITPAY
Authorizationstring✓Otentikasi dengan bearer token lihat disini pada bagian access tokenBearer ZGMyNDA3NWQtNmM4Ny00NGNiLTQ2NTAtMDhkYWMxNTAzNzY0

Request Body Payment Link​

ParameterTypeMandatoryKeteranganContoh
partnerReferenceNostring✓Nomor referensi unik dari partnerPL-ORDER-20241209-0001
amountobject✓Detail jumlah transaksiLihat amount
urlParamsarray of object✗Konfigurasi URLLihat urlParams
externalStoreIdstring✗ID toko eksternalSTORE-001
validUpTostring✓Waktu kedaluwarsa transaksi2024-12-09T23:59:59+07:00
additionalInfoobject✓Informasi tambahan transaksiLihat additionalInfo

amount request​

ParameterTipeMandatoriKeteranganContoh
valuestring✓Jumlah total pembayaran ISO4217 dengan 2 desimal. Lihat bagian kalkulasi amount untuk detail perhitungan amount100000.00
currencystring✓Kode mata uang, hanya menerima IDR.IDR

urlParams request​

ParameterTipeMandatoriKeteranganContoh
urlstring✓URL pengalihanhttps://merchant.com/notify
typestring✓Tipe URL; PAY_NOTIFY dan PAY_RETURNPAY_NOTIFY
isDeeplinkstring✓Penanda deeplink, saat ini hanya bisa NN

additionalInfo request​

ParameterTypeMandatoryKeteranganContoh
purchaseOrderstring✗Nomor purchase orderPO-EXAMPLE-0001
companyDetailsstring✗Detail perusahaanExample Merchant Corp
billTostring✗Email yang akan mendapatkan informasi tagihan[email protected]
currencystring✗Mata uang transaksiIDR
itemsarray of object✓Daftar item (min 1, max 10)Lihat items
notesstring✗Catatan tambahanSample payment link
taxPercentagestring✗Persentase pajak dalam bentuk decimal (contoh: 0.2 = 20%, 2 = 200%) yang diterapkan pada jumlah subtotal item0.2
discountstring✗Nilai diskon, dikurangi setelah subtotal item1000
additionalFeestring✗Biaya tambahan1500
isFeeChargedToUserboolean✗Menentukan apakah biaya dibebankan ke userfalse
customerNamestring✗Nama pelangganCustomer Test
customerMobileNostring✗Nomor HP pelanggan081200000000
customerAddressstring✗Alamat pelangganJl. Sudirman No. 123, Jakarta
customerEmailstring✗Email pelanggan[email protected]

item request​

ParameterTypeMandatoryKeteranganContoh
itemNamestring✓Nama item (1–40 karakter)Sample Product A
itemSkustring✗Kode SKU itemSKU-A001
itemNotesstring✗Catatan itemSample product item
quantitystring✓Jumlah item1
pricestring✓Harga per item10000

kalkulasi amount​

Catatan pembulatan amount

Jika hasil perhitungan amount menghasilkan nilai desimal (misalnya 123.45), sistem akan melakukan pembulatan ke atas ke nilai rupiah terdekat.

Contoh: hasil perhitungan 123.45 akan dibulatkan menjadi 124.00.

Pastikan integrasi Anda mengantisipasi perbedaan kecil ini antara nilai perhitungan awal dan amount akhir yang diproses oleh Doitpay.

subtotal = Σ (item.price × item.quantity)

tax = subtotal × taxPercentage

amount = (subtotal + additionalFee - discount) + tax
KomponenDeskripsi
subtotalTotal harga seluruh item (price × quantity)
taxPajak yang dihitung dari subtotal
additionalFeeBiaya tambahan yang ditambahkan ke transaksi
discountPotongan harga yang mengurangi total
amountTotal akhir yang harus dibayarkan

Contoh perhitungan

"additionalInfo": {
  "additionalFee": "1500",
  "taxPercentage": "0.02",
  "discount": "1000",
  "items": [
    {
      "itemName": "Product A",
      "price": "10000",
      "quantity": "1"
    },
    {
      "itemName": "Product B",
      "price": "20000",
      "quantity": "1"
    }
  ]
}

Langkah 1 – Hitung Subtotal

ItemPerhitunganHasil
Product A1 × 10,00010,000
Product B1 × 20,00020,000
Total30,000

Langkah 2 – Hitung Pajak

tax = subtotal × taxPercentage
tax = 30,000 × 0.02 = 600

Langkah 3 – Hitung Total Amount

amount = (subtotal + additionalFee - discount) + tax
amount = (30,000 + 1,500 - 1,000) + 600
amount = 31,100

Request akhir amount

"amount": {
  "currency": "IDR",
  "value": "31100.00"
}

Example Payment Link - Full Request​

{
  "externalStoreId": "STORE-001",
  "partnerReferenceNo": "PL-ORDER-20241209-0001",
  "validUpTo": "2024-12-09T23:59:59+07:00",
  "additionalInfo": {
    "additionalFee": "1500",
    "taxPercentage": "0.02",
    "billTo": "[email protected]",
    "companyDetails": "Example Merchant Corp",
    "currency": "IDR",
    "customerAddress": "Jl. Sudirman No. 123, Jakarta",
    "customerEmail": "[email protected]",
    "customerMobileNo": "081200000000",
    "customerName": "Customer Test",
    "discount": "1000",
    "isFeeChargedToUser": false,
    "items": [
      {
        "itemName": "Sample Product A",
        "itemNotes": "Sample product item",
        "itemSku": "SKU-A001",
        "price": "10000",
        "quantity": "1"
      },
      {
        "itemName": "Sample Product B",
        "itemNotes": "Sample product item",
        "itemSku": "SKU-B001",
        "price": "20000",
        "quantity": "1"
      }
    ],
    "notes": "Sample payment link",
    "purchaseOrder": "PO-EXAMPLE-0001"
  },
  "amount": {
    "currency": "IDR",
    "value": "31100.00"
  },
  "urlParams": [
    {
      "type": "PAY_RETURN",
      "url": "https://merchant.example.com/payment/return",
      "isDeeplink": "N"
    },
    {
      "url": "https://merchant.example.com/payment/notify",
      "type": "PAY_NOTIFY",
      "isDeeplink": "N"
    }
  ]
}

Example Payment Link - Mandatory Request​

{
  "additionalInfo": {
    "items": [
      {
        "itemName": "Sample Product A",
        "itemNotes": "Sample product item",
        "itemSku": "SKU-A001",
        "price": "10000",
        "quantity": "1"
      },
      {
        "itemName": "Sample Product B",
        "itemNotes": "Sample product item",
        "itemSku": "SKU-B001",
        "price": "20000",
        "quantity": "1"
      }
    ]
  },
  "amount": {
    "currency": "IDR",
    "value": "31100.00"
  },
  "partnerReferenceNo": "PL-ORDER-20241209-0001",
  "urlParams": [
    {
      "type": "PAY_RETURN",
      "url": "https://merchant.example.com/payment/return",
      "isDeeplink": "N"
    },
    {
      "url": "https://merchant.example.com/payment/notify",
      "type": "PAY_NOTIFY",
      "isDeeplink": "N"
    }
  ]
}
ParameterTypeMandatoryKeteranganContoh
responseCodestring✓Kode response dari sistem2005400
responseMessagestring✓Pesan responseSuccess
referenceNostring✓Nomor referensi dari sistem/payment gateway01KN6MW3JJZJV8J6C41BGJJTW0
partnerReferenceNostring✓Nomor referensi dari partnerPL-ORDER-20241209-0001
webRedirectUrlstring✓URL untuk redirect ke halaman pembayaranhttps://payment-link.com/abc
additionalInfoobject✓Informasi tambahanLihat additionalInfo

amount response​

ParameterTipeMandatoriKeteranganContoh
valuestring✓ISO4217 dengan 2 desimal100000.00
currencystring✓Kode mata uang, hanya menerima IDR.IDR

additionalInfo response​

ParameterTypeMandatoryKeteranganContoh
paymentCodestring✓Kode pembayaran1234567890

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

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

Header Check Payment​

ParameterTipeMandatoriKeteranganContoh
Content-Typestring✓string yang menunjukkan jenis media.application/json
X-TIMESTAMPstring✓ISO-86012022-09-16T13:00:00+07:00
X-SIGNATUREstring✓Lihat bagian symmetric signature
X-PARTNER-IDstring✓Merchant Ref dari dashboard Doitpay01JP4QP4R908GVK9X5KN7YCJEG
X-EXTERNAL-IDstring(64)✓Request ID yang unik.
CHANNEL-IDstring✓Nilai seharusnya DOITPAY
Authorizationstring✓Otentikasi dengan bearer token lihat disini pada bagian access tokenBearer ZGMyNDA3NWQtNmM4Ny00NGNiLTQ2NTAtMDhkYWMxNTAzNzY0

Request Body Check Payment​

ParameterTipeMandatoriKeteranganContoh
originalPartnerReferenceNostring✓Referensi transaksi asli01KN6Q41ZPXNRQ72VFG6R3F9PK

Example Check Payment​

{
  "originalPartnerReferenceNo": "01KFJCH1XWF1DKJMB259ZC7JMQ"
}

Response Body Check Payment​

ParameterTypeMandatoryKeteranganContoh
responseCodestring✓Kode response dari sistem2005500
responseMessagestring✓Pesan responseRequest has been processed successfully
originalReferenceNostring✓Nomor referensi original dari sistem01KN6MW3JJZJV8J6C41BGJJTW0
originalPartnerReferenceNostring✓Nomor referensi original dari partner01KN6MW3JJZJV8J6C41BGJJTW0
serviceCodestring✓Kode service transaksi54
latestTransactionStatusstringStatus transaksi terkini00
• 00: Success
• 01: Initiated
• 02: Paying
• 03: Pending
• 04: Refunded
• 05: Canceled
• 06: Failed
• 07: Not found
paidTimestring✓Waktu pembayaran2024-12-09T23:00:00+07:00
transAmountobject✓Nilai transaksi yang dibayarkanLihat transAmount response

transAmount response​

ParameterTipeKeteranganContoh
valuestringISO4217 dengan 2 desimal1000.00
currencystringKode mata uang, hanya menerima IDR.IDR
  • Method: POST
  • Type:application/json
  • Path: https://yourdomain.com/v1.0/payment-link/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​

ParameterTipeMandatoriKeteranganContoh
X-TIMESTAMPstring✓ISO-86012022-09-16T13:00:00+07:00
X-SIGNATUREstring✓Lihat Symmetric Signature Payment Notification
X-PARTNER-IDstring✓Merchant Ref dari dashboard Doitpay01JP4QP4R908GVK9X5KN7YCJEG
X-EXTERNAL-IDstring(64)✓Request ID yang unik.
CHANNEL-IDstring✓

Request Body Payment Notification​

ParameterTipeMandatoriKeteranganContoh
originalPartnerReferenceNostring✓Referensi transaksi asliORDER123456789
originalReferenceNostring✓Nomor referensi e-walletEW123456789
latestTransactionStatusstring✓Status akhir transaksi00
• 00: Success
• 01: Initiated
• 02: Paying
• 03: Pending
• 04: Refunded
• 05: Canceled
• 06: Failed
• 07: Not found
amountobject✓Detail jumlah transaksiLihat amount
additionalInfoobject✓Informasi tambahan notifikasiLihat additionalInfo

amount Request Body Payment Notification​

ParameterTipeKeteranganContoh
valuestringISO4217 dengan 2 desimal. Menunjukkan nominal pembayaran.1000.00
currencystringKode mata uang, hanya menerima IDR.IDR

additionalInfo Request Body Payment Notification​

ParameterTipeKeteranganContoh
channelCodestringKode kanal e-walletDANA

Response Body​

ParameterTipeKeteranganContoh
responseCodestringKode response, lihat bagian daftar Response Code di bawah2005600
responseMessagestringPenjelasan terhadap response code yang diterimaSuccessful

Response Code Payment Notification​

KodeKeterangan
200XX00Berhasil membuat request. Dimana XX adalah service code untuk setiap API Payment Link.
409XX00Conflict external ID saat membuat payment link. Dimana XX adalah service code untuk setiap API Payment Link.
400XX01Invalid field format. Dimana XX adalah service code untuk setiap API Payment Link.
400XX02Missing mandatory field. Dimana XX adalah service code untuk setiap API Payment Link.
401XX00Unauthorized Signature. Dimana XX adalah service code untuk setiap API Payment Link.
401XX01Invalid Access Token. Dimana XX adalah service code untuk setiap API Payment Link.
500XX00Terjadi kesalahan sistem di doitpay, mohon dibantu menghubungi doitpay untuk mendapatkan detail. Dimana XX adalah service code untuk setiap API Payment Link