Create Payment

Endpoint ini digunakan untuk membuat transaksi pembayaran baru. Endpoint ini mendukung berbagai metode pembayaran melalui satu interface seragam. Anda hanya perlu mengganti parameter method_type dan method_detail.

⚠️ Penting: Hanya tenant dengan role Client yang dapat mengakses endpoint ini. Anda harus menggunakan API Key, bukan JWT.

POST /v1/payments/create

Request Headers

Header	Tipe	Required	Deskripsi
Authorization	string	✅	Harus berisi Bearer {api_key}
Content-Type	string	✅	Selalu application/json
X-Idempotency-Key	string	✅	Key unik per pesanan (contoh: nomor order dari sistem Anda) untuk mencegah duplikasi jika terjadi network error

Request Body

Field	Tipe	Required	Deskripsi
amount	integer	✅	Nominal tagihan dalam satuan terkecil (sen). Contoh: Rp 100.000 ditulis sebagai 10000000
currency	string	✅	Mata uang. Saat ini hanya mendukung "IDR"
method_type	string	✅	Jenis metode pembayaran. Lihat tabel Method Type
method_detail	object	✅	Parameter spesifik untuk metode pembayaran. Selalu sertakan field "type" yang nilainya sama dengan method_type. Lihat per-method di bawah
customer_name	string	❌	Nama pelanggan Anda
customer_email	string	❌	Email pelanggan (wajib berformat email valid jika diisi)
customer_phone	string	❌	Nomor handphone pelanggan (penting untuk beberapa tipe E-Wallet)
items	array	❌	Detail produk/layanan yang dibeli pelanggan
expiry_minutes	integer	❌	Waktu kadaluarsa dalam menit. Default: 60. Minimum: 2 (Winpay)

Method Type (method_type)

Nilai	Keterangan
virtual_account	Transfer via Virtual Account Bank
qris	Pembayaran QRIS (Dynamic)
e_wallet	Dompet Digital (OVO, DANA, dll)
over_the_counter	Pembayaran di gerai ritel (Alfamart, Indomaret)

Method Detail

Field method_detail wajib diisi dan bentuk objeknya bergantung pada nilai method_type. Perhatikan bahwa field "type" wajib ada di dalam objek method_detail.

1. Virtual Account

{
  "type": "virtual_account",
  "bank": "BCA" // Lihat list bank yang aktif di /v1/active-methods
}

2. QRIS

{
  "type": "qris"
}

3. E-Wallet

{
  "type": "e_wallet",
  "wallet_type": "DANA" // OVO, DANA, SHOPEEPAY, dll
}

4. Over The Counter (Gerai)

{
  "type": "over_the_counter",
  "store": "ALFAMART" // ALFAMART, INDOMARET
}

Array Items

Objek array opsional untuk rincian produk:

[
  {
    "id": "SKU-001",
    "name": "Kopi Susu Gula Aren",
    "price": 2500000, 
    "quantity": 2
  }
]

(Ingat: price dalam bentuk sen, sehingga 2500000 = Rp 25.000)

---

Response

Struktur response standar mengembalikan rincian pembayaran termasuk instruksi spesifik per-metode (method_data).

Response Berhasil (200 OK)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "b6a3b2b8-f09d-4767-8fa0-68153c30a91f",
    "payment_code": "TEST-12345678",
    "idempotency_key": "order-123",
    "amount": 10000000,
    "currency": "IDR",
    "method_type": "virtual_account",
    "method_data": {
      "type": "virtual_account",
      "bank": "BCA",
      "va_number": "88880123456789"
    },
    "status": "pending",
    "provider": "winpay",
    "provider_payment_id": "WP-998877",
    "customer_name": "Budi Santoso",
    "customer_email": "[email protected]",
    "customer_phone": "081234567890",
    "items": [],
    "expires_at": "2026-07-21T12:00:00Z",
    "paid_at": null,
    "amount_paid": null,
    "failure_reason": null,
    "created_at": "2026-07-21T11:00:00Z",
    "updated_at": "2026-07-21T11:00:00Z"
  }
}

Response Field method_data

Field ini akan berubah-ubah sesuai metode pembayaran, serupa dengan request method_detail:

• Virtual Account: { "type": "virtual_account", "bank": "BCA", "va_number": "8888..." }
• QRIS: { "type": "qris", "qr_string": "000201010211...", "qr_image_url": "https://..." }
• E-Wallet: { "type": "e_wallet", "wallet_type": "DANA", "redirect_url": "https://...", "deeplink": "dana://..." }
• Over The Counter: { "type": "over_the_counter", "store_name": "ALFAMART", "payment_code": "44445555" }

---

Contoh Request Lengkap

1. Virtual Account

curl -X POST https://gerbang-pay-api.gai.co.id/v1/payments/create \
  -H "Authorization: ApiKey gp_live_xxx" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-va-001" \
  -d '{
    "amount": 15000000,
    "currency": "IDR",
    "method_type": "virtual_account",
    "method_detail": { "type": "virtual_account", "bank": "BCA" },
    "customer_name": "Budi"
  }'

2. QRIS

curl -X POST https://gerbang-pay-api.gai.co.id/v1/payments/create \
  -H "Authorization: ApiKey gp_live_xxx" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-qris-002" \
  -d '{
    "amount": 5000000,
    "currency": "IDR",
    "method_type": "qris",
    "method_detail": { "type": "qris" }
  }'

3. E-Wallet

curl -X POST https://gerbang-pay-api.gai.co.id/v1/payments/create \
  -H "Authorization: ApiKey gp_live_xxx" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-ewallet-003" \
  -d '{
    "amount": 2500000,
    "currency": "IDR",
    "method_type": "e_wallet",
    "method_detail": { "type": "e_wallet", "wallet_type": "OVO" }
  }'

4. Over The Counter (Gerai Ritel)

curl -X POST https://gerbang-pay-api.gai.co.id/v1/payments/create \
  -H "Authorization: ApiKey gp_live_xxx" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-otc-004" \
  -d '{
    "amount": 10000000,
    "currency": "IDR",
    "method_type": "over_the_counter",
    "method_detail": { "type": "over_the_counter", "store": "ALFAMART" }
  }'

---

Response Error Umum

400 Bad Request

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "bad request: Amount must be greater than zero"
  }
}

409 Idempotency Conflict

Terjadi jika Anda mengirim X-Idempotency-Key yang sama persis namun dengan parameter body yang berbeda.

{
  "success": false,
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "idempotency conflict: Same key submitted with different payload"
  }
}

502 Provider Error

Terjadi jika server Winpay atau Midtrans menolak request Anda (contoh: nama bank salah).

{
  "success": false,
  "error": {
    "code": "PROVIDER_ERROR",
    "message": "provider error [winpay]: Bank BCA is not supported for this merchant"
  }
}