Cancel Payment

Endpoint ini digunakan untuk membatalkan secara manual tagihan/pembayaran yang masih dalam status pending. Begitu pembayaran dibatalkan, statusnya berubah menjadi cancelled dan pelanggan tidak dapat lagi membayarnya (bergantung pada dukungan provider).

⚠️ Catatan: Saat ini, proses pembatalan hanya mengubah state (status) di sisi internal database Gerbang Pay. Fitur untuk meneruskan permintaan pembatalan secara aktif langsung ke API Winpay atau Midtrans belum sepenuhnya diimplementasikan (pembatalan ke provider belum dilakukan). Pelanggan yang mencoba membayar VA yang telah di-cancel via Gerbang Pay mungkin mendapati VA tersebut masih aktif di sistem bank.

POST /v1/payments/{payment_id}/cancel

Request Parameter

Parameter	Tipe	Lokasi	Required	Deskripsi
payment_id	string (UUID)	URL Path	✅	ID pembayaran yang akan dibatalkan

Request Headers

Header	Tipe	Required	Deskripsi
Authorization	string	✅	Bearer {api_key} atau Bearer {jwt_token}

Response

Jika sukses, response akan berisi data pembayaran lengkap dengan field status yang sudah diperbarui menjadi cancelled.

Contoh Request

curl -X POST https://gerbang-pay-api.gai.co.id/v1/payments/550e8400-e29b-41d4-a716-446655440000/cancel \
  -H "Authorization: ApiKey gp_live_xxxxxxxxxxxx"

Contoh Response Sukses (200 OK)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "b6a3b2b8-f09d-4767-8fa0-68153c30a91f",
    "payment_code": "TEST-12345678",
    "amount": 10000000,
    "currency": "IDR",
    "method_type": "virtual_account",
    "status": "cancelled",
    "provider": "winpay",
    "created_at": "2026-07-21T11:00:00Z",
    "updated_at": "2026-07-21T11:15:00Z"
    // ... field lain
  }
}

Response Error Umum

409 Invalid State Transition

Pembatalan hanya bisa dilakukan jika status transaksi saat ini adalah pending atau challenged. Jika transaksi sudah paid (lunas), expired (kadaluarsa), atau sudah pernah di-cancelled, sistem akan menolak permintaan ini.

{
  "success": false,
  "error": {
    "code": "INVALID_STATE_TRANSITION",
    "message": "invalid state transition: from paid to cancelled"
  }
}

404 Not Found

Terjadi jika payment tidak ditemukan atau dimiliki oleh tenant lain.

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "not found: payment 550e8400... not found"
  }
}