canonical: https://jentic.com/apis/picpay.com/picpay

# PicPay Business Checkout API

Jentic publishes the only available OpenAPI specification for PicPay Business Checkout API, keeping it validated and agent-ready. The PicPay API enables Brazilian e-commerce merchants to accept payments through the PicPay digital wallet, supporting payment initiation via QR codes and payment URLs, real-time status checking, and full or partial refunds. It is designed for integration into checkout flows, allowing customers to complete purchases using their PicPay balance, and provides webhook notifications for payment lifecycle events. Authentication uses an API token passed in the x-picpay-token header, and all endpoints exchange JSON payloads for payment operations.

## For AI agents

Create PicPay payment requests with QR codes, check payment status in real time, process refunds and cancellations, and handle webhook notifications for completed transactions so an agent can orchestrate Brazilian e-commerce checkout flows.

## Scope

Does not handle merchant onboarding, settlement reports, dispute management, or account balance inquiries - use only for creating payment requests, checking status, and processing refunds for PicPay digital wallet transactions.

## Capabilities

- Create payment requests with QR codes and payment URLs via POST /payments
- Check payment status by reference ID through GET `/payments/{referenceId}/status`
- Cancel or refund payments via POST `/payments/{referenceId}/cancellations`
- Process partial or full refunds with POST `/payments/{referenceId}/refunds`
- Receive real-time payment status updates through webhook endpoint POST /notifications
- Support multiple payment statuses: created, expired, analysis, paid, completed, refunded, chargeback
- Generate QR codes with base64 images for customer scanning
- Set payment expiration times and callback URLs for status notifications

## Use cases

### Brazilian e-commerce checkout integration

Integrate PicPay digital wallet into an e-commerce checkout flow for Brazilian customers. When a customer selects PicPay as their payment method, the merchant calls POST /payments with the order details including amount in BRL, customer information, and callback URL. The API returns a paymentUrl and QR code that can be displayed to the customer. Once the customer scans the QR code with their PicPay app and authorizes payment, PicPay sends a webhook notification to the merchant's callbackUrl, allowing the order to be fulfilled immediately.

Example prompt: Call POST /payments with referenceId 'order-12345', value 99.90 (BRL), callbackUrl 'https://merchant.com/webhooks/picpay', buyer details including firstName, lastName, document (CPF), email, and phone. Display the returned paymentUrl and qrcode.base64 to the customer. Listen for webhook at /notifications to confirm payment completion.

### Payment status polling and reconciliation

For merchants who want to poll payment status instead of relying solely on webhooks, the API provides GET `/payments/{referenceId}/status` to check the current state of any payment. This is useful for reconciliation processes, customer service inquiries, or as a fallback when webhook delivery fails. The endpoint returns one of seven status values (created, expired, analysis, paid, completed, refunded, chargeback) along with the authorizationId needed for refund operations.

Example prompt: Call GET `/payments/{referenceId}/status` with the order's referenceId every 30 seconds until status changes from 'created' to 'paid' or 'completed'. If status becomes 'expired', notify the customer to retry. Store the authorizationId for future refund operations.

### Order cancellation and refund processing

When a customer requests a refund or an order needs to be cancelled, merchants can use POST `/payments/{referenceId}/refunds` for full or partial refunds by specifying an optional amount in BRL. For cancellations before payment is completed, POST `/payments/{referenceId}/cancellations` handles the workflow. Both endpoints require the referenceId from the original payment creation and return confirmation IDs that can be stored for audit trails.

Example prompt: To refund 50% of a payment, call GET `/payments/{referenceId}/status` to retrieve the authorizationId, then POST `/payments/{referenceId}/refunds` with value: 49.95 (half of the original 99.90 BRL). For full cancellation before payment clears, call POST `/payments/{referenceId}/cancellations` with the authorizationId.

### AI agent checkout orchestration via Jentic

An AI agent managing a Brazilian e-commerce platform uses Jentic to discover PicPay payment capabilities without reading documentation. The agent searches Jentic for 'create PicPay payment for Brazilian customer', loads the payment creation schema, executes POST /payments with the order amount and customer CPF, generates the QR code for display, then listens for the webhook notification to confirm payment. Jentic stores the x-picpay-token credential encrypted in its vault, so the agent never handles the raw API token.

Example prompt: Search Jentic for 'create PicPay payment', load the schema for createPayment, execute it with referenceId, value in BRL, buyer CPF and contact details, and callbackUrl. Display the returned QR code image (base64) to the customer and wait for webhook notification at /notifications to mark order as paid.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/payments` | Create a payment request with QR code |
| GET | `/payments/{referenceId}/status` | Check payment status |
| POST | `/payments/{referenceId}/cancellations` | Cancel a payment |
| POST | `/payments/{referenceId}/refunds` | Refund a payment |
| POST | `/notifications` | Webhook endpoint for payment notifications |

## Key resources

- **Payments** — Create payment requests, check status, and process refunds and cancellations
- **Notifications** — Receive webhook notifications for payment lifecycle events

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 64 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 61 / 100
  - AI-Readiness & Agent Experience: 48 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 68 / 100
- **View full report:** https://jentic.com/apis/picpay.com/picpay/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the PicPay Business Checkout API by hand means handling its x-picpay-token header auth and coding each payment, status check, cancellation, and refund call against the digital wallet flow yourself. Through Jentic you install once, import PicPay from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** PicPay puts the payment reference id in the URL path (`/payments/{referenceId}/...`), so a rule can pin your agent to acting on payments it created: it can check status for a reference and nothing outside that. You choose the operations it may call, so money-moving ones like cancellation or refund are not included unless you add them.
- **Credential handling:** Your PicPay x-picpay-token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a PicPay payment for a Brazilian customer' or 'refund a PicPay transaction', and Jentic returns the matching PicPay operation with its JSON request schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stripe API** — Global payment processing platform supporting 135+ currencies and multiple payment methods
- **Toss Payments API** — Korean digital payment platform similar to PicPay for South Korean market

## FAQ

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

PicPay does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call PicPay 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 PicPay API use?

The PicPay API uses an API token passed in the x-picpay-token header. When you call it through Jentic, the token is stored encrypted in the Jentic credential vault and injected at execution time, so the secret never enters the agent's prompt or logs.

### What payment statuses can PicPay transactions have?

PicPay payments can have seven statuses: created (payment initiated), expired (QR code expired), analysis (under fraud review), paid (customer authorized), completed (funds settled), refunded (money returned), and chargeback (disputed). Check status with GET `/payments/{referenceId}/status.`

### Can I process partial refunds with the PicPay API?

Yes. Call POST `/payments/{referenceId}/refunds` with an optional 'value' field containing the refund amount in BRL. If omitted, the entire payment is refunded. The API requires the authorizationId from the original payment status response.

### How do I receive payment notifications from PicPay?

When creating a payment via POST /payments, include a callbackUrl where PicPay will send webhook notifications as JSON payloads containing referenceId and authorizationId. Implement POST /notifications endpoint on your server to receive these updates when payment status changes.

### Is the PicPay API only for Brazilian merchants?

Yes. The PicPay Business Checkout API is designed for Brazilian e-commerce, accepts amounts in BRL (Brazilian Real), and requires customer CPF (Brazilian tax ID) in the buyer object. It integrates with the PicPay digital wallet, which is primarily used in Brazil.

### How do I generate a QR code for PicPay payment?

Call POST /payments with your payment details. The response includes a qrcode object with two fields: 'content' (the QR code data string) and 'base64' (a base64-encoded image). Display the base64 image to your customer, or use the content string to generate your own QR code graphic.

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

Yes. Jentic One is self-hosted by you, so your own rules decide which PicPay operations and credentials the agent may use. Because PicPay carries the payment reference ID in the URL path (`/payments/{referenceId}/...`), you can pin the agent to acting on payments it created, for example allowing only GET `/payments/{referenceId}/status` to check state. Money-moving operations like POST `/payments/{referenceId}/cancellations` and POST `/payments/{referenceId}/refunds` are excluded unless you explicitly grant them.