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
Field
Description
Type
id
Unique identifier (UUID)
String
bill_id
Identifier of the bill this payment is associated with
String
status
Payment status. Can be unpaid, failed, refused, paid, refunded, or chargedback
String
payment_method
Payment method used. Can be boleto, debit_card, credit_card, or pix
String
amount_cents
Total amount in cents for this payment
Integer
paid_amount_cents
Total amount actually paid in cents
Integer
refunded_amount_cents
Total amount refunded in cents
Integer
paid_at
Timestamp indicating when the payment was successfully paid in ISO8601 format
String
refunded_at
Timestamp indicating when the payment was refunded in ISO8601 format
String
installments
Number of installments for this payment (always 1 for boleto and PIX)
Integer
barcode
Boleto barcode number or PIX QR code string
String
barcode_image_url
URL to access the barcode or QR code image. null for credit_card payments and for refused or failed payments
String
url
Checkout page of the payment’s bill (<checkout host>/parcela/pagamento?bill_id=<bill_id>). For the boleto PDF, use download boleto
String
expires_at
Timestamp indicating when the payment will expire in ISO8601 format
String
refused_reason
Code indicating the reason for payment refusal. Always present; null unless status is refused. See the values below
String
refused_reason_description
Human-readable description of why the payment was refused
String
created_at
Indicates when the record was created in ISO8601 format
String
Payment Status Values
Status
Description
unpaid
The payment has been created but not yet paid
failed
The payment attempt failed due to technical issues or processing errors
refused
The payment was refused by the payment gateway or bank. Check refused_reason for details
paid
The payment was successfully processed and the amount has been received
refunded
The payment was refunded to the customer
chargedback
The payment was charged back (disputed by the customer and reversed)
Payment Method Values
Method
Description
boleto
Brazilian bank slip payment method (boleto bancário)