About the Vehicle Debit API
The vehicle debt API allows the creation of applications that enable the search and settlement of vehicle debts, such as fines, IPVA, licensing and mandatory insurance, increasing the number of transactions and the time the user uses the application. With this service, the customer can settle all vehicle debts in a single session and cover 95% of the national vehicle fleet in 20 states.
Use case:
As a Fintech, I want to be able to provide my users with the possibility of paying vehicle debts by informing the state, vehicle license plate, renavam and CPF or CNPJ with the aim of having this practicality on my platform and/or system.
Nesse artigo você irá aprender sobre:
- Limitations and exceptions
- Types of Debits
- Supported States
- Set up a webhook to receive debit information.
- Check whether a vehicle has outstanding debts
- Execute payment of a vehicle debt
- homologation
Prerequisites for implementation:
- Have a Celcoin API key, for more information access this link
- Have familiarity with Rest APIs using the OAuth 2.0 protocol.
- If you have purchased the product/solution, and wish to use the functionality in a production environment, please contact our sales team via email at [email protected]. For technical questions, simply contact support via the link .
Limitations and exceptions:
For PE (state of Pernambuco) the mandatory fields are License Plate, Renavam and CPF/CNPJ.
For RJ (state of Rio de Janeiro) the mandatory fields are License Plate, Renavam and CPF/CNPJ
For PR (state of Paraná) the mandatory fields are License Plate, Renavam and CPF/CNPJ.
For SC (state of Santa Catarina) the mandatory fields are License Plate and Renavam. However, the validated data is Renavam.
Note: Currently, the DETRANs of PR (Paraná) and RS (Rio Grande do Sul) may return "VEHICLE_WITHOUT_DEBTS" even for non-existent plates, due to a limitation in data validation in these states. If it is necessary to verify the existence of the vehicle, we suggest using the license plate enrichment service.
Types of debits:
- Fees for various services, such as yard fines
- Traffic fines
- Fines managed by RENAINF
- Vehicle IPVA
- Vehicle licensing fee
- Single payment for vehicle IPVA
- Installment payment for vehicle IPVA
- Mandatory Vehicle Insurance Fee (DPVAT)
- Overdue Mandatory Vehicle Insurance Fee
Supported states:
It is possible to consult and pay off debts for vehicles in the following states:
- Acre
- Alagoas
- Ceara
- Distrito Federal
- Holy Spirit
- Goias
- Maranhao
- Mato Grosso
- Mato Grosso do Sul
- Pernambuco
- Piauí
- Paraná
- Rio de Janeiro
- Rio Grande do Norte
- Rondônia
- Rio Grande do Sul
- Roraima
- Santa Catarina
- São Paulo
Attention!
In a sandbox environment, it is possible to test all existing scenarios in the product, regardless of the state. More details in our Test Mass .
Configuring webhook (trigger)
To be able to receive vehicle debts from Celcoin for its users, it is necessary to configure a webhook.
The webhook is a way of receiving information asynchronously, triggers are generally fired in JSON format when an event occurs, in practice for vehicle debit APIs it will be used to receive information in your system about the vehicle debits that were consulted, or when a payment attempt is made, where it is possible to validate whether the payment was processed correctly, or if a failure occurred.
Therefore, first of all, you need to authenticate yourself in the Celcoin API. If you have any doubts about how to carry out this process, we recommend reading the article ( Obtaining your credentials ).
For security and compliance reasons, webhooks registered in the Vehicle Debit product must be authenticated . To this end, we provide Basic Auth authentication and also the JWT token .
Ao se autenticar na api será retornado um acess_token, com esse valor deve ser realizado um POST na api Registra uma URL para recebimento de notificações via Webhook ou na api Registrar Webhook Com Token - JWT. Lembre-se que no header deve ser passado a propriedade Authorization populando o seu valor com Bearer + acess_token, retornado da chamada de autenticação, seguindo os padrões o Oauth 2.0.
Below are the webhook registration request templates, with the two authentications available in the Vehicle Debit product:
Modelo de request Basic Auth:
cURL
curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/vehicledebtsapi/v1/webhook/register' \ --header 'accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer acess_token' \ --data-raw '{ "url": "https://gatilho.com.br" "clientId": "string", "clientSecret": "string" }'
Modelo de request Token JWT:
cURL
curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/vehicledebtsapi/v1/webhook/registerWithToken' \ --header 'accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer acess_token' \ --data-raw '{ "url": "https://gatilho.com.br", "url_token": "https://gerartokengatilho.com.br", "client_id": "d35f22170e.meucarrosemdebito.celcoinapi.v5", "client_secret": "777f7e971374e03ae92128c10ab45e677oi5ce97f684fde8c527b123456789f", "content_type": "application/x-www-form-urlencoded", "token_type": "Bearer", "grant_type": "client_credentials", "token_field": "access_token", "handles": [ { "name": "Escope", "value": "Débito Veicular" } ] } '
- Note que os endereços para realizar o cadastro do webhook são diferentes entre os tipos de autenticação.* Você deve escolher um dos modelos de autenticação disponível para cadastrar seu webhook.* Não é mais necessário cadastrar o "type:settlement" para receber os webhooks de liquidação. Apenas cadastrando os webhooks conforme exemplos, enviaremos todos os tipos de webhooks disponíveis no produto para você.
If the configuration occurs as expected, our API will return the following information:
Response model:
JSON
{ "message": "Nova URL atualizada com sucesso", "errorCode": "000" }
When the webhook is configured for the first time in our API, a GET trigger will be sent to the API webhook to validate whether the URL sent in the request is valid. This process only occurs once in the configuration.
Webhook template sent when first configured:
json
{ "type": "webhook-register", "errorCode": "000", "url": "https://webhook.site/38625015-d2f3-440a-97a5-0883a84a5575", "message": "URL do Webhook registrada com Sucesso" }
For more details on authentication via JWT token, see the documentation .
With the webhook configured, we can start the process of consulting and settling vehicle debts.
Vehicle Debt Consultation and Payment Simulation
In order to show what the flow of consultation and payment of a vehicle debt might be like for a user, we created this presentation that simulates the entire process:
🦉
Débitos Veiculares - cel_payments
Open Recipe
Before continuing to read this documentation, learn more details about the Synchronous and Asynchronous returns of the Vehicle Debit APIs.
Check whether a vehicle has outstanding debts:
To obtain information about a vehicle debt, it is necessary to perform this query in the API (Generates an asynchronous request to query vehicle debts) using the POST method, where some information such as state, renavam, vehicle license plate, CPF or CNPJ must be filled in the body.
Request template:
cURL
curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/vehicledebtsapi/v1/debts' \ --header 'accept: application/json' \ --header 'Authorization: Bearer acess_token' \ --header 'Content-Type: application/json' \ --data-raw '{ "state": "DF", "licensePlate": "JFI8753", "renavam": "56387604559", "cpfCnpj": "11111111111", "clientRequestId": "teste hml 20221014 01" } '
Parâmetros do Body:
| Field | Description | Type |
|---|---|---|
| state | State where the vehicle is registered | String (2) |
| licensePlate | Placa do veículo | String (10) |
| reindeer | Vehicle's Renavam | String (20) |
| cpfCnpj | Documento do proprietário do veículo | String (20) |
| clientRequestId | Transaction identifier, can be an internal transaction ID | String (36) |
Return model:
JSON
{ "transactionId": 9393366, "message": "processing", "errorCode": "000" }
Note that this API is asynchronous, therefore, Celcoin will return to the webhook configured in our API what debts this customer has for the vehicle that was searched for.
Webhook structure model for vehicles with debts:
JSON
{ "type": "debts", "transactionId": 817210768, "clientRequestId": "c676c954-aa6d-4cb5-a812-c1907a53a442", "vehicle": { "uf": "DF", "document": "39268450828", "licensePlate": "DIS9865", "renavam": "01203988813" }, "debts": [ { "id": "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF", "amount": 85.13, "title": "Infração Vencida - I004242123", "description": "I004242123 - Infração de Trânsito", "ait": "5E0083715", "dueDate": null, "expirationDate": null, "hasDiscount": false, "isExpired": true, "type": "ticket", "year": null, "required": false, "dependsOn": [ "1F6F233B-468D-4F5B-A7E7-8F9AF7DF571D", "1ACB4E2C-8880-4B13-BA8E-86E070DD9717", "2D377399-CF39-4407-99F5-7553A2D77C44", "CC811B6A-6096-4C5E-A159-4AF437F72DCE", "FAB7FDDE-4864-489B-A8AB-40697649ECF0", "01F89CC3-152C-4E37-9072-FB8AE5FF01CD", "B1E18EAE-E7A0-4B6C-8E9B-45503FA32A64", "954AE42A-CD32-4CCA-AF9F-27E00C7593FE" ], "distinct": [] }, { "id": "01F89CC3-152C-4E37-9072-FB8AE5FF01CD", "amount": 296.4, "title": "Infração Vencida - I004242123", "description": "I004242123 - Infração de Trânsito", "ait": "5E0083715", "dueDate": "2022-12-28T00:00:00", "expirationDate": "2022-12-28T00:00:00", "hasDiscount": false, "isExpired": true, "type": "ticket", "year": null, "required": false, "dependsOn": [ "1F6F233B-468D-4F5B-A7E7-8F9AF7DF571D", "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF", "1ACB4E2C-8880-4B13-BA8E-86E070DD9717", "2D377399-CF39-4407-99F5-7553A2D77C44", "CC811B6A-6096-4C5E-A159-4AF437F72DCE", "FAB7FDDE-4864-489B-A8AB-40697649ECF0", "B1E18EAE-E7A0-4B6C-8E9B-45503FA32A64", "954AE42A-CD32-4CCA-AF9F-27E00C7593FE" ], "distinct": [] }, { "id": "1ACB4E2C-8880-4B13-BA8E-86E070DD9717", "amount": 296.4, "title": "Infração Vencida - I004242123", "description": "I004242123 - Infração de Trânsito", "ait": "5E0083715", "dueDate": "2022-12-28T00:00:00", "expirationDate": "2022-12-28T00:00:00", "hasDiscount": false, "isExpired": true, "type": "ticket", "year": null, "required": false, "dependsOn": [ "1F6F233B-468D-4F5B-A7E7-8F9AF7DF571D", "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF", "2D377399-CF39-4407-99F5-7553A2D77C44", "CC811B6A-6096-4C5E-A159-4AF437F72DCE", "01F89CC3-152C-4E37-9072-FB8AE5FF01CD", "FAB7FDDE-4864-489B-A8AB-40697649ECF0", "B1E18EAE-E7A0-4B6C-8E9B-45503FA32A64", "954AE42A-CD32-4CCA-AF9F-27E00C7593FE" ], "distinct": [] }, { "id": "1F6F233B-468D-4F5B-A7E7-8F9AF7DF571D", "amount": 140.5, "title": "Infração Vencida - I004242123", "description": "I004242123 - Infração de Trânsito", "ait": "5E0083715", "dueDate": "2022-12-28T00:00:00", "expirationDate": "2022-12-28T00:00:00", "hasDiscount": false, "isExpired": true, "type": "ticket", "year": null, "required": false, "dependsOn": [ "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF", "1ACB4E2C-8880-4B13-BA8E-86E070DD9717", "2D377399-CF39-4407-99F5-7553A2D77C44", "CC811B6A-6096-4C5E-A159-4AF437F72DCE", "FAB7FDDE-4864-489B-A8AB-40697649ECF0", "01F89CC3-152C-4E37-9072-FB8AE5FF01CD", "B1E18EAE-E7A0-4B6C-8E9B-45503FA32A64", "954AE42A-CD32-4CCA-AF9F-27E00C7593FE" ], "distinct": [] }, { "id": "FAB7FDDE-4864-489B-A8AB-40697649ECF0", "amount": 85.13, "title": "Infração Vencida - I004242123", "description": "I004242123 - Infração de Trânsito", "ait": "5E0083715", "dueDate": "2022-12-28T00:00:00", "expirationDate": "2022-12-28T00:00:00", "hasDiscount": false, "isExpired": true, "type": "ticket", "year": null, "required": false, "dependsOn": [ "1F6F233B-468D-4F5B-A7E7-8F9AF7DF571D", "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF", "1ACB4E2C-8880-4B13-BA8E-86E070DD9717", "2D377399-CF39-4407-99F5-7553A2D77C44", "CC811B6A-6096-4C5E-A159-4AF437F72DCE", "01F89CC3-152C-4E37-9072-FB8AE5FF01CD", "B1E18EAE-E7A0-4B6C-8E9B-45503FA32A64", "954AE42A-CD32-4CCA-AF9F-27E00C7593FE" ], "distinct": [] }, { "id": "CC811B6A-6096-4C5E-A159-4AF437F72DCE", "amount": 127.69, "title": "Infração em Notificação - I004242492", "description": "I004242492 - Infração de Trânsito", "ait": "5E0083715", "dueDate": null, "expirationDate": "2022-12-28T00:00:00", "hasDiscount": true, "isExpired": false, "type": "ticket", "year": null, "required": false, "dependsOn": [ "1F6F233B-468D-4F5B-A7E7-8F9AF7DF571D", "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF", "1ACB4E2C-8880-4B13-BA8E-86E070DD9717", "2D377399-CF39-4407-99F5-7553A2D77C44", "FAB7FDDE-4864-489B-A8AB-40697649ECF0", "01F89CC3-152C-4E37-9072-FB8AE5FF01CD", "B1E18EAE-E7A0-4B6C-8E9B-45503FA32A64", "954AE42A-CD32-4CCA-AF9F-27E00C7593FE" ], "distinct": [] }, { "id": "954AE42A-CD32-4CCA-AF9F-27E00C7593FE", "amount": 85.13, "title": "Infração em Notificação - I004242492", "description": "I004242492 - Infração de Trânsito", "ait": "5E0083715", "dueDate": null, "expirationDate": "2022-12-28T00:00:00", "hasDiscount": true, "isExpired": false, "type": "ticket", "year": null, "required": false, "dependsOn": [ "1F6F233B-468D-4F5B-A7E7-8F9AF7DF571D", "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF", "1ACB4E2C-8880-4B13-BA8E-86E070DD9717", "2D377399-CF39-4407-99F5-7553A2D77C44", "CC811B6A-6096-4C5E-A159-4AF437F72DCE", "FAB7FDDE-4864-489B-A8AB-40697649ECF0", "01F89CC3-152C-4E37-9072-FB8AE5FF01CD", "B1E18EAE-E7A0-4B6C-8E9B-45503FA32A64" ], "distinct": [] }, { "id": "B1E18EAE-E7A0-4B6C-8E9B-45503FA32A64", "amount": 85.13, "title": "Infração a Vencer - CJ00729123", "description": "CJ00729123 - Infração de Trânsito", "ait": "5E0083715", "dueDate": "2022-12-28T00:00:00", "expirationDate": "2022-12-28T00:00:00", "hasDiscount": true, "isExpired": false, "type": "ticket", "year": null, "required": false, "dependsOn": [ "1F6F233B-468D-4F5B-A7E7-8F9AF7DF571D", "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF", "1ACB4E2C-8880-4B13-BA8E-86E070DD9717", "2D377399-CF39-4407-99F5-7553A2D77C44", "CC811B6A-6096-4C5E-A159-4AF437F72DCE", "FAB7FDDE-4864-489B-A8AB-40697649ECF0", "01F89CC3-152C-4E37-9072-FB8AE5FF01CD", "954AE42A-CD32-4CCA-AF9F-27E00C7593FE" ], "distinct": [] }, { "id": "2D377399-CF39-4407-99F5-7553A2D77C44", "amount": 206.86, "title": "Infração a Vencer - CJ00729123", "description": "CJ00729123 - Infração de Trânsito", "ait": "5E0083715", "dueDate": "2022-12-28T00:00:00", "expirationDate": "2022-12-28T00:00:00", "hasDiscount": true, "isExpired": false, "type": "ticket", "year": null, "required": false, "dependsOn": [ "1F6F233B-468D-4F5B-A7E7-8F9AF7DF571D", "9547B3A8-05B9-4D1C-8C72-A500BB6D93EF", "1ACB4E2C-8880-4B13-BA8E-86E070DD9717", "CC811B6A-6096-4C5E-A159-4AF437F72DCE", "FAB7FDDE-4864-489B-A8AB-40697649ECF0", "01F89CC3-152C-4E37-9072-FB8AE5FF01CD", "B1E18EAE-E7A0-4B6C-8E9B-45503FA32A64", "954AE42A-CD32-4CCA-AF9F-27E00C7593FE" ], "distinct": [] }, { "id": "E9B42A19-7E70-4E86-98A6-82B6EECC8EE4", "amount": 5.23, "title": "Seguro Obrigatório 2022", "description": "Seguro Obritatório 2022", "dueDate": null, "expirationDate": "2022-12-28T00:00:00", "hasDiscount": false, "isExpired": true, "type": "insurance", "year": 2022, "required": false, "dependsOn": [], "distinct": [ "312D6A5F-2B5A-4694-84DA-F640FC01CC74" ] }, { "id": "312D6A5F-2B5A-4694-84DA-F640FC01CC74", "amount": 1009.36, "title": "Licenciamento 2022", "description": "Licenciamento 2022", "dueDate": null, "expirationDate": "2022-12-28T00:00:00", "hasDiscount": false, "isExpired": true, "type": "licensing", "year": 2022, "required": false, "dependsOn":[], "distinct": [ "E9B42A19-7E70-4E86-98A6-82B6EECC8EE4" ] } ] }
If the vehicle has no outstanding debts, a webhook will be sent with this information.
Webhook structure model for vehicles without debts:
JSON
{ "type": "VehicleWithoutDebts", "transactionId": 817622466, "clientRequestId": "0a384059-eaf0-4240-9dc7-f4125671b4c9", "vehicle": { "uf": "DF", "document": "3138777503", "licensePlate": "RCK0E56", "renavam": "33864569420" } }
Webhook structure template for vehicles not found:
JSON
{ "type": "VehicleNotFound", "transactionId": 817211803, "clientRequestId": "0a384059-eaf0-4240-9dc7-f4125671b4c9" }
If DETRANS services are unavailable, excessively slow or experience any other type of error that makes the consultation unfeasible, a webhook will be sent with this information.
JSON
{ "type": "search-error-event", "status": "ERROR", "transactionId": 817211803, "clientRequestId": "bbf6c1c8-6c60-4806-9454-21a71e1ce1df", "error": [ { "errorCode": "900", "message": "Serviço indisponível." } ] }
Descriptive table of fields returned in the webhook
| Field | Description | Type |
|---|---|---|
| transactionId | Query operation identifier | Numeric(BigInt) |
| clientRequestId | Transaction identifier, can be an internal transaction ID | String |
| uf | Vehicle status reported in the query | String |
| document | CPF/CNPJ informed in the query | String |
| licensePlate | Vehicle license plate provided in the query | String |
| reindeer | Renavam of the vehicle informed in the query | String |
| id | Debit identifier | String |
| amount | Amount to be paid on the debt. Interest or discount already calculated if applied. | Numeric |
| title | Debit name | String |
| description | Debit Description | String |
| ait | ||
| Detran fine identifier. |
The Traffic Violation Report (AIT), also known as a traffic ticket, is a document issued by the competent traffic authority when an infraction is committed. It records the details of the infraction. This information will only be presented in fine-type debts (ticket). Initially available for the state of São Paulo.
| String | | dueDate | Original due date of the invoice. Even if it is expired, the date displayed in this field remains the original due date. This field may be displayed as null. | String | | expirationDate | Maximum payment date allowed. In the case of overdue debts, the expirationDate field will be the date of the query, where the amount value will be updated each day. This field may be displayed as null. | String | | hasDiscount | Contains information on whether there is a discount. The discount amount is not displayed. | Boolean (True or False) | | isExpired | Identifies whether the query has already expired. | Boolean (True or False) | | type | Type of debt (IPVA, Fine, Licensing) For more details see the table below | String | | year | Year of debt | Numeric | | required | Indicates the obligation of that debt in payment | Boolean (True or False) | | dependsOn | It is a list of IDs of other debts that indicates the need for that debt to be accompanied by others in the payment. | Array (String) | | distinct | It is a list of other debt IDs that indicate debts that should not be paid together. | Array (String) |
-
When requesting a query, we perform renavam validation, which consists of analyzing whether the check digit is valid or not. If it is not valid, we will not proceed with the query and return an error in the API. This validation is performed in both the sandbox and production environments. For more details, see our error table .
-
The Detran environment of the State of SP undergoes maintenance during the early hours of the morning, between midnight and 7 am, during which time it is not possible to perform queries for this state. For more details, see our error table .
-
When dependent, distinct and mandatory debts are returned in the query, they have rules for requesting payment that must be followed, access the following link of the documentation for better understanding link .
-
For the states of Goiás, Maranhão, Mato Grosso do Sul and Rio Grande do Sul, only IPVA Single Quota will be returned in the query.
-
Para o estado de Mato Grosso do Sul todos os débitos em aberto retornados na consulta, obrigatoriamente eles devem ser pagos, caso avance para o fluxo de pagamento.
-
Para o estado do Paraná todos os débitos em aberto retornados na consulta, obrigatoriamente eles devem ser pagos, caso avance para o fluxo de pagamento. Exceto o IPVA, ele pode ser pago separadamente.
-
Temos um rate limit na consulta de Débito Veicular onde está limitado em 1 consulta para a mesma placa/Renavam no intervalo de 2 minutos. Caso haja mais consultas que o previsto, a requisição retornará o status code 429 (Too Many Requests).
Table representing the types returned in the Webhook.
| Type | Description |
|---|---|
| services | Fees for various services, such as yard fines |
| ticket | Traffic fines |
| renainf_ticket | Fines managed by RENAINF |
| IPVA | IPVA do veículo. É equivalente ao “ipva_unique” |
| licensing | Vehicle licensing fee |
| ipva_unique | Single payment for vehicle IPVA |
| ipva_installment | Installment payment for vehicle IPVA |
| insurance | Mandatory Vehicle Insurance Fee (DPVAT) |
| expired_insurance | Overdue Mandatory Vehicle Insurance Fee |
Execute payment of a vehicle debt
Ao receber o webhook deve ser realizado a liquidação do débito veicular, para isso é necessário um POST na api Cria um pagamento, informando o transactionid (id único gerado para a pesquisa de débitos) e a lista de débitos que o usuário selecionou para efetuar o pagamento.
Request model:
JSON
curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/vehicledebtsapi/v1/payDebts' \ --header 'accept: application/json' \ --header 'Authorization: Bearer {{acess_token}}' \ --header 'Content-Type: application/json' \ --data '{ "transactionId": 9393366, "debtIdList": [ "28850DB5-05EA-4461-A84A-EE04EF9B545D" ], "clientRequestId": "teste hml 20221014 01" }'
If you have contracted the debt installment service, using the acquiring service itself, you must inform the agreed installment details with your user in the payment request.
cURL
curl --location --request POST 'https://sandbox.openfinance.celcoin.dev/vehicledebtsapi/v1/payDebts' \ --header 'accept: application/json' \ --header 'Authorization: Bearer {{acess_token}}' \ --header 'Content-Type: application/json' \ --data '{ "transactionId": 9393366, "debtIdList": [ "28850DB5-05EA-4461-A84A-EE04EF9B545D" ], "clientRequestId": "teste hml 20221014 01", "installments": { "amount": 1200, "quantity": 10, "value": 120, "entryValue": 0 } }'
Parâmetros do Body:
| Field | Description | Type |
|---|---|---|
| debtIdList | List of debts to be paid | Array (String 36) |
| transactionId | ID generated when checking your debts | Numeric(BigInt) |
| clientRequestId | Transaction identifier, can be an internal transaction ID. | String (36) |
| amount | Total Installment Amount, including fees | Numeric(BigInt) |
| quantity | Total Number of Installments | Numeric(BigInt) |
| value | Value of each installment | Numeric(BigInt) |
Return model:
JSON
{ "paymentId": "507B6664-03AE-40EB-9D53-6D27F25587EA", "errorCode": "000", "message": "Solicitação recebida com sucesso. Aguarde a resposta do processamento no webhook cadastrado." }
Note that this call is also asynchronous, so we will send if the settlement was successful to the configured webhook.
Json structure template sent to webhook:
JSON
{ "type": "receipt", "paymentId": "29C32257-2DDB-41B0-9BB0-4CB64783443F", "receipt": { "licensePlate": "DIS9865", "renavam": "01203988813", "state": "DF", "description": "Licenciamento 2022", "debtId": "312D6A5F-2B5A-4694-84DA-F640FC01CC74", "amount": 1009.36, "authentication": "F2.2D.2C.32.74.24.11.59.81.C1.FD.C2.91.A3.BF.93", "dueDate": "2022-12-28T00:00:00", "clientRequestId": "29d648b8-594f-436c-ba53-a543fdaf9467", "year": 2022, "payDate": "2022-12-28T00:00:00" } }
Once the debt has been settled by the competent bodies, you will receive a second webhook containing the settlement information.
Json structure template sent to webhook:
JSON
{ "type": "settlement-events", "status": "SUCCESS", "paymentId": "D5011AAF-3EB9-41FC-92BB-A1198F4A7E10", "clientRequestId":"webhookLiquidacaoSucesso", "debtId": "E6D1E0E0-AD5E-4A1C-9E3C-91E02174A485", "metaDetran": [ { "state": "SP" }, { "licencePlate": "ABC6E61" }, { "renavam": "00322732381" }, { "document": "05388365760" }, { "nsuDetran": "000220114622" }, { "settlementBank": "BRADESCO" }, { "settlementDateTime": "2023-10-27T19:05:12" }, { "amount": "134.20" }, { "dueDate": "2023-10-27T00:00:00" }, { "debitType": "ticket" }, { "year": "2023" }, { "debtDescription": "Transitar velocidade superior a maxima permitida em ate 20%" } ] }
Please note that the debt may take between 3 and 5 business days to be written off at Detran. Until then, the debt may be presented in subsequent queries.
Depending on the DMV, not all data in the fields of the settlement receipt is available. If the data is not sent, the field will be returned blank.
If Celcoin is unable to make the payment at Detran, or a refund occurs, the webhook below will be returned.
Json structure template sent to webhook:
json
{ "paymentId": "9B351F9F-E021-4050-9489-DC1834DFCF4E", "clientRequestId": "1672424961", "type": "debitNotAuthorized", "processedDate": "2022-12-30T18:29:33", "errorCode":"900", "errorMessage": "Transação não autorizada", "debitId": "D22426B6-35A5-4744-A07E-4067AD98F067" }
Table representing the errorCode returned in the Unauthorized Debit Webhook
| Error Message | Error Code | Description |
|---|---|---|
| This payment is in the process of being settled | 100 | This error code will be returned when requesting a payment for a debt that is already in the open settlement process. |
| This debit is linked to another payment with an open settlement process | 110 | This code will be returned when payment is requested for a debt that depends on the settlement of another debt that is in the process of being settled. |
| Insufficient Balance to Make Payment of Debt | 120 | Podem ocorrer situações em que, mesmo após validar o saldo via API, a sua Conta Pagamento Proprietária fique sem saldo, por exemplo, realizar o pagamento de uma recarga e com isso o saldo não ser suficiente para quitar todos os débitos veiculares. |
| Detran Unavailable for Payment | 130 | This error will be returned in cases where Detran is unavailable for payment requests. |
| Unauthorized transaction | 900 | When requesting cancellation with the agencies, if there is any problem in settling the debts, we will return this error message. |
Error codes 100 and 110 will only occur when our system identifies a possible duplicate payment. We cannot guarantee that the charges will be unique for all Detrans.
The Unauthorized Debit Webhook example reflects the "Unauthorized Transaction" scenario. Note that we may have other error codes, as per the table above.
In this scenario, we recommend opening a ticket for our team to analyze what happened.
Attention!
-
The debt IDs change with each new query, except for the state of SP, where the ID remains the same . By default, a query is valid until the end of the day it was made, and the IDs do not change during this period until payment is requested.
-
Once a query has been carried out and more than one vehicle debt is returned, if it is selected at the time of payment to only settle one debt, it is necessary to carry out a new query, this occurs because Detran does not settle the payment at the time it receives the request.
We created this dynamic to ensure that no duplicate payments occur.
-
Receipts are sent in JSON in separate fields. This allows you to compose the receipt according to your business needs.
-
The receipt is individualized, which means that when requesting a payment where there is more than one debt, you will receive more than one receipt webhook, as they are settled by the agency.
When you receive this webhook, simply show the user that the payment was successful.
For more information about possible errors mapped for each API, we recommend that you search our documentation via the link .
homologation
The instructions for approving this product are centralized in this link