API Reference

Integrate chargebacks, risk assessment, checkout, card vault, workflows, and more into your stack.

Base URL https://api.truova.com/api/v1

Authentication

Authenticated endpoints require a Bearer JWT or an API key. Use POST /auth/login to obtain a JWT, or manage API keys via /auth/api-keys.

Bearer Token

Pass the access token returned by /auth/login in the Authorization header.

Header

Authorization: Bearer <access_token>

API Key

Alternatively, pass a long-lived API key in the X-API-Key header. Keys use the prefix trv_live_.

Header

X-API-Key: trv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Navigate to Settings → API Keys in the Truova dashboard to create keys. Never expose keys in client-side code.

POST /auth/login Obtain access + refresh tokens

Request Body

Field	Type		Description
email	string	required	User email address
password	string	required	User password

curl

curl -X POST https://api.truova.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@example.com","password":"secret"}'

Response

200 OK

{
  "success": true,
  "data": {
    "access_token": "eyJhbGci...",
    "refresh_token": "eyJhbGci...",
    "expires_in": 900
  }
}

POST /auth/refresh Refresh access token

Request Body

Field	Type		Description
refresh_token	string	required	Refresh token from login

Response

200 OK

{
  "success": true,
  "data": {
    "access_token": "eyJhbGci...",
    "expires_in": 900
  }
}

GET /auth/me Get current user

Returns the authenticated user's profile and role.

Response

200 OK

{
  "success": true,
  "data": {
    "id": "usr_a1b2c3",
    "email": "dev@example.com",
    "name": "Dev User",
    "role": "TenantAdmin",
    "tenant_id": "tnt_xyz"
  }
}

Also available: POST /auth/register, POST /auth/api-keys, GET /auth/api-keys, DELETE /auth/api-keys/:id.

Base URL

All endpoints are relative to the base URL.

Production

https://api.truova.com/api/v1

Errors

The API uses standard HTTP status codes. All errors return a consistent JSON envelope.

Error Response

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "transaction_id is required",
  "timestamp": "2026-03-25T14:32:00.000Z"
}

Status	Meaning
200	Success
201	Created
400	Bad Request — invalid parameters
401	Unauthorized — missing or invalid credentials
403	Forbidden — insufficient permissions
404	Not Found
422	Unprocessable Entity — validation error
429	Rate Limited — too many requests
500	Internal Server Error

Checkout & Payment Links

Create branded payment links and serve a hosted checkout page. Payers access checkout via a token — no authentication required on the payer side.

POST /payment-ops/links Create payment link

Request Body

Field	Type		Description
amount	integer	required	Amount in smallest currency unit (centavos)
currency	string	required	ISO 4217 code (e.g., BRL)
description	string	optional	Description shown on the checkout page
customer_id	string	optional	Pre-fill payer details
expires_at	string	optional	ISO 8601 expiry timestamp
metadata	object	optional	Arbitrary key-value pairs

curl

curl -X POST https://api.truova.com/api/v1/payment-ops/links \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"amount":29900,"currency":"BRL","description":"Order #1234"}'

Response

201 Created

{
  "success": true,
  "data": {
    "id": "lnk_a1b2c3d4",
    "token": "c_t8x9z0abc",
    "url": "https://app.truova.com/c/t8x9z0abc",
    "amount": 29900,
    "currency": "BRL",
    "status": "active",
    "expires_at": null
  }
}

POST /checkout/:token/pay Process payment

Submit payment for a checkout link. Supports PIX and card. No authentication required — the token grants access.

Path Parameters

Parameter	Type		Description
token	string	required	Checkout link token

Request Body

Field	Type		Description
payment_method	string	required	`pix` or `credit_card`
card_token	string	optional	Vault token (required for card payments)
customer	object	optional	Payer details (name, email, document)

curl

curl -X POST https://api.truova.com/api/v1/checkout/t8x9z0abc/pay \
  -H "Content-Type: application/json" \
  -d '{"payment_method":"pix","customer":{"name":"Maria Silva","email":"m@example.com"}}'

Response

200 OK

{
  "success": true,
  "data": {
    "status": "pending",
    "payment_method": "pix",
    "pix_qr_code": "00020126...",
    "pix_copy_paste": "00020126...",
    "expires_at": "2026-03-25T15:30:00.000Z"
  }
}

GET /checkout/:token Get checkout page data

Returns metadata needed to render a checkout page: amount, description, branding, and available payment methods. No authentication required.

Response

200 OK

{
  "success": true,
  "data": {
    "token": "t8x9z0abc",
    "amount": 29900,
    "currency": "BRL",
    "description": "Order #1234",
    "status": "active",
    "payment_methods": ["pix", "credit_card"]
  }
}

Also available: GET /checkout/:token/status, GET /payment-ops/links, DELETE /payment-ops/links/:id.

Card Vault

Tokenize and manage payment cards. Store cards once and reference them by token in subsequent checkout and recovery flows.

POST /card-vault/tokenize Tokenize a card

Submit card data to receive a vault token. Raw card numbers are never stored — only the token and masked metadata are persisted.

Request Body

Field	Type		Description
number	string	required	Full card number (transmitted over TLS, never stored)
holder_name	string	required	Cardholder name
expiry_month	integer	required	Expiry month (1–12)
expiry_year	integer	required	4-digit expiry year
cvv	string	required	Card verification value (not persisted)
customer_id	string	optional	Associate card with a customer

curl

curl -X POST https://api.truova.com/api/v1/card-vault/tokenize \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"number":"4111111111111111","holder_name":"Maria Silva","expiry_month":12,"expiry_year":2029,"cvv":"123"}'

Response

201 Created

{
  "success": true,
  "data": {
    "token": "card_tok_a1b2c3d4",
    "last4": "1111",
    "brand": "visa",
    "holder_name": "Maria Silva",
    "expiry_month": 12,
    "expiry_year": 2029
  }
}

GET /card-vault/cards List vaulted cards

Returns all vaulted cards for the tenant. Only masked metadata is returned — never the full card number.

Response

200 OK

{
  "success": true,
  "data": [
    {
      "token": "card_tok_a1b2c3d4",
      "last4": "1111",
      "brand": "visa",
      "customer_id": "cust_789",
      "created_at": "2026-03-20T10:00:00.000Z"
    }
  ]
}

Also available: GET /card-vault/cards/:token, GET /card-vault/cards/by-customer/:customerId, DELETE /card-vault/cards/:token.

Chargebacks

Manage the full chargeback lifecycle from intake to submission. Cases flow through: received → enriching → awaiting_review → ready_to_submit → submitted → won / lost / abandoned.

GET /chargebacks List chargeback cases

Returns a paginated list of chargeback cases for the authenticated tenant.

Query Parameters

Parameter	Type		Description
page	integer	optional	Page number (default: 1)
limit	integer	optional	Results per page (default: 20, max: 100)
status	string	optional	Filter by status: received, enriching, awaiting_review, ready_to_submit, submitted, won, lost, abandoned

Response

200 OK

{
  "success": true,
  "data": [
    {
      "id": "cb_a1b2c3d4",
      "external_case_id": "dp_abc123",
      "provider": "stripe",
      "dispute_reason_code": "13.1",
      "amount": 15000,
      "currency": "BRL",
      "status": "awaiting_review",
      "received_at": "2026-03-20T10:00:00.000Z",
      "due_at": "2026-04-03T23:59:59.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 47
  }
}

GET /chargebacks/:id Get chargeback details

Returns full details for a single chargeback case including linked evidence and decision logs.

Path Parameters

Parameter	Type		Description
id	string	required	Chargeback case ID

Response

200 OK

{
  "success": true,
  "data": {
    "id": "cb_a1b2c3d4",
    "transaction_id": "txn_xyz789",
    "provider": "stripe",
    "external_case_id": "dp_abc123",
    "dispute_reason_code": "13.1",
    "internal_reason_category": "merchandise_not_received",
    "amount": 15000,
    "currency": "BRL",
    "status": "awaiting_review",
    "received_at": "2026-03-20T10:00:00.000Z",
    "due_at": "2026-04-03T23:59:59.000Z",
    "evidence_count": 3,
    "outcome": null
  }
}

GET /chargebacks/:id/timeline Get case timeline

Returns a chronological list of events for a chargeback case: status changes, evidence additions, decisions, and submissions.

Response

200 OK

{
  "success": true,
  "data": [
    {
      "event": "case_created",
      "timestamp": "2026-03-20T10:00:00.000Z",
      "actor": "system",
      "details": "Chargeback received from Stripe"
    },
    {
      "event": "evidence_added",
      "timestamp": "2026-03-20T10:01:30.000Z",
      "actor": "workflow:auto_enrich",
      "details": "Delivery proof collected from logistics"
    },
    {
      "event": "status_changed",
      "timestamp": "2026-03-20T10:02:00.000Z",
      "actor": "system",
      "details": "Status changed to awaiting_review"
    }
  ]
}

GET /chargebacks/stats Get chargeback statistics

Returns aggregate statistics: total cases, win rate, recovered amount, and breakdown by status.

Response

200 OK

{
  "success": true,
  "data": {
    "total_cases": 234,
    "won": 187,
    "lost": 32,
    "pending": 15,
    "win_rate": 0.854,
    "total_amount_disputed": 4875000,
    "total_amount_recovered": 3920000,
    "currency": "BRL"
  }
}

POST /chargebacks Create chargeback case

Manually create a chargeback case. Typically cases are created automatically via the inbound webhook, but this endpoint supports manual intake.

Request Body

Field	Type		Description
transaction_id	string	required	Truova transaction ID
provider	string	required	Payment provider (stripe, adyen, cielo, etc.)
external_case_id	string	optional	Provider's dispute identifier
dispute_reason_code	string	required	Provider reason code (e.g., "13.1")
amount	integer	required	Disputed amount in smallest currency unit
currency	string	required	ISO 4217 currency code
due_at	string	optional	Submission deadline (ISO 8601)

curl

curl -X POST https://api.truova.com/api/v1/chargebacks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"transaction_id":"txn_xyz789","provider":"stripe","dispute_reason_code":"13.1","amount":15000,"currency":"BRL"}'

POST /chargebacks/:id/evidence Attach evidence

Attach evidence to a chargeback case. Evidence types include delivery proof, customer communication, invoice, and more.

Request Body

Field	Type		Description
evidence_type	string	required	delivery_proof, invoice, customer_communication, refund_policy, etc.
source_system	string	optional	Origin system (e.g., erp, logistics, zendesk)
file_url	string	optional	URL to the evidence file
content	string	optional	Text content of the evidence

curl

curl -X POST https://api.truova.com/api/v1/chargebacks/cb_a1b2c3d4/evidence \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"evidence_type":"delivery_proof","source_system":"logistics","file_url":"https://storage.example.com/pod.pdf"}'

Response

201 Created

{
  "success": true,
  "data": {
    "id": "ev_e1f2g3h4",
    "case_id": "cb_a1b2c3d4",
    "evidence_type": "delivery_proof",
    "confidence": 0.92,
    "created_at": "2026-03-25T14:35:00.000Z"
  }
}

POST /chargebacks/:id/submit Submit case to provider

Submit the evidence package for a chargeback case to the payment provider. The case must be in ready_to_submit status. Submission is idempotent — re-submitting returns the existing submission.

Response

200 OK

{
  "success": true,
  "data": {
    "submission_id": "sub_w1x2y3z4",
    "case_id": "cb_a1b2c3d4",
    "status": "submitted",
    "submitted_at": "2026-03-25T15:00:00.000Z"
  }
}

Also available: PUT /chargebacks/:id, GET /chargebacks/:id/timeline, GET /chargebacks/stats.

Transactions

GET /transactions List transactions

Returns a paginated list of transactions for the authenticated tenant.

Query Parameters

Parameter	Type		Description
page	integer	optional	Page number (default: 1)
limit	integer	optional	Results per page (default: 20, max: 100)
status	string	optional	Filter by authorization status

Response

200 OK

{
  "success": true,
  "data": [
    {
      "id": "txn_xyz789",
      "order_id": "ord_456",
      "provider": "stripe",
      "payment_method": "credit_card",
      "amount": 29900,
      "currency": "BRL",
      "authorization_status": "approved",
      "capture_status": "captured",
      "created_at": "2026-03-18T09:15:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1543
  }
}

POST /transactions Create transaction

Register a new transaction. Useful for syncing transactions from your system into Truova for monitoring and chargeback matching.

Request Body

Field	Type		Description
order_id	string	optional	Associated order identifier
provider	string	required	Payment provider (stripe, adyen, cielo, etc.)
payment_method	string	required	credit_card, pix, boleto, wallet
amount	integer	required	Amount in smallest currency unit (centavos)
currency	string	required	ISO 4217 currency code (e.g., BRL, USD)
provider_reference	string	optional	Provider transaction reference
metadata	object	optional	Arbitrary metadata

Request

{
  "order_id": "ord_456",
  "provider": "stripe",
  "payment_method": "credit_card",
  "amount": 29900,
  "currency": "BRL",
  "provider_reference": "pi_3abc123",
  "metadata": {
    "customer_id": "cust_789"
  }
}

Response

201 Created

{
  "success": true,
  "data": {
    "id": "txn_new123",
    "order_id": "ord_456",
    "provider": "stripe",
    "amount": 29900,
    "currency": "BRL",
    "authorization_status": "pending",
    "created_at": "2026-03-25T14:40:00.000Z"
  }
}

POST /transactions/:id/attempts Record payment attempt

Request Body

Field	Type		Description
provider	string	required	Provider used for this attempt
status	string	required	approved, declined, failed, timeout
failure_reason	string	optional	Reason for failure (if declined/failed)

curl

curl -X POST https://api.truova.com/api/v1/transactions/txn_xyz789/attempts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"provider":"stripe","status":"declined","failure_reason":"insufficient_funds"}'

Response

201 Created

{
  "success": true,
  "data": {
    "id": "att_p1q2r3",
    "transaction_id": "txn_xyz789",
    "attempt_number": 2,
    "provider": "stripe",
    "status": "declined",
    "failure_reason": "insufficient_funds",
    "requested_at": "2026-03-25T14:42:00.000Z"
  }
}

Also available: GET /transactions/:id, GET /transactions/stats.

Customers

Manage customer profiles. Customers can be linked to orders, transactions, and vaulted cards. External system IDs are stored for cross-reference.

POST /customers Create customer

Request Body

Field	Type		Description
name	string	required	Customer full name
email	string	required	Email address
phone	string	optional	Phone in E.164 format
document	string	optional	Tax ID or national document number
external_ids	object	optional	IDs from external systems (e.g., {"erp":"CUS-001"})
attributes	object	optional	Arbitrary metadata

curl

curl -X POST https://api.truova.com/api/v1/customers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Maria Silva","email":"maria@example.com","phone":"+5511999999999"}'

Response

201 Created

{
  "success": true,
  "data": {
    "id": "cust_a1b2c3",
    "name": "Maria Silva",
    "email": "maria@example.com",
    "phone": "+5511999999999",
    "created_at": "2026-03-25T14:00:00.000Z"
  }
}

GET /customers List customers

Query Parameters

Parameter	Type		Description
page	integer	optional	Page number (default: 1)
limit	integer	optional	Results per page (default: 20, max: 100)
email	string	optional	Filter by email

Also available: GET /customers/:id, PUT /customers/:id, DELETE /customers/:id.

Orders

Register and manage orders. Orders are the commercial context for transactions and chargebacks — link them to customers and attach metadata for evidence enrichment.

POST /orders Create order

Request Body

Field	Type		Description
customer_id	string	optional	Truova customer ID
amount	integer	required	Order total in smallest currency unit
currency	string	required	ISO 4217 currency code
external_ids	object	optional	IDs from external systems (e.g., {"erp":"ORD-1234"})
metadata	object	optional	Items, shipping address, delivery date, etc.

curl

curl -X POST https://api.truova.com/api/v1/orders \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":"cust_a1b2c3","amount":29900,"currency":"BRL","external_ids":{"erp":"ORD-1234"}}'

Response

201 Created

{
  "success": true,
  "data": {
    "id": "ord_a1b2c3d4",
    "customer_id": "cust_a1b2c3",
    "amount": 29900,
    "currency": "BRL",
    "created_at": "2026-03-25T09:00:00.000Z"
  }
}

Also available: GET /orders, GET /orders/:id, PUT /orders/:id, DELETE /orders/:id.

Risk Assessment

Score transactions for fraud risk in real time. The engine evaluates multiple signals and returns a score (0 = safe, 1 = high risk) with contributing factors and a recommendation.

POST /risk/assess Assess transaction risk

Request Body

Field	Type		Description
context_type	string	required	Entity type (transaction, order)
context_id	string	required	Entity identifier
transaction_data	object	required	Transaction details: amount, currency, customer_email, ip_address, payment_method, device_fingerprint

curl

curl -X POST https://api.truova.com/api/v1/risk/assess \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"context_type":"transaction","context_id":"txn_xyz789","transaction_data":{"amount":29900,"currency":"BRL","ip_address":"189.45.32.100","payment_method":"credit_card"}}'

Response

200 OK

{
  "success": true,
  "data": {
    "score": 0.23,
    "factors": [
      { "name": "ip_geolocation", "weight": 0.15, "detail": "IP matches billing country" },
      { "name": "velocity", "weight": 0.08, "detail": "2 transactions in last 24h" }
    ],
    "recommendation": "approve",
    "evaluated_at": "2026-03-25T14:32:01.123Z"
  }
}

Also available: GET /risk, GET /risk/latest, GET /risk/stats, GET /risk/alerts.

Payment Recovery

Create and execute recovery actions for failed payments. Strategies include retry, fallback to another provider, customer notification, or payment link generation.

GET /payment-ops/recovery-actions List recovery actions

Returns a list of payment recovery actions, optionally filtered by status.

Query Parameters

Parameter	Type		Description
status	string	optional	Filter: pending, executing, completed, failed
transaction_id	string	optional	Filter by transaction

Response

200 OK

{
  "success": true,
  "data": [
    {
      "id": "ra_m1n2o3",
      "transaction_id": "txn_xyz789",
      "strategy": "retry_same_provider",
      "status": "pending",
      "created_at": "2026-03-25T14:45:00.000Z"
    }
  ]
}

POST /payment-ops/recovery-actions Create recovery action

Create a new payment recovery action. The action will be queued for execution.

Request Body

Field	Type		Description
transaction_id	string	required	Transaction to recover
strategy	string	required	retry_same_provider, fallback_provider, notify_customer, generate_payment_link
config	object	optional	Strategy-specific configuration

Request

{
  "transaction_id": "txn_xyz789",
  "strategy": "fallback_provider",
  "config": {
    "fallback_provider": "adyen",
    "max_retries": 3
  }
}

Response

201 Created

{
  "success": true,
  "data": {
    "id": "ra_p4q5r6",
    "transaction_id": "txn_xyz789",
    "strategy": "fallback_provider",
    "status": "pending",
    "created_at": "2026-03-25T14:48:00.000Z"
  }
}

POST /payment-ops/recovery-actions/:id/execute Execute recovery action

Immediately execute a pending recovery action. The action transitions to "executing" and the result is returned asynchronously.

Path Parameters

Parameter	Type		Description
id	string	required	Recovery action ID

Response

200 OK

{
  "success": true,
  "data": {
    "id": "ra_p4q5r6",
    "status": "executing",
    "started_at": "2026-03-25T14:50:00.000Z"
  }
}

Workflows

Define, publish, and execute automation workflows. Definitions describe the graph (steps, conditions, actions). Executions are running instances tied to a specific entity.

GET /workflows/definitions/templates List workflow templates

Returns available workflow templates: chargeback contest, payment recovery, meeting automation, and any custom tenant templates.

Response

200 OK

{
  "success": true,
  "data": [
    {
      "id": "tpl_chargeback_auto_contest",
      "name": "Chargeback Auto Contest",
      "trigger_type": "chargeback.received",
      "step_count": 6
    }
  ]
}

POST /workflows/definitions/from-template Create definition from template

Request Body

Field	Type		Description
template_id	string	required	Template to base the definition on
name	string	required	Name for the new definition
overrides	object	optional	Step or config overrides from the template defaults

POST /workflows/execute Execute workflow

Start a new workflow execution against a specific entity.

Request Body

Field	Type		Description
workflow_id	string	required	Workflow definition ID
context_type	string	required	chargeback, transaction, or order
context_id	string	required	Entity identifier
input	object	optional	Input variables passed to the first step

curl

curl -X POST https://api.truova.com/api/v1/workflows/execute \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id":"wf_auto_contest","context_type":"chargeback","context_id":"cb_a1b2c3d4","input":{"auto_submit":true}}'

Response

201 Created

{
  "success": true,
  "data": {
    "execution_id": "wfx_s1t2u3v4",
    "workflow_id": "wf_auto_contest",
    "status": "running",
    "started_at": "2026-03-25T14:55:00.000Z"
  }
}

GET /workflows/executions/:id Get execution status

Poll the status of a workflow execution, including step progress and final result.

Response

200 OK

{
  "success": true,
  "data": {
    "execution_id": "wfx_s1t2u3v4",
    "status": "completed",
    "started_at": "2026-03-25T14:55:00.000Z",
    "ended_at": "2026-03-25T14:57:12.000Z",
    "steps_completed": 5,
    "steps_total": 5,
    "result": {
      "decision": "contest",
      "confidence": 0.91,
      "submission_id": "sub_w1x2y3z4"
    }
  }
}

Also available: GET /workflows/definitions, POST /workflows/definitions, GET /workflows/definitions/:id, PUT /workflows/definitions/:id, DELETE /workflows/definitions/:id, POST /workflows/definitions/:id/publish, GET /workflows/definitions/:id/history, GET /workflows/stats.

Integrations

Configure connectors to external systems: PSPs, ERPs, CRMs, logistics providers, and helpdesks. Each connector implements a standard capability model.

GET /integrations/connectors List connectors

Returns all configured connectors for the tenant with their type, vendor, status, and capabilities.

Response

200 OK

{
  "success": true,
  "data": [
    {
      "id": "conn_a1b2c3",
      "connector_type": "psp",
      "vendor": "stripe",
      "status": "active",
      "capabilities": ["fetch_order", "submit_dispute", "refund_payment"]
    }
  ]
}

POST /integrations/connectors Create connector

Request Body

Field	Type		Description
connector_type	string	required	psp, erp, crm, logistics, helpdesk
vendor	string	required	Vendor identifier (e.g., stripe, hubspot, shopify)
auth_config	object	required	Authentication credentials (encrypted at rest)
mapping_config	object	optional	Field mapping overrides

curl

curl -X POST https://api.truova.com/api/v1/integrations/connectors \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"connector_type":"psp","vendor":"stripe","auth_config":{"api_key":"sk_live_..."}}'

POST /integrations/connectors/:id/test Test connector health

Run a health check against the connector's external system. Returns latency, status, and any authentication errors.

Response

200 OK

{
  "success": true,
  "data": {
    "healthy": true,
    "latency_ms": 142,
    "checked_at": "2026-03-25T15:10:00.000Z"
  }
}

Also available: GET /integrations/connectors/:id, PUT /integrations/connectors/:id, DELETE /integrations/connectors/:id, POST /integrations/connectors/:id/sync.

Plans & Subscriptions

Manage billing plans and customer subscriptions. Plans define pricing and feature limits; subscriptions bind a customer to a plan with lifecycle management.

GET /plans List plans

Response

200 OK

{
  "success": true,
  "data": [
    {
      "id": "plan_starter",
      "name": "Starter",
      "price": 49900,
      "currency": "BRL",
      "interval": "monthly",
      "features": { "chargebacks_per_month": 100, "api_calls_per_minute": 60 }
    }
  ]
}

POST /subscriptions Create subscription

Request Body

Field	Type		Description
plan_id	string	required	Plan to subscribe to
customer_id	string	required	Customer being subscribed
card_token	string	optional	Vault card token for recurring billing

Also available: POST /plans, GET /plans/:id, PATCH /plans/:id, GET /subscriptions, GET /subscriptions/:id, PATCH /subscriptions/:id/cancel, PATCH /subscriptions/:id/pause, PATCH /subscriptions/:id/resume, PATCH /subscriptions/:id/update-card.

Notifications

Send transactional notifications via WhatsApp and email. Commonly used in payment recovery workflows and customer communication.

POST /notifications/whatsapp/send Send WhatsApp message

Send a templated WhatsApp message via the WhatsApp Business API (Cloud API). Used for payment reminders, recovery links, and case updates.

Request Body

Field	Type		Description
to	string	required	Recipient phone number (E.164 format, e.g., +5511999999999)
template	string	required	Template name (e.g., payment_reminder, recovery_link)
variables	object	optional	Template variable replacements

Request

{
  "to": "+5511999999999",
  "template": "payment_reminder",
  "variables": {
    "customer_name": "Maria Silva",
    "amount": "R$ 299,00",
    "payment_link": "https://pay.truova.com/r/abc123"
  }
}

Response

200 OK

{
  "success": true,
  "data": {
    "message_id": "wamid.abc123def456",
    "status": "sent",
    "sent_at": "2026-03-25T15:00:00.000Z"
  }
}

POST /notifications/email/test Send test email

Send a test email to verify your email notification configuration. Useful for testing templates before using them in production workflows.

Request Body

Field	Type		Description
to	string	required	Recipient email address
subject	string	required	Email subject line
body	string	required	Email body (HTML supported)

Request

{
  "to": "dev@example.com",
  "subject": "Payment reminder - Order #456",
  "body": "<h1>Payment Pending</h1><p>Please complete your payment.</p>"
}

Response

200 OK

{
  "success": true,
  "data": {
    "message_id": "msg_email_abc123",
    "status": "sent"
  }
}

Also available: GET /notifications/email/status, GET /notifications/whatsapp/status.

Webhooks / Inbound

Receive chargeback notifications and payment events from your providers. Truova normalizes the payload, persists the raw event, and triggers the appropriate workflow. Payloads are validated with HMAC signatures and replay-protected with a 5-minute timestamp window.

POST /inbound/webhooks/:source Receive provider webhook

Receive chargeback or payment notifications from a provider. :source identifies the provider (e.g., stripe, adyen, cielo).

Path Parameters

Parameter	Type		Description
source	string	required	Provider identifier (stripe, adyen, cielo, etc.)

Headers

Header	Type		Description
X-Webhook-Signature	string	optional	HMAC-SHA256 signature for payload verification
X-Webhook-Timestamp	string	optional	Unix timestamp for replay protection

Example Payload

{
  "id": "evt_1234567890",
  "type": "chargeback.created",
  "data": {
    "dispute_id": "dp_abc123",
    "amount": 15000,
    "currency": "BRL",
    "reason_code": "13.1",
    "transaction_id": "txn_xyz789"
  }
}

Response

201 Created

{
  "success": true,
  "data": {
    "event_id": "evt_trv_a1b2c3d4",
    "source": "stripe",
    "status": "accepted",
    "created_at": "2026-03-25T14:32:00.000Z"
  }
}

POST /inbound/events Submit internal event

Publish a typed event directly into the Truova event bus. Use this for integrations that push data rather than expecting Truova to pull.

Request Body

Field	Type		Description
event_type	string	required	e.g., chargeback.received, payment.failed, order.created
payload	object	required	Event-specific data
external_event_id	string	optional	Idempotency key — duplicate events with the same ID are ignored

Rate Limits

API requests are rate-limited per API key. Limits depend on your plan.

Plan	Requests / minute	Burst
Starter	60	10 / second
Growth	300	30 / second
Enterprise	1,000+	Custom

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

Rate Limit Headers

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1711375920
Retry-After: 8

Versioning

The API is versioned via the URL path. The current version is v1. Breaking changes will be introduced in new versions only. Non-breaking additions (new fields, new endpoints) may be added to existing versions without notice.

Versioned URL

https://api.truova.com/api/v1/chargebacks