Skip to main content

Online payment

Use a prebuilt checkout page to start accepting online payments.

E-commerce plugins

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​

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.

Hosted checkout flow

info

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.

info

Payments expire 24 hours after creation by default.

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
        }
    ]
}

After creating a Payment, redirect your customer to the checkoutUrl returned in the response.

QR code

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.

warning

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.

Next steps​

Optional

Prefill customer data​

Optional

Separate authorization and confirm​