Selling Workflow
The typical Vatly flow
For most use cases, the Vatly integration follows the same happy path:
- Create your Vatly account and collect your API key.
- Configure the products you want to sell in the Vatly dashboard.
- Register a webhook endpoint that Vatly can reach.
- Create a checkout with the product IDs you want to sell.
- Redirect the customer to the hosted checkout URL.
- Listen for the payment webhook and fulfill the order in your app.
- Stay prepared to handle refunds and chargebacks after the sale.
This guide ties those steps together so you can see the full flow before diving into each API endpoint.
1. Finish the initial setup
Start with the basics:
- Create your Vatly account.
- Grab your API keys from the dashboard under Settings > API.
- For live payments, connect your Mollie account and complete onboarding with both Mollie and Vatly.
Most merchants and developers should begin in test mode. In test mode, the customers, products, and checkouts you create stay in your test environment so you can validate the full flow safely before you start accepting real payments. The online Vatly dashboard has a testmode toggle. For API calls, use your dedicated test API key (starting with test_).
When you are ready to sell for real, switch to live mode. Each product you want to sell must be verified by Vatly before it can be used in a live selling flow.
Do not wait until the last minute to create your products in the dashboard. Product verification can take some time because Vatly needs to review them for compliance before they can be used in a live selling flow.
If you have not made your first authenticated request yet, start with the Quickstart guide.
2. Set up the products you want to sell
Before you can create a checkout, you need at least one product in Vatly.
You can sell two kinds of products:
- One-off products for a single purchase such as a digital download, license, or one-time service.
- Subscription plans for recurring access such as a SaaS plan.
Products are configured in the Vatly dashboard. After creating them, keep track of their product IDs because you will need those IDs when you create a checkout through the API.
3. Register your webhook before going live
Set up your webhook endpoint before you send customers to checkout. That endpoint is how Vatly tells your application that something important happened, such as a checkout being paid, a subscription changing, or a refund being created.
Configure the webhook in the dashboard and make sure the endpoint is:
- Reachable from the public internet
- Served over HTTPS
- Able to verify the
x-vatly-signatureheader
This is a critical part of the integration. Use webhooks to confirm what happened instead of relying only on the customer's browser returning to your site.
4. Create a checkout for the right products
When a customer is ready to buy, your app creates a checkout with the product IDs you configured earlier. A checkout can contain:
- A single one-off product
- A single subscription plan
- A list of products, depending on what your flow allows
The API request is made from your backend using your secret API key.
curl https://api.vatly.com/v1/checkouts \
-H "Authorization: Bearer live_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"products": [
{ "id": "one_off_product_Vr8kQdFhSrG4Y3DnfsdqH", "quantity": 1 }
],
"redirectUrlSuccess": "https://example.com/success",
"redirectUrlCanceled": "https://example.com/canceled"
}'
use Vatly\Api\VatlyApiClient;
$vatly = new VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');
$checkout = $vatly->checkouts->create([
'products' => [
[
'id' => 'one_off_product_Vr8kQdFhSrG4Y3DnfsdqH',
'quantity' => 1,
],
],
'redirectUrlSuccess' => 'https://example.com/success',
'redirectUrlCanceled' => 'https://example.com/canceled',
]);
$checkoutUrl = $checkout->links->checkoutUrl->href;
return redirect()->away($checkoutUrl);
The response includes a hosted checkout URL in links.checkoutUrl.href. That is the URL your customer should visit to complete payment.
{
"id": "checkout_QGQ0qDrQ2B4O1yXVTr6Wc",
"status": "open",
"products": [
{
"id": "one_off_product_Vr8kQdFhSrG4Y3DnfsdqH",
"quantity": 1
}
],
"redirectUrlSuccess": "https://example.com/success",
"redirectUrlCanceled": "https://example.com/canceled",
"links": {
"checkoutUrl": {
"href": "https://checkout.vatly.com/chk_test_123456789"
}
}
}
Read the Checkouts API reference
5. Redirect the customer to the checkout URL
After creating the checkout, redirect the customer to the URL returned by Vatly.
At that point, Vatly handles the hosted payment flow. The customer completes payment on the Vatly checkout page and is then redirected back to your success or cancellation URL.
The browser redirect is helpful for user experience, but your backend should still wait for the relevant webhook event before treating the order as paid.
6. Fulfill the order after payment
Once the checkout is paid, Vatly notifies your webhook endpoint. That is the point where your application should decide what to deliver.
Typical fulfillment actions include:
- Granting access to your SaaS
- Sending an email with access instructions
- Providing a download link for a digital product
- Activating a subscription in your own application
The exact webhook event you handle depends on your setup, but checkout.paid and the related order or subscription events are the key signals that the sale completed.
7. Prepare for post-payment events
The happy path ends with a successful sale and fulfillment, but a production integration also needs to handle post-payment scenarios.
At minimum, merchants and developers should be prepared for:
- Refunds, whether partial or full
- Chargebacks, which are created when a payment dispute is initiated
These events should also flow through your webhook handling so your application can revoke access, update account state, notify staff, or trigger follow-up support processes when needed.
Vatly actively prevents and disputes chargebacks. If extra evidence is needed, Vatly will check in with you for details such as proof of delivery or proof that the customer received access to the product.