​
Start payment

Creates a payment session for integrated checkout and returns a checkoutSessionId to redirect the payer.

​
Request

​
method
POST
/pay/api/start-payment
Authentication: Authorization: Bearer {token} — role VpayTerminal

​
Body

FieldTypeRequiredDescription
callbackSuccessUrlstringYesSuccess redirect URL
callbackFailUrlstringYesFailure redirect URL
callbackBackUrlstringNoCancel / back URL
totalTransactionAmountdecimalYesMust be > 0
currencyCodestringYese.g. CRC, USD
terminalNumberstringNoDefaults from JWT terminal
transactionReferenceNumberstringYesUnique merchant reference
generalPurchaseDescriptionstringNoPurchase description
userEmailstringNoPayer email
culturestringNoes or en
additionalChargesarrayNoExtra charges
itemsarrayNoLine items
See Conventions for nested object shapes.

​
Response 200

FieldTypeDescription
checkoutSessionIdstringRedirect to /pay/checkout-payment/{id}
internalTransactionReferenceNumberstringVpay internal reference
{
  "checkoutSessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "internalTransactionReferenceNumber": "VPAY-INT-12345"
}

​
Errors

StatusTypeDescription
400—Validation errors
401—Unauthorized
422VPAY_001Duplicate transactionReferenceNumber
422VPAY_005Terminal not registered
500—Internal error

​
Example

curl -X POST "{sandboxBaseUrl}/pay/api/start-payment" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackSuccessUrl": "https://merchant.example.com/success",
    "callbackFailUrl": "https://merchant.example.com/fail",
    "totalTransactionAmount": 1500.00,
    "currencyCode": "CRC",
    "transactionReferenceNumber": "ORDER-2026-001",
    "culture": "es"
  }'