​
Error codes

Vpay returns standard HTTP status codes. Business errors use ProblemDetails with a type field set to a VPAY_* code.

​
HTTP status summary

HTTPWhen
200Success
400Request validation failed (missing/invalid fields)
401Authentication failed or missing Bearer token
404Payment session not found (GET /pay/api/payment/...)
422Business rule violation (duplicate session, inactive terminal, etc.)
500Unexpected server error

​
Vpay error types (type)

CodeHTTPTitleMessage (EN)Recommended action
VPAY_001422Payment session already existsThe payment session already exists.Use a new transactionReferenceNumber or query existing session
VPAY_002422Payment session does not existThe payment session does not exist.Verify checkoutSessionId; link may be invalid or expired
VPAY_003422BeePay API communication errorCommunication error with card processor API.Retry; contact support if persistent
VPAY_004422Card processor controlled errorControlled error from card processor.Review processor message; adjust request
VPAY_005422Terminal not registeredPayment terminal not registered in the system.Verify terminal provisioning with Vpay
VPAY_006422Transaction declinedTransaction declined by processor.Ask payer to use another card or contact issuer
VPAY_007404Payment not foundSpecified payment not found.Confirm checkoutSessionId and environment
VPAY_008422Payment cannot be reversedPayment not in reversible state.Not applicable to public checkout API v1
VPAY_009422Reversal processor errorError during reversal.Not applicable to public checkout API v1
VPAY_010200Reversal successfulReversal completed.Not applicable to public checkout API v1
VPAY_011422Settled or amount mismatchCannot reverse settled transaction.Not applicable to public checkout API v1
Codes VPAY_008–VPAY_011 are listed for completeness; they apply to reversal flows outside this public integration guide.

​
Validation errors (400)

Example: 
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Validation failed",
  "status": 400,
  "errors": {
    "CallbackSuccessUrl": ["CallbackSuccessUrl is required."],
    "TotalTransactionAmount": ["TotalTransactionAmount must be greater than zero."]
  }
}
Fix the listed fields and retry.

​
Authentication errors (401)

  • Invalid client_id / client_secret at auth endpoint
  • Expired or malformed JWT on protected routes
  • Token without VpayTerminal role
Re-authenticate and ensure the Bearer header is present.

​
Declined payments (VPAY_006)

Card declines during checkout may surface as VPAY_006 in API responses. The payer sees a friendly message on the hosted form; your backend should treat state: 2 (Failed) on payment status as the source of truth after redirect.

​
Support

When contacting support, include checkoutSessionId, transactionReferenceNumber, internalTransactionReferenceNumber, and X-idoperacion if used. See Support.