Charges
Create and track charges and get payment receipts.
A charge specifies the amount a customer should pay your company. After creating it, track its status to check whether the customer paid. Creation alone does not confirm payment or available account balance.
The base URL for requests is https://api.raims.com.
Customer and environment
Use a customer already registered in the company and environment of the API key. To register the payer, see Create a customer. To look up an existing record, use Retrieve a customer.
Copy the customer's id to customer_id when creating the charge.
Do not send your own system's identifier in that field. Sandbox records
and charges are kept separate from Production data. Use Sandbox to test
without moving real funds.
Use Simulation to confirm a payment or apply a failure to a test charge. You can also test pending or failed issuance and cancellation, as well as boleto clearing before settlement. These endpoints are exclusive to Sandbox and let you check results without making a real payment.
To issue Pix when creating the charge, the linked customer must have a valid CPF/CNPJ. The API uses this record; do not send another tax ID in the charge request. The tax ID identifies the customer being charged without requiring payment from a bank account held by that person or business.
Create a charge
Create a new charge, with POST /v1/charges, accepts the
customer and charge amount. Send amount_cents as an integer in cents:
10000 represents R$ 100,00. The allowed amount ranges from 100 to
999999999999 cents.
Each request creates one charge. payment_method_types lets you define
a custom list of accepted methods that overrides the account default
for that charge only. Omitting the list or sending null keeps inheritance
from the checkout configuration. Platform availability still applies,
and a custom link configuration can reduce the charge's options.
payment_method is separate from the list and keeps the behavior for
choosing or restricting a method when the list is not provided. With a
custom list, omit this field or send 0. See formats and codes in
Payment methods.
Title and description are optional and accept up to 512 characters each.
Store the identifier returned by the API to associate the charge with your system. If a request ends without a conclusive response, check the result before repeating the request.
Receive Pix when creating a charge
In POST /v1/charges, send the customer_id of a registered customer
and payment_method: 1, without a custom list in payment_method_types.
Issuance uses the valid CPF/CNPJ in that record; do not send another tax ID,
name or email in the charge request. The response includes
payment_information.pix, with copy_paste, expires_at and qr_code_base64.
You can display this data in your system without sending the payer to
Raims checkout. Issuance does not confirm payment.
payment_information.pix_status shows the result: available when Pix
is available, pending while issuance has not been confirmed, failed
when it could not be issued and not_generated when no Pix issuance
is available. For failed, check payment_information.pix_error for the reason.
Display the QR Code and use the copy-and-paste code
When receiving Pix during creation with POST /v1/charges, the QR Code
is returned in payment_information.pix.qr_code_base64 as a Base64 PNG
image. To display it on a page, add the data:image/png;base64, prefix
before this value. copy_paste is the code to copy, and expires_at
shows expiration in Unix UTC seconds.
201 and 202 responses for Pix
If you receive 202, the charge already has an ID but Pix is not yet available.
Store that ID and look up the same charge in
Retrieve a charge. Do not create another charge
to track this issuance. The lookup returns the available data and current
status; looking it up does not issue another code.
If issuance remains pending or fails, contact support and provide the
charge ID. A 201 response confirms charge creation. Check
payment_information.pix_status and the payment data to see whether Pix
is available.
Pix at creation or in checkout
A list such as payment_method_types: [1] configures the accepted methods
but keeps issuance after checkout selection. To request Pix during
creation itself, use payment_method: 1.
Receive a boleto when creating a charge
In POST /v1/charges, send payment_method: 2, without a custom list in
payment_method_types. In customer_id, use the ID of a customer with a
name, valid email, valid CPF/CNPJ and address. The postal code is in
zip_code and the number in street_number in the customer record.
You do not need to send another payer or address in the charge request.
Email is required for issuance even with send_email: false; providing
it in the record does not request a message.
Raims looks up its postal code catalog to fill in missing street, neighborhood, city and state when this data is available. Existing address values are kept. The number must be in the record; it and the address complement do not come from the postal code. The complement is optional. If the postal code does not supply all required data, complete the address in Update an existing customer before issuing the boleto.
The address used for issuance does not change the customer record. This differs from completion when creating a customer: there, providing a number or complement prevents postal code completion. During boleto issuance, they can be filled in while Raims completes the other missing fields.
When the boleto is available, payment_information.boleto contains
line_digits, barcode and due_date. Use the payment line and barcode
in your system. The due date is in Unix UTC seconds and corresponds to
the boleto date. Issuing this data does not confirm payment. In Sandbox,
the boleto is simulated and must not be used for a real payment.
A list such as payment_method_types: [2] configures boleto in checkout,
with issuance after the payer's selection. To issue it during creation,
use payment_method: 2.
201 and 202 responses for boleto
payment_information.boleto_status shows available when data is
available, pending when issuance has not yet been confirmed, failed
when it could not be issued and not_generated when no issuance is
available or requested. boleto_error gives the reason for a pending
result or failure, when present.
A 201 response confirms charge creation; check boleto_status to see
whether the boleto was issued. For 202, store the ID and track the same
charge in Retrieve a charge. The lookup does not
repeat or renew issuance. If it remains pending or fails, contact support
with the charge ID without creating another charge to repeat issuance.
If customer data prevents creation, correct the record indicated by the error before resending the request. Confirmed issuance also does not mean the customer paid; track the charge's status.
Boleto payment progress appears in payment_information.boleto_payment_status:
awaiting_payment for an issued boleto awaiting payment, compensated
for a cleared payment awaiting settlement and settled for a settled
payment. Without available progress data, the field returns null.
Clearing does not yet mean available credit. To test these steps, see
Boleto clearing and settlement.
Reference in your system
Send the order or charge identifier in your system as external_reference,
for example PEDIDO-123. This field belongs to the charge and is separate
from the external reference registered on the customer.
The reference is optional. At creation, omitting the field, sending null,
empty text or only spaces leaves the charge without a reference. The API
removes leading and trailing spaces. The create, lookup and update responses
include external_reference, with the registered value or null.
You can change or remove the reference in
Update an existing charge. Omitting the field keeps
the current value; sending null, empty text or only spaces removes the
reference. This change does not change the Raims identifier or linked customer.
In GET /v1/charges, the external_reference filter searches for the full
current value of the charge's reference. The comparison is case-sensitive
and accent-sensitive. Keep the same value along with other filters when
navigating by cursor. A create or update may take a few seconds to appear
in this search; avoid continuous requests at short intervals.
The same reference can appear on more than one charge. Repeating this
reference alone does not make the API reuse a charge. Also store the
returned id to recognize each charge and check an inconclusive result
before trying again.
Additional integration data
Use metadata to store small pieces of information that associate the
charge with your system, such as a branch or sales channel. Customer and
charge data are separate: the customer's map is not copied to a new charge.
{
"metadata": {
"filial": "SP-01",
"canal": "site"
}
}The map accepts up to 32 keys, with names made up of unaccented letters, numbers, periods, hyphens or underscores and text values. Names are case-sensitive. Limits also apply to the complete map after an update. Do not store passwords, tokens, personal documents or other sensitive data.
If metadata is not provided at creation, the charge has an empty map.
During updates, the keys you send are added or replaced; other keys are
kept. Omitting metadata or sending {} keeps the data. Send null
as a key's value to remove it, or metadata: null to clear the map.
An empty string is a valid value and does not remove the key.
Create, update and lookup responses return metadata, with {} when
there are no values. This data does not change amount, due date or payment.
It cannot be used as list filters and is not automatically included in
webhook bodies. To search by your system's code, use external_reference.
You can update only metadata after a charge is paid or refunded.
If the same request also changes the title, description or external
reference, it follows the rules for those fields. When the state prevents
that edit, none of the request's fields are changed.
Due date
Provide the due date in due_date, in Unix UTC seconds. Choose a date
and time at least five minutes after the request reaches the API.
Account for transmission time when calculating that interval. The maximum
is the corresponding day ten years from today, in São Paulo time.
For Pix, the due date keeps the specified time. Boleto uses the São Paulo due date, including the same day. Charge and checkout expiration does not confirm cancellation of a boleto already issued. To stop receiving payments through that boleto, track confirmation of the charge revocation.
Checkout link and email requests
To receive checkout_url without sending an email, use create_checkout: true
when creating the charge and keep send_email: false. A return URL is
not required to receive the link. Use the returned address to send the payer
to that charge's checkout.
success_redirect_url and cancel_redirect_url configure the destinations
for returning from checkout to the company's website. success_redirect_url
is the destination after payment confirmation. cancel_redirect_url is the
destination of the option to return to the website; this navigation does
not revoke the charge.
Send complete HTTPS URLs of up to 2048 characters each on a company domain.
Do not use credentials in the URL, an IP address, localhost or a Raims domain.
The fields are optional: you can omit them, send null or leave them empty.
Fields containing only spaces also do not define a return URL.
Providing at least one of these URLs generates the link. Look up the charge
to confirm payment in your system even if the payer returned through
the success URL.
create_checkout and send_email are optional and use false when omitted.
Without these options and without return URLs, the request creates the
charge without generating a link or requesting an email; checkout_url
returns null.
Use send_email: true to request that the charge be emailed to the
customer's registered email. You also receive the link in checkout_url.
First check that the customer has a valid email. To obtain only the link,
use create_checkout: true with send_email: false.
This checkout belongs to a specific charge. To obtain or configure the link of a charge already created, use Payment links.
While the company awaits completion of its registration review, sending is restricted to the account holder's email. An email that is missing, invalid or different from the holder's email under that condition prevents creation with an email request. Outside that pending-registration restriction, a missing or invalid email does not prevent creating the charge and link, but no email is sent. Direct boleto issuance requires a valid email even without requesting a message. A successful request does not confirm email delivery or payment of the charge.
List charges
List charges, with GET /v1/charges, looks up records
in the company and environment of the key. Use filters for charge identifier,
external reference, customer, email registered on the charge, status,
registered payment method and creation, due date and payment intervals.
Changing the customer's email does not change the email already registered
on existing charges.
Use customer_id with the ID received when creating or looking up the
customer to list their charges. The link stays the same if the customer's
name or email changes. You can combine this filter with others. A valid
ID without accessible charges in the company and environment of the key
returns an empty list. Also keep customer_id when copying the cursor
to the next page.
Use external_reference to search for the charge reference's current value.
The comparison is exact, case-sensitive and accent-sensitive: PEDIDO-123
does not match pedido-123 or a fragment such as 123. You can combine
this filter with others; keep the same value when navigating by cursor.
A create or update may take a few seconds to appear in this search.
Avoid continuous requests at short intervals to try to speed up the update.
status and payment_method filters accept comma-separated codes.
For status, use the codes from 0 to 13 described in the endpoint.
The payment method filter codes are in
Payment methods.
The response contains list and page. Start without a cursor and process
the received charges. While page.has_next is true, copy
page.next_after to after in the next request, keeping the filters and
sorting. Copy the entire cursor without interpreting or calculating its
contents. A page accepts up to 100 charges and uses 10 when page_size
is not provided. The Listing and pagination
guide also explains how to go back with before. Send only one cursor per request.
created_gte and created_lte filter the creation date in Unix UTC seconds,
including the specified instants. By default, the newest records appear
first. sort_key accepts amount_cents or created_at; sort_order
accepts asc or desc, defaults to desc, and also lets you reverse
the default sorting direction. If you provide a creation interval without
choosing sort_key, the query sorts by created_at.
Use due_gte and due_lte to look up charges by due date in Unix UTC
seconds. The limits are inclusive: due_gte includes due dates from the
specified instant onward, and due_lte includes due dates up to that instant.
You can provide one limit or combine both; the end must be equal to or
later than the start. To query a full day, convert the start and end of
that day to UTC according to the time zone used in your system.
The interval uses the charge's due_date, including for paid charges.
Combine with status to select a specific condition, such as expired
charges. The due-date filter can be used with other filters and does
not change the chosen sorting. Keep all filters when using after or
before; to query another period, start again without a cursor.
Use paid_gte and paid_lte to find charges paid in a period. Values
are Unix UTC seconds and include both limits. The filter uses the charge's
original payment date, not creation, due date or funds availability date.
Charges without a payment date are excluded from this filter. A later
refund does not remove the charge from the period when it was paid;
combine with status to restrict its current condition. Payment confirmation
may take a few seconds to appear in the search. Keep the same filters
when navigating by cursor and avoid continuous requests to try to speed
up the update.
payment_method shows the charge's current method; payment_method_types
shows the configured custom list, or null for inheritance, without
representing the options available at that moment. checkout_payment_method
shows the method used to generate payment in checkout. If payment_method
was 0, generating Pix or boleto in checkout changes this value to 1
or 2, respectively. Simply selecting the checkout option does not
change the filter. See
Payment methods.
checkout_url returns an existing link or null. Listing charges does
not create a link or request an email. The returned status accounts for
the charge's due date. The status filter may take a few seconds to reflect
changes; avoid continuous requests at short intervals to try to speed
up this update.
Retrieve a charge
Retrieve a charge, with GET /v1/charges/{id},
looks up the record, status and payment data in one request. Use the
identifier received when creating or listing charges. The charge must
belong to the company and environment of the key.
payment_information.pix_status and payment_information.pix_error
show the Pix issuance result. For boleto, check boleto_status and
boleto_error in the same object. If creation returned 202, use the
same ID in this lookup. The response may remain pending; repeated
lookups do not restart issuance.
Use status to track the charge's condition and is_payable to check
whether it can accept payment. payment_method shows the charge's current
method; payment_method_types shows the configured custom list or
null for inheritance; checkout_payment_method shows the method used
to generate payment, or null before generation. Selecting an option
on screen does not confirm issuance or payment. When creating with
payment_method: 1, check payment_information.pix; with
payment_method: 2, check payment_information.boleto for the available data.
The payment_information object brings together the QR Code, Pix
copy-and-paste code and its expiration, or the data of a boleto already
issued. Pix and boleto can be issued during creation with the respective
payment_method or after checkout selection. Before issuance, a charge
can accept payment without Pix or boleto data. When no issuance is
available for the chosen method or the charge cannot accept payment,
the data is null. The record and status remain available, including
for paid, canceled or expired charges.
The lookup returns the existing checkout link or null. It does not
change the charge or generate or renew Pix, boleto or link. It also
does not request an email. Repeated lookups do not speed up issuance
or payment confirmation. The list shows a charge summary and status
without Pix and boleto data.
For counts, amounts and payment rate, see Charge statistics in Financial information.
Boleto PDF
Use Download a boleto, with
GET /v1/charges/{id}/boleto, to obtain the PDF of a boleto already issued.
The identifier is the charge's ID. You can attach the file to your system
or give it to the customer without opening checkout. The request requires
the API key for the same company and environment.
The download requires an issued boleto with the data needed to generate the file. You can obtain it while awaiting payment, during clearing and after settlement. A canceled or failed boleto or one without issuance data has no PDF available. Charge expiration alone does not confirm boleto cancellation.
If you receive BOLETO_DOCUMENT_NOT_AVAILABLE, look up the charge to
check boleto issuance and progress. Repeating the download does not
issue or renew the boleto or change its due date.
The endpoint returns JSON with url and expires_at. Make a GET request
to the complete url to download the PDF from files.raims.com without
sending Authorization or the API key in that download. expires_at
shows expiration in Unix UTC seconds; after that, call the authenticated
endpoint again. An invalid or expired link may receive HTTP 403 during
download without the API's JSON error envelope.
The URL can be reused until it expires and grants access to anyone who
has it. Share it only with authorized people and do not record it in logs.
The document contains boleto instructions and does not prove payment. In Sandbox, it is identified as a simulation and must not be used for payment. To document a confirmed payment, use the receipt described below.
Payment data and receipt
Use Look up payment data, with
GET /v1/charges/{id}/payment, to obtain confirmed payment data and display
it in your system. For the prepared document, use
Download a payment receipt, with
GET /v1/charges/{id}/receipt. The identifier is the charge's ID, with
the ch_ prefix.
The receipt is available for paid charges, partially refunded charges or charges with a dispute won by the company, as long as payment amount and date are recorded. If the document is unavailable, look up the charge to check its state before trying again.
The data lookup shows amount, payment method, date and registered details
of the payer and receiving company. The payer's name and tax ID are those
registered on the charge; they do not prove ownership of the bank account
that made the payment. Fields without available information may be null.
For Production Pix payments, end_to_end_id shows the receipt's bank
identifier when available. Use it to check the payment against the bank
receipt or in your system's reconciliation. The field is null when
there is no confirmed bank identification, for boleto payments and in
Sandbox. A null value does not undo payment confirmation. This identifier
differs from the charge's ch_ ID and the data used to initiate Pix.
The endpoint response is JSON with url and expires_at. Make the request
from your integration's server with the API key. Download the PDF from the
complete url at files.raims.com without sending the key in that download.
expires_at shows expiration in Unix UTC seconds. If the link expires,
call the authenticated endpoint again for another link. An invalid or
expired link may receive HTTP 403 during download without the API's
JSON error envelope.
The URL can be reused until it expires and grants access to anyone who
has it; share it only with authorized people and do not record it in logs.
The document is issued by Raims and does not replace a tax invoice or
bank payment receipt. In Sandbox, the data and receipt identify the payment
as simulated.
A partial refund does not change the payment receipt's original amount.
To document each completed refund, use the
refund receipt, with the rf_ identifier of the
corresponding request.
Update a charge
Update an existing charge, with
PATCH /v1/charges/{id}, changes the title, description, external reference
and metadata by public identifier. Send 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.
The metadata map follows the update by key
rules. See how to use external_reference in
Reference in your system.
Amount, due date and linked customer are defined at creation and cannot
be changed by this request. To charge another amount or use another due
date, revoke the eligible charge. Wait for revocation confirmation before
creating the replacement charge. The due date alone does not prevent
editing a charge that remains open. Paid, canceled, refunded charges or
charges in other final states do not allow these fields to be edited.
A request that changes only metadata remains allowed for an existing
charge; see Additional integration data.
If the state prevents editing, CHARGE_NOT_UPDATABLE shows the current
state and accepted states. Look up the charge before deciding how to
continue; editing does not change its financial state.
Editing keeps the identifier, status and payment data. It does not generate or renew Pix, boleto or checkout link or request an email.
Revoke a charge
Revoke a charge, with DELETE /v1/charges/{id},
cancels a charge that should no longer accept payment. Use the ID from
creation or lookup, in the same company and environment as the key.
In Sandbox, you can test revocation without moving real funds. To check tracking of a pending or failed cancellation, prepare the result in Simulation before sending the revocation request.
In Production, revocation depends on the charge's status and payment data already issued. For issued Pix, cancellation must be confirmed. For boleto, the request may remain pending until confirmation. Track the same charge through the individual lookup; an accepted request does not mean cancellation is complete. If you do not receive cancellation confirmation, look up the same charge before trying again.
A rejection with CHARGE_NOT_REVOCABLE shows the state or payment condition
that prevented the action. A boleto still being issued, a payment already
identified and a rejected cancellation require different follow-up actions.
Check the message and charge; revocation is not a way to request a refund.
The record and history remain available for lookup after revocation. Repeating the request for a charge already canceled in the same company and environment returns the same confirmation. To charge again, create another charge.
A paid Pix charge can follow the refund flow. Revocation does not refund, reimburse or return funds and does not request an email.
See the fields and responses in Create a new charge, List charges, Retrieve a charge, Update an existing charge and Revoke a charge. To prepare your integration credential, see Authentication.