Agentic payments

How it fits

Agentic payments let an agent initiate a Pix transfer on behalf of a customer through Iniciador's agent-initiated payments rail. They require an approved Iniciador agentic connection, which is separate from merchant payment connections on /v1/payments; in production they also require an approved business identity.

Discover banks

Discover destination institutions with GET /v1/agentic/banks (agentic_payments:read), optionally filtered by search. Each bank carries the participant_id Iniciador uses to route the payment.

The list is the one Iniciador returned at Tyxter's latest successful check of your agentic connection, made when the connection is connected and then hourly; it is not a live provider call, and search and limit apply to it. When that check found no bank, data is empty. Until the first check succeeds (for example right after you register the connection), the request fails with 503 agentic_banks_unavailable; retry later. When the latest check was refused for the connection's credentials, it fails with 400 agentic_provider_unauthorized: fix the credentials. When the latest check refused the connection's custom API base URL as unsafe, it fails with 400 unsafe_iniciador_agentic_api_base_url: register the connection with a public API base URL. Sandbox simulator connections answer their one sandbox bank at once.

Authorizations

Authorizations are reusable customer consents. POST /v1/agentic/authorizations (agentic_payments:write, Idempotency-Key) creates one for a customer_tax_id with an agent_reason; the response can start as authorization_link_pending with next_action = null and resolve to an authorization_url the customer opens to grant consent. List with GET /v1/agentic/authorizations, retrieve one with GET /v1/agentic/authorizations/{authorization_id}, and revoke with POST /v1/agentic/authorizations/{authorization_id}/revoke. A missing authorization returns agentic_authorization_not_found.

Payments

Create a payment with POST /v1/agentic/payments (agentic_payments:write, Idempotency-Key). method is one of PIX_DICT (with pix_key), PIX_QRCODE (with qr_code), or PIX_MANU (with creditor account details). description is the bank-statement memo forwarded to Iniciador and is limited to 140 characters; Tyxter rejects longer input instead of truncating. agent_reason is separate and remains the user-visible hosted-page reason shown to the payer. Build payment requests from structured app state, not from webhook retry text or free-form prose.

The response carries a status timeline (authorization_required, payment_link_pending, pending, paid, cancelled, rejected, expired, error) and a next_action with the hosted payment_url to surface to the customer. List with GET /v1/agentic/payments, retrieve with GET /v1/agentic/payments/{payment_id}, and cancel a non-terminal payment with POST /v1/agentic/payments/{payment_id}/cancel. A missing payment returns agentic_payment_not_found.

Fees

Each accepted agentic payment 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. This applies on the Tyxter platform Iniciador app and on your own Iniciador connection alike. Payment fees on the Billing page has the full rules, including the 402 insufficient_balance refusal described below.

Every accepted payment carries its payment-service fees in fees, the same object on merchant payment requests (/v1/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). Cancelling a payment that has a provider_payment_id keeps its hold until the provider confirms the outcome, so in production the cancel response shows fees.completion.state unresolved (held in sandbox). A cancel before the payment has a provider_payment_id releases the hold in sandbox. In production, a cancel before the payment has a provider_payment_id releases the hold only when worker-proven complete create history excludes an uncertain provider create. If that proof is unavailable, the hold remains reserved and fees.completion.state is unresolved; existing worker recovery can release a fresh undispatched payment after establishing that proof. API cancellation cannot use a bare pre-dispatch observation; existing active-worker recovery must confirm absence. Older unknown history remains held. 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 or cancel 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.

Error codes

Before a connection exists, agentic calls fail with agentic_payment_provider_connection_required. If neither a participant_id nor a resolvable participant is supplied, payment creation fails with agentic_payment_participant_required.

For production bank enrollment failures, do not treat raw Iniciador strings as Tyxter configuration errors. If a create-authorization flow rejects with error_code = agentic_bank_not_available, call GET /v1/agentic/banks and choose one of the returned participant_id values, or ask Iniciador to enable that bank for the tenant's production provider account. If error_code = agentic_authorization_enrollment_failed and provider_error_code = CREATE_ENROLLMENT_ERROR (or provider_error_message = Tool execution failed), the selected bank is not enabled/entitled for that Iniciador agentic production application; the connection credentials and Tyxter webhook configuration can be correct while that bank still fails. Try an available bank from /v1/agentic/banks or escalate to Iniciador with the provider_error_code/details.

Sandbox

Sandbox agentic keys exercise the same routes, schemas, and error codes with deterministic provider behavior; only the Iniciador adapter differs.

Endpoints

Agent guidance

Treat Tyxter as the system of record. Surface the hosted next_action.url for authorization or payment confirmation; never fabricate an authorization URL, Pix payload, or paid status from Tyxter data. Wait for Tyxter to return next_action.url and a terminal status.