Conventions

Content type

Requests: Content-Type: application/json
Responses: JSON (success) or RFC 7807 ProblemDetails (errors)

Error format (ProblemDetails)

Failed requests return a ProblemDetails object:

{
  "type": "VPAY_001",
  "title": "Sesión de pago ya existe",
  "status": 422,
  "detail": "The payment session already exists.",
  "instance": "correlation-guid"
}

type — Vpay error code (e.g. VPAY_001) when applicable
status — HTTP status code
Validation 400 responses may include an errors dictionary keyed by field name

See Error codes.

Shared payment fields

Start payment (`POST /pay/api/start-payment`)

Field	Type	Required	Notes
`callbackSuccessUrl`	string	Yes	Redirect after successful payment
`callbackFailUrl`	string	Yes	Redirect after failed payment
`callbackBackUrl`	string	No	Redirect when payer cancels / goes back
`totalTransactionAmount`	decimal	Yes	Must be greater than 0
`currencyCode`	string	Yes	ISO currency (e.g. `CRC`, `USD`)
`terminalNumber`	string	No	Resolved from JWT `client_id` if omitted
`transactionReferenceNumber`	string	Yes	Unique merchant reference
`generalPurchaseDescription`	string	No	Shown on checkout
`userEmail`	string	No	Payer email
`culture`	string	No	UI locale hint (e.g. `es`, `en`)
`additionalCharges`	array	No	See below
`items`	array	No	Line items (optional)

additionalCharges[]

Field	Type
`chargeName`	string
`chargeAmount`	decimal
`chargeCurrencyCode`	string — must match request `currencyCode` when charges are present

items[]

Field	Type
`itemCode`	string
`quantity`	integer
`description`	string
`amount`	decimal
`currencyCode`	string — must match request `currencyCode` when items are present

Generate payment link (`POST /pay/api/generate-payment-link`)

Same monetary and line-item fields as start payment, without callback URLs. Additional required fields:

Field	Required
`generalPurchaseDescription`	Yes
`userEmail`	Yes (valid email)
`culture`	Yes

JSON API vs browser routes

Documented as API (server-to-server):

POST /api/public/security/auth
POST /pay/api/start-payment
POST /pay/api/generate-payment-link
GET /pay/api/payment/{checkoutSessionId}

Browser-only (hosted UI, not JSON API):

GET /pay/checkout-payment/{checkoutSessionId}
GET /pay/link/{id}
POST /pay/process-payment (form submission from checkout page)

Integrate using the JSON API from your backend; redirect payers to hosted checkout URLs.

Idempotency and references

transactionReferenceNumber must be unique per terminal for a new payment session.
Reusing a reference for an in-flight or completed session returns VPAY_001.

​Conventions

​Content type

​Error format (ProblemDetails)

​Shared payment fields

​Start payment (POST /pay/api/start-payment)

​Generate payment link (POST /pay/api/generate-payment-link)

​JSON API vs browser routes

​Idempotency and references

​Related

Start payment

Generate payment link