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.

Step 1: Jentic One Host machine

# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fpicpay.com%2Fpicpay" | sh

Step 2: Agent machine

# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fpicpay.com%2Fpicpay" | sh
jentic register       # connects your agent to your Jentic One instance

Jentic 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

GET STARTED

Start building with PicPay Business Checkout API

Explore with Jentic One

View OpenAPI Document

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?

What agents get from Jentic-routed access to this vendor.

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 isolation

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.

Intent-based discovery

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

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

Complementary

Toss Payments API

Korean digital payment platform similar to PicPay for South Korean market

Use Toss Payments for Korean customers, PicPay for Brazilian customers - both are regional digital wallet leaders

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

PicPay Business Checkout API

Name: PicPay Business Checkout API
Brand: PicPay Business Checkout API
Availability: InStock

AI ReadinessAI-Aware (B)64/100

See full scorecard

Agent-ready OpenAPI document · curated by JenticPaymentsPayment ProcessingapiKey5 EndpointsREST

Know of an official OpenAPI document? Contribute it →

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.

Jentic One on Github View OpenAPI Document

Show dimension breakdown

100

Foundational Compliance

Base layer of spec validity and structural soundness.

Grade: A+Signals: 4

99%

Lint Results

Aggregated quality score from linter diagnostics, weighted by severity.

100%

Resolution Completeness

Percentage of `$ref` references that resolve successfully.

100%

Specification Validity

Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).

100%

Structural Integrity

Structural correctness score based on schema issues using logarithmic dampening.

Developer Experience & Jentic Compatibility

Clarity, completeness, and ingestion readiness for developers and tooling.

Grade: B-Signals: 4

Example Density

How richly the API is illustrated with examples.

100%

Example Validity

Percentage of examples that conform to their schemas.

45%

Response Coverage

Percentage of operations with complete response definitions (success, client error, server error).

100%

Tooling Readiness

Health of API ingestion, bundling, and resolution within Jentic pipelines.

AI-Readiness & Agent Experience

Semantic breadth, depth, and agent comprehension for AI systems.

Grade: D+Signals: 4

42%

Description Coverage

Coverage of descriptions across API elements.

Error Standardization

Coverage of RFC 9457 Problem Details for error responses.

100%

OperationId Quality

Coverage, uniqueness, and casing consistency of operationIds for AI inference.

50%

Summary Coverage

Coverage of summaries across operations/tags/info.

Agent Usability

Functional utility, complexity comfort, and AI orchestration readiness.

Grade: A+Signals: 1

94%

Complexity Comfort

Agent comfort level based on API operational and structural complexity.

Security

Trust, risk posture, and security compliance.

Grade: C-Signals: 1

50%

Authentication Strength

Average quality of security schemes based on authentication method strength (weakest link for OAuth2).

AI Discoverability

Findability, semantic richness, and reasoning readiness.

Grade: B+Signals: 1

68%

Descriptive Richness

Clarity and depth of descriptions across API elements.

Connect the PicPay Business Checkout API to your agent

Capabilities

Start building with PicPay Business Checkout API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs

PicPay Business Checkout API

Jentic AI Readiness Score

PicPay Business Checkout API

Foundational Compliance

Lint Results

Resolution Completeness

Specification Validity

Structural Integrity

Developer Experience & Jentic Compatibility

Example Density

Example Validity

Response Coverage

Tooling Readiness

AI-Readiness & Agent Experience

Description Coverage

Error Standardization

OperationId Quality

Summary Coverage

Agent Usability

Complexity Comfort

Security

Authentication Strength

AI Discoverability

Descriptive Richness