Payment Overview

A Payment represents a payment transaction for a bill. It can be paid via PIX, boleto (bank slip), debit card, or credit card. Each payment tracks the transaction status, amounts, and payment method details.

Payment Schema

FieldDescriptionType
idUnique identifier (UUID)String
bill_idIdentifier of the bill this payment is associated withString
statusPayment status. Can be unpaid, failed, refused, paid, refunded, or chargedbackString
payment_methodPayment method used. Can be boleto, debit_card, credit_card, or pixString
amount_centsTotal amount in cents for this paymentInteger
paid_amount_centsTotal amount actually paid in centsInteger
refunded_amount_centsTotal amount refunded in centsInteger
paid_atTimestamp indicating when the payment was successfully paid in ISO8601 formatString
refunded_atTimestamp indicating when the payment was refunded in ISO8601 formatString
installmentsNumber of installments for this payment (always 1 for boleto and PIX)Integer
barcodeBoleto barcode number or PIX QR code stringString
barcode_image_urlURL to access the barcode or QR code image. null for credit_card payments and for refused or failed paymentsString
urlCheckout page of the payment’s bill (<checkout host>/parcela/pagamento?bill_id=<bill_id>). For the boleto PDF, use download boletoString
expires_atTimestamp indicating when the payment will expire in ISO8601 formatString
refused_reasonCode indicating the reason for payment refusal. Always present; null unless status is refused. See the values belowString
refused_reason_descriptionHuman-readable description of why the payment was refusedString
created_atIndicates when the record was created in ISO8601 formatString

Payment Status Values

StatusDescription
unpaidThe payment has been created but not yet paid
failedThe payment attempt failed due to technical issues or processing errors
refusedThe payment was refused by the payment gateway or bank. Check refused_reason for details
paidThe payment was successfully processed and the amount has been received
refundedThe payment was refunded to the customer
chargedbackThe payment was charged back (disputed by the customer and reversed)

Payment Method Values

MethodDescription
boletoBrazilian bank slip payment method (boleto bancário)
debit_cardDebit card payment
credit_cardCredit card payment (supports multiple installments)
pixBrazilian instant payment system

Refused Reason Values

unauthorized_by_bank, expiration_date, card_restricted, incompatible_modality, invalid_number, inexistent_account, unsupported_operation, insufficient_funds, unsupported_brand, withdrawal_limit_exceeded, security_block, withdrawal_count_exceeded, blocked_card, lost_or_stolen_card, closed_account, defaulting_card, account_restricted, suspected_fraud, confirmed_fraud, lost_card, stolen_card, invalid_transaction, double_transmission, refused_by_bank, exceeded_retry_limit, invalid_card, invalid_cvv, invalid_pin, expired_pin, invalid_data, invalid_installment, issuer_unavailable, unknown, account_not_found, invalid_amount, bank_error, provider_error, antifraud, acquirer, invalid_capture_amount, pin_attempts_exceeded, authentication_error, other, waiting