Errors

Use details.code to handle payment errors. It is the stable, machine-readable identifier for each error. Authentication failures can omit details and include only a message.

Error envelope

{
  "success": false,
  "message": "Payment was declined.",
  "details": {
    "code": "PAYMENT_DECLINED"
  }
}

Some codes add fields to details. For example, VOID_FAILED and PARTIAL_REFUND_PENDING include retryable and a suggestedAction. PAYMENT_DECLINED, PAYMENT_TIMEOUT and PAYMENT_GATEWAY_ERROR include id, the failed payment’s ID, when the payment engine returns one for the attempt (some timeouts do not). GET /payments/{id} returns that payment: failed after a decline or gateway error, and voided or unknown after a timeout, whose outcome may not be settled. Authentication failures with HTTP status 401 or 403 carry only message.

Error codes

Code	HTTP	Meaning
`VALIDATION_ERROR`	400	The request is malformed or a field is invalid. See `message` for details
`PAYMENT_DECLINED`	402	The card was declined
`PAYMENT_BLOCKED`	403	Payments are blocked for the case identified by the payment-level `referenceId`. Do not retry
`PAYMENT_HELD`	409	The case identified by the payment-level `referenceId` has a temporary payment hold. Try again later
`DECLINE_BLOCKED`	409	This card was declined recently and is temporarily blocked. Use another card or try again later
`VELOCITY_LIMIT`	429	Too many recent attempts for this case or card. Wait before retrying
`PAYMENT_NOT_ALLOWED`	422	The payment does not meet the portal’s payment rules or applicable case restrictions
`PORTAL_ACCESS_DENIED`	403	The portal does not exist or your API account may not use it
`PAYMENT_NOT_FOUND`	404	The payment does not exist or belongs to another API account
`IDEMPOTENCY_MISMATCH`	409	The `Idempotency-Key` was already used with a different request
`IDEMPOTENCY_IN_PROGRESS`	409	A request with this `Idempotency-Key` is still being processed. Retry after `Retry-After`
`IDEMPOTENCY_RECONCILIATION_REQUIRED`	409	An earlier request with this key ended in an unknown state. Contact GroGov before retrying
`INVALID_STATE`	422	The payment cannot be refunded or voided in its current state, or the refund exceeds the remaining amount
`VOID_FAILED`	422	The payment gateway rejected the void. Check `details.suggestedAction` for the next operation
`INTERNAL_ERROR`	500	An unexpected server error
`CAPTURE_NOT_SUPPORTED`	501	Authorize-then-capture is not supported. Payments charge immediately
`VAULT_NOT_SUPPORTED`	501	Storing cards and charging stored vault cards are not supported
`PAYMENT_GATEWAY_ERROR`	502	The payment gateway returned an error. The payment did not succeed
`PARTIAL_REFUND_PENDING`	502	The principal was refunded but the service fee refund failed. Retry the refund
`GATEWAY_NOT_CONFIGURED`	503	The portal has no payment gateway configured
`IDEMPOTENCY_UNAVAILABLE`	503	A request with an `Idempotency-Key` cannot be processed safely right now. Nothing was charged or refunded. Contact GroGov support
`PAYMENT_TIMEOUT`	504	The payment gateway response was missing or unreadable. The outcome is unknown. Check the payment before retrying

Handling patterns

Case-specific restrictions use the payment-level referenceId. This is separate from each line item’s referenceId. The applicable restrictions depend on the agency’s payment configuration.

`402 PAYMENT_DECLINED`

Show message to the cardholder. If details.id is present, the declined attempt is recorded as a failed payment. Do not retry the same card without cardholder action (a new card, a different payment method).

`403 PAYMENT_BLOCKED`

The agency has blocked payments for the case identified by the payment-level referenceId. Do not retry the blocked payment. Direct the payer to the agency.

`504 PAYMENT_TIMEOUT`

The outcome is unknown. The card may have been charged. Check the payment status before retrying. If details.id is present, call GET /payments/{id} with it. Otherwise, list recent payments (GET /payments with portalId and a from/to window) to see whether the payment succeeded before trying again. If the original request carried an Idempotency-Key, retrying with the same key returns 409 IDEMPOTENCY_RECONCILIATION_REQUIRED rather than charging twice. See Idempotency.

`502 PAYMENT_GATEWAY_ERROR`

The gateway reported an error and the payment did not go through. It is safe to retry after a short delay.

`422 INVALID_STATE` / `VOID_FAILED`

The payment does not allow the requested operation. It may already be voided or fully refunded, or the refund may exceed the remaining amount. The message states the remaining amount in cents. For VOID_FAILED, check details.suggestedAction: "refund" means the batch has settled and a refund is the correct next step; "retry_void" means part of the void succeeded and the void should be retried.

`502 PARTIAL_REFUND_PENDING`

The principal was refunded, but the separate service-fee refund failed. Retry the same refund; details.remainingRefundableAmountCents shows what is still outstanding.

`409` idempotency codes

For IDEMPOTENCY_MISMATCH, use a new key for a different operation. For IDEMPOTENCY_IN_PROGRESS, wait for the interval in Retry-After and retry with the same key. For IDEMPOTENCY_RECONCILIATION_REQUIRED, follow the idempotency guidance.

`501 CAPTURE_NOT_SUPPORTED` / `VAULT_NOT_SUPPORTED`

The feature is not supported. Send capture: "sale" (the default) and a card or card_token payment method.

`503 GATEWAY_NOT_CONFIGURED`

The portal has no payment gateway configured. Contact the agency or GroGov support before retrying.

`503 IDEMPOTENCY_UNAVAILABLE`

GroGov cannot record the Idempotency-Key for this request right now, so it was refused before anything was charged or refunded. Contact GroGov support; retry the same request with the same key once they confirm it is fixed.

`403 PORTAL_ACCESS_DENIED`

Your API account may not use the portalId in the request. Unknown portal IDs return the same code, so the response does not reveal whether a portal exists. Check the portalId, and contact GroGov if you expected access.

Get started

Core concepts

Hosted checkout

Testing

Error envelope

Error codes

Handling patterns

`402 PAYMENT_DECLINED`

`403 PAYMENT_BLOCKED`

`504 PAYMENT_TIMEOUT`

`502 PAYMENT_GATEWAY_ERROR`

`422 INVALID_STATE` / `VOID_FAILED`

`502 PARTIAL_REFUND_PENDING`

`409` idempotency codes

`501 CAPTURE_NOT_SUPPORTED` / `VAULT_NOT_SUPPORTED`

`503 GATEWAY_NOT_CONFIGURED`

`503 IDEMPOTENCY_UNAVAILABLE`

`403 PORTAL_ACCESS_DENIED`

​Error envelope

​Error codes

​Handling patterns

​402 PAYMENT_DECLINED

​403 PAYMENT_BLOCKED

​504 PAYMENT_TIMEOUT

​502 PAYMENT_GATEWAY_ERROR

​422 INVALID_STATE / VOID_FAILED

​502 PARTIAL_REFUND_PENDING

​409 idempotency codes

​501 CAPTURE_NOT_SUPPORTED / VAULT_NOT_SUPPORTED

​503 GATEWAY_NOT_CONFIGURED

​503 IDEMPOTENCY_UNAVAILABLE

​403 PORTAL_ACCESS_DENIED

Error envelope

Error codes

Handling patterns

`402 PAYMENT_DECLINED`

`403 PAYMENT_BLOCKED`

`504 PAYMENT_TIMEOUT`

`502 PAYMENT_GATEWAY_ERROR`

`422 INVALID_STATE` / `VOID_FAILED`

`502 PARTIAL_REFUND_PENDING`

`409` idempotency codes

`501 CAPTURE_NOT_SUPPORTED` / `VAULT_NOT_SUPPORTED`

`503 GATEWAY_NOT_CONFIGURED`

`503 IDEMPOTENCY_UNAVAILABLE`

`403 PORTAL_ACCESS_DENIED`