Dokumentasi API VeltrayPay

VeltrayPay REST API memungkinkan website toko online, bot Telegram, maupun aplikasi mobile Anda untuk membuat tagihan QRIS otomatis dan menerima konfirmasi pembayaran secara realtime. 100% Tanpa KYC — daftar dan langsung integrasikan dalam 5 menit!

Base API URL: https://pay.veltray.com/api/v1/gateway

1. Autentikasi

Semua permintaan API mewajibkan pengiriman API Key Anda. Anda dapat membuat API Key di Portal Merchant tanpa perlu upload KTP.

Kirimkan API Key melalui HTTP Request Header:

X-API-Key: nk_your_secret_api_key_here

2. Buat Tagihan QRIS Baru

POST /invoice/create

Membuat invoice tagihan QRIS baru dengan kode unik verifikasi otomatis.

Parameter Request (JSON)

Field	Tipe	Wajib	Deskripsi
`amount`	Numeric	Ya	Nominal tagihan dalam Rupiah (min. 1000)
`merchant_ref`	String	Ya	Nomor invoice internal toko Anda (misal: INV-2026-001)
`callback_url`	String	Opsional	URL webhook toko Anda untuk notifikasi lunas
`customer_name`	String	Opsional	Nama pelanggan
`customer_phone`	String	Opsional	Nomor WhatsApp pelanggan

Contoh Request (cURL)

curl -X POST "https://pay.veltray.com/api/v1/gateway/invoice/create" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "amount": 50000,
    "merchant_ref": "ORDER-9912",
    "customer_name": "Budi Santoso",
    "callback_url": "https://toko-anda.com/api/callback"
  }'

Contoh Response Sukses (201 Created)

{
  "success": true,
  "message": "Tagihan QRIS berhasil dibuat",
  "data": {
    "invoice_code": "VT-261106THUFK0",
    "merchant_ref": "ORDER-9912",
    "amount": 50000,
    "unique_code": 142,
    "total_amount": 50142,
    "fee": 500,
    "merchant_received": 49642,
    "payment_method": "qris",
    "status": "pending",
    "qr_image_url": "https://api.qrserver.com/v1/create-qr-code/?size=350x350&data=...",
    "checkout_url": "https://pay.veltray.com/pay/checkout/VT-261106THUFK0",
    "expired_at": "2026-11-06T11:45:00+07:00",
    "created_at": "2026-11-06T11:15:00+07:00"
  }
}

3. Cek Status Tagihan

GET /invoice/status/{invoice_code}

Mengecek status tagihan secara berkala jika Anda tidak menggunakan webhook.

curl -X GET "https://pay.veltray.com/api/v1/gateway/invoice/status/VT-261106THUFK0" \
  -H "X-API-Key: YOUR_API_KEY"

4. Webhook Callback Realtime

Saat pembeli berhasil melakukan scan dan pembayaran QRIS, server VeltrayPay akan secara otomatis mengirimkan permintaan HTTP POST ke callback_url toko Anda dengan payload JSON berikut:

{
  "event": "payment.received",
  "invoice_code": "VT-261106THUFK0",
  "merchant_ref": "ORDER-9912",
  "amount": 50000,
  "total_amount": 50142,
  "fee": 500,
  "merchant_received": 49642,
  "status": "paid",
  "paid_at": "2026-11-06T11:20:15+07:00",
  "timestamp": 1793938815
}

Pastikan server webhook Anda merespons dengan HTTP 200 OK dan JSON {"status": "ok"} agar sistem kami mengetahui callback berhasil diterima.

5. Verifikasi Keamanan Signature (HMAC SHA256)

Untuk memastikan callback benar-benar berasal dari server resmi VeltrayPay dan bukan upaya penipuan (*spoofing*), kami menyertakan header signature:

X-VeltrayPay-Sign: 7a8f9c4b2e... (HMAC SHA256 Hash)

Contoh Verifikasi Signature di PHP:

$incomingSignature = $_SERVER['HTTP_X_VELTRAYPAY_SIGN'] ?? '';
$rawPayload = file_get_contents('php://input');
$myWebhookSecret = 'whsec_your_secret_from_dashboard';

$expectedSignature = hash_hmac('sha256', $rawPayload, $myWebhookSecret);

if (hash_equals($expectedSignature, $incomingSignature)) {
    // Signature VALID! Silakan proses pesanan / kirim voucher ke pelanggan
    $data = json_decode($rawPayload, true);
    // updateDatabaseOrder($data['merchant_ref'], 'PAID');
    http_response_code(200);
    echo json_encode(['status' => 'ok']);
} else {
    // Signature INVALID! Tolak request
    http_response_code(403);
    echo json_encode(['error' => 'Invalid signature']);
}