Update an existing charge
Update the title, description and integration data of a charge.
Updates the title, description, external reference and metadata of an
existing charge. Use the identifier received when creating or looking up
the charge, in the authenticated company and environment.
Send only the fields you want to change. Omitted fields keep their current
value; for text fields, null or empty text clears the field you send.
An empty body ({}) keeps the data. Amount, due date and linked customer
remain as defined at creation.
The metadata map is updated by key. See how to add or remove values in
Additional integration data.
Editing is allowed for charges that remain open, including after their due date.
Paid, canceled, refunded charges or charges in other final states only
allow changes to metadata. If you mix this data with other fields in a
request rejected because of the state, nothing is changed.
See the editing and replacement rules in
Update a charge.
To associate the charge with your system, see
Reference in your system.
Path Params
The charge's public identifier in Raims, received when creating or listing charges.
Up to 100 characters
Headers
Unique key chosen by your system to identify this request. When retrying, send the same key and parameters. Without this header, the request is processed normally. See the idempotency guide for retention and handling pending or uncertain responses.
1 to 255 characters
Body Params
Applying an example replaces the body fields.
Charge title. Omit it to keep the current title; send null or empty text to remove it.
Up to 512 characters
Charge description. Omit it to keep the current description; send null or empty text to remove it.
Up to 512 characters
Order or charge reference in your system. Omit it to keep the current value; send null or empty text to remove it. It can be repeated on other charges and is separate from the customer reference.
Up to 120 characters
Integration data associated with the resource. Provide key and text pairs. Keys are case-sensitive. Omitting it or sending {} keeps the data; null removes all pairs, and null for a key removes only that key. Empty text is a valid value.
Up to 32 entries, Keys: up to 40 characters, Values: up to 500 characters, JSON: up to 8192 UTF-8 bytes
Responses
Response Body
Charge updated. Omitted fields keep their current contents; null or empty text clears them. Sending {} returns the charge unchanged. Editing is allowed for open charges, including after the due date.
Public charge identifier.
Public identifier of the linked customer.
Charge amount in Brazilian real cents.
Charge payment method: 0 undefined, 1 Pix, 2 boleto, 3 credit card and 4 debit card. The value 0 may change to 1 or 2 when Pix or boleto is generated in checkout. Checkout selection appears separately in checkout_payment_method.
Payment method reported by checkout: 0 undefined, 1 Pix, 2 boleto, 3 credit card and 4 debit card. null when this information is not yet available. Selecting an option on screen does not confirm payment generation or that the charge was paid.
Charge due date in Unix UTC seconds.
Charge title, or null when not provided.
Charge description, or null when not provided.
Charge status, accounting for the due date. 0 created, 1 awaiting payment, 2 authorized, 3 processing, 4 paid, 5 partially refunded, 6 refunded, 7 canceled, 8 expired, 9 failed, 10 chargeback, 11 chargeback under review, 12 chargeback lost and 13 chargeback won.
Creation time in Unix UTC seconds.
Link for the payer to open checkout, or null when no link is available.
Indicates whether the charge can be paid. Pix or boleto data may still be missing in payment_information; check status to track payment.
Payment instructions and Pix or boleto issuance result. pix and boleto are null when data is unavailable.
Pix payment data, or null when unavailable.
Pix copy-and-paste code to pay the charge.
Pix code expiration in Unix UTC seconds.
Base64 PNG image of the QR Code without a data URI prefix. To display it in a browser, add data:image/png;base64, before the value.
Boleto payment data, or null when unavailable.
47-digit payment line of the issued boleto.
44-digit barcode of the issued boleto.
Boleto due date in Unix UTC seconds.
Pix issuance result: not_generated when no issuance is available or requested; available when data is available; pending while there is no confirmed result; failed when issuance was unsuccessful.
Reason for pending or failed Pix issuance, or null. Store the charge ID and use the individual lookup to track it. If the condition persists, contact support; do not repeat creation to try to issue Pix.
Stable error code.
Error explanation in English. For validation errors, it summarizes the category; details identify the corrections. Use the codes to handle the response.
Invalid fields or references submitted in the body, with the field, code and explanation. Omitted for general errors and when there is no field correction to indicate.
Public name of the JSON field, query parameter, path parameter or header related to the error. Nested fields and lists retain their path and index. $ represents the root of the JSON body.
Reason for the field error, such as REQUIRED, INVALID_TAXID, UNKNOWN_FIELD, DUPLICATE_FIELD or INVALID_TYPE.
Explanation in English of the problem with this field or parameter and the available correction. Do not use the text to determine your integration flow.
Boleto issuance result: not_generated when no issuance is available or requested; available when data is available; pending while there is no confirmed result; failed when issuance was unsuccessful.
Reason for pending or failed boleto issuance, or null. Store the charge ID and use the individual lookup to track it. If the condition persists, contact support; do not repeat creation to try to issue the boleto.
Stable error code.
Error explanation in English. For validation errors, it summarizes the category; details identify the corrections. Use the codes to handle the response.
Invalid fields or references submitted in the body, with the field, code and explanation. Omitted for general errors and when there is no field correction to indicate.
Public name of the JSON field, query parameter, path parameter or header related to the error. Nested fields and lists retain their path and index. $ represents the root of the JSON body.
Reason for the field error, such as REQUIRED, INVALID_TAXID, UNKNOWN_FIELD, DUPLICATE_FIELD or INVALID_TYPE.
Explanation in English of the problem with this field or parameter and the available correction. Do not use the text to determine your integration flow.
Boleto payment progress: awaiting_payment awaits payment, compensated awaits settlement and settled confirms settlement. Null when no progress data is available. Clearing does not yet mean available credit.
List of payment methods configured for the charge, or null when it uses the inherited checkout configuration. 1 means Pix and 2 means boleto. The list does not change with the method used for payment and does not represent current checkout availability.
Order or charge reference in your system, or null when not provided. It is separate from the customer reference and can be repeated on other charges.
Integration data associated with the resource. Returns {} when there are no values. This map is not used as a search filter or automatically included in webhook events.
Response Body
Invalid JSON, identifier, or fields. Check error.details for the field, code, and message explaining the correction.
Code and explanation of the error returned by the API.
Stable error code.
Error explanation in English. For validation errors, it summarizes the category; details identify the corrections. Use the codes to handle the response.
Invalid fields or references submitted in the body, with the field, code and explanation. Omitted for general errors and when there is no field correction to indicate.
Public name of the JSON field, query parameter, path parameter or header related to the error. Nested fields and lists retain their path and index. $ represents the root of the JSON body.
Reason for the field error, such as REQUIRED, INVALID_TAXID, UNKNOWN_FIELD, DUPLICATE_FIELD or INVALID_TYPE.
Explanation in English of the problem with this field or parameter and the available correction. Do not use the text to determine your integration flow.
Response Body
No charge was found for the specified id in the authenticated company and environment. Check the identifier.
Code and explanation of the error returned by the API.
Stable error code.
Error explanation in English. For validation errors, it summarizes the category; details identify the corrections. Use the codes to handle the response.
Invalid fields or references submitted in the body, with the field, code and explanation. Omitted for general errors and when there is no field correction to indicate.
Public name of the JSON field, query parameter, path parameter or header related to the error. Nested fields and lists retain their path and index. $ represents the root of the JSON body.
Reason for the field error, such as REQUIRED, INVALID_TAXID, UNKNOWN_FIELD, DUPLICATE_FIELD or INVALID_TYPE.
Explanation in English of the problem with this field or parameter and the available correction. Do not use the text to determine your integration flow.
Response Body
The charge's state prevents changing its title, description, or external reference, or another request is in progress. A request that changes only metadata can update a finalized charge. If fields are sent together and a change is blocked, no changes are applied. Retrieve the charge before trying again.
Code and explanation of the error returned by the API.
Stable error code.
Error explanation in English. For validation errors, it summarizes the category; details identify the corrections. Use the codes to handle the response.
Invalid fields or references submitted in the body, with the field, code and explanation. Omitted for general errors and when there is no field correction to indicate.
Public name of the JSON field, query parameter, path parameter or header related to the error. Nested fields and lists retain their path and index. $ represents the root of the JSON body.
Reason for the field error, such as REQUIRED, INVALID_TAXID, UNKNOWN_FIELD, DUPLICATE_FIELD or INVALID_TYPE.
Explanation in English of the problem with this field or parameter and the available correction. Do not use the text to determine your integration flow.
For common errors, see HTTP response codes.