Dokumentasi API Pembayaran

Mulai cepat

Tiga langkah sampai pembayaran pertama Anda terbentuk.

1. Daftar dan terbitkan kunci sandbox dari halaman ringkasan.
2. Kirim permintaan pembuatan pembayaran seperti contoh di bawah.
3. Daftarkan alamat notifikasi agar sistem Anda tahu ketika pelanggan sudah membayar.

curl -X POST http://localhost:3040/api/v1/payments \
  -H "Authorization: Bearer lg_sandbox_kunci_anda" \
  -H "Idempotency-Key: PESANAN-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "PESANAN-0001",
    "amount": 150000,
    "method": { "type": "VIRTUAL_ACCOUNT", "channel": "BNI" }
  }'

Autentikasi

Setiap permintaan menyertakan kunci pada tajuk Authorization.

Authorization: Bearer lg_sandbox_a1b2c3d4_xxxxxxxxxxxxxxxx
Idempotency-Key: PESANAN-0001
Content-Type: application/json

Kanal pembayaran

Daftar kanal yang benar-benar dapat Anda pakai, sudah dikelompokkan dan mengikuti lingkungan kunci yang dipakai. Gunakan ini untuk menyusun pilihan pembayaran, agar Anda tidak menawarkan kanal yang akan ditolak saat tagihan dibuat.

curl https://api.langsunggas.example/api/v1/channels \
  -H "Authorization: Bearer lg_sk_test_xxxxxxxx"

{
  "environment": "SANDBOX",
  "total": 9,
  "data": [
    {
      "group": "VIRTUAL_ACCOUNT",
      "group_name": "Virtual Account",
      "channels": [
        {
          "code": "BNI",
          "name": "Bank BNI",
          "method_type": "VIRTUAL_ACCOUNT",
          "description": "Virtual account nominal terkunci",
          "available": true
        }
      ]
    },
    {
      "group": "QR",
      "group_name": "QRIS",
      "channels": [
        {
          "code": "QRIS",
          "name": "QRIS",
          "method_type": "QRIS",
          "description": "Pindai kode dari aplikasi apa pun yang mendukung QRIS",
          "available": true
        }
      ]
    }
  ]
}

Kolom code adalah nilai yang Anda kirim padamethod.channel, sedangkan method_typeadalah nilai untuk method.type.

Membuat pembayaran

Virtual Account:

{
  "reference_id": "PESANAN-2026-0001",
  "amount": 275000,
  "method": { "type": "VIRTUAL_ACCOUNT", "channel": "BNI" },
  "customer": { "name": "Budi Santoso" }
}

QRIS:

{
  "reference_id": "PESANAN-2026-0002",
  "amount": 45000,
  "method": { "type": "QRIS" }
}

Jawaban berhasil dengan kode 201:

{
  "id": "pay_xxxxxxxxxxxx",
  "reference_id": "PESANAN-2026-0001",
  "status": "PENDING",
  "amount": 275000,
  "currency": "IDR",
  "method": {
    "type": "VIRTUAL_ACCOUNT",
    "channel": "BNI",
    "accountNumber": "8808999979278987",
    "accountName": "XDT-InoPay"
  },
  "expires_at": "2026-08-21T03:59:21.317Z",
  "created_at": "2026-08-21T02:59:21.631Z"
}

Idempotensi

Tajuk Idempotency-Key wajib disertakan pada setiap pembuatan pembayaran. Tajuk ini mencegah tagihan ganda ketika jaringan bermasalah dan permintaan yang sama terkirim dua kali.

Membaca pembayaran

Daftar memakai penomoran berbasis kursor. Sertakan nilainext_cursor dari jawaban sebelumnya untuk mengambil halaman berikutnya.

{
  "data": [
    {
      "id": "pay_xxxxxxxxxxxx",
      "status": "PAID",
      "amount": 275000,
      "paid_at": "2026-08-21T03:01:04Z"
    }
  ],
  "has_more": true,
  "next_cursor": "cmt2xxxxxxxxxx"
}

Notifikasi

Ketika status pembayaran berubah, kami mengirim pemberitahuan ke alamat yang Anda daftarkan pada halaman Notifikasi.

{
  "id": "evt_xxxxxxxxxxxx",
  "type": "payment.paid",
  "created_at": "2026-08-21T03:01:05Z",
  "livemode": true,
  "data": {
    "payment": {
      "id": "pay_xxxxxxxxxxxx",
      "reference_id": "PESANAN-2026-0001",
      "status": "PAID",
      "amount": 275000,
      "paid_at": "2026-08-21T03:01:04Z"
    }
  }
}

Pengiriman dianggap berhasil hanya bila sistem Anda menjawab dengan kode 2xx dalam sepuluh detik. Bila gagal, pengiriman diulang dengan jeda menaik: satu menit, lima menit, tiga puluh menit, dua jam, delapan jam, lalu dua puluh empat jam.

Verifikasi tanda tangan

Contoh dengan Node.js:

import { createHmac, timingSafeEqual } from "node:crypto";

// Ambil isi mentah, jangan diuraikan lebih dulu.
const rawBody = await request.text();
const timestamp = request.headers.get("x-webhook-timestamp");
const signature = request.headers.get("x-webhook-signature");

// Tolak notifikasi lama untuk mencegah pengiriman ulang.
if (Math.abs(Date.now() - Number(timestamp)) / 1000 > 300) {
  return new Response(null, { status: 400 });
}

const diharapkan = createHmac("sha256", RAHASIA_ANDA)
  .update(timestamp + "." + rawBody)
  .digest("hex");

const a = Buffer.from(diharapkan);
const b = Buffer.from(signature);

if (a.length !== b.length || timingSafeEqual(a, b) === false) {
  return new Response(null, { status: 400 });
}

const event = JSON.parse(rawBody);
return new Response(null, { status: 200 });

Contoh dengan PHP:

<?php
$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'];
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];

if (abs(round(microtime(true) * 1000) - (int)$timestamp) / 1000 > 300) {
    http_response_code(400);
    exit;
}

$diharapkan = hash_hmac('sha256', $timestamp . '.' . $rawBody, RAHASIA_ANDA);

if (!hash_equals($diharapkan, $signature)) {
    http_response_code(400);
    exit;
}

$event = json_decode($rawBody, true);
http_response_code(200);

Status pembayaran

CREATED  ->  PENDING  ->  PAID
                 |
                 +-->  EXPIRED / FAILED / CANCELLED

Kode kesalahan

Seluruh kesalahan memakai bentuk yang sama.

{
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Nominal di luar batas yang diizinkan",
    "request_id": "req_xxxxxxxx",
    "details": []
  }
}

Batas permintaan

Melampaui batas menghasilkan kode 429. Tunggu sesuai tajukRetry-After sebelum mencoba lagi.

Praktik yang disarankan

• Simpan nilai id yang kami kembalikan, bukan hanya nomor pesanan Anda sendiri.
• Sediakan pemeriksaan berkala sebagai cadangan bila notifikasi tidak kunjung tiba, misalnya karena peladen Anda sempat mati.
• Catat setiap notifikasi yang masuk beserta hasil pemeriksaan tanda tangannya, agar penelusuran masalah lebih mudah.
• Uji seluruh alur pada lingkungan sandbox, termasuk keadaan gagal, sebelum beralih ke produksi.