Generate payment link
Creates a one-time payment link the payer can open in a browser.
Request
/pay/api/generate-payment-link
Authorization: Bearer {token} — role VpayTerminal
Body
| Field | Type | Required | Description |
|---|
totalTransactionAmount | decimal | Yes | Must be > 0 |
currencyCode | string | Yes | e.g. CRC, USD |
terminalNumber | string | No | Resolved from JWT if omitted |
transactionReferenceNumber | string | Yes | Unique merchant reference |
generalPurchaseDescription | string | Yes | Shown to payer |
userEmail | string | Yes | Valid email address |
culture | string | Yes | es or en |
additionalCharges | array | No | Extra charges |
items | array | No | Line items |
Response 200
| Field | Type | Description |
|---|
checkoutSessionId | string | Session ID for status API |
paymentLink | string | URL to send to payer |
internalTransactionReferenceNumber | string | Vpay internal reference |
expirationDateTime | datetime | Link expiry (UTC) |
{
"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"
}
Errors
| Status | Type | Description |
|---|
400 | — | Validation errors (email, culture, amount, etc.) |
401 | — | Unauthorized |
422 | VPAY_001 | Duplicate reference |
422 | VPAY_005 | Terminal not registered |
500 | — | Internal error |
Example
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"
}'
