canonical: https://jentic.com/apis/nupaybusiness.com.br/nupaybusiness

# Nupaybusiness NuPay for Business Checkout API

Jentic publishes the only available OpenAPI specification for NuPay for Business Checkout API, keeping it validated and agent-ready. NuPay for Business is Nubank's checkout product for Brazilian merchants, providing payment capture, refunds, recipient management, and OAuth2 authorization with CIBA-OTP support. The API exposes a checkout payments suite, a recipient registry, and a full set of OAuth2 endpoints including back-channel authentication for low-friction payer authorization. It is used by Brazilian e-commerce, marketplaces, and SaaS billing flows that want native Pix and Nubank-account checkout.

## For AI agents

Capture and refund checkout payments, manage payout recipients, and run OAuth2 CIBA flows for the NuPay for Business gateway.

## Scope

Does not handle accounting, KYC onboarding, or merchant settlement reporting - use for NuPay checkout payments, refunds, recipients, and OAuth2 authorization only.

## Capabilities

- Create a checkout payment order for a Brazilian merchant
- Query the current status of a payment by PSP reference
- Cancel a pending payment before it captures
- Issue a refund against a captured payment
- Register and look up payout recipients by reference ID
- Initiate and complete a CIBA back-channel authorization with OTP
- Resend an OTP code for a back-channel authorization in flight

## Use cases

### Brazilian Checkout Capture

Brazilian e-commerce sites accept payments through NuPay by creating a payment order via POST `/v1/checkouts/payments` and polling status via the PSP-reference status endpoint until the transaction captures. Pix and Nubank-account flows sit behind the same surface, so the merchant integrates once and offers multiple local methods.

Example prompt: Call POST `/v1/checkouts/payments` with the order amount and method, then poll GET `/v1/checkouts/payments/{pspReferenceId}/status` until captured

### Refunds and Cancellations

Operations issue cancellations on pending orders via POST `/v1/checkouts/payments/{pspReferenceId}/cancel` and refund captured orders via the refunds endpoint. Both flows are scoped to the original PSP reference, preserving the audit trail expected by Brazilian financial regulators.

Example prompt: Call POST `/v1/checkouts/payments/{pspReferenceId}/refunds` with the refund amount, then GET the refund by ID to confirm settlement

### CIBA Back-Channel Authorization

Merchants offering high-trust flows initiate a CIBA back-channel authorization through POST `/v1/backchannel/authentication`, the payer receives an OTP, and the merchant completes the flow with `/v1/backchannel/authentication/complete.` This avoids redirect-based browser hops and works well in voice or chat contexts.

Example prompt: Call POST `/v1/backchannel/authentication` with the payer reference, collect the OTP, and POST `/v1/backchannel/authentication/complete` with the OTP value

### Agent-Driven Brazilian Checkout

An AI agent embedded in a Brazilian commerce assistant creates checkout payments and tracks status on behalf of the user. Through Jentic the agent searches for 'create a NuPay payment', loads the POST `/v1/checkouts/payments` schema, and executes without learning the bespoke OAuth2 CIBA conventions.

Example prompt: Search Jentic for 'create a NuPay checkout payment', load the schema for POST `/v1/checkouts/payments`, and execute with the order amount and merchant ID

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/checkouts/payments` | Create a payment order |
| GET | `/v1/checkouts/payments/{pspReferenceId}/status` | Query payment status |
| POST | `/v1/checkouts/payments/{pspReferenceId}/cancel` | Cancel a pending payment |
| POST | `/v1/checkouts/payments/{pspReferenceId}/refunds` | Request a refund |
| POST | `/v1/recipients` | Create a beneficiary |
| POST | `/v1/backchannel/authentication` | Initiate CIBA OTP authorization |
| POST | `/v1/backchannel/authentication/complete` | Validate OTP code |
| POST | `/v1/token` | Exchange code or refresh token |

## Key resources

- **Payments** — Create checkout payments, query status, and cancel pending orders
- **Refunds** — Request refunds and query refund status against captured payments
- **Recipients** — Register and look up payout recipients
- **Authorization** — Generate OAuth2 URLs, run CIBA back-channel authentication, and exchange tokens

## Why Jentic

- **Setup:** Wiring NuPay for Business by hand means juggling two auth schemes, the X-Merchant-Key header and an OAuth2 JWT bearer token, running the CIBA back-channel flow, and choosing the sandbox or production host yourself. Through Jentic you install once, import NuPay from the API Directory, store the merchant key and client secret once, and your agent calls it.
- **Permission scoping:** NuPay puts the payment id in the URL path (`/v1/checkouts/payments/{pspReferenceId}/...`), so a rule can pin your agent to the operations it needs against those payments: it can create payments and check status while a destructive operation like cancel or refund is not included unless you add it. You choose the operations it may call.
- **Credential handling:** Your NuPay merchant key and OAuth2 client secret are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Brazilian checkout payment' or 'run CIBA authorization', and Jentic returns the matching NuPay operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stripe** — Global card processor with growing Pix support in Brazil
- **Adyen Checkout** — Enterprise checkout API with multi-method coverage including Brazilian rails
- **PayPal Invoicing** — B2B invoicing alongside Brazilian consumer checkout via NuPay

## FAQ

### Why is there no official OpenAPI spec for NuPay for Business Checkout API?

NuPay for Business does not publish an OpenAPI specification on its public docs site. Jentic generates and maintains this spec so that AI agents and developers can call NuPay for Business Checkout API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the NuPay for Business Checkout API use?

The spec declares two schemes: an apiKey scheme for merchant identification and a bearer token scheme for OAuth2-issued access tokens. Through Jentic both are stored encrypted in the vault and injected at execution, so the raw secrets never enter the agent's context.

### Can I cancel a payment that has not yet captured?

Yes. Call POST `/v1/checkouts/payments/{pspReferenceId}/cancel` with the PSP reference returned at creation. The endpoint only succeeds while the payment is still pending - once captured, use the refund flow instead.

### How do I run a CIBA back-channel authorization through Jentic?

Search Jentic for 'CIBA back-channel authentication', load the schema for POST `/v1/backchannel/authentication`, then collect the OTP and call POST `/v1/backchannel/authentication/complete.` Jentic handles credential injection on both calls.

### What are the rate limits for the NuPay for Business Checkout API?

Rate limits are not declared in the OpenAPI spec. NuPay applies merchant-tier limits in production; check your NuPay merchant dashboard or contact your account manager for the exact quotas attached to your client.

### How do I refund a captured payment?

Call POST `/v1/checkouts/payments/{pspReferenceId}/refunds` with the refund amount, then GET `/v1/checkouts/payments/{pspReferenceId}/refunds/{refundId}` to confirm the refund settled. Both calls require the original PSP reference.

### Can I limit what my agent is allowed to do with the NuPay for Business Checkout API?

Yes. Jentic One is self-hosted, so your own rules decide which NuPay operations and credentials the agent may use. Because NuPay carries the payment id in the URL path, you can pin the agent to just the operations it needs, letting it create payments and check status while cancel and refund stay out of reach unless you add them. Your merchant key and OAuth2 client secret are stored encrypted by your instance and injected at execution, never entering the agent's context.