​
Getting started

This tutorial walks through authenticating and creating a payment with cURL. Replace placeholders with your sandbox credentials and base URL. Prerequisites: Active Vpay terminal credentials (client_id, client_secret) and HTTPS access to {sandboxBaseUrl}.

​
1. Confirm base URL

Use your sandbox or production Payment Gateway host: 
{sandboxBaseUrl}
Example: https://sandbox.example.com

​
2. Obtain an access token

curl -X POST "{sandboxBaseUrl}/api/public/security/auth" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'
Response (200): 
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "expiresIn": 3600
}
Save token for subsequent requests. See Authentication.

​
3a. Integrated checkout — start payment

curl -X POST "{sandboxBaseUrl}/pay/api/start-payment" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-idoperacion: optional-correlation-id" \
  -d '{
    "callbackSuccessUrl": "https://merchant.example.com/payment/success",
    "callbackFailUrl": "https://merchant.example.com/payment/fail",
    "callbackBackUrl": "https://merchant.example.com/cart",
    "totalTransactionAmount": 1500.00,
    "currencyCode": "CRC",
    "transactionReferenceNumber": "ORDER-2026-001",
    "generalPurchaseDescription": "Online purchase",
    "userEmail": "customer@example.com",
    "culture": "es"
  }'
Response (200): 
{
  "checkoutSessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "internalTransactionReferenceNumber": "VPAY-INT-12345"
}

curl -X POST "{sandboxBaseUrl}/pay/api/generate-payment-link" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "totalTransactionAmount": 1500.00,
    "currencyCode": "CRC",
    "transactionReferenceNumber": "LINK-2026-001",
    "generalPurchaseDescription": "Invoice #1042",
    "userEmail": "customer@example.com",
    "culture": "es"
  }'
Response (200): 
{
  "checkoutSessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "paymentLink": "{sandboxBaseUrl}/pay/link/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "internalTransactionReferenceNumber": "VPAY-INT-12346",
  "expirationDateTime": "2026-06-20T12:00:00Z"
}

​
4. Open checkout in the browser

Integrated checkout: 
{sandboxBaseUrl}/pay/checkout-payment/{checkoutSessionId}
Payment link: use the paymentLink URL from step 3b, or: 
{sandboxBaseUrl}/pay/link/{checkoutSessionId}
The payer completes card entry on the hosted Vpay form. On success or failure, Vpay redirects to your callbackSuccessUrl or callbackFailUrl (integrated checkout).

​
5. Query payment status

After the payer returns to your site, confirm the final state from your backend: 
curl -X GET "{sandboxBaseUrl}/pay/api/payment/{checkoutSessionId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response (200): 
{
  "totalTransactionAmount": "1500.00",
  "currencyCode": "CRC",
  "transactionReferenceNumber": "ORDER-2026-001",
  "authorizationCode": "ABC123",
  "state": 1
}
See Payment status for state values.

​
6. Next steps

Integrated checkout

Full redirect flow and callbacks.

Payment links

Shareable URLs and expiration.

API reference

Endpoint details and field tables.

Testing

Sandbox cards and Swagger.

​
Common issues

SymptomLikely causeAction
401 UnauthorizedMissing, expired, or invalid Bearer tokenCall POST /api/public/security/auth again
400 validation errorsRequired fields missing or invalid amountsCheck Conventions and validators
VPAY_001Duplicate transactionReferenceNumberUse a new unique reference per payment
VPAY_005Terminal not registered or inactiveContact Vpay support with your client_id