Financing & installments

Financing lets a contact pay over time instead of all at once. Qualy supports two financing providers: PagBank for Brazilian credit-card installments (parcelamento), and Klarna for pay-later and pay-over-time options in supported regions.

Working with financing is a two-step flow:

1. Retrieve options — find out which financing types are available for an amount or Payment Intent, and the maximum number of installments.
2. Simulate a plan — pick a number of installments and get the exact per-installment amount, the total with interest, and the fees.

Gateways & methods

Each request must name the gateway and its financing method. The valid combinations are:

Retrieving financing options

Call POST /v1/payment-gateways/financing/options to see what is available. You can describe the amount in one of two ways:

• Pass a paymentIntent ID — Qualy uses the Payment Intent's outstanding due amount.
• Pass an amount and currency directly — useful before a Payment Intent exists (e.g. on a checkout page).

Request fields

Example (PagBank)

try {
  const response = await fetch(
    'https://api.qualyhq.com/v1/payment-gateways/financing/options',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'ApiKey your-api-key-here',
        'X-TENANT-ID': 'your-tenant-id-here',
      },
      body: JSON.stringify({
        gateway: 'pagbank',
        method: 'PGBNK_CC',
        amount: 135000, // R$ 1,350.00
        currency: 'BRL',
      }),
    }
  );

  const { data } = await response.json();
  console.log(data.options);
} catch (error) {
  console.error(error);
}

The response lists the available financing types. For PagBank, nInstallments is the maximum number of installments the buyer can choose from (1 up to this value):

{
  "data": {
    "options": [
      {
        "type": "installments",
        "amount": 135000,
        "currency": "BRL",
        "nInstallments": 12
      }
    ]
  }
}

Example (Klarna)

try {
  const response = await fetch(
    'https://api.qualyhq.com/v1/payment-gateways/financing/options',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'ApiKey your-api-key-here',
        'X-TENANT-ID': 'your-tenant-id-here',
      },
      body: JSON.stringify({
        gateway: 'klarna',
        method: 'KLARNA_PYMT',
        paymentIntent: '6634f56c7dbbc16e07b5025e',
      }),
    }
  );

  const { data } = await response.json();
  console.log(data.options);
} catch (error) {
  console.error(error);
}

Klarna returns one entry per available category. pay-later settles the full amount on a later date; installments splits it into four payments:

{
  "data": {
    "options": [
      { "type": "pay-later", "amount": 135000, "currency": "AUD" },
      { "type": "installments", "amount": 135000, "currency": "AUD", "nInstallments": 4 }
    ]
  }
}

Option fields

Simulating a plan

Once you know the maximum number of installments, call POST /v1/payment-gateways/financing/simulate with a specific nInstallments to get the exact cost breakdown.

Each simulation is persisted and returns an _id. Keep this ID — it is the reference to the chosen plan and appears on the resulting transaction's financing details.

Request fields

Same as the options endpoint, plus a required nInstallments:

Example

try {
  const response = await fetch(
    'https://api.qualyhq.com/v1/payment-gateways/financing/simulate',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'ApiKey your-api-key-here',
        'X-TENANT-ID': 'your-tenant-id-here',
      },
      body: JSON.stringify({
        gateway: 'pagbank',
        method: 'PGBNK_CC',
        amount: 135000, // R$ 1,350.00
        currency: 'BRL',
        nInstallments: 12,
      }),
    }
  );

  const { data } = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

Response

{
  "data": {
    "_id": "6634f8a17dbbc16e07b50312",
    "total": 153090,
    "currency": "BRL",
    "method": "PGBNK_CC",
    "nInstallments": 12,
    "installmentAmount": 12758,
    "feePercentage": 0.1340,
    "interestRate": 0.1182
  }
}

Partial amounts

When financing against a Payment Intent, you can finance less than the full due by also passing an amount (in cents). Qualy clamps it to the outstanding amount so the contact is never overcharged. Omit amount to finance the full balance.

Cross-currency financing

A Payment Intent can be denominated in one currency (say AUD) while the contact pays in another. PagBank financing always settles in BRL, so when you finance an AUD Payment Intent:

• The Payment Intent's settlement currency must resolve to BRL.
• A locked FX quote must exist on the Payment Intent — Qualy converts the due to BRL at that rate before building the plan.

If the settlement currency is not BRL, or no FX quote is available, the request is rejected. See Collecting payments for how settlement currency is determined.

Next steps

After simulating a plan, collect the payment using the chosen financing method. See Collecting payments for the sign flow, and Setting up webhooks to be notified when each installment is captured.