Create Charge
POST - https://dominio.com.br/api/charges/
The Create a Charge endpoint in the ENV Bank API allows users to generate and initiate a new financial charge.
⚠️Attention
From 10/01/2024, it will be mandatory to include the following parameters when using the Create Charge endpoint:
debtor_name (string, required): Full name of the payer.
debtor_document_number (string, mandatory): CPF or CNPJ of the payer.
These new parameters aim to increase security and ensure compliance with financial regulations. Therefore, all charge creation requests made after this date must include this information.
🚧 HEADERS
Authorization (string, required): The access token generated by the authentication endpoint must be included in the authorization header in the format Bearer .
✅ Charge Status
PENDING: The charge has been created and is awaiting payment from the customer.
PAID: The charge has been successfully paid by the customer.
REFUNDED: The transaction has been refunded to the customer.
FAILED: The charge was failed because payer is in “receiver blocklist”. Anti-Fraud reasons.
EXPIRED: The charge was not paid within the validity period and has expired, becoming invalid.
🟢 How to Create a txid
The TXID must be unique for each transaction to avoid conflicts. A good practice is to generate a TXID by combining a specific prefix (such as "TX" for transactions) with a programmatically generated unique identifier, such as a random alphanumeric code.
To create a TXID, follow these steps:
Choose a Prefix: Use a prefix that clearly identifies the nature of the identifier, for example, "TX" for transactions.
Generate a Unique Identifier: Combine the prefix with a programmatically generated unique identifier. This identifier should be alphanumeric, between 26 and 35 characters long, and must not contain special characters, periods, spaces, dashes, slashes, etc. In other words, it should consist of letters and numbers only.
➡️ Practical Tips
Parameter Validation: Ensure that the txid, amount, and expiration parameters are valid and meet the endpoint requirements before sending the request.
Testing: Perform testing in a sandbox environment before using the endpoint in production to ensure the integration is working correctly.
Expiration: is the charge expiration time in seconds. This parameter defines how long the charge will be valid before expir
Body Params
amount float required Charge amount
TXID string required
Between 26 and 35 characters. It's not allowed special characters. Only letters and numbers are accepted.
Example: TX202312012030iwQzTdpUeDUr1
expiration int32 required Defaults to 300
Charge expiration in seconds.
debtor_name string required
Debtor's name. (Payer's name)
debtor_document_number string required
Debtor's CPF or CNPJ. (Payer's CPF or CNPJ)
Exemplo:
curl --request POST \
--url https://dominio.com.br/api/charges/ \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--data '
{
"amount": 0.01,
"txid": "TX202212012030iwQzTdpUeDUr1",
"expiration": 300,
"debtor_name": "NOME_PAGADOR",
"debtor_document_number": "DOCUMENTO_PAGADOR"
}
'
Resposta Positiva: RESPOSTA 200 JSON
{
"external_id": null,
"txid": "TX202212012040iwQzTdpUeDUr1",
"debtor_document_number": "24109362880",
"debtor_name": "michel",
"amount": 0.01,
"status": "ATIVA",
"qr_code": "00020126860014br.gov.bcb.pix2564pix.bancoe2.com.br/qr/v3/at/73194abd-c4ed-474b-851b-aa5722b2b81e5204000053039865802BR5913NOVA_BET_LTDA6010SANTA_RITA62070503***630403BA",
"qr_code_image_url": "https://envfsp.com/qr_code/TX202212012040iwQzTdpUeDUr1",
"expires_at": "2025-08-14T17:10:40Z",
"account_id": 1,
"updated_at": "2025-08-14T16:55:40Z",
"created_at": "2025-08-14T16:55:40Z"
}
Resposta ERRO:
RESPOSTA 400
{"error_code":"AC004","reason":"A requisição que busca alterar ou criar uma cobrança para pagamento imediato não respeita o schema ou está semanticamente errada."}
RESPOSTA 403 Forbidden
{"error_code":"AC005","reason":"Requisição de participante autenticado que viola alguma regra de autorização."}
RESPOSTA 404
{"error_code":"AC006","reason":"Entidade não encontrada."}
RESPOSTA 503
{"error_code":"AC006","reason":"Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento."}
