Metadata

Metadata adalah objek berisi teks yang ditambahkan ke pembayaran. Gunakan untuk menyimpan referensi dari sistemmu, seperti ID order, ID pelanggan, atau nama kampanye.

Menambah metadata

Kirim metadata saat membuat pembayaran:

curl -X POST "https://api.baiyar.com/v1/payments" \
  -H "Authorization: Bearer $BAIYAR_KEY" \
  -H "Idempotency-Key: order-1001-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000000,
    "currency": "IDR",
    "payment_method": "payment.qris",
    "metadata": { "order_id": "1001", "customer_id": "cus_42" }
  }'

Metadata tidak bisa diubah setelah pembayaran dibuat. Jika nilainya berubah, buat pembayaran baru.

Batas

	Batas
Jumlah key	Sampai 20
Nilai	Teks, sampai 500 karakter

Angka dikirim sebagai teks ("42"), dan nilai tidak pernah berupa objek atau daftar.

Di mana ia kembali

metadata disertakan dalam setiap respons yang memuat pembayaran dan dalam event webhook terkait, seperti payment.succeeded:

{
  "data": {
    "id": "pay_01k7q3m8x2v5t9n4b6c1d0e7fa",
    "status": "paid",
    "metadata": { "order_id": "1001", "customer_id": "cus_42" }
  },
  "meta": { "request_id": "req_Hy3k9QzT2LmN8vXa" }
}

Jika tidak diisi, nilainya {}.

Praktik terbaik

• Simpan ID dari sistemmu di metadata agar event webhook bisa dicocokkan dengan order tanpa request tambahan.
• Jangan simpan secret atau data pribadi. Metadata dikembalikan apa adanya dan disertakan dalam event yang dikirim ke endpoint-mu.
• Untuk mencari pembayaran berdasarkan referensimu, gunakan merchant_reference dan filter dengan nama yang sama. Daftar pembayaran tidak mendukung filter metadata. Lihat Filter daftar.

Halaman terkait

• Buat pembayaran
• Webhook
• Tipe data