Skip to main content

Introduction

Postpaid Card​

The APIs for postpaid card issuance offer QI Tech partners a simple and efficient way to allow their clients to request and issue Postpaid Cards, both physical and virtual.

At QI Tech, we provide our partners the opportunity to become sub-issuers. Through our APIs, they can offer their own clients the possibility to issue postpaid cards, creating a complete solution for banking and financial services.

To better understand our system, we present an overview of how the postpaid card ecosystem works. However, it's important to note that, as with all our APIs, service activation must be performed with our team, and calls are authenticated.

The postpaid card is a card linked to a credit line that allows the holder to make transactions, with payment being made later. Unlike prepaid cards, postpaid cards do not require the account balance to be pre-loaded. The user can make purchases and pay later, according to the approved credit limit.

Transactions made through the postpaid card will be charged on the holder's invoice, with a specific deadline for payment. If payment is not made by the due date, the holder may be subject to financial charges, such as interest and fees.

Program​

To issue a postpaid card, the partner needs to have a program configured in the integration with QI Tech. The program defines the rules and parameters necessary for card issuance in compliance with card brands, such as VISA.

Here are some important information about the program:

  • Program type - Refers to the card usage modality. In this case, it's the Postpaid modality.
  • Card brand - We use the VISA brand for issued cards.
  • Card layout - Refers to the card design, both for the physical and virtual model, which will be displayed in the graphical interface.
Attention

To configure a new postpaid card program, it's necessary to involve QI Tech's commercial and implementation teams.

Wallet​

To issue postpaid credit cards, it's necessary to first create a wallet that organizes the client's invoice. The wallet functions as an "account" where all cards and billing configurations are stored.

What is a Wallet

The wallet is like the client's account where all cards and invoices are stored:

  • One wallet = invoice: Each wallet corresponds to the invoice of a specific client (identified by CPF/CNPJ)
  • Multiple payment methods: The same wallet can have different payment instruments (cards, PIX, etc.)
  • Separate instruments: After creating the wallet, it will be necessary to separately create the payment instruments (credit cards, limits, etc.)
  • Centralized management: The wallet centralizes all operations and configurations related to that client

For more details on wallet creation, consult the complete wallet creation documentation.

Issuance Flow​

To issue postpaid credit cards, the process follows a logical sequence that begins with creating a wallet for the client. This wallet functions as an "account" to organize all cards and billing configurations.

After creating the wallet, it's necessary to create a payment instrument of type postpaid_card. This instrument is responsible for managing all transactions and purchases made with the card. When creating the instrument, a physical or virtual card is automatically created as requested.

Payment Instrument

The payment instrument of type postpaid_card:

  • Centralizes transactions: All purchases made with the card are linked to this instrument for management
  • Automatically creates the card: When creating the instrument, a physical or virtual card is automatically created as requested
  • Manages lifecycle: Monitoring the status and operations of the card is done through the postpaid card management endpoints

To create the payment instrument, consult the PaymentInstrument creation documentation.

Limit Configuration​

The wallet has a global credit limit that defines the maximum ceiling available for use. Individual limits for payment instruments can also be configured.

How Limits Work
  • Wallet limit: Defines the maximum credit ceiling available for use
  • Instrument limits: Each instrument can have its own configured limit, as long as it's smaller than the wallet's
  • Practical example: A wallet with a R$ 100 limit can have two instruments with limits of R$ 100 and R$ 80, but when the usage of both instruments reaches R$ 100, no more purchases will be possible
  • Real-time validation: Both the instrument limit and wallet limit are validated before allowing a new transaction
Limits in Payroll Wallets

Wallets of type payroll have two distinct limits:

  • postpaid_credit_limit: Postpaid credit limit for purchases and transactions with the card
  • payroll_withdraw_limit: Specific limit for payroll withdrawals (salary/benefit), which are automatically deducted from the client's payroll

Both limits appear in the wallet_limits list of the wallet and function independently, allowing the client to have one limit for card purchases and another specific limit for benefit withdrawals.

Card Management and Monitoring​

With the wallet and payment instrument configured, the card (physical or virtual) is automatically created and becomes available for use. The wallet centralizes all billing information, allowing monitoring of transactions, payments, and interest and penalty configurations.

Monitoring the card's status and lifecycle can be performed through the postpaid card management endpoints, which allow monitoring all stages of the card's lifecycle, from creation to write-off or cancellation.

Wallet Entries​

Wallet entries are debts that are registered in the client's wallet. These debts can be of different types:

  • Revolving credit (revolving_credit): Credit amounts made available to the client
  • Payroll withdrawal (payroll_withdraw): Debt generated by withdrawal of the limit that will be deducted monthly from INSS
  • Payroll overdue (payroll_overdue): Debt generated by non-payment of the invoice that will also be deducted monthly from INSS
How Wallet Entries Work
  • One entry = one debt: Each entry is a specific debt
  • Becomes item in invoice: Each installment automatically becomes an item in the invoice
  • Organized in invoice: Items are organized in invoices
  • Everything centralized: All debts are organized in the wallet

For more information and consultation of wallet entries, consult the Wallet Entries documentation.

Wallet Entry Webhooks

To monitor wallet entry status changes in real time, use the Wallet Entry webhooks.

Payment Instrument Entries​

Payment instrument entries are transactions made with the card. Each purchase or withdrawal becomes an entry:

  • Card transactions: Purchases made with the postpaid card
  • Card withdrawals: Withdrawals made with the postpaid card
  • Other operations: Other transactions related to the instrument
How Payment Instrument Entries Work
  • Automatic linking: Each entry is automatically linked to an invoice item
  • Invoice organization: Invoice items are organized in invoices
  • Automatic invoice creation: When a new transaction is created, the system automatically creates the necessary invoices to accommodate all transaction installments, based on the wallet's closure configuration
Important about Cancellations
  • Open invoices: Cancellations in open invoices immediately free up the limit and remove the amount from the invoice
  • Closed invoices: Cancellations in closed invoices create chargebacks that will appear in the invoice_payments_chargebacks field and will be used in the next invoice

For more information and consultation of payment instrument entries, consult the Payment Instrument Entries documentation.

Payment Instrument Entry Webhooks

To monitor payment instrument entry status changes in real time, use the Payment Instrument Entry webhooks.

Invoices​

Invoices are created automatically as needed for invoice items. They function as containers that group related items:

  • Automatic creation: They are created automatically when necessary, based on the wallet's closure configuration
  • Initial status: All start with status opened
  • Receives new items: New purchases and transactions go to open invoices
  • Automatic closure: Invoices are automatically closed one day after their closure date
Invoice Lifecycle
  • opened: Open invoice, receiving new items. In this status, new invoice items can be added to the invoice
  • closed: Closed invoice, no longer receives items. In this status, the invoice has been processed and the invoice slip is updated with the new amount and due date. The slip can be consulted through the slip endpoints
  • processing_payment: Awaiting payment. Applied only for payroll type wallets when there is only remaining amount to be paid with the benefit after payroll deduction
Payroll Wallets

For payroll type wallets, closure works in a special way:

  • Payroll deduction: INSS deduction amounts are grouped in an invoice payment of type payroll_discount that will be automatically deducted from payroll. This payment is created with status processing_payment when the deduction is requested from INSS and changes to paid when the deduction payment is made
  • Updated slip: When there is remaining amount after payroll deduction, the invoice slip is updated with the new amount. The slip can be consulted, but the invoice payment of type bank_slip will only be created when the slip is effectively paid
  • Processing_payment status: If there is no amount to be paid via slip, the invoice remains with status processing_payment until the benefit payment is made

For more information and consultation of invoices, consult the Invoices documentation.

Invoice Items​

Invoice items are automatically created for each installment of entries (wallet entry or payment instrument entry). They represent the individual components that make up an invoice:

  • Debt installments: Each installment of a wallet entry generates an invoice item
  • Individual transactions: Each installment of a payment instrument entry generates an invoice item
  • Invoice breakdown: Allow granular control of each item
Invoice Item Characteristics
  • Mandatory linking: Every invoice item must be linked to an invoice
  • Traceability: Maintain reference to the original entry
  • Individual status: Each item can have its own status (pending, paid, canceled)
  • Detailed values: Contain specific information such as amount, limit used, and amount paid

For more information and consultation of invoice items, consult the Invoice Items documentation.