Skip to main content

Payment Methods

Each billing account can have multiple stored payment methods. One of them is marked as the default for automatic charges.

Supported Types​

TypeDescriptionAutomatic Charge
cardCredit/debit cardYes
bank_slipBoleto bancarioNo
pixPIX (instant transfer)No
bank_transferBank transferNo

Note: Only credit card supports automatic charging (charge_automatically).

Credit Card​

Stored Data​

  • Brand (Visa, Mastercard, Elo, Amex, Hipercard)
  • First 6 digits (BIN)
  • Last 4 digits
  • Cardholder name
  • Expiration month and year
  • Fingerprint (unique card identifier at the gateway)

Tokenization​

The card is tokenized on the client side via the gateway SDK and stored securely:

  1. Customer submits card data through the gateway form
  2. Gateway returns a temporary card token (sent to the API as card_token)
  3. The server uses the token to create the customer and card at the gateway (Pagar.me)
  4. Only gateway tokens and masked data are stored

Expiration Monitoring​

The system automatically checks for cards expiring within the next 30 days and can send proactive notifications to the customer.

Boleto (bank_slip)​

  • Generated for each individual charge
  • Includes barcode and URL for PDF download
  • Configurable payment deadline (default: 3 days)
  • Confirmation via gateway webhook when paid

PIX​

  • QR Code generated for each charge
  • EMV format with PNG/base64 image
  • Default expiration: 30 minutes
  • Real-time confirmation via webhook

Bank Transfer (bank_transfer)​

Stored data:

  • Bank code, bank name
  • Branch and account number
  • Type: checking or savings
  • Account holder name and document

Confirmation is manual — the operator must verify receipt.

Default Method​

  • Each billing account has one default method
  • The first method created is automatically set as default
  • When the default method is removed, the next active method is promoted

Removal​

When removing a payment method:

  • Validates that there are no pending/processing payments with this method
  • For cards: deletes the card from the gateway
  • If it was the default: reassigns to another active method
  • Status changes to removed