Introduction
Integrate payments with Vpay, a hosted payment gateway for e-commerce and business applications. The API is JSON over HTTPS and supports two integration modes:- Integrated checkout — Your backend starts a session and redirects the payer to a Vpay-hosted checkout form.
- Payment link — Your backend generates a shareable URL the payer opens to complete payment.
High-level flow
Key concepts
| Concept | Description |
|---|---|
| Terminal | Your payment terminal, identified by OAuth2 client_id (JWT subject). Requires role VpayTerminal. |
| checkoutSessionId | Unique session identifier returned when you start a payment or generate a link. |
| transactionReferenceNumber | Your merchant reference for the payment (must be unique per terminal). |
| paymentLink | URL returned by generate-payment-link for the payer to open. |
| internalTransactionReferenceNumber | Vpay internal reference for support and reconciliation. |
Base URLs
| Environment | Base URL |
|---|---|
| Production | https://vpay.didi.cr |
https://vpay.didi.cr/pay/api/start-payment).
Swagger UI
Explore and test endpoints interactively in the OpenAPI UI: https://vpay.didi.cr/swagger Swagger complements this documentation; the MDX reference and Conventions reflect the supported public integration surface.Public API surface (v1)
| Method | Path | Auth |
|---|---|---|
POST | /api/public/security/auth | No |
POST | /pay/api/start-payment | Bearer + VpayTerminal |
POST | /pay/api/generate-payment-link | Bearer + VpayTerminal |
GET | /pay/api/payment/{checkoutSessionId} | Bearer + VpayTerminal |
- Integrated checkout:
GET /pay/checkout-payment/{checkoutSessionId} - Payment link:
GET /pay/link/{id}
Next steps
Getting started
Follow a step-by-step tutorial with cURL examples to authenticate and create your first payment.
Swagger UI
Open the interactive API reference to explore endpoints and try requests.