Welcome to Levpay!


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.

Documentation

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.

Integration steps

Our integration process is divided into 3 phases:

  1. Partner development and testing in the approval environment

  2. Validation of the orders generated in homologation made by Levpay

    1. We start this step after confirming the partner via email
    2. Levpay validates data generated in the approval environment and confirms the quantity and standard of the orders
  3. 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.

Platform and Ecommerce

Library

  • php - PHP integration for Levpay API

Transparent Checkout

Have you got your levToken?

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

here

There is a sample output bellow.

description:"test token"
access_key:"9118dd90-ef78-4a95-8c9f-54a96ce3406f"
secret_key:"37fbe944-73cb-4aac-9718-ec911803583e"

Security

Keeping integration safety

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.

Requirements for API

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.

Order Statuses

Every order in Levpay follows the order path in the following image.

statuses

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


Basic Auth

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:

https://homolog.levpay.com

Exchange credentials for token

REQUEST

Headers
Authorization Basic `base64(access_key:secret_key)`
Content-type application/json
Accept application/json

RESPONSE

Headers
Content-Type application/json
200 application/json
                            {
        "token": "...",
        "tokenType": "Bearer"
    }

                      
                        
                      
Available Banks

List available Banks

  • Banco do Brasil

  • Itau

  • Santander

  • Bradesco

  • Caixa Econômica.

REQUEST

RESPONSE

Headers
Content-Type application/json
Authorization Bearer ...
200 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": {}
    }
]

                      
                        
                      
New transfer order

Fields descritions

Orders

  • 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

Customers

  • 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”.

Checkout Transfer

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.

Introductions after checkout

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].

REQUEST

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": {}
    }
}

                        
                          
                        

RESPONSE

Headers
Content-Type application/json
201 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"
}

                      
                        
                      
New boleto order

Fields descritions

Orders

  • 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)

Customers

  • 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)

Checkout Boleto

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.

Introductions after checkout

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,

REQUEST

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": {}
    }
}

                        
                          
                        

RESPONSE

Headers
Content-Type application/json
201 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"
}

                      
                        
                      
Cancel order

Cancel

To cancel Order, use the UUID value on cancel endpoint.

REQUEST

Headers
Authorization Bearer ...

RESPONSE

Headers
Content-Type application/json
200 application/json
                        {
    "uuid":"619f041c-94af-467a-94dc-d47d562c3291",
    "status":"canceled"
}

                      
                        
                      
Order current status

Status

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

REQUEST

Headers
Authorization Bearer ...

RESPONSE

Headers
Content-Type application/json
302 application/json
                        {
    "uuid":"619f041c-94af-467a-94dc-d47d562c3291",
    "status":"pending"
}

                      
                        
                      
Payback

Automatic Update after payment set status paid

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.

example: https://your-domain.com/levpay/payback

REQUEST

RESPONSE

Headers
Content-Type application/json
X-Lev-Signature v2.public.eyJ1dWlkIjo...
200 application/json
                        {
    "uuid":"619f041c-94af-467a-94dc-d47d562c3291",
    "status":"paid",
    "data":{}
}

                      
                        
                      
Receipt Upload

Upload

Field descriptions

Orders

  • order_uuid: ac6843db-ae2e-4269-8573-a4b20066ae62 (string, required)

  • file: iVBORw0KGgoAAAANSUhEUgAAAqUAAAJsCAYAAADEP9pOAAAgAE… (base64 image, required)

  • name: 001_1568910996.png (number, required)

  • receipt_infos: (object, optional)

Receipt Infos Object

  • 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

REQUEST

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"
    }           
}

                        
                          
                        

RESPONSE

Headers
Content-Type application/json
200 application/json
                        {
    "status": "ok"
}