PicPay Business Checkout API
★ Only Publicly Available OpenAPI DocumentPayments FintechPayment ProcessingapiKey5 EndpointsREST
For 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.
Use for: I need to create a PicPay payment request for a Brazilian customer, Generate a QR code for PicPay payment, Check if a PicPay payment has been completed, Refund a PicPay transaction
Not supported: 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.
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.
Install Jentic One Beta
Connect the PicPay Business Checkout API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the PicPay Business Checkout API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with PicPay Business Checkout API.
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
Patterns agents use PicPay Business Checkout API for, with concrete tasks.
★ 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.
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.
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.
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.
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
5 endpoints — jentic publishes the only available openapi specification for picpay business checkout api, keeping it validated and agent-ready.
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
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
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
The PicPay x-picpay-token is stored encrypted in the Jentic vault. Agents receive a scoped execution token and the authentication header is injected at call time, so the raw API token never appears in agent prompts, logs, or tool outputs.
Intent-based discovery
Agents search Jentic by intent (for example 'create PicPay payment for Brazilian customer' or 'refund PicPay transaction') and Jentic returns the matching PicPay operation along with its JSON request schema, so the agent can call /payments or /refunds without reading any documentation.
Time to first call
Direct PicPay integration: half a day to a day to wire authentication, model the payment and refund payloads, handle webhook setup, and implement status polling. Through Jentic: under 30 minutes — search, load schema, execute.
Related APIs
Alternatives and complements available in the Jentic catalogue.
Alternative
Stripe API
Global payment processing platform supporting 135+ currencies and multiple payment methods
Choose Stripe for international payments or multi-currency support; use PicPay specifically for Brazilian customers who prefer digital wallet payments
Alternative
Mercado Pago API
Latin American payment platform by Mercado Libre, strong in Brazil and Argentina
Use Mercado Pago when operating across multiple Latin American markets; PicPay is more focused on Brazil
Alternative
PagSeguro API
Brazilian payment gateway offering credit cards, boleto, and digital wallet
PagSeguro provides broader payment methods in Brazil; PicPay specializes in digital wallet QR code payments
FAQs
Specific to using PicPay Business Checkout API through Jentic.
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 at https://app.jentic.com/sign-up.
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.
GET STARTED