​
Integrated checkout

Use integrated checkout when the payer starts payment from your website or app and you redirect them to Vpay’s hosted form.

​
Sequence

​
Steps

​
1. Authenticate

Obtain a Bearer token. See Authentication.

​
2. Start payment

POST /pay/api/start-payment with amount, currency, merchant reference, and callback URLs. Required callbacks:
  • callbackSuccessUrl — payer lands here after approval
  • callbackFailUrl — payer lands here after decline or error
Optional:
  • callbackBackUrl — payer cancels or navigates back from checkout
Response includes checkoutSessionId and internalTransactionReferenceNumber.

​
3. Redirect payer

Send the payer’s browser to: 
{sandboxBaseUrl}/pay/checkout-payment/{checkoutSessionId}
Build this URL on your backend; do not expose your API token to the browser.

​
4. Payer completes payment

Vpay renders the hosted checkout (card fields, 3DS when required). Processing may involve:
  • ThreeDsFingerprintRequired / ThreeDsChallengeRequired (legacy 3DS flows)
  • OnvoAuthenticationRequired (ONVO processor redirect)
These states are handled inside the hosted UI; your integration does not call separate 3DS APIs in v1.

​
5. Callback redirect

After processing, Vpay redirects the browser to:
  • callbackSuccessUrl on approval, or
  • callbackFailUrl on failure
Append query parameters may include session identifiers depending on your callback implementation — always verify status server-side.

​
6. Confirm status server-side

Call GET /pay/api/payment/{checkoutSessionId} from your backend. Treat this response as the authoritative payment result before fulfilling the order.

​
Best practices

  • Use HTTPS for all callback URLs.
  • Never trust client-side redirect alone — always query payment status.
  • Use unique transactionReferenceNumber values per order.
  • Pass X-idoperacion for support correlation.

Start payment API

Payment status