NAV Navbar
Http cURL

Introdução

Seja bem-vindo à documentação da versão 1.0 da API do Ipay Soluções Financeiras.

Autenticação

Para começar a utilizar a API do Ipay, você deve primeiramente autenticar-se.
A API do Ipay utiliza o fluxo de OAuth para conceder a autorização aos usuários.
Após fazer o processo de autenticação, você deve guardar seu token de acesso(access_token) e token para revalidar(refresh_token) o token de acesso quando o mesmo estiver expirado.
Com o token de acesso em mãos, você deve adicionar ele aos cabeçalhos de todas as requisições à API.

Authorization: Bearer INSIRA SEU TOKEN DE ACESSO AQUI

E o token de cliente, que é fornecido no dashboard do Ipay

Token: INSIRA O TOKEN DE CLIENTE AQUI

Abaixo segue a lista de endpoints relacionadas à autenticação.

Endpoint Método Resumo Detalhes
/v1/signin POST Autentica o usuário Link
/v1/refresh-token POST Renova os tokens de acesso Link
/v1/revoke-token POST Revoga o token fornecido Link

SignIn

Faz o SignIn do usuário da API, baseado no fluxo de OAuth.

POST /v1/signin HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Host: api.ipay.net.br
{
   "token":"meu-token-de-usuário",
   "password":"mypassword"
}
HTTP/1.1 200 OK
Content-Type: application/json
curl -H "Content-type:application/json" \\
      https://api.ipay.net.br/v1/signin \\
      -d '{
             "token": "meu-token-de-usuário",
             "password": "mypassword"
          }'

Exemplo de resposta:

{
  "token_type": "bearer",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3OD",
  "expires_in": "15m",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3OD",
}

Requisição HTTP

POST https://api.ipay.net.br/v1/signin

Parâmetros da requisição

Parâmetro Tipo Obrigatório Exemplo Descrição
token String Sim "token-de-cliente" Token de cliente(criado no dashboard do Ipay).
password String Sim "minha-senha" Senha de usuário

Resultado

Chave Tipo Exemplo Descrição
token_type String "bearer" Tipo do token
access_token String "tokendeacesso" Token de acesso
expires_in String "15m" Segundos ou uma string descrevendo um intervalo de tempo
refresh_token String "refreshtoken Token para renovar o token de acesso

Erros

Status HTTP Mensagem
400 Por favor verifique os parâmetros
404 Usuário não encontrado

Renovar token de acesso

Renova os tokens do usuário, invalidando os antigos.

POST /v1/refresh-token HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Host: api.ipay.net.br
{
   "refresh-token": "meu-refresh-token"
}
HTTP/1.1 200 OK
Content-Type: application/json
curl -H "Content-type:application/json" \
      https://api.ipay.net.br/v1/refresh-token \
      -d '{
             "refreshToken": "meu-refresh-token",
          }'

Exemplo de resposta:

{
  "token_type": "bearer",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3OD",
  "expires_in": "15m",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3OD",
}

Requisição HTTP

POST https://api.ipay.net.br/v1/refresh-token

Parâmetros da requisição

Parâmetro Tipo Obrigatório Exemplo Descrição
refresh-token String Sim "meu-refresh-token" Refresh token, retornado no processo de SignIn.

Resultado

Chave Tipo Exemplo Descrição
token_type String "bearer" Tipo do token
access_token String "tokendeacesso" Token de acesso
expires_in String "15m" Segundos ou uma string descrevendo um intervalo de tempo
refresh_token String "refreshtoken Token para renovar o token de acesso

Erros

Status HTTP Mensagem
400 Por favor verifique os parâmetros
401 Refresh token utilizado anteriormente.

Revogar tokens

Revoga o token fornecido.

POST /v1/revoke-token HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Host: api.ipay.net.br
{
   "type": "access",
   "token": "meu-token"
}
HTTP/1.1 200 OK
Content-Type: application/json
curl -H "Content-type:application/json" </span>
      https://api.ipay.net.br/v1/revoke-token </span>
      -d '{
            "type": "access",
            "token": "meu-token"
           }'

Requisição HTTP

POST https://api.ipay.net.br/v1/revoke-token

Parâmetros da requisição

Parâmetro Tipo Obrigatório Exemplo Descrição
token String Sim "meu-token" Refresh token, retornado no processo de SignIn.
type String Sim "access" Ou "refresh" Tipo do token que deve ser revogado.

Resultado

Vazio

Erros

Status HTTP Mensagem
400 Por favor verifique os parâmetros
400 Tipo de token inválido.

Clientes para faturar

Nessa seção você encontra os endpoints referentes aos seus clientes para faturar.

Abaixo segue a lista de endpoints relacionadas à clientes para faturar.

Endpoint Método Resumo Detalhes
/v1/billing-customers POST Cadastra um cliente para faturar Link
/v1/billing-customers/TOKEN_DO_CLIENTE_PARA_FATURAR PUT Atualiza um cliente para faturar pelo token Link
/v1/billing-customers/TOKEN_DO_CLIENTE_PARA_FATURAR DELETE Deleta um cliente para faturar pelo token Link
/v1/billing-customers/TOKEN_DO_CLIENTE_PARA_FATURAR GET Recupera um cliente para faturar pelo token Link
/v1/billing-customers GET Recupera uma lista de clientes para faturar Link

Cadastrar um cliente para faturar

Cadastra um novo cliente para faturar.

POST /v1/billing-customers HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Token: SEU_TOKEN_DE_CLIENTE
Host: api.ipay.net.br
{
    "billingCustomer": {
        "initialBillingDate": "2019-04-12",
        "name": "test",
        "cpfCnpj": "25.071.205/0001-99",
        "email": "a@a.com",
        "emailIsActive": true,
        "zipcode": "92420-000",
        "address": "rua exemplo",
        "addressNumber": "500",
        "addressComplement": "bloco 25, AP 207",
        "neighborhood":" Sarandi",
        "city": "Porto Alegre",
        "state": "RS",
        "phone": "955451515",
        "phone2": "955451515",
        "cellPhone": "955451515",
        "dueDate": "02",
        "calculateLatePayment": true,
        "mode": "automatico",
        "typePayment": "boleto",
    }
}
HTTP/1.1 200 OK
Content-Type: application/json
curl -H "Content-type:application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiQ3hlQktwdjRQWW9WcmpacH" \
     -H "Token: 22138bdb667c98ba749912d0717248d7" \
      https://api.ipay.net.br/v1/billing-customers \
      -d '{
            "billingCustomer": {
                "initialBillingDate": "2019-04-12",
                "name": "test",
                "cpfCnpj": "25.071.205/0001-99",
                "email": "a@a.com",
                "emailIsActive": true,
                "zipcode": "92420-000",
                "address": "rua exemplo",
                "addressNumber": "500",
                "addressComplement": "bloco 25, AP 207",
                "neighborhood":" Sarandi",
                "city": "Porto Alegre",
                "state": "RS",
                "phone": "955451515",
                "phone2": "955451515",
                "cellPhone": "955451515",
                "dueDate": "02",
                "calculateLatePayment": true,
                "mode": "automatico",
                "typePayment": "boleto",
            }
        }'

Exemplo de resposta:

{
    "billingCustomer": {
        "situation": "novo",
        "lastBillingDate": null,
        "initialBillingDate": "2019-04-12",
        "lastPaymentDate": "0000-00-00",
        "mode": "automatico",
        "typePayment": "boleto",
        "name": "test",
        "cpfCnpj": "25071205000199",
        "email": "a@a.com",
        "emailIsActive": true,
        "zipcode": "92420000",
        "address": "rua exemplo",
        "addressNumber": "500",
        "addressComplement": "bloco 25, AP 207",
        "neighborhood": " Sarandi",
        "city": "Porto Alegre",
        "state": "RS",
        "phone": "955451515",
        "phone2": "955451515",
        "cellPhone": "955451515",
        "dueDate": "02",
        "calculateLatePayment": true,
        "token": "0b7fb410b9d81bc23b90e981331316c6",
        "createdAt": "2019-06-16"
    }
}

Requisição HTTP

POST https://api.ipay.net.br/v1/billing-customers

Parâmetros da requisição (Body)

Parâmetro Tipo Obrigatório Exemplo Descrição
billingCustomer.name String Sim "Fulano" Nome do cliente ou empresa para faturar.
billingCustomer.cpfCnpj String Sim (CPF ou CNPJ) "67.541.847/0001-54" CNPJ ou CPF do cliente para faturar.
billingCustomer.email String Não "email@a.com" Email do cliente para faturar.
billingCustomer.emailIsActive Boolean Não true Se o email está ativo.
billingCustomer.zipcode String Sim "92420-270" CEP (código postal).
billingCustomer.address String Sim "Rua tal" Nome da rua.
billingCustomer.addressNumber String Sim "458" Número da residência.
billingCustomer.addressComplement String Não "Ap 345" Complemento do endereço.
billingCustomer.neighborhood String Sim "Bairro centro" Nome do bairro.
billingCustomer.city String Sim "Porto Alegre" Nome da cidade.
billingCustomer.state String Sim "RS" UF.
billingCustomer.phone String Sim "51999999999" Telefone.
billingCustomer.phone2 String Não "51999999999" Telefone extra.
billingCustomer.cellPhone String Não "51999999999" Telefone celular.
billingCustomer.dueDate String Sim "05" Dia do vencimento.
billingCustomer.calculateLatePayment Boolean Sim true Se deve calcular o atraso do cliente.
billingCustomer.mode String Sim "normal" Tipo do cliente para faturar. (Tipos)
billingCustomer.initialBillingDate String Sim "2019-04-30" Data de início da cobrança.
billingCustomer.typePayment String Não "boleto" Tipo de pagamento do cliente.(Tipos)

Resultado

Objeto cliente para faturar.

Erros

Status HTTP Mensagem
400 Por favor verifique os parâmetros
400 Tipo de data inválido. Deve ser igual a ISOString.
400 Email Inválido.
400 CPF ou CNPJ Inválido.
403 Token de cliente inválido.

Atualizar um cliente para faturar pelo token

Atualiza um cliente para faturar.

PUT /v1/billing-customers/fd4ff8058dae914b5bafa4fd7f8a73fb HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Token: SEU_TOKEN_DE_CLIENTE
Host: api.ipay.net.br
{
    "billingCustomer": {
        "initialBillingDate": "2019-04-12",
        "name": "test",
        "cnpj": "25.071.205/0001-99",
        "email": "a@a.com",
        "emailIsActive": true,
        "zipcode": "92420-000",
        "address": "rua exemplo",
        "addressNumber": "500",
        "addressComplement": "bloco 25, AP 207",
        "neighborhood":" Sarandi",
        "city": "Porto Alegre",
        "state": "RS",
        "phone": "955451515",
        "phone2": "955451515",
        "cellPhone": "955451515",
        "dueDate": "02",
        "calculateLatePayment": true,
        "mode": "automatico"
    }
}
HTTP/1.1 200 OK
Content-Type: application/json
curl -X PUT \
     -H "Content-type:application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiQ3hlQktwdjRQWW9WcmpacH" \
     -H "Token: 22138bdb667c98ba749912d0717248d7" \
      https://api.ipay.net.br/v1/billing-customers/fd4ff8058dae914b5bafa4fd7f8a73fb \
      -d '{
            "billingCustomer": {
                "initialBillingDate": "2019-04-12",
                "name": "test",
                "cnpj": "25.071.205/0001-99",
                "email": "a@a.com",
                "emailIsActive": true,
                "zipcode": "92420-000",
                "address": "rua exemplo",
                "addressNumber": "500",
                "addressComplement": "bloco 25, AP 207",
                "neighborhood":" Sarandi",
                "city": "Porto Alegre",
                "state": "RS",
                "phone": "955451515",
                "phone2": "955451515",
                "cellPhone": "955451515",
                "dueDate": "02",
                "calculateLatePayment": true,
                "mode": "automatico"
            }
        }'

Exemplo de resposta:

{
    "billingCustomer": {
        "situation": "novo",
        "lastBillingDate": null,
        "initialBillingDate": "2019-04-12",
        "lastPaymentDate": "0000-00-00",
        "mode": "automatico",
        "typePayment": "boleto",
        "name": "test",
        "cpfCnpj": "25071205000199",
        "email": "a@a.com",
        "emailIsActive": true,
        "zipcode": "92420000",
        "address": "rua exemplo",
        "addressNumber": "500",
        "addressComplement": "bloco 25, AP 207",
        "neighborhood": " Sarandi",
        "city": "Porto Alegre",
        "state": "RS",
        "phone": "955451515",
        "phone2": "955451515",
        "cellPhone": "955451515",
        "dueDate": "02",
        "calculateLatePayment": true,
        "token": "0b7fb410b9d81bc23b90e981331316c6",
        "createdAt": "2019-06-16"
    }
}

Requisição HTTP

PUT https://api.ipay.net.br/v1/billing-customers/TOKEN_DO_CLIENTE_PARA_FATURAR

Parâmetros da requisição (URL)

Parâmetro Tipo Obrigatório Exemplo Descrição
token String Sim "fd4ff8058dae914b5bafa4fd7f8a73fb" Token do cliente ou empresa para faturar.

Parâmetros da requisição (Body)

Parâmetro Tipo Obrigatório Exemplo Descrição
billingCustomer.name String Não "Fulano" Nome do cliente ou empresa para faturar.
billingCustomer.cnpj String Não "67.541.847/0001-54" CNPJ da empresa para faturar.
billingCustomer.cpf String Não "123.456.789-10" Cpf do cliente para faturar.
billingCustomer.email String Não "email@a.com" Email do cliente para faturar.
billingCustomer.emailIsActive Boolean Não true Se o email está ativo.
billingCustomer.zipcode String Não "92420-270" CEP (código postal).
billingCustomer.address String Não "Rua tal" Nome da rua.
billingCustomer.addressNumber String Não "458" Número da residência.
billingCustomer.addressComplement String Não "Ap 345" Complemento do endereço.
billingCustomer.neighborhood String Não "Bairro centro" Nome do bairro.
billingCustomer.city String Não "Porto Alegre" Nome da cidade.
billingCustomer.state String Não "RS" UF.
billingCustomer.phone String Não "51999999999" Telefone.
billingCustomer.phone2 String Não "51999999999" Telefone extra.
billingCustomer.cellPhone String Não "51999999999" Telefone celular.
billingCustomer.dueDate String Não "05" Dia do vencimento.
billingCustomer.calculateLatePayment Boolean Não true Se deve calcular o atraso do cliente.
billingCustomer.mode String Não "normal" Tipo do cliente para faturar. (Tipos)
billingCustomer.initialBillingDate String Não "2019-04-30" Data de início da cobrança.

Resultado

Objeto cliente para faturar.

Erros

Status HTTP Mensagem
400 Por favor verifique os parâmetros
400 Tipo de data inválido. Deve ser igual a ISOString.
400 Email Inválido.
400 CPF ou CNPJ Inválido.
403 Token de cliente inválido.
404 Cliente para faturar não encontrado.

Recuperar uma lista de clientes para faturar

Retorna uma lista de clientes para faturar. Este endpoint suporta parâmetros de paginação.

GET /v1/billing-customers HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Host: api.ipay.net.br
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Token: SEU_TOKEN_DE_CLIENTE
HTTP/1.1 200 OK
Content-Type: application/json
curl -H "Content-type:application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiQ3hlQktwdjRQWW9WcmpacH" \
     -H "Token: 22138bdb667c98ba749912d0717248d7" \
      https://api.ipay.net.br/v1/billing-customers \

Exemplo de resposta:

{
    "billingCustomers": [
        {
            "situation": "novo",
            "lastBillingDate": null,
            "initialBillingDate": "2019-04-12",
            "lastPaymentDate": "0000-00-00",
            "mode": "automatico",
            "typePayment": "boleto",
            "name": "test",
            "cpfCnpj": "25071205000199",
            "email": "a@a.com",
            "emailIsActive": true,
            "zipcode": "92420000",
            "address": "rua exemplo",
            "addressNumber": "500",
            "addressComplement": "bloco 25, AP 207",
            "neighborhood": " Sarandi",
            "city": "Porto Alegre",
            "state": "RS",
            "phone": "955451515",
            "phone2": "955451515",
            "cellPhone": "955451515",
            "dueDate": "02",
            "calculateLatePayment": true,
            "token": "0b7fb410b9d81bc23b90e981331316c6",
            "createdAt": "2019-06-16"
        }
    ],
    "total": 6,
    "skipped": 2,
    "count": 1
}

Requisição HTTP

GET https://api.ipay.net.br/v1/billing-customers

Parâmetros da requisição (URL)

Nenhum

Resultado

Uma lista de objetos de clientes para faturar.

Erros

Status HTTP Mensagem
403 Token de cliente inválido.

Recuperar um cliente para faturar pelo token

Retorna um cliente para faturar.

GET /v1/billing-customers/fd4ff8058dae914b5bafa4fd7f8a73fb HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Host: api.ipay.net.br
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Token: SEU_TOKEN_DE_CLIENTE
HTTP/1.1 200 OK
Content-Type: application/json
curl -H "Content-type:application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiQ3hlQktwdjRQWW9WcmpacH" \
     -H "Token: 22138bdb667c98ba749912d0717248d7" \
      https://api.ipay.net.br/v1/billing-customers/fd4ff8058dae914b5bafa4fd7f8a73fb \

Exemplo de resposta:

{
    "billingCustomer": {
        "situation": "novo",
        "lastBillingDate": null,
        "initialBillingDate": "2019-04-12",
        "lastPaymentDate": "0000-00-00",
        "mode": "automatico",
        "typePayment": "boleto",
        "name": "test",
        "cpfCnpj": "25071205000199",
        "email": "a@a.com",
        "emailIsActive": true,
        "zipcode": "92420000",
        "address": "rua exemplo",
        "addressNumber": "500",
        "addressComplement": "bloco 25, AP 207",
        "neighborhood": " Sarandi",
        "city": "Porto Alegre",
        "state": "RS",
        "phone": "955451515",
        "phone2": "955451515",
        "cellPhone": "955451515",
        "dueDate": "02",
        "calculateLatePayment": true,
        "token": "0b7fb410b9d81bc23b90e981331316c6",
        "createdAt": "2019-06-16"
    }
}

Requisição HTTP

GET https://api.ipay.net.br/v1/billing-customers/TOKEN_DO_CLIENTE_PARA_FATURAR

Parâmetros da requisição (URL)

Parâmetro Tipo Obrigatório Exemplo Descrição
token String Sim "fd4ff8058dae914b5bafa4fd7f8a73fb" Token do cliente ou empresa para faturar.

Resultado

Objeto cliente para faturar.

Erros

Status HTTP Mensagem
400 Por favor verifique os parâmetros
403 Token de cliente inválido.
404 Cliente para faturar não encontrado.

Deletar um cliente para faturar pelo token

Deleta um cliente para faturar.

DELETE /v1/billing-customers/fd4ff8058dae914b5bafa4fd7f8a73fb HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Host: api.ipay.net.br
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Token: SEU_TOKEN_DE_CLIENTE
HTTP/1.1 200 OK
Content-Type: application/json
curl -X DELETE \
     -H "Content-type:application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiQ3hlQktwdjRQWW9WcmpacH" \
     -H "Token: 22138bdb667c98ba749912d0717248d7" \
      https://api.ipay.net.br/v1/billing-customers/fd4ff8058dae914b5bafa4fd7f8a73fb \

Exemplo de resposta:

Requisição HTTP

DELETE https://api.ipay.net.br/v1/billing-customers/TOKEN_DO_CLIENTE_PARA_FATURAR

Parâmetros da requisição (URL)

Parâmetro Tipo Obrigatório Exemplo Descrição
token String Sim "fd4ff8058dae914b5bafa4fd7f8a73fb" Token do cliente ou empresa para faturar.

Resultado

Vazio.

Erros

Status HTTP Mensagem
400 Por favor verifique os parâmetros
403 Token de cliente inválido.
404 Cliente para faturar não encontrado.

Tipos de clientes para faturar

Os clientes para faturar podem ser de algum dos tipos descritos abaixo:

Tipo Valor Descrição
Normal "normal" Pagamentos normais.
Pausado "pausado" Se a recorrência está pausada.
Automático "automatico" Se a cobrança é automática.
Manual "manual" Se a cobrança é manual.
Cancelado "cancelado" Se a cobrança foi cancelada.

Tipos de pagamentos de clientes

Os clientes para faturar podem ter alguns dos tipos de pagamento descritos abaixo:

Tipo Valor Descrição
Boleto "boleto" Se o pagamento será em boleto.
Cartão "cartao" Se o pagamento será com cartão.

Situações de clientes para faturar

Os clientes para faturar podem fazer parte de alguma das situações descritas abaixo:

Tipo Valor Descrição
Reprocessar "reprocessar" Se deverá reprocessar o pagamento.
Processando "processando" Se está processando.
Novo "novo" Se é um cliente novo.
Processado "processado" Se o cliente já foi processado.

Objeto cliente para faturar

O objeto de um cliente fatura pode ser definido como abaixo:

Exemplo do objeto de cliente para faturar:

{
    "billingCustomer": {
        "situation": "novo",
        "lastBillingDate": null,
        "initialBillingDate": "2019-04-12",
        "lastPaymentDate": "0000-00-00",
        "mode": "automatico",
        "typePayment": "boleto",
        "name": "test",
        "cpfCnpj": "25071205000199",
        "email": "a@a.com",
        "emailIsActive": true,
        "zipcode": "92420000",
        "address": "rua exemplo",
        "addressNumber": "500",
        "addressComplement": "bloco 25, AP 207",
        "neighborhood": " Sarandi",
        "city": "Porto Alegre",
        "state": "RS",
        "phone": "955451515",
        "phone2": "955451515",
        "cellPhone": "955451515",
        "dueDate": "02",
        "calculateLatePayment": true,
        "token": "0b7fb410b9d81bc23b90e981331316c6",
        "createdAt": "2019-06-16"
    }
}
Chave Tipo Exemplo de valor Descrição
situation String "novo" Situação do cliente (Situações).
lastBillingDate String "2019-04-30" Data do último faturamento.
initialBillingDate String "2019-04-30" Data de inicio da cobrança.
lastPaymentDate String "2019-04-30" Data do último pagamento.
mode String "normal" Tipo do cliente. (Tipos).
typePayment String "boleto" Tipo do cliente. (Tipos).
name String "Fulano" Nome do cliente para faturar.
cpfCnpj String "25.071.205/0001-99" CNPJ ou CPF do cliente para faturar.
email String "email@email.com" Email do cliente para faturar.
emailIsActive Boolean true Se o email está ativo.
zipcode String "92420-000" CEP (código postal).
address String "Rua tal" Nome da rua.
addressNumber String "405" Número da residência.
addressComplement String "Ap 345" Complemento do endereço.
neighborhood String "Bairro centro" Nome do bairro.
city String "Porto Alegre" Nome da cidade.
state String "RS" UF.
phone String "51999999999" Telefone.
phone2 String "51999999999" Telefone extra.
cellPhone String "51999999999" Telefone celular.
dueDate String "05" Dia do vencimento.
calculateLatePayment Boolean true Se deve calcular o atraso do cliente.
token String "fd4ff8058dae914b5ba73fb" Identificador do cliente para faturar.
createdAt String "2019-04-30" Data em que foi criado o cliente.

Cartões

Nessa seção você encontra os endpoints referentes aos cartões de seus clientes para faturar.

Abaixo segue a lista de endpoints relacionadas aos cartões.

Endpoint Método Resumo Detalhes
/v1/cards POST Cadastra um cartão de um cliente para faturar Link
/v1/cards/TOKEN_DO_CARTAO PUT Atualiza um cartão de um cliente para faturar Link
/v1/cards/TOKEN_DO_CARTAO GET Recupera um cartão pelo token Link
/v1/cards/billing-customer/TOKEN_DO_CLIENTE_PARA_FATURAR GET Recupera uma lista de cartões de um cliente Link

Cadastrar um cartão

Cadastra um novo cartão de um cliente para faturar.

POST /v1/cards HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Token: SEU_TOKEN_DE_CLIENTE
Host: api.ipay.net.br
{
    "card": {
        "number": "5419546764260333",
        "month": "03",
        "year": "26",
        "brand": "MasterCard",
        "name": "TESTE T T TESTE",
        "securityCode": "123",
        "status": "primary",
        "customer": "ae8da5c174cdcdb7a34ed9085fd7c426"
    }
}
HTTP/1.1 200 OK
Content-Type: application/json
curl -H "Content-type:application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiQ3hlQktwdjRQWW9WcmpacH" \
     -H "Token: 22138bdb667c98ba749912d0717248d7" \
      https://api.ipay.net.br/v1/cards \
      -d '{
        "card": {
            "number": "5419546764260333",
            "month": "03",
            "year": "26",
            "brand": "MasterCard",
            "name": "TESTE T T TESTE",
            "securityCode": "123",
            "status": "primary",
            "customer": "ae8da5c174cdcdb7a34ed9085fd7c426"
        }
    }'

Exemplo de resposta:

{
    "card": {
        "number": "...0333",
        "month": "03",
        "year": "26",
        "token": "b9c79510171e4c27aae5f4df19a02ffe",
        "brand": "MasterCard",
        "name": "TESTE T T TESTE",
        "status": "primary",
        "createdAt": "2019-06-22"
    }
}

Requisição HTTP

POST https://api.ipay.net.br/v1/cards

Parâmetros da requisição (Body)

Parâmetro Tipo Obrigatório Exemplo Descrição
card.number String Sim "5419546764260333" Número do cartão.
card.month String Sim "12" Mês de validade (2 dígitos).
card.year String Sim "27" Ano de validade. (2 dígitos)
card.brand String Sim "VISA" Bandeira do cartão.
card.name String Sim "FULANO DE TAL" Nome(como está no cartão).
card.secutiryCode String Sim "123" Código de segurança.
card.status String Sim "primary" Status do cartão (Status de cartões).
card.customer String Sim "ae8da5c174cdcdb7a34ed9085fd7c426" Token do cliente para faturar que o cartão pertence.

Resultado

Objeto cartão.

Erros

Status HTTP Mensagem
400 Por favor verifique os parâmetros
400 Expiração do cartão inválida.
400 Número do cartão inválido.
400 CVV do cartão inválido.
400 Status do cartão inválido.
400 Cartão inválido.
403 Cliente para faturar não encontrado.
403 Token de cliente inválido.

Recuperar uma lista de cartões

Retorna uma lista de cartões de um cliente para faturar. Este endpoint suporta parâmetros de paginação.

GET /v1/cards/billing-customer/TOKEN-DO-CLIENTE-PARA-FATURAR HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Host: api.ipay.net.br
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Token: SEU_TOKEN_DE_CLIENTE
HTTP/1.1 200 OK
Content-Type: application/json
curl -H "Content-type:application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiQ3hlQktwdjRQWW9WcmpacH" \
     -H "Token: 22138bdb667c98ba749912d0717248d7" \
      https://api.ipay.net.br/v1/cards/billing-customer/0b7fb410b9d81bc23b90e981331316c6 \

Exemplo de resposta:

{
    "cards": [
        {
            "number": "...0782",
            "month": "12",
            "year": "25",
            "token": "279s6510171e4c27aae5f4df19a02ffe",
            "brand": "Visa",
            "name": "TESTE TESTE",
            "status": "secondary",
            "createdAt": "2019-06-15"
        },
        {
            "number": "...0333",
            "month": "03",
            "year": "26",
            "token": "b9c79510171e4c27aae5f4df19a02ffe",
            "brand": "MasterCard",
            "name": "TESTE T T TESTE",
            "status": "primary",
            "createdAt": "2019-06-22"
        }
    ],
    "total": 2,
    "skipped": 0,
    "count": 2
}

Requisição HTTP

GET https://api.ipay.net.br/v1/cards/billing-customer/TOKEN-DO-CLIENTE-PARA-FATURAR

Parâmetros da requisição (URL)

Parâmetro Tipo Obrigatório Exemplo Descrição
token do cliente String Sim "fd4ff8058dae914b5bafa4fd7f8a73fb" Token do cliente ou empresa para faturar.

Resultado

Uma lista de objetos de cartões.

Erros

Status HTTP Mensagem
403 Token de cliente inválido.
403 Cliente para faturar não encontrado.

Recuperar um cartão pelo token

Retorna um cartão.

GET /v1/cards/fd4ff8058dae914b5bafa4fd7f8a73fb HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Host: api.ipay.net.br
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Token: SEU_TOKEN_DE_CLIENTE
HTTP/1.1 200 OK
Content-Type: application/json
curl -H "Content-type:application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiQ3hlQktwdjRQWW9WcmpacH" \
     -H "Token: 22138bdb667c98ba749912d0717248d7" \
      https://api.ipay.net.br/v1/cards/fd4ff8058dae914b5bafa4fd7f8a73fb \

Exemplo de resposta:

{
    "card": {
        "number": "...0333",
        "month": "03",
        "year": "26",
        "token": "b9c79510171e4c27aae5f4df19a02ffe",
        "brand": "MasterCard",
        "name": "TESTE T T TESTE",
        "status": "primary",
        "createdAt": "2019-06-22"
    }
}

Requisição HTTP

GET https://api.ipay.net.br/v1/cards/TOKEN_DO_CARTAO

Parâmetros da requisição (URL)

Parâmetro Tipo Obrigatório Exemplo Descrição
token String Sim "fd4ff8058dae914b5bafa4fd7f8a73fb" Token do cartão.

Resultado

Objeto cartão.

Erros

Status HTTP Mensagem
400 Por favor verifique os parâmetros
403 Token de cliente inválido.
404 Cartão não encontrado.

Atualizar um cartão pelo token

Atualiza um cartão.

PUT /v1/cards/fd4ff8058dae914b5bafa4fd7f8a73fb HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Token: SEU_TOKEN_DE_CLIENTE
Host: api.ipay.net.br
{
    "card": {
        "number": "5419546764260333",
        "month": "03",
        "year": "26",
        "brand": "MasterCard",
        "name": "TESTE T T TESTE",
        "securityCode": "123",
        "status": "primary",
        "customer": "ae8da5c174cdcdb7a34ed9085fd7c426"
    }
}
HTTP/1.1 200 OK
Content-Type: application/json
curl -X PUT \
     -H "Content-type:application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiQ3hlQktwdjRQWW9WcmpacH" \
     -H "Token: 22138bdb667c98ba749912d0717248d7" \
      https://api.ipay.net.br/v1/cards/fd4ff8058dae914b5bafa4fd7f8a73fb \
      -d '{
            "card": {
                "number": "5419546764260333",
                "month": "03",
                "year": "26",
                "brand": "MasterCard",
                "name": "TESTE T T TESTE",
                "securityCode": "123",
                "status": "primary",
                "customer": "ae8da5c174cdcdb7a34ed9085fd7c426"
            }
        }'

Exemplo de resposta:

{
    "card": {
        "number": "...0333",
        "month": "03",
        "year": "26",
        "token": "b9c79510171e4c27aae5f4df19a02ffe",
        "brand": "MasterCard",
        "name": "TESTE T T TESTE",
        "status": "primary",
        "createdAt": "2019-06-22"
    }
}

Requisição HTTP

PUT https://api.ipay.net.br/v1/cards/TOKEN_DO_CARTAO

Parâmetros da requisição (URL)

Parâmetro Tipo Obrigatório Exemplo Descrição
token String Sim "fd4ff8058dae914b5bafa4fd7f8a73fb" Token do cartão.

Parâmetros da requisição (Body)

Parâmetro Tipo Obrigatório Exemplo Descrição
card.number String Sim "5419546764260333" Número do cartão.
card.month String Sim "12" Mês de validade (2 dígitos).
card.year String Sim "27" Ano de validade. (2 dígitos)
card.brand Boolean Sim "VISA" Bandeira do cartão.
card.name String Sim "FULANO DE TAL" Nome(como está no cartão).
card.secutiryCode String Sim "123" Código de segurança.
card.status String Sim "primary" Status do cartão (Status de cartões).
card.customer String Sim "ae8da5c174cdcdb7a34ed9085fd7c426" Token do cliente para faturar que o cartão pertence.

Resultado

Objeto cartão.

Erros

Status HTTP Mensagem
400 Por favor verifique os parâmetros
400 Expiração do cartão inválida.
400 Status do cartão inválido.
400 Número do cartão inválido.
400 CVV do cartão inválido.
400 Cartão inválido.
403 Cliente para faturar não encontrado.
403 Token de cliente inválido.

Status de cartões

Os cartões dos clientes para faturar podem ter os status descritos abaixo:

Tipo Valor Descrição
Primário "primary" Cartão primário.
Secundário "secondary" Cartão secundário.

Objeto cartão

O objeto de um cartão de um cliente fatura pode ser definido como abaixo:

Exemplo do objeto de cartão:

{
    "card": {
        "number": "...0333",
        "month": "03",
        "year": "26",
        "token": "b9c79510171e4c27aae5f4df19a02ffe",
        "brand": "MasterCard",
        "name": "TESTE T T TESTE",
        "status": "primary",
        "createdAt": "2019-06-22"
    }
}
Chave Tipo Exemplo de valor Descrição
number String "...1234" Últimos 4 dígitos do cartão
month String "08" Mês de validade.
year String "28" Ano de validade.
brand String "Visa" Bandeira do cartão.
name String "TESTE T T TESTE" Nome do cliente (como está no cartão)
status String "primary" Status do cartão (Status de cartões).
token String "fd4ff8058dae914b5ba73fb" Identificador do cartão.
createdAt String "2019-04-30" Data em que foi cadastrado.

Serviços

Nessa seção você encontra os endpoints referentes aos serviços.

Abaixo segue a lista de endpoints relacionadas aos serviços.

Endpoint Método Resumo Detalhes
/v1/services POST Cadastra um novo serviço Link
/v1/services/TOKEN_DO_SERVICO PUT Atualiza um serviço Link
/v1/services/TOKEN_DO_SERVICO DELETE Deleta um serviço pelo token Link
/v1/services/TOKEN_DO_SERVICO GET Recupera um serviço pelo token Link
/v1/services GET Recupera uma lista de serviços do cliente Link

Cadastrar um serviço

Cadastra um novo serviço.

POST /v1/services HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Token: SEU_TOKEN_DE_CLIENTE
Host: api.ipay.net.br
{
    "service": {
        "price": 1222,
        "description": "TESTE API",
        "status": "active"
    }
}
HTTP/1.1 200 OK
Content-Type: application/json
curl -H "Content-type:application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiQ3hlQktwdjRQWW9WcmpacH" \
     -H "Token: 22138bdb667c98ba749912d0717248d7" \
      https://api.ipay.net.br/v1/services \
      -d '{
            "service": {
                "price": 1222,
                "description": "TESTE API",
                "status": "active"
            }
        }'

Exemplo de resposta:

{
    "service": {
        "description": "TESTE API",
        "price": "1222",
        "status": "inactive",
        "createdAt": "2019-06-23",
        "token": "5d9d7b5aac1a8340cd6498dda5d0a73a"
    }
}

Requisição HTTP

POST https://api.ipay.net.br/v1/services

Parâmetros da requisição (Body)

Parâmetro Tipo Obrigatório Exemplo Descrição
service.price String Sim "1000" Valor do serviço (Valor do Serviço).
service.description String Sim "Descrição do meu serviço" Descrição do serviço.
service.status String Sim "active" Status do serviço (Status de serviços).

Resultado

Objeto serviço.

Erros

Status HTTP Mensagem
400 Por favor verifique os parâmetros
400 A descrição do serviço deve ter no máximo 100 caracteres.
400 Status do serviço inválido.
403 Token de cliente inválido.

Recuperar um serviço pelo token

Retorna um serviço.

GET /v1/services/fd4ff8058dae914b5bafa4fd7f8a73fb HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Host: api.ipay.net.br
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Token: SEU_TOKEN_DE_CLIENTE
HTTP/1.1 200 OK
Content-Type: application/json
curl -H "Content-type:application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiQ3hlQktwdjRQWW9WcmpacH" \
     -H "Token: 22138bdb667c98ba749912d0717248d7" \
      https://api.ipay.net.br/v1/services/fd4ff8058dae914b5bafa4fd7f8a73fb \

Exemplo de resposta:

{
    "service": {
        "description": "TESTE API",
        "price": "1222",
        "status": "inactive",
        "createdAt": "2019-06-23",
        "token": "5d9d7b5aac1a8340cd6498dda5d0a73a"
    }
}

Requisição HTTP

GET https://api.ipay.net.br/v1/services/TOKEN_DO_CARTAO

Parâmetros da requisição (URL)

Parâmetro Tipo Obrigatório Exemplo Descrição
token String Sim "fd4ff8058dae914b5bafa4fd7f8a73fb" Token do serviço.

Resultado

Objeto serviço.

Erros

Status HTTP Mensagem
400 Por favor verifique os parâmetros
403 Token de cliente inválido.
404 Serviço não encontrado.

Recuperar uma lista de serviços

Retorna uma lista de serviços do cliente. Este endpoint suporta parâmetros de paginação.

GET /v1/services HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Host: api.ipay.net.br
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Token: SEU_TOKEN_DE_CLIENTE
HTTP/1.1 200 OK
Content-Type: application/json
curl -H "Content-type:application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiQ3hlQktwdjRQWW9WcmpacH" \
     -H "Token: 22138bdb667c98ba749912d0717248d7" \
      https://api.ipay.net.br/v1/services \

Exemplo de resposta:

{
    "services": [
        {
            "description": "TESTE API",
            "price": "1223",
            "status": "inactive",
            "createdAt": "2019-06-23",
            "token": null
        }
    ],
    "total": 50,
    "skipped": 1,
    "count": 1
}

Requisição HTTP

GET https://api.ipay.net.br/v1/services

Parâmetros da requisição (URL)

Vazio

Resultado

Uma lista de objetos de serviços.

Erros

Status HTTP Mensagem
403 Token de cliente inválido.

Atualizar um serviço pelo token

Atualiza um serviço.

PUT /v1/services/fd4ff8058dae914b5bafa4fd7f8a73fb HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Token: SEU_TOKEN_DE_CLIENTE
Host: api.ipay.net.br
{
    "service": {
        "price": 12622,
        "description": "UPDATED TESTE",
        "status": "active"
    }
}
HTTP/1.1 200 OK
Content-Type: application/json
curl -X PUT \
     -H "Content-type:application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiQ3hlQktwdjRQWW9WcmpacH" \
     -H "Token: 22138bdb667c98ba749912d0717248d7" \
      https://api.ipay.net.br/v1/services/fd4ff8058dae914b5bafa4fd7f8a73fb \
      -d '{
            "service": {
                "price": 12622,
                "description": "UPDATED TESTE",
                "status": "inactive"
            }
        }'

Exemplo de resposta:

{
    "service": {
        "description": "UPDATED TESTE",
        "price": "12622",
        "status": "active",
        "createdAt": "2019-06-23",
        "token": "9bdbb1281b5062342f256ee488427bfe"
    }
}

Requisição HTTP

PUT https://api.ipay.net.br/v1/services/TOKEN_DO_SERVICO

Parâmetros da requisição (URL)

Parâmetro Tipo Obrigatório Exemplo Descrição
token String Sim "fd4ff8058dae914b5bafa4fd7f8a73fb" Token do serviço.

Parâmetros da requisição (Body)

Parâmetro Tipo Obrigatório Exemplo Descrição
service.price String Não "1000" Valor do serviço (Valor do Serviço).
service.description String Não "Descrição do meu serviço" Descrição do serviço.
service.status String Não "active" Status do serviço (Status de serviços).

Resultado

Objeto serviço.

Erros

Status HTTP Mensagem
400 Por favor verifique os parâmetros
400 A descrição do serviço deve ter no máximo 100 caracteres.
400 Status do serviço inválido.
403 Token de cliente inválido.
404 Serviço não encontrado.

Deletar um serviço pelo token

Deleta um serviço.

DELETE /v1/services/fd4ff8058dae914b5bafa4fd7f8a73fb HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Host: api.ipay.net.br
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Token: SEU_TOKEN_DE_CLIENTE
HTTP/1.1 200 OK
Content-Type: application/json
curl -X DELETE \
     -H "Content-type:application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiQ3hlQktwdjRQWW9WcmpacH" \
     -H "Token: 22138bdb667c98ba749912d0717248d7" \
      https://api.ipay.net.br/v1/services/fd4ff8058dae914b5bafa4fd7f8a73fb \

Exemplo de resposta:

Requisição HTTP

DELETE https://api.ipay.net.br/v1/services/TOKEN_DO_SERVICO

Parâmetros da requisição (URL)

Parâmetro Tipo Obrigatório Exemplo Descrição
token String Sim "fd4ff8058dae914b5bafa4fd7f8a73fb" Token do serviço.

Resultado

Vazio.

Erros

Status HTTP Mensagem
400 Por favor verifique os parâmetros
403 Token de cliente inválido.
404 Serviço para faturar não encontrado.

Status de serviços

Os serviços dos clientes podem ter os status descritos abaixo:

Tipo Valor Descrição
Ativo "active" Se o serviço está ativo.
Inativo "inactive" Se o serviço está inativo.

Valores de serviços

Todos os valores enviados para a API, deverão estar formatados sem pontuação, como podemos ver no exemplo abaixo:

Valor do serviço 1000, corresponde à R$ 10,00 da mesma forma que 10000 equivale a R$100,00.

Objeto serviço

O objeto de um serviço de um cliente pode ser definido como abaixo:

Exemplo do objeto de serviço:

{
    "service": {
        "description": "TESTE API",
        "price": "1222",
        "status": "inactive",
        "createdAt": "2019-06-23",
        "token": "5d9d7b5aac1a8340cd6498dda5d0a73a"
    }
}
Chave Tipo Exemplo de valor Descrição
description String "TESTE API" Descrição do serviço.
price String "1000" Valor do serviço.
status String "active" Status do serviço (Status de serviços).
token String "5d9d7b5aac1a8340cd6498d" Identificador do serviço.
createdAt String "2019-04-30" Data em que foi cadastrado.

Faturas

Nessa seção você encontra os endpoints referentes as faturas.

Abaixo segue a lista de endpoints relacionadas as faturas.

Endpoint Método Resumo Detalhes
/v1/invoices POST Cadastra uma nova fatura Link
/v1/invoices/TOKEN_DA_FATURA PUT Atualiza um serviço Link
/v1/invoices/TOKEN_DA_FATURA DELETE Deleta um serviço pelo token Link
/v1/invoices/TOKEN_DA_FATURA GET Recupera uma fatura pelo token Link
/v1/invoices GET Recupera uma lista de faturas do cliente Link

Cadastrar uma fatura

Cadastra uma nova fatura.

POST /v1/invoices HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Token: SEU_TOKEN_DE_CLIENTE
Host: api.ipay.net.br
{
    "invoice": {
        "createdAt": "2019-04-30",
        "paymentType": "cartao",
        "price": "12121",
        "customer": "a1a43149-fa12-4f28-a4e9-a66762de5bbd"
    }
}
HTTP/1.1 200 OK
Content-Type: application/json
curl -H "Content-type:application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiQ3hlQktwdjRQWW9WcmpacH" \
     -H "Token: 22138bdb667c98ba749912d0717248d7" \
      https://api.ipay.net.br/v1/invoices \
      -d '{
            "invoice": {
                "createdAt": "2019-04-30",
                "paymentType": "cartao",
                "price": "1000",
                "customer": "a1a43149-fa12-4f28-a4e9-a66762de5bbd"
            }
        }'

Exemplo de resposta:

{
    "invoice": {
        "paymentType": "cartao",
        "status": "aberto",
        "createdAt": "2019-04-30",
        "type": "I",
        "invoiceNumber": "440",
        "dueDate": "30",
        "delayedDays": "0",
        "penaltyPrice": "0",
        "interestPrice": "0",
        "total": "1000",
        "price": "1000",
        "boletoBarcode": null,
        "returnedErrorCode": null,
        "returnedCodeAcquirer": null,
        "returnedMessage": null,
        "tid": null,
        "capture": null,
        "nsu": null,
        "paymentDate": null,
        "token": "8c5ee0fe356fd45ff06c129a10a4b334"
    }
}

Requisição HTTP

POST https://api.ipay.net.br/v1/invoices

Parâmetros da requisição (Body)

Parâmetro Tipo Obrigatório Exemplo Descrição
invoice.createdAt String Sim "2019-09-30" Data da fatura.
invoice.paymentType String Sim "cartao" Tipos de pagamento.(Tipos de pagamento).
invoice.price String Sim "1000" Valor da fatura. (Valor da Fatura).
invoice.customer String Sim "ae8da5c174cdcdb7a34ed9085fd7c426" Token do cliente para faturar que o cartão pertence.

Resultado

Objeto fatura.

Erros

Status HTTP Mensagem
400 Por favor verifique os parâmetros
400 Data da fatura inválida.
400 Tipo de pagamento inválido.
403 Token de cliente inválido.
404 Cliente para faturar não encontrado.

Recuperar uma fatura pelo token

Retorna uma fatura.

GET /v1/invoices/fd4ff8058dae914b5bafa4fd7f8a73fb HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Host: api.ipay.net.br
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Token: SEU_TOKEN_DE_CLIENTE
HTTP/1.1 200 OK
Content-Type: application/json
curl -H "Content-type:application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiQ3hlQktwdjRQWW9WcmpacH" \
     -H "Token: 22138bdb667c98ba749912d0717248d7" \
      https://api.ipay.net.br/v1/invoices/fd4ff8058dae914b5bafa4fd7f8a73fb \

Exemplo de resposta:

{
    "invoice": {
        "paymentType": "cartao",
        "price": "12121",
        "status": "aberto",
        "createdAt": "2019-04-30",
        "type": "I",
        "invoiceNumber": "452",
        "dueDate": "30",
        "delayedDays": "0",
        "penaltyPrice": "0",
        "interestPrice": "0",
        "total": "12121",
        "boletoBarcode": null,
        "returnedErrorCode": null,
        "returnedCodeAcquirer": null,
        "returnedMessage": null,
        "tid": null,
        "capture": null,
        "nsu": null,
        "paymentDate": null,
        "token": "befd099e290012c42eb899de23f61bc2"
    }
}

Requisição HTTP

GET https://api.ipay.net.br/v1/invoices/TOKEN_DO_CARTAO

Parâmetros da requisição (URL)

Parâmetro Tipo Obrigatório Exemplo Descrição
token String Sim "fd4ff8058dae914b5bafa4fd7f8a73fb" Token da fatura.

Resultado

Objeto fatura.

Erros

Status HTTP Mensagem
400 Por favor verifique os parâmetros
403 Token de cliente inválido.
404 Fatura não encontrada.

Deletar uma fatura pelo token

Deleta uma fatura.

DELETE /v1/invoices/fd4ff8058dae914b5bafa4fd7f8a73fb HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Host: api.ipay.net.br
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Token: SEU_TOKEN_DE_CLIENTE
HTTP/1.1 200 OK
Content-Type: application/json
curl -X DELETE \
     -H "Content-type:application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiQ3hlQktwdjRQWW9WcmpacH" \
     -H "Token: 22138bdb667c98ba749912d0717248d7" \
      https://api.ipay.net.br/v1/invoices/fd4ff8058dae914b5bafa4fd7f8a73fb \

Exemplo de resposta:

Requisição HTTP

DELETE https://api.ipay.net.br/v1/invoices/TOKEN_DA_FATURA

Parâmetros da requisição (URL)

Parâmetro Tipo Obrigatório Exemplo Descrição
token String Sim "fd4ff8058dae914b5bafa4fd7f8a73fb" Token da fatura.

Resultado

Vazio.

Erros

Status HTTP Mensagem
400 Por favor verifique os parâmetros
403 Token de cliente inválido.
404 Fatura não encontrada.

Recuperar uma lista de faturas

Retorna uma lista de faturas de um cliente para faturar. Este endpoint suporta parâmetros de paginação.

GET /v1/invoices/billing-customer/TOKEN-DO-CLIENTE-PARA-FATURAR HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Host: api.ipay.net.br
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Token: SEU_TOKEN_DE_CLIENTE
HTTP/1.1 200 OK
Content-Type: application/json
curl -H "Content-type:application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiQ3hlQktwdjRQWW9WcmpacH" \
     -H "Token: 22138bdb667c98ba749912d0717248d7" \
      https://api.ipay.net.br/v1/invoices/billing-customer/0b7fb410b9d81bc23b90e981331316c6 \

Exemplo de resposta:

{
    "invoices": [
        {
            "paymentType": null,
            "price": "100",
            "status": "Processamento",
            "createdAt": "2018-06-18",
            "type": "A",
            "invoiceNumber": "2",
            "dueDate": "18",
            "delayedDays": "0",
            "penaltyPrice": "0",
            "interestPrice": "0",
            "total": "100",
            "boletoBarcode": null,
            "returnedErrorCode": null,
            "returnedCodeAcquirer": null,
            "returnedMessage": null,
            "tid": null,
            "capture": null,
            "nsu": null,
            "paymentDate": "0000-00-00",
            "token": null
        },
        {
            "paymentType": null,
            "price": "100",
            "status": "Processamento",
            "createdAt": "2018-06-18",
            "type": "A",
            "invoiceNumber": "2",
            "dueDate": "18",
            "delayedDays": "0",
            "penaltyPrice": "0",
            "interestPrice": "0",
            "total": "100",
            "boletoBarcode": null,
            "returnedErrorCode": null,
            "returnedCodeAcquirer": null,
            "returnedMessage": null,
            "tid": null,
            "capture": null,
            "nsu": null,
            "paymentDate": "0000-00-00",
            "token": null
        }
    ],
    "total": 39,
    "skipped": 1,
    "count": 2
}

Requisição HTTP

GET https://api.ipay.net.br/v1/invoices/billing-customer/TOKEN-DO-CLIENTE-PARA-FATURAR

Parâmetros da requisição (URL)

Parâmetro Tipo Obrigatório Exemplo Descrição
token do cliente String Sim "fd4ff8058dae914b5bafa4fd7f8a73fb" Token do cliente ou empresa para faturar.

Resultado

Uma lista de objetos de faturas.

Erros

Status HTTP Mensagem
403 Token de cliente inválido.
403 Cliente para faturar não encontrado.

Atualizar uma fatura pelo token

Atualiza uma fatura.

PUT /v1/invoices/fd4ff8058dae914b5bafa4fd7f8a73fb HTTP/1.1
User-Agent: MyClient/1.0.0
Accept: application/json
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Token: SEU_TOKEN_DE_CLIENTE
Host: api.ipay.net.br
{
    "invoice": {
        "createdAt": "2019-09-14",
        "paymentType": "boleto",
        "price": "15",
        "customer": "a1a43149-fa12-4f28-a4e9-a66762de5bbd"
    }
}
HTTP/1.1 200 OK
Content-Type: application/json
curl -X PUT \
     -H "Content-type:application/json" \
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiQ3hlQktwdjRQWW9WcmpacH" \
     -H "Token: 22138bdb667c98ba749912d0717248d7" \
      https://api.ipay.net.br/v1/invoices/fd4ff8058dae914b5bafa4fd7f8a73fb \
      -d '{
                "invoice": {
                    "createdAt": "2019-09-14",
                    "paymentType": "boleto",
                    "price": "15",
                    "customer": "a1a43149-fa12-4f28-a4e9-a66762de5bbd"
                }
            }'

Exemplo de resposta:

{
    "invoice": {
        "paymentType": "boleto",
        "price": "15",
        "status": "aberto",
        "createdAt": "2019-09-14",
        "type": "I",
        "invoiceNumber": "466",
        "dueDate": "14",
        "delayedDays": "0",
        "penaltyPrice": "0",
        "interestPrice": "0",
        "total": "15",
        "boletoBarcode": null,
        "returnedErrorCode": null,
        "returnedCodeAcquirer": null,
        "returnedMessage": null,
        "tid": null,
        "capture": null,
        "nsu": null,
        "paymentDate": null,
        "token": "8756d6dc8f265a156be9d9e6fc5f0092"
    }
}

Requisição HTTP

PUT https://api.ipay.net.br/v1/invoices/TOKEN_DA_FATURA

Parâmetros da requisição (URL)

Parâmetro Tipo Obrigatório Exemplo Descrição
token String Sim "fd4ff8058dae914b5bafa4fd7f8a73fb" Token da fatura.

Parâmetros da requisição (Body)

Parâmetro Tipo Obrigatório Exemplo Descrição
invoice.createdAt String Sim "2019-09-30" Data da fatura.
invoice.paymentType String Sim "cartao" Tipos de pagamento.(Tipos de pagamento).
invoice.price String Sim "1000" Valor da fatura. (Valor da Fatura).
invoice.customer String Sim "ae8da5c174cdcdb7a34ed9085fd7c426" Token do cliente para faturar que o cartão pertence.

Resultado

Objeto fatura.

Erros

Status HTTP Mensagem
400 Por favor verifique os parâmetros
400 Data da fatura inválida.
400 Tipo de pagamento inválido.
403 Token de cliente inválido.
404 Cliente para faturar não encontrado.

Objeto fatura

O objeto de uma fatura pode ser definido como abaixo:

Exemplo do objeto de fatura:

{
    "invoice": {
        "paymentType": "cartao",
        "price": "12121",
        "status": "aberto",
        "createdAt": "2019-04-30",
        "type": "I",
        "invoiceNumber": "452",
        "dueDate": "30",
        "delayedDays": "0",
        "penaltyPrice": "0",
        "interestPrice": "0",
        "total": "12121",
        "boletoBarcode": null,
        "returnedErrorCode": null,
        "returnedCodeAcquirer": null,
        "returnedMessage": null,
        "tid": null,
        "capture": null,
        "nsu": null,
        "paymentDate": null,
        "token": "befd099e290012c42eb899de23f61bc2"
    }
}
Chave Tipo Exemplo de valor Descrição
paymentType String "cartao" Tipo de opção de pagamento. (Tipos de pagamento)
price String "1000" Valor Principal a ser cobrado(Sem juros).
status String "aberto" Status da fatura. (Status de faturas).
token String "5d9d7b5aac1a8340cd6498d" Identificador da fatura.
createdAt String "2019-04-30" Data em que foi cadastrado.
type String "A" De que forma foi gerada. (Tipos de gerações de fatura)
invoiceNumber String "123" Um numero de controle sequencial.
dueDate String "30" Dia de Vencimento da fatura.
delayedDays String "2" Quantos dias esta em atraso a fatura(caso não pago).
penaltyPrice String "2" Valor da multa em caso de atraso.
interestPrice String "2" Valor de juros em caso de atraso.
total String "1004" Valor total incluindo multa e juros.
boletoBarcode String "1516156516" Numero de codigo de barras do registro do boleto.
returnedErrorCode String "00" Retorno status da requisição.
returnedCodeAcquirer String "99" Retorno status da requisição.
returnedMessage String "" Retorno das mensagens(Transacao capturada com sucesso
tid String "2121" Identificador.
capture String "1" Captura do valor da venda na hora ou posterior Cartão.
nsu String "010010" Numero de identificação da autorizacão cartão.
paymentDate String "2019-04-30" Data do pagamento da fatura.

Status de faturas

As faturas dos clientes podem ter os status descritos abaixo:

Tipo Valor Descrição
Aberta "aberta" Se a fatura está aberta.
Pago "pago" Se a fatura está paga.
Vencida "vencida" Se a fatura está vencida.
Processamento "processamento" Se a fatura está em processamento.

Tipos de gerações de faturas

As faturas dos clientes podem ser geradas em alguma das formas descritas abaixo:

Tipo Valor Descrição
Sistema "A" Se a fatura foi gerada pelo sistema.
Manual "M" Se a fatura foi gerada manualmente.
API "I" Se a fatura foi gerada pela API.

Paginação

O número máximo de registros retornados por um endpoint de listagem é de 100 registros.

Exemplo de resposta paginada:

{
    "dadosDoEndpoint": [],
    "total": 6,
    "skipped": 2,
    "count": 2
}

Alguns endpoints da API do Ipay suportam os query parameters offset e limit, que auxiliam na paginação de determinados endpoints que podem retornar muitos resultados.


Nota
Os parâmetros poderão ser combinados, por exemplo:

http://localhost:3000/v1/exemplos?offset=3&limit=50, este exemplo retornará 50 registros a partir do terceiro registro.

Os endpoints que permitem o uso de query parameters de paginação retornarão alguns campos no json de resposta que indicarão a paginação.

Chave Tipo Exemplo de valor Descrição
total Inteiro 25 Total de registros que existem e que podem ser acessados.
skipped Inteito 3 Quantidade de itens que foram "pulados"/"ignorados"
count Inteiro 12 Quantidade de itens retornados na requisição atual.

Formato de erros

Exemplo de mensagem de erro no corpo da requisição (quando há erros):

{
    "mensagem": "Ocorreu um erro"
}

Exemplo de resposta bem sucedida:

{
    "chave": "valor"
}

Todos os erros contidos na requisição são informados por meio do código HTTP da resposta, e de uma mensagem de erro.
Requisições bem sucedidas são respondidas com status HTTP de sucesso, e uma resposta, caso haja.