Payments

Merchant payment webhook contract

Subscribe to payment.created, payment.approval_available (or its payment.link_generated alias), and the terminal payment.paid, payment.failed, payment.expired, and payment.cancelled events. Every event carries the following sanitized snapshot under envelope data; raw provider callbacks and mutable provider_metadata are never included.

Webhook data

payment.created has status: "link_pending" and payment_link_url: null. The two link-ready names have status: "link_generated" and a non-null URL. Terminal event names match their data.status.

payment.created

{
  "id": "evt_created_01K...",
  "type": "payment.created",
  "created_at": "2026-07-09T11:59:59.100Z",
  "occurred_at": "2026-07-09T11:59:59.000Z",
  "environment": "sandbox",
  "trace_id": "trc_01K...",
  "data": {
    "id": "pay_01K...",
    "object": "payment_request",
    "payment_request_id": "pay_01K...",
    "status": "link_pending",
    "amount_brl": "42.00",
    "currency": "BRL",
    "description": "Class booking",
    "customer_name": "Diego",
    "customer_phone": "+5511987654321",
    "customer_email": "[email protected]",
    "external_reference": "booking_123",
    "metadata": { "booking_id": "booking_123" },
    "payment_link_url": null,
    "provider": "abacate_pay",
    "provider_payment_id": null,
    "provider_approval_id": null,
    "provider_event_id": null
  }
}

payment.approval_available

{
  "id": "evt_01K...",
  "type": "payment.approval_available",
  "created_at": "2026-07-09T12:00:01.000Z",
  "occurred_at": "2026-07-09T12:00:00.000Z",
  "environment": "sandbox",
  "trace_id": "trc_01K...",
  "data": {
    "id": "pay_01K...",
    "object": "payment_request",
    "payment_request_id": "pay_01K...",
    "status": "link_generated",
    "amount_brl": "42.00",
    "currency": "BRL",
    "description": "Class booking",
    "customer_name": "Diego",
    "customer_phone": "+5511987654321",
    "customer_email": "[email protected]",
    "external_reference": "booking_123",
    "metadata": { "booking_id": "booking_123" },
    "payment_link_url": "https://pay.example.com/pay_01K...",
    "provider": "abacate_pay",
    "provider_payment_id": "bill_01K...",
    "provider_approval_id": null,
    "provider_event_id": null
  }
}

payment.paid

{
  "id": "evt_paid_01K...",
  "type": "payment.paid",
  "created_at": "2026-07-09T12:00:02.000Z",
  "occurred_at": "2026-07-09T12:00:01.500Z",
  "environment": "sandbox",
  "trace_id": "trc_01K...",
  "data": {
    "id": "pay_01K...",
    "object": "payment_request",
    "payment_request_id": "pay_01K...",
    "status": "paid",
    "amount_brl": "42.00",
    "currency": "BRL",
    "description": "Class booking",
    "customer_name": "Diego",
    "customer_phone": "+5511987654321",
    "customer_email": "[email protected]",
    "external_reference": "booking_123",
    "metadata": { "booking_id": "booking_123" },
    "payment_link_url": "https://pay.example.com/pay_01K...",
    "provider": "abacate_pay",
    "provider_payment_id": "bill_01K...",
    "provider_approval_id": null,
    "provider_event_id": "provider_evt_01K..."
  }
}

Monotonic consumer

const terminal = new Set(['paid', 'failed', 'expired', 'cancelled']);

function applyPaymentStatus(current, incoming) {
  if (terminal.has(current)) return current; // terminal is absorbing
  if (terminal.has(incoming)) return incoming;
  if (current === 'link_generated' && incoming === 'link_pending') return current;
  return incoming;
}

// Dedupe event.id before calling this function. Never send a link when the
// resulting state is terminal, even if a link-ready event arrived last.

Fees

Every accepted payment carries its payment-service fees in fees, the same object on agentic payments (/v1/agentic/payments), returned by create, retrieve, list and every other route that returns the payment. fees.initiation.amount_brl is the flat initiation fee, charged once at acceptance whatever the outcome. fees.completion.amount_brl is the completion fee, fees.completion.rate of the amount (a fraction: "0.01" is 1%), held from the balance at acceptance until the outcome. fees.completion.state is held, settled (the payment collected the money and the fee is charged), released (the hold was returned to the balance, normally because the payment ended without being paid) or unresolved (a production hold still held after the payment reached a final status, or 24 hours after acceptance, while Tyxter waits for the provider to confirm the outcome). fees.rate_card_id is the pricing version, and the two reservation_id values match payment_fee.reservation_id on GET /v1/billing/ledger. Amounts are decimal strings with four places.

In sandbox fees.simulated is true: the same amounts are recorded and nothing leaves the balance; list those ledger entries with GET /v1/billing/ledger?environment=sandbox. fees: null means no fee is owed, because the payment was charged none (it was accepted before payment-service fees applied, or by an API version that did not charge them). A creation, request approval or sandbox status call replayed with the same Idempotency-Key returns its stored response, with the fees as they were at the original call (a response stored before the field existed replays without it); retrieve the payment for the current state.

Creation refuses for the fees before anything is created or charged, and leaves no idempotency receipt: 402 insufficient_balance when the production balance cannot cover the initiation fee plus the completion hold (top up, then retry with the same Idempotency-Key), and 503 payment_fee_pricing_unavailable when the fee prices cannot be read (retry later). Both carry the error.feedback pointer. A production key whose credit is exhausted is refused before that with 402 credit_balance_exhausted, which is not retryable until credit recovers and carries no error.feedback pointer.

Create

Request

Response

List

Query

Response

Retrieve

Response

Cancel a hosted checkout

Send an empty JSON object with payments:write and an optional Idempotency-Key. HTTP 200 returns the current payment while cancellation runs asynchronously. Poll the payment or consume its terminal webhook to observe provider confirmation. A keyed retry replays the original response; retrieve for current state. Supported terminal payments are a no-op; a link that is not ready returns 409 payment_link_not_ready. Transparent Pix and unsupported providers return 400 payment_cancellation_unsupported with error.feedback and no mutation. Pix requires a provider-confirmed terminal outcome such as expiry. Failed or uncertain reads and deletion attempts keep the completion fee held for automated recovery. Confirmed paid takes precedence; nonpaid release also requires proven create history. The SDK method is client.payments.cancel(id, { idempotencyKey }).

Request approval

Request

Response

Sandbox terminal status

Sandbox-only fixture. Forces a payment request to paid, failed, expired, or cancelled and emits the matching customer-visible payment event, such as payment.paid, without calling a provider.

The connectionless sandbox default uses a deterministic hosted-link fixture. It does not emulate Abacate Pay checkout or transparent-Pix options; select an Abacate Pay sandbox connection, then re-read GET /v1/provider-connections/status and require channels.payments.active_mode === "abacate_pay" before sending provider_options.abacate_pay. This read requires provider_connections:read; a key without it receives 403 insufficient_scope.

Request

Response