Cancel Payment

This endpoint is used to manually cancel a bill/payment that is still in the pending status. Once a payment is cancelled, its status changes to cancelled and the customer can no longer pay for it (depending on provider support).

⚠️ Note: Currently, the cancellation process only changes the state (status) internally in the Gerbang Pay database. The feature to actively forward the cancellation request directly to the Winpay or Midtrans API has not yet been fully implemented (cancellation to the provider is not performed). Customers who try to pay for a VA that has been cancelled via Gerbang Pay may find the VA is still active in the bank's system.

POST /v1/payments/{payment_id}/cancel

Request Parameters

Parameter	Type	Location	Required	Description
payment_id	string (UUID)	URL Path	✅	ID of the payment to be cancelled

Request Headers

Header	Type	Required	Description
Authorization	string	✅	Bearer {api_key} or Bearer {jwt_token}

Response

If successful, the response will contain the complete payment data with the status field updated to cancelled.

Example 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"

Example Success Response (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"
    // ... other fields
  }
}

Common Error Responses

409 Invalid State Transition

Cancellation can only be performed if the current transaction status is pending or challenged. If the transaction is already paid, expired, or has already been cancelled, the system will reject this request.

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

404 Not Found

Occurs if the payment is not found or belongs to another tenant.

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