Online payment
Use a prebuilt checkout page to start accepting online payments.
Voucherly can be easily added as a payment method using one of the E-commerce plugins.
Quick Guide
Let’s walk through a simple example of integrating the payment flow from scratch.
1. Redirect your customer to Voucherly Checkout
- Hosted checkout
- Gateway
The simplest and preferred way to integrate Voucherly is to use Voucherly Checkout as a single checkout page for all your Payment gateways.
Add a checkout button to your website that calls a server-side endpoint to create a Payment in Voucherly.
You can build a custom payments integration by displaying Payment gateway components on your site.
Voucherly offers a GET Payment gateway API to fetch the active and available payment gateways for your merchant account.
Use this to dynamically display specific Payment gateways on your website, instead of generic labels like Voucherly or Pay online. Once the customer selects a Payment gateway, call a server-side endpoint to create a Payment in Voucherly.
Additionally, Voucherly provides a GET Customer payment methods API to retrieve a customer's saved payment methods. This lets you display their preferred Payment methods upfront, enabling seamless direct charges and further reducing friction during the checkout process.
Refer to the Create Payment API for detailed functionality and usage.
You can also create a Payment for an existing customer, allowing you to prefill the checkout form with their contact details and unify their purchase history. A Payment represents the experience your customer sees when redirected to the payment form. You can configure it with options such as:
- Lines. Specify the items to charge for. For each item, the
isFood
field determines whether it can be paid with vouchers. - Discounts. Define the discounts applied to cart.
Ensure you set redirectOkUrl
to the URL where the customer is redirected after successful payment. You can also provide a redirectKoUrl
where the customer is redirected if they cancel the payment process.
Payments expire 24 hours after creation by default.
- Hosted checkout
- Gateway
Example request
{
"mode": "Payment",
"customerEmail": "mario.rossi@voucherly.it",
"customerFirstName": "Mario",
"customerLastName": "Rossi",
"redirectOkUrl": "https://{redirect_host}}/payment/success",
"redirectKoUrl": "https://{{redirect_host}}/payment/error",
"callbackUrl": "https://{{s2s_host}}/payment/s2s",
"country": "IT",
"lines": [
{
"quantity": 2,
"unitAmount": 250,
"unitDiscountAmount": 10,
"discountAmount": 0,
"productName": "Muffin al Cioccolato",
"productImage": "https://cdn.trovaricetta.com/photo/2016/10/07/1771032/b/muffin-al-cioccolato-facilissimi.jpg",
"isFood": true
}
],
"discounts": [
{
"discountName": "Coupon",
"discountDescription": "",
"amount": 200
}
]
}
Specify the selected Payment gateway using the selectedPaymentGateway
parameter or the Customer payment method using the customerPaymentMethodId
parameter.
Example request
{
"mode": "Payment",
"selectedPaymentGateway": "GATEWAY",
"customerPaymentMethodId": "my-customer-method-1",
"customerEmail": "mario.rossi@voucherly.it",
"customerFirstName": "Mario",
"customerLastName": "Rossi",
"redirectOkUrl": "https://{redirect_host}}/payment/success",
"redirectKoUrl": "https://{{redirect_host}}/payment/error",
"callbackUrl": "https://{{s2s_host}}/payment/s2s",
"country": "IT",
"lines": [
{
"quantity": 2,
"unitAmount": 250,
"unitDiscountAmount": 10,
"discountAmount": 0,
"productName": "Muffin al Cioccolato",
"productImage": "https://cdn.trovaricetta.com/photo/2016/10/07/1771032/b/muffin-al-cioccolato-facilissimi.jpg",
"isFood": true
}
],
"discounts": [
{
"discountName": "Coupon",
"discountDescription": "",
"amount": 200
}
]
}
After creating a Payment, redirect your customer to the checkoutUrl
returned in the response.
When the consumer is physically purchasing in a Brick & Mortar store with a screen facing them, you can display the checkoutUrl
as a QR code.
Example response
{
"id": "my-payment-id-1",
"tenant": "live",
"mode": "Payment",
"customerId": "my-customer-id-1",
[...]
"checkoutUrl": "https://example.voucherly.it/checkout",
"status": "Requested",
[...]
}
2. Handle before-redirect Callback S2S
Voucherly sends a callback when a customer successfully completes a Payment. This callback can be used to:
- Send an order confirmation email to your customer.
- Record the sale in a database.
- Initiate a shipping workflow.
It's highly recommended to listen for this callback instead of relying solely on the customer being redirected back to your website. Triggering actions only from your Checkout landing page can be unreliable.
Voucherly sends the callback to the endpoint specified as callbackUrl
in the Create Payment API request.
Learn more in our Callback S2S guide.
Make sure your endpoint processes callbacks correctly. Failure to do so may lead to payment cancellations and refunds.
3. Show a success page
It’s important for your customers to see a success or error page after submitting the payment form.
When a customer completes payment on the Voucherly Checkout page, they are redirected to the URLs specified in the Create Payment API request:
- If the payment is successful, the customer is redirected to the
redirectOkUrl
. - If the payment fails, the customer is redirected to the
redirectKoUrl
.
Payment information is passed via the query string:
- success. Indicates the Payment result (
OK
for success,KO
for failure). - status. The status of the Payment.
- paymentId. The unique Voucherly identifier for the Payment.
- referenceId. The merchant's custom reference ID.
- amount. The total paid amount in cents.
- voucherAmount. The portion of the paid amount covered by vouchers in cents.
- walletAmount. The portion of the paid amount covered by wallet credit in cents.
- transactions. The number of transactions involved in the Payment.
- customerId. The unique Voucherly identifier for the customer.
- customerEmail. The customer's email address.
- customerFirstName. The customer's first name.
- customerLastName. The customer's last name.
- tenant. live or sand.