> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pagamerican.app/llms.txt
> Use this file to discover all available pages before exploring further.
# vTurb
> Send your approved purchases to vTurb so it can attribute each sale to the video that produced it.
vTurb hosts the videos in your funnel and tracks the session each viewer came from. This integration closes the loop: when a purchase is approved, the platform tells vTurb which session produced it, so your video reports show revenue and not just plays.
The mechanism in one sentence: on every approved purchase the platform sends a `POST` with `Content-Type: application/json` to the postback URL you configure, carrying the sale and the conversion key that vTurb planted in the checkout link.
## Before you start
Two values have to line up, one from each product:
* **The postback URL.** vTurb calls it the webhook URL. In vTurb, open **Settings > Conversion Tracking** and copy it.
* **The conversion key parameter.** vTurb writes a conversion key (a value that starts with `v3_`) into one query-string parameter of the link that carries the viewer to your checkout. You choose which parameter that is, on both sides.
The parameter name is the whole integration. If vTurb writes the key into one parameter and the platform is configured to read a different one, sales are still delivered and vTurb cannot match a single one of them.
## How to configure
In vTurb, go to **Settings > Conversion Tracking**, copy the webhook URL, and note which tracking parameter that setup uses for the conversion key.
In the dashboard, go to **Integrations** and open the **VTurb** card. The screen is titled **Configure Integration with VTurb**.
Paste the vTurb webhook URL into **Postback URL**. The field only accepts a full URL, so a bare hostname is rejected when you save.
Choose the parameter vTurb writes the conversion key into: **SRC**, **SCK**, **VTID**, **SID** or **SUB**. New configurations start on **SRC**.
Under **Events to be mapped**, the **Purchase** checkbox decides whether anything is sent at all. It is checked by default. Click **Save Integration**.
The configuration is one per account, not one per product. The screen says so under the title: "Configure once and reuse across all your offers". There is no product or offer selector on it.
The configuration belongs to the role you were in when you saved it. If you use the dashboard both as a producer and as an affiliate, each role holds its own vTurb configuration, and a sale uses the one belonging to the role that earned it.
## Events sent
| Event in the UI | Value sent as `type` | When it fires |
| --------------- | -------------------- | ---------------------------------------------- |
| **Purchase** | `Purchase` | The front-end purchase of an order is approved |
| **Purchase** | `upsell` | An upsell in the funnel is approved |
| **Purchase** | `downsell` | A downsell in the funnel is approved |
One checkbox covers all three. Upsells and downsells have no toggle of their own, so unchecking **Purchase** stops every one of them. The `is_first_purchase` field is `true` only for the front-end purchase and `false` for an upsell or a downsell, which is how vTurb can tell them apart.
Nothing else reaches vTurb. Checkout starts, refunds and chargebacks are not sent to this integration, and there is no screen where they can be turned on. If you need those, use [webhooks](/integrations/webhooks/overview), which do carry them.
For an affiliated sale the platform delivers twice: once against the producer's configuration and once against the affiliate's. Each side receives its own amount in `creator_net_amount`.
## The conversion key
The conversion key is read at delivery time from the query string the checkout captured when the buyer arrived. The platform looks for exactly the parameter you selected, matching it in lower case or in upper case (`src` and `SRC` both resolve, `Src` does not), and puts the value it finds into `vturb_ck`.
If the parameter is not in the captured query string, `vturb_ck` is sent as `null`. Nothing rejects the delivery and nothing warns you.
This path reads the captured query string in full, so `vtid`, `sid` and `sub` work here even though they are not among the [tracking parameters](/integrations/webhooks/overview#tracking-parameters) that webhook payloads return.
## What the platform sends
The body is a single JSON object, not the array used by PagAmerican webhooks. Every field below is present on every delivery.
```json theme={null}
{
"event_id": "a1b2c3d4-0000-0000-0000-000000000000",
"checkout_id": "b2c3d4e5-0000-0000-0000-000000000000",
"type": "Purchase",
"is_first_purchase": true,
"content_ids": "900001,900002",
"creator_id": 90000,
"currency": "USD",
"product_name": "Example Product - 6 units,Example Add-on",
"first_name": "Jane Doe",
"last_name": "Jane Doe",
"phone": "5551234567",
"email": "jane.doe@example.com",
"zip_code": "00000",
"items_total": 97.9,
"transaction_total": 103.77,
"creator_net_amount": 103.77,
"tracking_search_params": {
"src": "v3_00000000-0000-0000-0000-000000000000",
"utm_source": "facebook",
"utm_campaign": "EXAMPLE-CAMPAIGN|120000000000000000"
},
"vturb_ck": "v3_00000000-0000-0000-0000-000000000000"
}
```
| Field | Description |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `event_id` | Identifier of the approved purchase behind this delivery, useful for deduplication |
| `checkout_id` | The checkout session the order came from |
| `type` | `Purchase`, `upsell` or `downsell` |
| `is_first_purchase` | `true` only for the front-end purchase |
| `content_ids` | Offer IDs of this purchase, comma-separated |
| `creator_id` | The producer who owns the product |
| `currency` | Transaction currency, uppercase |
| `product_name` | Offer names of this purchase, comma-separated |
| `first_name` | The customer's full name |
| `last_name` | The customer's full name again (both fields carry the same value) |
| `phone` | The customer's phone |
| `email` | The customer's email |
| `zip_code` | Shipping ZIP code |
| `items_total` | Gross value of the items on the order |
| `transaction_total` | Total charged on the order |
| `creator_net_amount` | Repeats `transaction_total` on the producer's delivery, and carries the affiliate's commission on the affiliate's |
| `tracking_search_params` | The query string the checkout captured, as an object |
| `vturb_ck` | The conversion key, or `null` when the parameter was absent |
Two things about the amounts are easy to get backwards:
* **They are decimal amounts, not cents.** `97.9` means 97.90 in the transaction currency. This differs from webhook payloads, where every amount is an integer number of cents.
* **They describe the order, not the individual purchase.** On an upsell delivery, `type` and `content_ids` refer to the upsell, while `items_total` and `transaction_total` refer to the order as a whole.
## Delivery log
Every attempted delivery is recorded. Open **Integrations**, then **View Logs** on the **VTurb** card, for a list of **Sent At**, **Event**, **Status**, **Code** and **Details**, newest first.
The platform allows 5 seconds per attempt and retries a failed delivery three times, backing off between attempts. The log row is written after the last attempt and takes a moment to appear, so a purchase approved seconds ago may not be listed yet.
Read the columns as follows:
* **Event** always reads `purchase_approved`, on upsell and downsell rows too. The `Purchase` / `upsell` / `downsell` distinction is in the body, not in this column.
* **Status** is **Success** or **Failed**.
* **Code** shows `200` on success and a dash on failure. It does not report the status vTurb answered with; the reason is in **Details** instead.
* **Details** shows a dash on success and the error on failure.
The log records the HTTP call and nothing more. A row saying **Success** means vTurb accepted the request, not that vTurb was able to attribute the sale. The body that was sent is not shown.
## Troubleshooting
### The log says Success and vTurb shows no conversions
Neither product reports this as an error, which is what makes it hard to find.
The platform sends the purchase whether or not it found the conversion key. When the parameter you selected under **VTurb Conversion Key Parameter** is not in the link that brought the buyer to the checkout, `vturb_ck` goes out as `null`. vTurb receives a sale it cannot tie to any video session, so it counts nothing, while your delivery log fills up with green **Success** rows.
The delivery log cannot tell you this apart, because it does not show the body that was sent. Check the two ends instead:
1. **The two parameter names match.** The parameter selected under **VTurb Conversion Key Parameter** has to be the one vTurb writes the key into. vTurb's own setup can use `src`, `sck`, `vtid`, `sid`, `xcod` or `sub1` through `sub20`, and only the first four of those exist in the dashboard's list. Selecting **SUB** makes the platform look for a parameter named exactly `sub`, which is not the same as `sub1`.
2. **The key survives the trip to the checkout.** Open one of your checkout links the way a buyer would, and read the address bar on the checkout page. The parameter has to still be there, spelled the same way, carrying a value that starts with `v3_`. A redirect that drops the query string, a link shared without it, or a button on the video page that points straight at the checkout, all break the chain before the platform is involved.
If both ends look right and vTurb still records nothing, contact support with the date and time of a **Success** row. The delivered body is stored even though the screen does not show it, and support can read the conversion key back from it.
### The delivery log is empty
An empty log is a diagnostic, not a platform failure. Nothing was sent, which happens in exactly two cases:
* **The integration was never saved.** The **VTurb** card shows **Not Installed** and there is no **View Logs** button. Saving the screen once installs it.
* **The Purchase checkbox is unchecked.** The platform skips the delivery before it reaches the log, so no row is written, not even a failed one.
A configured integration with **Purchase** checked always writes a row, success or failure. If sales are being approved and the log stays empty, one of the two above is true.
### An affiliate sees nothing while the producer sees deliveries
The two configurations are independent. A producer's configuration never covers their affiliates, and an affiliate has to open **Integrations > VTurb** while in the **Affiliate** role and save their own postback URL. Until they do, an affiliated sale produces one delivery (the producer's), and the affiliate's log stays empty.
### The log shows Failed
The reason is in **Details**, since **Code** stays empty on a failure. Two messages mean something specific:
* **Starts with `Invalid URL`**: the value in **Postback URL** is not an address the platform can call. Re-copy it from **Settings > Conversion Tracking** in vTurb and save again.
* **`External service unavailable`**: vTurb failed too many deliveries in a short window, so the platform stopped calling it for 30 seconds and refused this one without ever leaving the platform. It clears on its own.
Everything else reads `Error calling external service:` followed by vTurb's own answer.
A failed delivery is not sent again. The three retries happen inside the delivery itself, before the row is written, so a purchase whose row says **Failed** never reaches vTurb. Fixing the configuration afterwards applies to later purchases only.
## FAQ
**Can I send a test delivery?**
No. This screen has no test action. The first delivery is the first real approved purchase, so the practical test is a purchase of your own on a live offer, then **View Logs**.
**Do I need one configuration per product?**
No. There is one configuration per account and it applies to every product and offer you sell.
**If I change the conversion key parameter, does it affect past sales?**
No. The parameter is read at the moment of delivery, so the change applies to purchases approved from then on. Deliveries already sent are unchanged, and sales whose checkout link carried the old parameter will no longer match after the switch.
**Can I turn the integration off without deleting it?**
Uncheck **Purchase** and save. Deliveries stop immediately and the configuration is kept, so re-checking the box resumes them.
Our team can help you set up your integration: [support@pagamerican.com](mailto:support@pagamerican.com)