Payment requests

How it fits

Use payment requests when your product needs to track a customer payment owed to you, such as a WhatsApp assistant reserving a class and asking the student to pay. A payment request collects money owed to you; it is not your Tyxter credit balance, which pays for platform usage, including the fees for each payment Tyxter accepts.

Fees

Each accepted payment request is charged two payment fees from your Tyxter credit balance: R$0.10 when it is accepted, and 1% of the amount, held until the outcome and charged only if the payment is paid. The response reports both in fees, and a payment created from the dashboard is charged the same way. In production, creation fails with 402 insufficient_balance when your balance cannot cover both, and with 503 payment_fee_pricing_unavailable when the fee prices cannot be read; nothing is created or charged, and on /v1/payments both errors carry the error.feedback pointer. A sandbox payment records the same fees with fees.simulated = true and never moves your balance. Payment fees on the Billing page has the full rules.

Lifecycle

• link_pending - request accepted, provider link generation is queued.
• link_generated - the provider returned an approval URL.
• approval_requested - an approval request was submitted for the payment.
• Terminal provider states include paid, failed, expired, and cancelled.

Endpoints

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 }).

Agent guidance

Agents should create and track Tyxter payment requests, but should not tell the end user a payment link exists until the API returns a non-null payment_link_url. Use Tyxter payment IDs in your product; keep provider IDs and Pix artifacts as observability and checkout metadata. Merchant providers currently include Abacate Pay.

In sandbox, use POST /v1/sandbox/payments/{payment_id}/status to force a terminal state such as paid and receive payment.paid without a real checkout.

Webhook endpoints can subscribe to both payment.approval_available and its additive alias payment.link_generated when the hosted link is minted. Payment event data is an immutable event-time snapshot with id, object: "payment_request", the legacy payment_request_id, and the status at occurrence time. Webhook delivery order is not guaranteed, even within one payment: payment.paid can arrive before a link-ready event. Dedupe by envelope id, use occurred_at as business-event time, and make the consumer monotonic: terminal states are absorbing, so late payment.created or link-ready events must not trigger a payment link or regress the stored state. created_at is when webhook fanout created the delivery envelope.

The connectionless sandbox default is a deterministic hosted-link fixture (responses report provider: "iniciador" as its schema name), not a universal provider simulator. To exercise Abacate Pay options such as transparent Pix, register and select an Abacate Pay sandbox connection first. 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.