Cashin API

The Cashin API brings together everything related to receiving money with PIX: generating dynamic QR codes and copy-and-paste payment codes, decoding existing QR codes, tracking the cash ins you received and requesting chargebacks on payments already settled.

Key Features

QR Code Generation: Create PIX QR codes with customizable payment details
Copy and Paste Codes: Generate text-based payment codes
Dynamic Payments: Set due dates, expiration dates, and late fees
QR Code Decoding: Decode existing PIX QR codes
Cash In Tracking: Look up a received payment by its EndToEndId, including the fee charged and how much has already been refunded
Chargeback Management: Request full or partial refunds of received payments and follow their outcome

Available Endpoints

Payment Generation

Generate a PIX Cash In (QR Code) - Generate a PIX payment code with QR code
Decode QR Code - Decode and extract information from PIX QR codes

Cash In Queries

Check Status and Details of a Generated PIX Cash In by ID or EndToEnd - Query a generated payment code by ID or EndToEndId
Check Status and Details of a Generated PIX Cash In by Tag - Query generated payment codes by tag
Find a PIX Cash In by EndToEndId - Retrieve a received payment, its fee and the amount already refunded

Chargeback Operations

Grouped under Chargeback API, which explains which route to use for each case.

Request a Chargeback by QR Code - Refund a payment using the QR Code ID
Check Chargeback Status by QR Code - Query the refund by chargeback ID or EndToEndId
Request a Chargeback by Cash In Transaction - Refund any received PIX using the cash in transaction ID
Check Chargeback Status by Cash In Transaction - Query the refund by chargeback ID

Authentication

All Cashin API endpoints require:

Bearer Token: Include in the Authorization header
HMAC Signature: Include in the hmac header for API audience requests

Fine Types

Type	Description	Example Value
NONE	No fine or interest	0
VALUE	Fixed value fine in BRL	5.00
PERCENT	Percentage fine (e.g., 2% = 2.0)	2.0

Cash In Flows

There are two ways for money to reach your account, and both end up in the same place: a cash in you can query and, if needed, refund.

Flow	How the payer pays	You generate something first?
QR Code / Copy and Paste	Scans the QR Code or pastes the code you sent	Yes — you create the code through the API
PIX Key or Branch and Account	Sends a PIX straight to your PIX key or to your branch + account number	No — the money simply arrives

1. Cash In via QR Code / Copy and Paste

You create the payment code, deliver it to the payer, and follow it until the money lands.

┌──────────────────────────────────────────────┐
│  POST /v2/finance/create-pix-copy-and-paste  │  ← You generate the QR Code / copy and paste code
└───────────────────────┬──────────────────────┘
                        │  webhook: QR_CODE_COPY_AND_PASTE_CREATED
                        ↓
                 ┌─────────────┐
                 │     NEW     │  ← Code created, waiting for the payer
                 └──────┬──────┘
                        │
                        ├─── Payer pays ──────→ ┌─────────────┐
                        │                       │ PROCESSING  │  ← Payment being settled
                        │                       └──────┬──────┘
                        │                              ↓
                        │                       ┌─────────────┐
                        │                       │    PAID     │  ← Money credited to your account
                        │                       └──────┬──────┘
                        │                              │  webhook: QR_CODE_COPY_AND_PASTE_PAID
                        │                              │
                        │                              │  Chargeback settled
                        │                              ↓
                        │                       ┌─────────────┐
                        │                       │ CHARGEBACK  │  ← Money returned to the payer
                        │                       └─────────────┘
                        │
                        ├─── Not paid until ──→ ┌─────────────┐
                        │    expiration_date    │   EXPIRED   │  ← Code can no longer be paid
                        │                       └─────────────┘
                        │
                        └─── Cancelled ───────→ ┌─────────────┐
                                                │  CANCELED   │  ← Code cancelled before payment
                                                └─────────────┘

How to check where it is:

GET /v2/finance/status-pix-copy-and-paste?id=12345          ← by QR Code ID
GET /v2/finance/status-pix-copy-and-paste?e2e_id=E123...    ← by EndToEndId
GET /v2/finance/status-pix-copy-and-paste/tag?tag=order-1   ← by tag

Once the code reaches PAID, you can also look the payment up as a cash in with GET /v2/finance/cashin/{e2e}, which returns the fee charged and the amount already refunded.

QR Code Status Descriptions

Status	Description	Next Steps
NEW	Code created and waiting for the payer	Deliver the code to the payer and wait for the payment webhook
PROCESSING	Payment is being settled	Wait for the final status (async)
PAID	Payment received and credited to your account	No action needed. Query `GET /cashin/{e2e}` for the fee and refund details
CHARGEBACK	The payment was refunded to the payer	Check the chargeback status for the refund details

2. Cash In via PIX Key or Branch and Account Number

Here there is nothing to generate. The payer sends a PIX directly to your PIX key or to your branch and account number, and the money arrives on its own. You find out through the webhook.

┌──────────────────────────────────────────────┐
│  Payer sends a PIX to your PIX key           │  ← Nothing is created through the API
│  or to your branch + account number          │
└───────────────────────┬──────────────────────┘
                        │
                        ↓
              ┌──────────────────────┐
              │  Money credited to   │  ← webhook: PIX_CASHIN_RECEIVED
              │    your account      │     (carries the EndToEndId)
              └──────────┬───────────┘
                         │
                         ↓
              ┌──────────────────────┐
              │  GET /v2/finance/    │  ← Amount, fee, payer identification
              │     cashin/{e2e}     │     and the "id" used for refunds
              └──────────┬───────────┘
                         │
                         ├─── Keep the money ──→  Nothing else to do
                         │
                         └─── Return the money ─→  Go to the Chargeback Flow below

Because no QR Code was involved, pix_qr_code_id comes back as null in the cash in response. Everything else works exactly the same, including chargebacks.

3. Chargeback Flow

Chargebacks work the same way for both cash in flows. The only difference is which webhook you receive at the end.

The diagram below uses the cash in transaction route, which accepts any received PIX. If your system stores the QR Code ID instead, use POST /v2/finance/chargebacks-pix-copy-and-paste and skip the first step. See Chargeback API for the comparison.

┌──────────────────────┐
│  GET /v2/finance/    │  ← Read the cash in "id" and how much
│     cashin/{e2e}     │     was already refunded
└──────────┬───────────┘
           ↓
┌──────────────────────┐
│  POST /v2/finance/   │  ← Request a full or partial refund
│      chargeback      │     (transaction_id, information, amount)
└──────────┬───────────┘
           ↓
    ┌─────────────┐
    │   PENDING   │  ← Payer at another institution: settling asynchronously
    └──────┬──────┘
           │
           ├─── Settled ─────────→ ┌─────────────┐
           │                       │   SUCCESS   │  ← Money returned to the payer
           │                       └─────────────┘
           │                       webhook: QR_CODE_COPY_AND_PASTE_REFUNDED
           │                                or PIX_CASHIN_REFUNDED
           │
           └─── Not completed ───→ ┌─────────────┐
                                   │  REJECTED   │  ← Refund could not be completed
                                   └─────────────┘
                                   webhook: QR_CODE_COPY_AND_PASTE_REFUNDED_ERROR
                                            or PIX_CASHIN_REFUNDED_ERROR

How to follow it:

GET /v2/finance/chargeback/status?id=550e8400-e29b-41d4-a716-446655440000

The id is the value returned by POST /v2/finance/chargeback.

Chargeback Status Descriptions

Status	Description	Next Steps
PENDING	Refund accepted and being settled. Only happens when the payer is at another institution	Poll the status endpoint or wait for the webhook
SUCCESS	Refund completed and funds returned to the payer. Refunds to payers in the same institution are settled immediately and already come back as `SUCCESS`	No action needed
REJECTED	Refund could not be completed	The amount stays in your account. Request a new refund if it is still needed

Chargeback Limits

Refunds are accepted for up to 90 days after the cash in was received
The sum of all refunds cannot exceed the original amount
Only one refund can be in processing at a time for the same cash in
The account must have enough available balance at the moment of the request

Date Fields

Field	Description	Required
due_date	When payment should be made by	Optional
expiration_date	When QR code/copy-paste code expires	Optional
fine_date	When late fees start being charged	Optional

Important Rules:

expiration_date must be at least 1 day after due_date
fine_date must be at least 1 day after due_date
If expiration_date passes, payment cannot be made

Best Practices

Set Expiration Dates: Always set expiration_date to prevent stale QR codes
Include Debtor Info: Provide debtor_name and debtor_document for better tracking
Use Tags: Include tag field for internal reference/tracking
Base64 Images: Set base_64_image: false if you don't need the image in response
Monitor Webhooks: Set up webhooks to receive payment notifications in real-time instead of polling
Check Before Refunding: Read transaction_chargeback_value before requesting a new refund to know how much of the cash in is still refundable
Store the EndToEndId: It is the key that links the webhook, the cash in query and the chargeback together