​
FAQ

​
How long is the access token valid?

The expiresIn field in the auth response indicates lifetime in seconds. Request a new token before it expires; there is no refresh token in client_credentials flow.

​
Can I call payment APIs from the browser?

No. Keep client_secret and Bearer tokens on your server. Only redirect payers to hosted checkout URLs (/pay/checkout-payment/... or /pay/link/...).

​
What happens if I reuse transactionReferenceNumber?

You receive VPAY_001 (payment session already exists). Generate a new unique reference for each new payment attempt. Not by default. Payment links do not use callbackSuccessUrl / callbackFailUrl. Poll GET /pay/api/payment/{checkoutSessionId} or implement your own notification flow.

​
How do I know if 3DS is required?

The hosted checkout handles 3DS and additional processor authentication internally. Your backend may see interim state values (32, 64, 128) if you poll during checkout. Wait for a terminal state before fulfilling orders.

​
Which currency codes are supported?

Pass ISO currency codes in currencyCode (e.g. CRC, USD). Supported currencies depend on your terminal configuration.

​
Can I customize the checkout UI?

v1 provides Vpay-hosted pages. Branding and processor selection are configured per terminal in Vpay back office.

​
Where are webhooks documented?

Processor webhooks are not part of the public merchant API in v1. Use payment status API and integrated checkout callbacks for merchant notification.

Support