Payment requests

Tyxter persists the payment request first, then a worker creates the provider payment with the configured payment connector. Treat payment_link_url = null as a normal short-lived pending state until the worker records the provider approval URL.

Agentic Payments is separate from payment requests. Agentic flows use /v1/agentic/*, payer-bank authorizations, and MCP polling; generic payment requests stay on /v1/payments for merchant collection.

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. This is separate from Tyxter billing credits, which pay for platform usage.

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

POST/v1/payments

GET/v1/payments

GET/v1/payments/{payment_id}

POST/v1/payments/{payment_id}/request-approval

POST/v1/sandbox/payments/{payment_id}/status

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.