Get started

API v2 lets you collect money from a person (pay-ins) and pay money to a person (payouts) with a single integration: country, currency and method travel in the request body, and what you can do today is listed by GET /v2/capabilities. You don’t pick a provider or a sending bank: the API routes each operation through the best available rail.

In five steps

1. Ask for your keys. TuCapi gives you two: tuc_live_… for production (https://api.tucapi.app) and tuc_test_… to test without moving money in the sandbox (https://api.tucapi.app/sandbox), with the scopes you need (payins:crear, payouts:crear, operaciones:leer, saldos:leer, webhooks:configurar). See Authentication.
2. Read the catalog. GET /v2/capabilities tells you which countries, currencies and methods your key has, with the fields each method requires. See Catalog.
3. Register your webhook. POST /v2/webhook-endpoints with your https URL; store the secret, it is shown only once. See Webhooks.
4. Create your first operation with an SDK or with curl, always with an Idempotency-Key. See Pay-ins and Payouts.
5. Receive the outcome by webhook (payout.confirmed, payout.failed, payin.confirmed, payin.failed) or look it up with GET /v2/transactions/{id}.

Three rules worth understanding before you write code

• Idempotency-Key is mandatory and it is your safety net. Sending the same request with the same key returns THE SAME operation. That is what makes retrying safe. See Idempotency and retries.
• There are three public states: pending, confirmed and failed. A failed always carries failure.code, a closed value you can switch on. A 201 does not mean “paid”: look at status.
• Amounts are strings with a decimal point ("1500.50"), never JSON numbers.

A payout in three lines

POST /v2/payouts

curl -X POST https://api.tucapi.app/v2/payouts \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: order-4821" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1500.50",
    "beneficiary": {
      "account_number": "04121234567",
      "bank_code": "0102",
      "document": {
        "number": "12345678",
        "type": "V"
      },
      "name": "Jane Doe"
    },
    "country": "VE",
    "currency": "VES",
    "metadata": {
      "order": "B-2"
    },
    "method": "mobile_payment",
    "purpose": "remittance",
    "reference": "remittance 456"
  }'

Response 201

{
  "amount": "1500.50",
  "bank_reference": null,
  "country": "VE",
  "created_at": "2026-09-23T14:59:05Z",
  "created_by": "company",
  "currency": "VES",
  "failure": null,
  "id": "6f1c2a9e-3b4d-4c5e-8f70-1a2b3c4d5e6f",
  "metadata": {
    "order": "B-2"
  },
  "method": "mobile_payment",
  "pending_reason": "processing",
  "purpose": "remittance",
  "reference": "remittance 456",
  "status": "pending",
  "type": "payout",
  "updated_at": "2026-09-23T14:59:05Z"
}

Where everything is

• Get started: What API v2 is, how a pay-in and a payout work, and the five steps to your first integration.
• Authentication: Your API key, scopes and the sandbox environment.
• Idempotency and retries: How to retry without paying twice; what to retry and what not to.
• Pay-ins: Collect from a person with a one-time code, by direct debit, or wait for the mobile payment or transfer they send.
• Payouts: Pay a person by mobile payment or bank transfer, your balance, and cancellation.
• Webhooks and events: How to receive the outcome of every operation, verify the signature and query events.
• Errors and failures: The error envelope, API error codes and operation failure codes.
• Catalog: Countries, currencies, methods with their fields and limits, banks and availability.
• SDKs: The official Go, Node and Python clients: what they solve and how to use them.
• MCP server: How to connect an AI assistant (Claude, ChatGPT, Gemini, Codex) to your account over MCP, read-only.