Migration guides
Migrating from PagBank
If you collect from Brazilian students with PagBank (PagSeguro), most of your integration has a direct equivalent in Qualy. Amounts are in centavos in both, so they port as they are. The difference is that in Qualy one payment can be paid by card, PIX or boleto, and you can pay schools and partners from it.
Concept map
| PagBank | Qualy | Notes |
|---|---|---|
| Customer | Contact + the payer on the payment | tax_id (CPF/CNPJ) becomes payer.id.number. |
| Order | Payment intent | items[].unit_amount → items[].amount. reference_id → number. |
| Charge | Transaction | Each payment attempt or receipt is a transaction on the payment. |
| Checkout / payment link | Payment link | One-off per student, or reusable per service. |
Card charge (CREDIT_CARD, DEBIT_CARD) | Method PGBNK_CC on the payment portal | Qualy runs cards through PagBank. Card entry happens on the portal. |
| Parcelamento (installments) | Financing with gateway: "pagbank" | BRL, up to 18x. Quote and simulate before the payer chooses. |
| PIX / PIX Automático | AS_PIX / AS_PIX_AUTO | See PIX. |
| Boleto | AS_BOLETO | See Boleto. |
Refund (/charges/{id}/cancel) | Refund | — |
| Chargeback | Dispute | — |
notification_urls | Qualy webhooks | paymentIntents.update, transactions.create. |
An order, in Qualy
await fetch('https://api.pagseguro.com/orders', {
method: 'POST',
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
reference_id: 'MAT-2027-0042',
customer: { name: 'João Silva', email: 'joao@example.com', tax_id: '12345678901' },
items: [{ name: 'Matrícula', quantity: 1, unit_amount: 135000 }],
notification_urls: ['https://example.com/webhooks/pagbank'],
}),
});
const res = await fetch('https://api.qualyhq.com/v1/payment-intents/create', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'ApiKey your-api-key-here',
'X-TENANT-ID': 'your-tenant-id-here',
},
body: JSON.stringify({
intentType: 'ad-hoc',
number: 'MAT-2027-0042',
contact: 'joao@example.com',
currency: 'BRL',
items: [{ name: 'Matrícula', amount: 135000 }],
}),
});
const { data: payment } = await res.json();
console.log(payment.links.short); // card, PIX or boleto: the payer chooses
Webhooks are set once for your account (see Setting up webhooks), not per order.
Want your own checkout for PIX or boleto? Sign the method directly and show the QR code or slip yourself. CPF and address go on payer; if something's missing you get a 424 listing it. See Collecting payments.
Field differences
| PagBank | Qualy |
|---|---|
customer.tax_id | payer.id.number with payer.id.country: "BR" (digits only) |
phones[] (country, area, number) | One string in E.164: "+5511999999999" |
address.street / number / locality / region_code / postal_code | address.line1 / line2 / city / state / postalCode, plus country: "BR" |
amount.value, unit_amount | amount (both in centavos) |
reference_id | number on the payment (Qualy uses PagBank's reference_id itself) |
What doesn't carry over
- Saved cards. Payers enter their card again on their first Qualy payment.
- PagBank ids (orders, charges,
reference_id) stay in PagBank. - Open PIX and boleto charges. Let them be paid or expire in PagBank; issue new balances as Qualy payments.
- Checkout links. Recreate them as payment links.