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 partnerORDER123456789
amountobject✓Detail jumlah transaksiLihat amount
urlParamsarray of object✗Konfigurasi URLLihat urlParams
externalStoreIdstring✗ID toko eksternalSTORE123
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-111111111
companyDetailsstring✗Detail perusahaanMerak Corporation
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 tambahanTest payment link 11111111
taxPercentagestring✗Persentase pajak dalam bentuk decimal (contoh: 0.1 = 10%, 1 = 100%) yang diterapkan pada jumlah subtotal item0.1
discountstring✗Nilai diskon, dikurangi setelah subtotal item0
additionalFeestring✗Biaya tambahan0
isFeeChargedToUserboolean✗Menentukan apakah biaya dibebankan ke userfalse
customerNamestring✗Nama pelangganAudrey Hepburn
customerMobileNostring✗Nomor HP pelanggan081234567890
customerAddressstring✗Alamat pelangganJl. Test No. 123, Jakarta
customerEmailstring✗Email pelanggan[email protected]

item request​

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

kalkulasi amount​

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": "",
  "partnerReferenceNo": "01KN6MW3JJZJV8J6C41BGJJTW0",
  "additionalInfo": {
    "additionalFee": "1500",
    "taxPercentage": "0.02",
    "billTo": "[email protected]",
    "companyDetails": "Merak Corporation",
    "currency": "IDR",
    "customerAddress": "Jl. Test No. 123, Jakarta",
    "customerEmail": "[email protected]",
    "customerMobileNo": "081234567890",
    "customerName": "Audrey Hepburn",
    "discount": "1000",
    "isFeeChargedToUser": false,
    "items": [
      {
        "itemName": "Product A",
        "itemNotes": "Test product",
        "itemSku": "SKU-001",
        "price": "10000",
        "quantity": "1"
      },
      {
        "itemName": "Product B",
        "itemNotes": "Test product",
        "itemSku": "SKU-001",
        "price": "20000",
        "quantity": "1"
      }
    ],
    "notes": "Test payment link {{$timestamp}}",
    "purchaseOrder": "PO-111111111",
  },
  "amount": {
    "currency": "IDR",
    "value": "31100.00"
  },
  "urlParams": [
    {
      "type": "PAY_RETURN",
      "url": "https://webhooks.tunnelite.com/webhooks/orange-whale-616416",
      "isDeeplink": "Y"
    },
    {
      "url": "https://webhook.site/a1714951-c2c0-417b-926b-d7204ecaed85",
      "type": "NOTIFICATION",
      "isDeeplink": "Y"
    }
  ]
}

Example Payment Link - Mandatory Request​

{
    "additionalInfo": {
        "items": [
            {
                "itemName": "Product",
                "itemNotes": "Test product",
                "itemSku": "SKU-001",
                "price": "10000",
                "quantity": "1"
            },
            {
                "itemName": "Product B",
                "itemNotes": "Another test product",
                "itemSku": "SKU-002",
                "price": "10000",
                "quantity": "2"
            }
        ]
    },
    "amount": {
        "currency": "IDR",
        "value": "30000.00"
    },
    "partnerReferenceNo": "01KKJYV2R1GYSHQ9C5ZYPY2S2W",
    "urlParams": [
        {
            "isDeeplink": "N",
            "type": "PAY_RETURN",
            "url": "https://example.com/success"
        }
    ]
}
ParameterTypeMandatoryKeteranganContoh
responseCodestring✓Kode response dari sistem2005400
responseMessagestring✓Pesan responseSuccess
referenceNostring✓Nomor referensi dari sistem/payment gateway01KN6MW3JJZJV8J6C41BGJJTW0
partnerReferenceNostring✓Nomor referensi dari partner01KN6MW3JJZJV8J6C41BGJJTW0
webRedirectUrlstring✓URL untuk redirect ke halaman pembayaranhttps://payment-link.com/abc
additionalInfoobject✓Informasi tambahan[Lihat additionalInfo](#additionalInfo response)

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: /api/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 responseSuccess
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