Documentation Index
Fetch the complete documentation index at: https://docs.utmify.com.br/llms.txt
Use this file to discover all available pages before exploring further.
Before you start
To send a request to our API, you will need an API credential. To get one, access your Utmify account and follow the path:Integrations → Webhooks → API Credentials → Add Credential → Create Credential
1. Request Format
1.1 Endpoint
1.2 Headers
1.3 Payload
1.3.1 Body
1.3.2 Customer
1.3.3 Product
1.3.4 TrackingParameters
1.3.5 Commission
2. Parameter Description
2.1 Headers
| Parameter | Example | Description |
|---|---|---|
| x-api-token | ”KVRxalfMiBfm8Rm1nP5YxfwYzArNsA0VLeWC” | API credential generated in the Utmify Dashboard. This token is used to identify the client and the dashboard that will receive the order. |
2.2 Body
| Parameter | Example | Description |
|---|---|---|
| orderId | ”FC72D9AK9” | Order identification on the sales platform. |
| platform | ”GlobalPay” | Name of the platform integrating with Utmify. Recommended in PascalCase. |
| paymentMethod | ”credit_card” | Payment method used in the transaction. |
| status | ”paid” | Payment status of the transaction. |
| createdAt | ”2024-07-25 15:34:14” | Date the order was created (UTC). Must always be the same date when the order status is updated. Note: only orders up to 7 days old are accepted, and up to 45 days for refunds or chargebacks. Non-compliance may result in blocking. |
| approvedDate | ”2024-07-25 15:41:12” | Date the payment was completed (UTC). If the order has not been paid yet, send null. |
| refundedAt | null | Date the order was refunded (UTC). If not refunded, send null. |
| customer | Customer | Information about the customer who made the purchase. |
| products | Array of Product | Information about the products in the transaction. |
| trackingParameters | TrackingParameters | URL parameters extracted from the checkout URL at the time of purchase and sent to Utmify via Webhook. |
| commission | Commission | Transaction values. |
| isTest | false | Defines whether the request is a test. If true, validation will be performed normally, but the transaction will not be saved. To save the order, do not send this field or set it to false. |
2.3 Customer
| Parameter | Example | Description |
|---|---|---|
| name | ”Lucas Sampaio” | Customer’s name. |
| ”[email protected]” | Customer’s email. | |
| phone | ”11991560063” | Customer’s phone number. |
| document | ”43887057481” | Customer’s CPF or CNPJ. |
| country | ”BR” | Customer’s country in ISO 3166-1 alpha-2 format. Not required. |
| ip | ”204.97.192.73” | Customer’s IP address. Not required, but recommended for better sales tracking. |
2.4 Product
| Parameter | Example | Description |
|---|---|---|
| id | ”FGC1375Z5” | Product identification. |
| name | ”Pants” | Product name. |
| planId | ”FTS7743C3” | Plan ID (if the platform offers multiple plans for the same product). If not available, send null. |
| planName | ”Christmas Promotion” | Plan name. If not available, send null. |
| quantity | 2 | Quantity purchased. |
| priceInCents | 11990 | Product price on the sales platform. |
2.5 TrackingParameters
| Parameter | Example | Description |
|---|---|---|
| src | null | Value of src extracted from the checkout URL. If not available, send null. |
| sck | null | Value of sck extracted from the checkout URL. If not available, send null. |
| utm_source | ”FB” | Value of utm_source extracted from the checkout URL. If not available, send null. |
| utm_campaign | ”Sales 2024/07/10” | Value of utm_campaign extracted from the checkout URL. If not available, send null. |
| utm_medium | ”ABO” | Value of utm_medium extracted from the checkout URL. If not available, send null. |
| utm_content | ”VIDEO 01” | Value of utm_content extracted from the checkout URL. If not available, send null. |
| utm_term | ”Instagram_Reels” | Value of utm_term extracted from the checkout URL. If not available, send null. |
2.6 Commission
| Parameter | Example | Description |
|---|---|---|
| totalPriceInCents | 14990 | Total transaction value in cents. |
| gatewayFeeInCents | 1500 | Amount received by the platform in cents. |
| userCommissionInCents | 13490 | Amount received by the seller in cents. This value cannot be 0, unless the user truly received nothing from the sale. If the platform does not want to inform the user commission (not recommended), set this value equal to totalPriceInCents. |
| currency | ”USD” | Purchase currency. If in BRL, this field is not required. |
3. Practical Request Examples
3.1 PIX Generated and Paid
A customer placed a PIX order at GlobalPay store through the checkout. The product purchased was a motor oil for $80.00 with $20.00 shipping. The platform charges $1.00 per paid PIX + 3% of the order value. The PIX was generated on 07/26/2024 at 11:35:13 and paid on 07/26/2024 at 11:43:37 (Brasilia time).3.1.1 PIX Generated
3.1.2 PIX Paid
3.2 Credit Card Paid and Refunded
A customer placed a credit card order on 07/15/2024 at 10:30:14 and requested a refund on 07/18/2024 at 22:44:39 (Brasilia time). The order was placed on the GlobalPay platform in dollars, containing a t-shirt for $35.00 and pants for $40.00. The platform charges a 5% fee per order.3.2.1 Card Paid
3.2.2 Card Refunded
4. Frequently Asked Questions
How do I access Utmify and set up the integration?
How do I access Utmify and set up the integration?
Just create a free account at: https://app.utmify.com.br/register
How do I know if the information I sent is correct?
How do I know if the information I sent is correct?
Our API validates all data sent in the payload. Invalid fields and accepted formats will be returned in the request response.
How do I know if the orders I sent were saved correctly?
How do I know if the orders I sent were saved correctly?
Access the account used to obtain the credential and navigate to the “Summary” tab. There you will find information about the orders saved on the platform, with filters by specific periods.
I received the error API_CREDENTIAL_NOT_FOUND. What does it mean?
I received the error API_CREDENTIAL_NOT_FOUND. What does it mean?
This error indicates that the API Credential was not provided or was passed incorrectly through the request headers. Please refer to the Request Format section for more details.