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.

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.

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_idvalues, 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.