Botpay API Documentation

version v1
baseUri api.botpay.com.br/v1/
protocols HTTPS

Bem vindo

A API Botpay está organizada com o estilo arquitetural REST (Representational State Transfer). Estruturamos a API de maneira que os recursos oferecidos pela Botpay pudessem ser utilizados de maneira simples e fácil.

Nossa API possui utiliza os códigos de resposta HTTP para indicar os erros e sucessos das requisições. O JSON é retornado por todas as respostas da API, incluindo erros. Isso facilita a identificação do problema ocorrido e consequentemente possibilita maior velocidade na correção de requisições incompatíveis com a API Botpay.

Recursos

A API Botpay possui 6 recursos disponíveis. Veja a seguir uma breve descrição de cada um. Você pode ver a descrição completa de cada recurso, estrutura e exemplos na aba Resources.

Contracts

O recurso `/contracts` possui dois métodos, o `GET` e o `POST`.

O método `GET`, quando requisitado, retorna um array JSON de objetos. Cada objeto representa um cliente e seus atributos os dados deste. Por método `POST` é possível cadastrar um contrato.

O recurso `/contracts` possui ainda um sub-recurso denominado `/{id}`. Este disponibiliza através dos métodos `GET` e `PUT` maneiras de manipular diretamente um cliente por meio de seu ID.

Ao acessar o contrato pelo seu id é possível acessar mais dois métodos: /{id}/status (Para atualização do status do contrato pela IC) e /{id}/signature (Inserir assinaturas referentes aos contratos)

Ambiente de testes

O Botpay possui dois ambientes:

1) o ambiente de produção

APP: app.botpay.com.br API: api.botpay.com.br

2) o ambiente de testes

Homologação: homologacao.botpay.com.br Sandbox: sandbox.botpay.com.br

Para fazer requisições à API você precisa solicitar seu Secret Token no APP. Mas lembre-se: as requisições feitas pela API são consideradas válidas.

Para realizar testes você deve utilizar a Sandbox (que é a versão de testes da API) e o Homologação (que é o ambiente de testes do APP). As requisições realizadas por esse ambiente nunca serão consideradas válidas pelo Botpay e ele só deve ser utilizado para testes de implantação do seu sistema.

Autenticação

Para conseguir fazer requisições à API você precisa:

Ter uma conta no sistema Botpay. Caso não tenha uma conta você precisará criar uma conta Botpay.
Um Secret Token.
Um Acess Token.

O Secret Token e o Acess Token compõem o método de autenticação de chave dupla utilizado pela API Botpay para oferecer maior segurança aos seus usuários. Veja a seguir como esses tokens podem ser gerados por você.

Secret Token

O Secret Token é uma chave privada que pode ser habilitada por você em seu perfil. Depois de gerada ela sempre será a mesma até que você gere uma nova chave. O Secret Token é necessário para gerar um Acess Token, logo, depois de ter seu Secret Token habilitado, você já está apto a gerar o Acess Token.

Como o nome já indica, o Secret Token é secreto e deve ser bem protegido. Preocupada com sua segurança, a Botpay utiliza o algoritmo SHA256 para gerar seu Secret Token. Você também deve fazer a sua parte e manter o seu Secret Token em segredo, pois com ele é possível fazer operações em seu nome. Sendo assim, não compartilhe o mesmo em áreas públicas.

Para gerar um novo Secret Token:

Faça login em sua conta Botpay.
Acesse a página de dados cadastrais, ou acesse este link para ser redirecionado(a) para lá.
Procure a seção intitulada Chaves de API
Clique no botão Criar chave
Clique em Confirmar

Pronto! Você já possui um Secret Token e já pode gerar um Acess Token na API.

Acess Token

O Access Token é uma chave temporária necessária para autenticar cada requisição feita à API. Diferentemente do Secret Token, o Acess Token expira após um determinado período de tempo. Quando isso acontece não será mais possível realizar requisições à API por meio dessa chave expirada, o que torna necessária a geração de um novo Acess Token.

Para gerar um Access Token faça uma requisição do tipo POST ao endereço https://api.botpay.com.br/v1/authenticate com os parâmetros de cabeçalho e corpo a seguir:

Header

Campo	Valor
Content-Type	application/json

Body

Campo	Valor
email	[email protected]
token	MeuSecretToken

Como resposta a essa requisição será retornado um objeto JSON contendo o seu acess_token, o token_type e o expires_in, momento a partir do qual o acces_token não possuirá mais validade. O expires_in exibe, respectivamente, a data de expiração do acces_token no padrão americano: YYYY-MM-DD h:i:s. Veja o exemplo de resposta a seguir:

Exemplo de Acess Token
{ "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC8xMjcuMC 4wLjE6ODAwM1wvYXBpXC9sb2dpbiIsImlhdCI6MTUxODc4NTU2OCwiZXhwIjoxNTE4Nzg 5MTY4LCJuYmYiOjE1MTg3ODU1NjgsImp0aSI6IkdKTXN6VVhYRm1vU29aQ2QiLCJzdWI iOjEsInBydiI6ImY1N2I4YzQ1N2M0NTlhOTE0MDRjMzhjYThlMWYzY2Y1ZDEyZGVkOGYif Q.gfgVq9zaEabY-CJU1mlodekxxPuP3006aNH11wN1bbA, "token_type":"bearer", "expires_in":"2020-07-29 19:41:53" }

Exemplo de Acess Token

{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC8xMjcuMC
4wLjE6ODAwM1wvYXBpXC9sb2dpbiIsImlhdCI6MTUxODc4NTU2OCwiZXhwIjoxNTE4Nzg
5MTY4LCJuYmYiOjE1MTg3ODU1NjgsImp0aSI6IkdKTXN6VVhYRm1vU29aQ2QiLCJzdWI
iOjEsInBydiI6ImY1N2I4YzQ1N2M0NTlhOTE0MDRjMzhjYThlMWYzY2Y1ZDEyZGVkOGYif
Q.gfgVq9zaEabY-CJU1mlodekxxPuP3006aNH11wN1bbA,
"token_type":"bearer",
"expires_in":"2020-07-29 19:41:53"
}

Pronto! Você já possui um Secret Token e um Access Token, portanto, já pode utilizar os recursos disponíveis na API Botpay.

Como utilizar o Acess Token para autenticar as minhas requisições?

A autenticação acontece por meio de dois parâmetros enviados no cabeçalho (header) de cada requisição realizada. Os primeiro parâmetro é o Authorization. A sua chave (token) deve ser enviada como valor desse parâmetro, precedida da palavra Bearer. O segundo parâmetro é o Content-Type. Como valor desse campo você apenas deve informar application/json

Veja o exemplo:

Campo	Valor
Authorization	Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC8 xMjcuMC4wLjE6ODAwM1wvYXBpXC9sb2dpbiIsImlhdCI6MTUxODc4NTU2OCw iZXhwIjoxNTE4Nzg5MTY4LCJuYmYiOjE1MTg3ODU1NjgsImp0aSI6IkdKTXN 6VVhYRm1vU29aQ2QiLCJzdWIiOjEsInBydiI6ImY1N2I4YzQ1N2M0NTlhOTE 0MDRjMzhjYThlMWYzY2Y1ZDEyZGVkOGYifQ.gfgVq9zaEabY-CJU1mlodekx xPuP3006aNH11wN1bbA
Content-Type	application/json

Erros

Além das descrições dos erros apresentados em Json, o BOTPAY retorna os códigos de resposta HTTP convencionais.

Código	Descrição
200 - OK	Tudo funcionou como o esperado.
201 - Created	O pedido foi cumprido, resultando na criação de um novo recurso.
400 - Bad Request	A solicitação não foi aceita, muitas vezes devido a falta de um parâmetro necessário.
401 - Unauthorized	Chave de API não fornecida ou inválida.
404 - Not found	Recurso inexistente.
417 - Expectation Failed	O servidor não pode atender à requisição por indefinição ou definição incorreta do Content-Type no cabeçalho da requisição.
422 - Unprocessable Entity	A requisição foi realizada, mas não pôde prosseguir devido a erros semânticos.
500 - Internal Server Error	Uma mensagem de erro genérica, dada quando uma condição inesperada foi encontrada e nenhuma mensagem mais específica é adequada.

/contracts

Coleção de contratos relacionados a uma empresa

/contracts get

GET: /contracts

Retorna todos os contratos relacionados a uma empresa.

Header Parameters

Authorization

Utilize esse campo para enviar um token válido. Inicie o preenchimento do campo com o termo Bearer e em seguida o token.

Property	Value
required	true
type	string
examples	`Bearer $2y$10$AJ9nr0NAUcl3VskG/VoVK.T0g3KmG9DZXkuyKk4PBsIuEoa9s7ER6`

Content-Type

Neste campo apenas preencha application/json

Property	Value
required	true
type	string
examples	`application/json`

Possible Responses

200

401

404

417

500

/contracts get

CURL EXAMPLE

curl -X GET "api.botpay.com.br/v1/contracts" \
	-H "Authorization: Bearer $2y$10$AJ9nr0NAUcl3VskG/VoVK.T0g3KmG9DZXkuyKk4PBsIuEoa9s7ER6" \
	-H "Content-Type: application/json"

REQUEST HEADERS

Authorization: Bearer $2y$10$AJ9nr0NAUcl3VskG/VoVK.T0g3KmG9DZXkuyKk4PBsIuEoa9s7ER6
Content-Type: application/json

RESPONSE BODY

200

[
  {
    "client_id": "77de68daecd823babbb58edb1c8e14d7106e83bb",
    "ic_id": "c1dfd96eea8cc2b62785275bca38ac261256e278",
    "status": "approved",
    "date": "2020-10-10",
    "description": "Contrato teste",
    "amount": "5000.00",
    "installments": 50
  },
  {
    "client_id": "1b6453892473a467d07372d45eb05abc2031647a",
    "ic_id": "c1dfd96eea8cc2b62785275bca38ac261256e278",
    "status": "processing_payment",
    "date": "2020-10-10",
    "description": "Contrato teste",
    "amount": "5000.00",
    "installments": 50
  }
]

Type

{
  "name": "type",
  "displayName": "type",
  "typePropertyKind": "TYPE_EXPRESSION",
  "type": "array",
  "items": {
    "name": "items",
    "displayName": "items",
    "typePropertyKind": "TYPE_EXPRESSION",
    "type": "object",
    "properties": [
      {
        "name": "client_id",
        "displayName": "client_id",
        "typePropertyKind": "TYPE_EXPRESSION",
        "type": "string",
        "required": true,
        "description": "Identificador único do cliente. Gerado automaticamente pelo sistema.",
        "key": "client_id"
      },
      {
        "name": "ic_id",
        "displayName": "ic_id",
        "typePropertyKind": "TYPE_EXPRESSION",
        "type": "string",
        "required": true,
        "description": "Identificador único da instituição de crédito.",
        "key": "ic_id"
      },
      {
        "name": "status",
        "displayName": "status",
        "typePropertyKind": "TYPE_EXPRESSION",
        "type": "string",
        "required": true,
        "description": "Status do contrato.",
        "key": "status"
      },
      {
        "name": "date",
        "displayName": "date",
        "typePropertyKind": "TYPE_EXPRESSION",
        "type": "string",
        "required": true,
        "description": "Data da criação do contrato.",
        "key": "date"
      },
      {
        "name": "description",
        "displayName": "description",
        "typePropertyKind": "TYPE_EXPRESSION",
        "type": "string",
        "required": true,
        "description": "Descrição do contrato.",
        "key": "description"
      },
      {
        "name": "amount",
        "displayName": "amount",
        "typePropertyKind": "TYPE_EXPRESSION",
        "type": "float",
        "required": true,
        "description": "Valor do contrato.",
        "key": "amount"
      },
      {
        "name": "installments",
        "displayName": "installments",
        "typePropertyKind": "TYPE_EXPRESSION",
        "type": "integer",
        "required": true,
        "description": "Número de parcelas.",
        "key": "installments"
      }
    ]
  }
}

/contracts post

POST: /contracts

Via método post é possível adicionar um contrato.

Header Parameters

Authorization

Utilize esse campo para enviar um token válido. Inicie o preenchimento do campo com o termo Bearer e em seguida o token.

Property	Value
required	true
type	string
examples	`Bearer $2y$10$AJ9nr0NAUcl3VskG/VoVK.T0g3KmG9DZXkuyKk4PBsIuEoa9s7ER6`

Content-Type

Neste campo apenas preencha application/json

Property	Value
required	true
type	string
examples	`application/json`

Possible Responses

200

401

404

417

422

500

/contracts post

CURL EXAMPLE

curl -X POST "api.botpay.com.br/v1/contracts" \
	-H "Authorization: Bearer $2y$10$AJ9nr0NAUcl3VskG/VoVK.T0g3KmG9DZXkuyKk4PBsIuEoa9s7ER6" \
	-H "Content-Type: application/json" \
	-d @request_body

REQUEST HEADERS

Authorization: Bearer $2y$10$AJ9nr0NAUcl3VskG/VoVK.T0g3KmG9DZXkuyKk4PBsIuEoa9s7ER6
Content-Type: application/json

REQUEST BODY

{
  "description": "Contrato teste",
  "date": "10/10/2020",
  "amount": 5000,
  "installments": 50, 
  "ic_id": 6,
  "requester":{
      "name": "Solicitante 2",
      "document": "000.000.000-00",
      "email": "[email protected]",
      "phone": "(38)99999-8888",
      "genre": "m",
      "birth": "10/10/1993"
  }
}

Type

{
  "name": "type",
  "displayName": "type",
  "typePropertyKind": "TYPE_EXPRESSION",
  "type": "object",
  "properties": [
    {
      "name": "description",
      "displayName": "description",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "string",
      "required": true,
      "description": "Descrição do contrato",
      "key": "description"
    },
    {
      "name": "date",
      "displayName": "date",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "string",
      "required": true,
      "description": "Data do contrato.",
      "key": "date"
    },
    {
      "name": "amount",
      "displayName": "amount",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "float",
      "required": true,
      "description": "Valor do contrato.",
      "key": "amount"
    },
    {
      "name": "installments",
      "displayName": "installments",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "integer",
      "required": true,
      "description": "Número de parcelas.",
      "key": "installments"
    },
    {
      "name": "ic_id",
      "displayName": "ic_id",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "integer",
      "required": true,
      "description": "Identificador da instituição de crédito.",
      "key": "ic_id"
    },
    {
      "name": "requester",
      "displayName": "requester",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "object",
      "required": true,
      "description": "Objeto JSON de solicitante do contrato.",
      "properties": [
        {
          "name": "name",
          "displayName": "name",
          "typePropertyKind": "TYPE_EXPRESSION",
          "type": "string",
          "required": true,
          "description": "Nome do solicitante.",
          "key": "name"
        },
        {
          "name": "document",
          "displayName": "document",
          "typePropertyKind": "TYPE_EXPRESSION",
          "type": "string",
          "required": true,
          "description": "CPF ou CNPJ do solicitante.",
          "key": "document"
        },
        {
          "name": "email",
          "displayName": "email",
          "typePropertyKind": "TYPE_EXPRESSION",
          "type": "string",
          "required": true,
          "description": "E-mail do solicitante.",
          "key": "email"
        },
        {
          "name": "phone",
          "displayName": "phone",
          "typePropertyKind": "TYPE_EXPRESSION",
          "type": "string",
          "required": true,
          "description": "Telefone do solicitante.",
          "key": "phone"
        },
        {
          "name": "genre",
          "displayName": "genre",
          "typePropertyKind": "TYPE_EXPRESSION",
          "type": "char",
          "required": false,
          "description": "Sexo do solicitante.",
          "key": "genre"
        },
        {
          "name": "birth",
          "displayName": "birth",
          "typePropertyKind": "TYPE_EXPRESSION",
          "type": "string",
          "required": false,
          "description": "Data de nascimento do solicitante",
          "key": "birth"
        }
      ],
      "key": "requester"
    }
  ]
}

RESPONSE BODY

200

{ 
  "client_id": "77de68daecd823babbb58edb1c8e14d7106e83bb",
  "ic_id": "c1dfd96eea8cc2b62785275bca38ac261256e278",
  "status": "approved",
  "date": "2020-10-10",
  "description": "Contrato teste",
  "amount": "5000.00",
  "installments": 50
}

Type

{
  "name": "type",
  "displayName": "type",
  "typePropertyKind": "TYPE_EXPRESSION",
  "type": "object",
  "properties": [
    {
      "name": "client_id",
      "displayName": "client_id",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "string",
      "required": true,
      "description": "Identificador único do cliente. Gerado automaticamente pelo sistema.",
      "key": "client_id"
    },
    {
      "name": "ic_id",
      "displayName": "ic_id",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "string",
      "required": true,
      "description": "Identificador único da instituição de crédito.",
      "key": "ic_id"
    },
    {
      "name": "status",
      "displayName": "status",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "string",
      "required": true,
      "description": "Status do contrato.",
      "key": "status"
    },
    {
      "name": "date",
      "displayName": "date",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "string",
      "required": true,
      "description": "Data da criação do contrato.",
      "key": "date"
    },
    {
      "name": "description",
      "displayName": "description",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "string",
      "required": true,
      "description": "Descrição do contrato.",
      "key": "description"
    },
    {
      "name": "amount",
      "displayName": "amount",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "float",
      "required": true,
      "description": "Valor do contrato.",
      "key": "amount"
    },
    {
      "name": "installments",
      "displayName": "installments",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "integer",
      "required": true,
      "description": "Número de parcelas.",
      "key": "installments"
    }
  ]
}

(id) representa o ID de um contrato. Deve ser passado via método GET.

/{id} get

GET: /contracts/{id}

Retorna os dados de um contrato específico pertencente a uma empresa. (id)

URI Parameters

Property	Value
required	true
type	string

Header Parameters

Authorization

Utilize esse campo para enviar um token válido. Inicie o preenchimento do campo com o termo Bearer e em seguida o token.

Property	Value
required	true
type	string
examples	`Bearer $2y$10$AJ9nr0NAUcl3VskG/VoVK.T0g3KmG9DZXkuyKk4PBsIuEoa9s7ER6`

Content-Type

Neste campo apenas preencha application/json

Property	Value
required	true
type	string
examples	`application/json`

Query Parameters

(id)

Identificador exclusivo de um contrato (ID). Contém 64 caracteres alfanuméricos. Na URL substitua (id) pelo ID de um contrato antes de iniciar a requisição.

Property	Value
required	false
type	string
examples	`a0bd94956b9f42cde97b95b10ad65bbaf2a8d87142caf819e4c099ed75126d72`

Possible Responses

200

400

401

404

417

500

/{id} get

CURL EXAMPLE

curl -X GET "api.botpay.com.br/v1/contracts/{id}?(id)=a0bd94956b9f42cde97b95b10ad65bbaf2a8d87142caf819e4c099ed75126d72" \
	-H "Authorization: Bearer $2y$10$AJ9nr0NAUcl3VskG/VoVK.T0g3KmG9DZXkuyKk4PBsIuEoa9s7ER6" \
	-H "Content-Type: application/json"

REQUEST HEADERS

Authorization: Bearer $2y$10$AJ9nr0NAUcl3VskG/VoVK.T0g3KmG9DZXkuyKk4PBsIuEoa9s7ER6
Content-Type: application/json

RESPONSE BODY

200

{ 
  "client_id": "77de68daecd823babbb58edb1c8e14d7106e83bb",
  "ic_id": "c1dfd96eea8cc2b62785275bca38ac261256e278",
  "status": "approved",
  "date": "2020-10-10",
  "description": "Contrato teste",
  "amount": "5000.00",
  "installments": 50
}

Type

{
  "name": "type",
  "displayName": "type",
  "typePropertyKind": "TYPE_EXPRESSION",
  "type": "object",
  "properties": [
    {
      "name": "client_id",
      "displayName": "client_id",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "string",
      "required": true,
      "description": "Identificador único do cliente. Gerado automaticamente pelo sistema.",
      "key": "client_id"
    },
    {
      "name": "ic_id",
      "displayName": "ic_id",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "string",
      "required": true,
      "description": "Identificador único da instituição de crédito.",
      "key": "ic_id"
    },
    {
      "name": "status",
      "displayName": "status",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "string",
      "required": true,
      "description": "Status do contrato.",
      "key": "status"
    },
    {
      "name": "date",
      "displayName": "date",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "string",
      "required": true,
      "description": "Data da criação do contrato.",
      "key": "date"
    },
    {
      "name": "description",
      "displayName": "description",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "string",
      "required": true,
      "description": "Descrição do contrato.",
      "key": "description"
    },
    {
      "name": "amount",
      "displayName": "amount",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "float",
      "required": true,
      "description": "Valor do contrato.",
      "key": "amount"
    },
    {
      "name": "installments",
      "displayName": "installments",
      "typePropertyKind": "TYPE_EXPRESSION",
      "type": "integer",
      "required": true,
      "description": "Número de parcelas.",
      "key": "installments"
    }
  ]
}

/contracts/{id}/status

Atualiza o status de um contrato, podendo aprovar (APPROVED) ou rejeitar (DECLINED).

/contracts/{id}/signature

Insere assinaturas ao contrato.

[BOTPAY]

Botpay API Documentation

Bem vindo

Recursos

Contracts

Ambiente de testes

Autenticação

Secret Token

Acess Token

Header

Body

Como utilizar o Acess Token para autenticar as minhas requisições?

Erros

/contracts

/contracts get

/contracts get

CURL EXAMPLE

REQUEST HEADERS

RESPONSE BODY

200

/contracts post

/contracts post

CURL EXAMPLE

REQUEST HEADERS

REQUEST BODY

RESPONSE BODY

200

/{id} get

/{id} get

CURL EXAMPLE

REQUEST HEADERS

RESPONSE BODY

200

/contracts/{id}/status

/contracts/{id}/signature