Here, you transact quickly, simply and safely.
We thought about every step so you can have an unique experience and process with a few code lines.
In this documentation you can explore all the products and functionalities that our API offers and adapt them to your browser, mobile or internal system.
API Levpay is a platform that generates business through payment technology. With one macro features and its modular structure, API makes innovative system’s means of billing, where the payment does not necessarily involve only the store and the customer.
Our integration process is divided into 3 phases:
Partner development and testing in the approval environment
Validation of the orders generated in homologation made by Levpay
Create access account in the production environment and share access via email
All development is done in the homologation environment and after approval of Levpay we release access in the production environment.
To send transactions, it is essential that you have a levToken. It is the required authentication for all requests sent to our endpoints.
To start, we are making the homologation levToken to be used in our Sandbox available. If you still haven’t got a levToken, please contact our support team.
If you have admin access, the levTokens can be created by navigation:
Administração > Clientes > Chaves > Criar
There is a sample output bellow.
description:"test token"
access_key:"9118dd90-ef78-4a95-8c9f-54a96ce3406f"
secret_key:"37fbe944-73cb-4aac-9718-ec911803583e"
In order to keep the exchange of messages safe it is necessary to have our servers freed in your environment. We strongly recommend that you liberate the levpay.com domain.
In case the liberation is not possible, you will find a list of IP’s that must be liberated:
000.000.000.000
111.111.111.111
222.222.222.222
In addition, because we are a CPI company, we need to keep the safety of information exchange with our APIs. Below you will find the accepted configurations:
Accepted protocols
TLS 1.1
TLS 1.2
Hashs Codes
SHA256
SHA384
SHA512
Cipher Suites
With encryption equal or superior to 128 bits.
The requirements sent to our API are mainly ways of communication with our system. For the communication to be successful, basic criteria must be respected, otherwise making a transaction will not be possible.
We dedicate the section Sending Valid Requests for you to configure your code in a simple manner and to avoid these kinds of slips.
Every order in Levpay follows the order path in the following image.
The following statuses will make API calls to update the merchant starting at August 10th, 2020:
paid
(specified as “payback” bellow)
analysis
denied
expired
The API call of these statuses will follow the pattern bellow:
curl --location --request POST 'https://yourdomain.com/specified/endpoint' \
--header 'X-Lev-Signature: v2.public.eyJ1dWlkIjo...' \
--header 'Content-Type: application/json' \
--data-raw '{
"status": "<status>",
"uuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // provided by Levpay on order create
"reason":"<reason>",
"duplicate":"<partner_reference>", // provided by the partner on order create
"data": {} // data sent for order from the partner
}'
The reason
field will be one of the following:
incorrect_voucher
incorrect_value
voucher_already_used
(fills the duplicate
field)
other
Our API was built under the REST architecture!
Use the levTokens to get a new access token. This token may expire and it is our authentication control to identify API access.
The request output bellow will be our access token.
With the levToken in hands, the only thing left to do is send it with the HTTP: Authorization heading. You must sent the format JSON (application/json) in the Content-type filed, as well as in the Accept field.
The endpoint of the Sandbox from Levpay is:
Headers | |
---|---|
Authorization | Basic `base64(access_key:secret_key)` |
Content-type | application/json |
Accept | application/json |
Headers | |
---|---|
Content-Type | application/json |
application/json
{
"token": "...",
"tokenType": "Bearer"
}
Banco do Brasil
Itau
Santander
Bradesco
Caixa Econômica.
Headers | |
---|---|
Content-Type | application/json |
Authorization | Bearer ... |
application/json
[
{
"id": 1,
"name": "Banco Itau",
"slug": "itau",
"account_owner": "Owner name",
"account_owner_document": "XXX.XXX.XXX-XX",
"account_agency": "XXXX-X",
"account_number": "XXXXXXXX-X",
"description": "",
"data": {}
}
]
payment_method: transferencia, boleto-express, lottery (string, required)
description: description about product (string, optional)
partner_reference: 111111 (string, required, max 255 character)
bank_slug: itau, banco-do-brasil, bradesco, caixa, santander, rendimento* (string, required)
amount: 99.99** (number, required)
expiration: 3600 (integer, optional - in seconds)
data: (object, optional - case I have other fields should be sent here)
Important:
rendimento
bank_slug
is only used for boleto-express
amount
in lottery payment method has to be between 4 and 2000 BRL
name: 111111 (string, required)
document_number: 000.000.000-11 (string, required, unique key)
phone_number: +55 31 00000-0000 (string, required) *
email: [email protected] (string, required)
data: (object, optional - case I have other fields should be sent here)
Important:
phone_number
has to be valid on the exact format string “+55 XX XXXXX-XXXX”.
You can generate a new order using this endpoint. This endpoint receive an JSON object that’s contain data of payment data of the client.
Are some recommendations, Levpay sends communication day email and SMS
We recommend to use the following text after checkout action, remember to replace the vars with API checkout values.
The RECEIPT_LINK
consists of the url https://homolog.levpay.com/receipt/?d={hash}
where we inform in the hash some data to fill out the form of sending of receipt. We will send this shortened url in the email.
Obrigado pela sua compra,
Seu pedido foi registrado e estamos aguardando o pagamento para iniciar o procedimento de entrega.
Forma de Pagamento: Depósito/Transferência
Siga os passos abaixo para concretizar sua compra:
1. Realize a transferência ou depósito na conta corrente abaixo:
Nome do banco: BANK_NAME
Titular: COMPANY_NAME
Agência: BRANCH_NUMBER
Conta corrente: ACCOUNT_NUMBER
2. Confirme a transferência/depósito clicando no botão abaixo para enviar o comprovante:
Enviar comprovante de transferência para o RECEIPT_LINK
Atenção: Para que este pedido seja entregue corretamente, é preciso que o depósito ou transferência seja concretizado em até 7 dias após a compra. Se houver algum problema, por favor, envie um e-mail para [email protected].
Headers | |
---|---|
Content-Type | application/json |
Authorization | Bearer ... |
application/json
{
"payment_method": "transferencia",
"description": "Produto XYZ",
"partner_reference": "92",
"bank_slug": "itau",
"amount": 99.99,
"expiration": 3600,
"data": {},
"customer": {
"name": "Thiago Avelino",
"document_number": "000.000.000-11",
"phone_number": "+55 11 00000-0000",
"email": "[email protected]",
"data": {}
}
}
Headers | |
---|---|
Content-Type | application/json |
application/json
{
"created_at":"2017-11-28T20:37:31.828662",
"expires_at":"2017-12-05T20:37:31.828662",
"partner_reference":"lev20171128180200",
"url":"http://bit.ly/...",
"uuid":"ac6843db-ae2e-4269-8573-a4b20066ae62"
}
payment_method: boleto-express (string, required)
description: description about product (string, optional)
partner_reference: 111111 (string, required, max 255 character)
bank_slug: rendimento (string, required)
amount: 20.00 (number, required)
expiration: 86400 (integer, optional - in seconds)
data: (object, optional - case I have other fields should be sent here)
name: Fulano de Tal (string, required)
document_number: 000.000.000-11 (string, required, unique key)
phone_number: +55 31 00000-0000 (string, required) This field need to be a valid phone number on the exact format string “+55 XX XXXXX-XXXX”.
email: [email protected] (string, required)
data: (object, optional - case I have other fields should be sent here)
You can generate a new boleto order using this endpoint. This endpoint receive an JSON object that’s contain data of payment data of the client.
Are some recommendations, Levpay sends communication day email and SMS
We recommend to use the following text after checkout action, remember to replace the vars with API checkout values.
The BOLETO_LINK
consists of the url https://boleto-homolog.levpay.com/{boleto_uuid}
. We will send this shortened url in the email.
Prezado(a) Fulano de Tal,
Seu pedido foi registrado e estamos aguardando o pagamento para iniciar o procedimento de entrega.
Número do pedido: 111111
Nome da loja: Loja
Data do pedido: 30/08/2019
Data de vencimento: 31/08/2019
Taxa Gestão: R$ 1,50
Total a pagar: R$ 21,50
Forma de Pagamento: Boleto Express
Tempo de Processamento: Alguns minutos após o pagamento
Clique aqui para vizualizar o boleto {BOLETO_LINK}
Atenção: Para que este pedido seja entregue corretamente, é preciso que o boleto seja pago até 3 dia(s) após a compra.
Caso seu boleto não seja pago dentro do prazo de vencimento seu pedido será automaticamente cancelado.
Caso precise falar conosco, envie um e-mail para [email protected]
Atenciosamente,
Headers | |
---|---|
Content-Type | application/json |
Authorization | Bearer ... |
application/json
{
"payment_method": "boleto-express",
"description": "Produto XYZ",
"partner_reference": "92",
"bank_slug": "rendimento",
"amount": 20.00,
"expiration": 86400,
"data": {},
"customer": {
"name": "Fulano de Tal",
"document_number": "000.000.000-11",
"phone_number": "+55 11 00000-0000",
"email": "[email protected]",
"data": {}
}
}
Headers | |
---|---|
Content-Type | application/json |
application/json
{
"created_at":"2019-09-10T20:37:31.828662",
"expires_at":"2019-09-11T20:37:31.828662",
"partner_reference":"lev20171128180200",
"url":"https://r.levpay.com/...",
"uuid":"ac6843db-ae2e-4269-8573-a4b20066ae62"
}
To cancel Order, use the UUID value on cancel endpoint.
Headers | |
---|---|
Authorization | Bearer ... |
Headers | |
---|---|
Content-Type | application/json |
application/json
{
"uuid":"619f041c-94af-467a-94dc-d47d562c3291",
"status":"canceled"
}
To manually check the status of an Order, use the UUID value on status endpoint to consult the payment data.
Status:
analysis
canceled
denied
expired
pending
paid
Headers | |
---|---|
Authorization | Bearer ... |
Headers | |
---|---|
Content-Type | application/json |
application/json
{
"uuid":"619f041c-94af-467a-94dc-d47d562c3291",
"status":"pending"
}
After release of the order we automatically send a payback (with method POST) to your service URL (software) previously configured with your Levpay Account Manager.
Every request receives a X-Lev-Signature
Header that can be used to verify It’s authenticity as being done by Levpay. It uses Platform-Agnostic Security Tokens (https://paseto.io/) to sign and let it be verified.
Every customer has a set of unique private and public tokens that are used to sign every request and the public token can be used to verify authenticity. Every customer’s public token can be found in their internal LevPay dashboard and should be set as a environment variable in a application.
Headers | |
---|---|
Content-Type | application/json |
X-Lev-Signature | v2.public.eyJ1dWlkIjo... |
application/json
{
"uuid":"619f041c-94af-467a-94dc-d47d562c3291",
"status":"paid",
"data":{}
}
order_uuid: ac6843db-ae2e-4269-8573-a4b20066ae62 (string, required)
file: iVBORw0KGgoAAAANSUhEUgAAAqUAAAJsCAYAAADEP9pOAAAgAE… (base64 image, required)
name: 001_1568910996.png (number, required)
receipt_infos: (object, optional)
payment_type: ted_same_bank (string, required, see options bellow)
cpf_cnpj: 01234567890 (string, required, cpf 11 characters, cnpj 14 characters)
name: John Downey (string, not null or empty)
bank_branch: 0123-4 (string, 1-20 characters)
bank_account: 56789-11 (string, 5-10 characters)
doc_number: 52365212515324484545 (string, not null or empty)
Payment Type is one of these options:
ted_same_bank
(1)
ted_other_bank
(1)
doc
(1)
envelop_deposit
(2)
deposit_online
(2)
cash_deposit
(2)
In (1) cases, the fields bank_branch
, bank_account
and name
are required, while in (2) cases doc_number
field is required
Headers | |
---|---|
Content-Type | application/json |
Authorization | Bearer ... |
application/json
{
"order_uuid": "ac6843db-ae2e-4269-8573-a4b20066ae62",
"file": "iVBORw0KGgoAAAANSUhEUgAAAqUAAAJsCAYAAADEP9pOAAAgAE...",
"name": "001_1568910996.png",
"receipt_infos": {
"name": "John Downey",
"cpf_cnpj": "01234567890",
"doc_number": "52365212515324484545",
"bank_branch": "0123-4",
"bank_account": "56789-11",
"payment_type":"envelop_deposit"
}
}
Headers | |
---|---|
Content-Type | application/json |
application/json
{
"status": "ok"
}