GPAY Developer API
API v1Merchant-facing contract for QRIS, DANA, VA and payouts. Provider details remain internal.
Migration status
Developer specification is provided for testing; production payment and payout are not enabled.
API base URL: https://api.gpay.live/v1. Use your GPAY merchant key and authorized IP. All money amounts are integers in IDR.
Contents
Authentication
Send Authorization: Bearer YOUR_GPAY_KEY over HTTPS. Requests must originate from a merchant-approved IP/CIDR; the merchant API key and merchant account must be active. Content type for POST is application/json.
POST /payments
QRIS, DANA and VA share one create endpoint
POST https://api.gpay.live/v1/payments
Authorization: Bearer YOUR_GPAY_KEY
Content-Type: application/json
Idempotency-Key: INV-10001-v1
{"reference_id":"INV-10001","amount":100000,"method":"QRIS","customer":"budi123"}
customer is one required string (merchant customer username or ID); never send an object. For DANA use "method":"DANA". For VA use "method":"VA","bank_code":"BCA" (bank codes must come from the enabled channel catalog). Do not send name, email, or phone fields. Positive amounts follow merchant minimum/limits; reference IDs must match [A-Za-z0-9._:-] and be at most 120 characters.
Successful create returns HTTP 201, a success flag, and payment object containing id, reference_id, amount, fee, method, customer, status, and any available QR/VA/DANA instructions. A provider-disabled installation returns 503 rather than a live payment instruction.
Inquiry, merchant balance & channels
GET /v1/payments/{id} # payment ID from create response
GET /v1/payments # list for authenticated merchant
GET /v1/payouts/{id} # payout ID from create response
GET /v1/payouts # list for authenticated merchant
GET /v1/balance # available / pending / reserved (IDR)
GET /v1/channels # enabled QRIS, DANA, VA and VA bank codes
Inquiry is scoped to the Bearer key's merchant. An unknown payment, payout, or another merchant's ID returns 404. Channels currently enumerate pay-in methods only; payout destinations use the separate payout catalog and policy.
POST /payouts
Uses GPAY merchant account policy and financial reservation
POST https://api.gpay.live/v1/payouts
Authorization: Bearer YOUR_GPAY_KEY
Content-Type: application/json
Idempotency-Key: WD-10001-v1
{"reference_id":"WD-10001","amount":100000,"channel":"BCA","account":"1234567890","name":"Synthetic Recipient"}
For a registered account, pass account_id instead of raw destination fields. A merchant with policy REGISTERED_ONLY must use an active approved account. Payout creation remains disabled until signed callback and MySQL settlement tests are completed.
Merchant webhooks and HMAC
Configure separate HTTPS URLs and secrets for PAYIN and PAYOUT in your Merchant panel. GPAY queues events for delivery; examples include payment.paid, payout.success, and payout.failed. Exact event vocabulary should be verified against the final integration tests.
X-GPAY-Event: payment.paid:GPY-EXAMPLE:PAID
X-GPAY-Timestamp: 1760000000
X-GPAY-Signature: v1=<hex sha256 HMAC>
signed_data = timestamp + "." + raw_request_body
expected = "v1=" + HMAC_SHA256_HEX(webhook_secret, signed_data)
Compare signatures with constant-time comparison; reject timestamps older than your replay window (for example, 300 seconds), store a unique event ID for duplicate delivery protection, and return a 2xx response promptly. Do not re-serialize JSON before computing the signature.
Idempotency and errors
Use a unique Idempotency-Key per business operation (8–190 safe characters). Repeating identical JSON can replay the cached response; a different body under the same key returns IDEMPOTENCY_CONFLICT (409). Merchant reference_id is also unique. An uncertain provider result must be reconciled before retrying with a new reference.
Typical errors: 400 invalid idempotency key; 401 unauthorized; 403 IP/merchant policy; 404 not found; 409 conflicting reference or in-progress request; 422 validation/limits; 429 rate limit; 503 provider or callback not ready. Error JSON includes success:false, error and message.
Integration examples
All samples use synthetic values and do not imply a live charge.
cURL
curl -X POST 'https://api.gpay.live/v1/payments' \
-H 'Authorization: Bearer YOUR_GPAY_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: INV-10001-v1' \
-d '{"reference_id":"INV-10001","amount":100000,"method":"QRIS","customer":"budi123"}'
PHP Native
$ch = curl_init('https://api.gpay.live/v1/payments');
curl_setopt_array($ch, [
CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer '.getenv('GPAY_API_KEY'), 'Content-Type: application/json', 'Idempotency-Key: INV-10001-v1'],
CURLOPT_POSTFIELDS => json_encode(['reference_id' => 'INV-10001', 'amount' => 100000, 'method' => 'QRIS', 'customer' => 'budi123']),
]);
$response = curl_exec($ch); curl_close($ch);
Laravel
$response = \Illuminate\Support\Facades\Http::withToken(config('services.gpay.api_key'))
->withHeaders(['Idempotency-Key' => 'INV-10001-v1'])
->post('https://api.gpay.live/v1/payments', [
'reference_id' => 'INV-10001', 'amount' => 100000, 'method' => 'QRIS', 'customer' => 'budi123',
]);
Node.js
const response = await fetch('https://api.gpay.live/v1/payments', {
method: 'POST',
headers: {Authorization: `Bearer ${process.env.GPAY_API_KEY}`,
'Content-Type':'application/json','Idempotency-Key':'INV-10001-v1'},
body: JSON.stringify({reference_id:'INV-10001', amount:100000, method:'QRIS', customer:'budi123'})
});
const payment = await response.json();