# Migrating from PagBank

> Migrate from the PagBank / PagSeguro API to Qualy: orders, charges, PIX, boleto, card parcelamento, refunds and notification webhooks mapped to Qualy, with code and field mappings.

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](https://v1-spec.qualyhq.com/#post-/v1/contacts/create) + the `payer` on the payment | `tax_id` (CPF/CNPJ) becomes `payer.id.number`. |
| Order | [Payment intent](/docs/guides/creating-payment-intents.md) | `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](/docs/guides/payment-links.md) | 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](/docs/guides/financing-options.md) 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](/docs/guides/collecting-payments.md#pix-brazil). |
| Boleto | `AS_BOLETO` | See [Boleto](/docs/guides/collecting-payments.md#boleto-brazil). |
| Refund (`/charges/{id}/cancel`) | [Refund](/docs/guides/issuing-transaction-refunds.md) | — |
| Chargeback | [Dispute](/docs/guides/handling-disputes.md) | — |
| `notification_urls` | [Qualy webhooks](/docs/webhooks/events.md) | `paymentIntents.update`, `transactions.create`. |

---

## An order, in Qualy

**PagBank**

```javascript
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'],
  }),
});
```

**Qualy (JavaScript)**

```javascript
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](/docs/webhooks.md)), 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](/docs/guides/collecting-payments.md#via-api-direct).

---

## 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](/docs/guides/payment-links.md).