Liqfy Integration Guide

Welcome. This guide is everything you need to accept payments through Liqfy — from your first API call to receiving signed webhooks in production.

#What Liqfy gives you

Liqfy is a Pix-first payment gateway. You create a Cobrança (charge) through a single canonical API and we route it to the right PSP/adquirente behind the scenes; the response gives you a BR Code and QR Code ready to render in your checkout. Card, MB WAY, Multibanco and crypto rails exist on the same account when enabled, but PIX is the entry point for every new integration.

Your application never talks to the PSP directly, never holds card data, and never has to change when we add or rotate underlying providers — the provider field and any PSP identifier are stripped by the serializer before the response reaches you (see API conventions §3).

text

┌────────────┐               ┌──────────┐                ┌─────────────┐
│            │ POST /charges │          │   routing      │  PSP/       │
│  Your app  ├──────────────▶│  Liqfy   ├───────────────▶│  adquirente │
│            │◀──────────────┤          │◀───────────────┤  (interno)  │
└──────┬─────┘  BR Code / QR └────┬─────┘   status       └─────────────┘
       │                          │
       │     signed webhook       │
       │◀─────────────────────────┘
       │   charge.paid
       ▼
   Order fulfilled

#Supported payment methods

Method	Region	Flow	Typical settlement
`PIX`	Brazil	QR code + copy-paste	Instant (seconds)
`CREDIT_CARD`	Global	Hosted redirect (3DS)	D+1 to D+30
`MBWAY`	Portugal	Push to phone + poll	Same day
`MULTIBANCO`	Portugal	Entity / Reference	1–3 business days
`BOLETO`	Brazil	Barcode + PDF	1–3 business days

PIX is the primary rail for Brazilian merchants and the flow every new integration should start with.

Availability is per account. The methods above are enabled individually for your account — a method you have not been enabled for is rejected at charge creation, not at checkout. Ask your Liqfy contact which rails are active before building against one.

#Read these in order

Getting Started — Auth, environments, conventions, your first call
PIX — End-to-end PIX flow with code samples
Webhooks — Register endpoints, verify signatures, handle retries
Errors — Error shape, status code map, retry strategies
API Reference — Every endpoint, every field, every status

Once you have PIX working end-to-end with webhooks, the other methods are tiny variations of the same flow:

Receiving payments is half the system. The other half is moving balance out:

Payouts / Withdrawals — PIX out, TED, Crypto (Saque)
Disputes and MED — Pix chargeback (BACEN MED): hold, disputes panel, appeal and outcomes

Operating your account:

API Keys — Issue, list, rotate, and revoke keys via dashboard or HTTP API

#The contract you build against

This guide documents the Liqfy v1 public contract: the apikey header with lq_test_* / lq_live_* keys, POST /v1/charges returning a ch_… id, and X-Liqfy-* webhook headers. That is the surface — there is nothing older you need to know about.

A couple of resource paths are worth noting: payouts live at /v1/withdrawals, and your balance at /v1/wallets. Should a canonical /v1/payouts alias land later, the current path keeps working and ships Deprecation / Sunset headers well before any removal.

#Coming soon

Sandbox environment — isolated test environment with deterministic outcomes (force PAID / REFUSED / EXPIRED) and a webhook simulator. (Planned — the document describes the proposed scope, not something you can use yet.)

#Need help?

Email integrations@liqfy.com.br with your request_id — every API error carries one, and it locates the exact request in our logs.