Zoov Payment API

Primeiros Passos

Tudo que você precisa para começar a integrar com a API Zoov Payment. Configure seu ambiente, obtenha suas credenciais e entenda as convenções.

Ambientes #

A Zoov Payment disponibiliza dois ambientes para integração. Utilize o Sandbox para desenvolvimento e testes, e o ambiente de Produção para transações reais.

Ambiente	API Base URL	Painel
Sandbox	`https://api-sandbox.deltapag.io`	painel-sandbox.deltapag.io
Produção	`https://api.deltapag.io`	painel.deltapag.io

Dica: O ambiente Sandbox permite realizar transações de teste sem movimentar valores reais. Utilize os cartões de teste para simular diferentes cenarios.

Autenticação #

Todas as requisicoes a API devem incluir um token de autenticação no header Authorization utilizando o esquema Bearer Token.

Como gerar seu token

Acesse o Painel Zoov Payment do ambiente desejado
Navegue até Configurações → Integracoes → API
Clique em "Gerar novo token"
Copie e armazene o token com seguranca

Importante: O token e exibido apenas uma vez no momento da geração. Armazene-o em local seguro. Em caso de perda, sera necessário gerar um novo token.

Exemplo de requisição autenticada

bash

curl -X GET https://sandbox-api.zoov.com.br/api/v2/customers \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json"

Convenções da API #

A API Zoov Payment segue padrões REST com algumas convenções importantes. Entenda como a API se comporta para integrar corretamente.

Resposta de criação (POST)

Requisicoes POST retornam 201 Created com corpo vazio. O recurso criado e referenciado pelos headers da resposta:

http response

HTTP/1.1 201 Created
Location: /api/v2/customers/cus_abc123
Content-ID: cus_abc123
Link: </api/v2/customers/cus_abc123>; rel="self"

Header	Descrição
`Location`	URL completa do recurso criado
`Content-ID`	Identificador único do recurso (UUID ou ID prefixado)
`Link`	Links HATEOAS para navegação entre recursos relacionados

Formatos de dados

Valores monetarios em centavos Todos os valores financeiros sao representados em centavos (inteiro). Exemplo: R$ 1.500,00 = 150000
Datas no formato ISO Datas sao enviadas e recebidas no formato YYYY-MM-DD. Exemplo: 2026-03-08
Timestamps em milissegundos Campos de data/hora (timestamps) utilizam milissegundos desde epoch Unix. Exemplo: 1709856000000

Respostas de erro

Quando uma requisição falha, a API retorna um código HTTP apropriado com detalhes do erro no corpo da resposta.

Código	Significado	Quando ocorre
400	Bad Request	Parâmetros inválidos ou malformados no corpo da requisição
401	Unauthorized	Token ausente, expirado ou inválido
404	Not Found	O recurso solicitado nao existe ou foi removido
422	Unprocessable Entity	Dados sintaticamente corretos mas semanticamente inválidos (ex.: CPF inválido)

json — exemplo de erro 422

{
  "error": "Unprocessable Entity",
  "status": 422,
  "message": "Validation failed",
  "details": [
    {
      "field": "document",
      "message": "CPF informado é inválido"
    }
  ]
}

Boas práticas: Sempre verifique o campo details nas respostas de erro para identificar exatamente qual campo precisa ser corrigido.

Cadastros & Fundações

Gerencie o cadastro de clientes, métodos de pagamento, endereços e catálogo de produtos.

Clientes #

Cadastre e gerencie seus clientes. O cliente é a entidade central para associar cartões, endereços e cobranças.

POST /api/v2/customers

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Criar um novo cliente na plataforma.

json — request body

{
  "name": "Tony Stark",
  "document": "51190844001",
  "birthdate": "2000-01-01",
  "phone": {
    "countryCode": 55,
    "areaCode": 48,
    "number": 998870001
  },
  "email": "stark@gmail.com",
  "address": {
    "street": "Rua Jair Hamms",
    "streetNumber": "38",
    "lineTwo": "Sala 101",
    "neighborhood": "Pedra Branca",
    "state": "SC",
    "zipCode": "88137084",
    "city": "Palhoca"
  }
}

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome completo do cliente
`document`	string	Não	CPF ou CNPJ (apenas números). Se informado, deve ser válido (11-14 dígitos).
`birthdate`	string (date)	Não	Data de nascimento (YYYY-MM-DD)
`email`	string	Não	Email do cliente
`phone.countryCode`	integer	Condicional	Código do país (ex: 55). Obrigatório se `phone` for enviado.
`phone.areaCode`	integer	Condicional	DDD (11-99). Obrigatório se `phone` for enviado.
`phone.number`	integer	Condicional	Número do telefone. Obrigatório se `phone` for enviado.
`address.street`	string	Condicional	Rua. Obrigatório se `address` for enviado.
`address.streetNumber`	string	Condicional	Número. Obrigatório se `address` for enviado.
`address.lineTwo`	string	Não	Complemento
`address.neighborhood`	string	Condicional	Bairro. Obrigatório se `address` for enviado.
`address.state`	string	Condicional	UF (ex: SC). Obrigatório se `address` for enviado.
`address.zipCode`	string	Condicional	CEP. Obrigatório se `address` for enviado.
`address.city`	string	Condicional	Cidade. Obrigatório se `address` for enviado.

Headers de Resposta

LocationURL do recurso criado

Content-IDID numérico do cliente criado

Status	Descrição
201	Cliente criado com sucesso
400	Requisição malformada
401	Não autorizado
422	Entidade não processável

Faça um GET na URL do header Location para obter os dados completos do cliente criado.

PUT /api/v2/customers/document/{document}

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Editar um cliente existente pelo documento. O campo name é obrigatório. (Deprecated)

Path: document (string) — CPF ou CNPJ do cliente.

json — request body

{
  "name": "Tony Stark",
  "birthdate": "2000-01-01",
  "phone": {
    "countryCode": 55,
    "areaCode": 48,
    "number": 998870001
  },
  "email": "stark@gmail.com"
}

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome completo do cliente
`document`	string	Não	CPF ou CNPJ
`birthdate`	string	Não	Data de nascimento (YYYY-MM-DD)
`email`	string	Não	Email do cliente
`phone.countryCode`	integer	Condicional	Código do país. Obrigatório se `phone` for enviado.
`phone.areaCode`	integer	Condicional	DDD (11-99). Obrigatório se `phone` for enviado.
`phone.number`	integer	Condicional	Número do telefone. Obrigatório se `phone` for enviado.
`address.street`	string	Condicional	Rua. Obrigatório se `address` for enviado.
`address.streetNumber`	string	Condicional	Número. Obrigatório se `address` for enviado.
`address.lineTwo`	string	Não	Complemento
`address.neighborhood`	string	Condicional	Bairro. Obrigatório se `address` for enviado.
`address.state`	string	Condicional	UF. Obrigatório se `address` for enviado.
`address.zipCode`	string	Condicional	CEP. Obrigatório se `address` for enviado.
`address.city`	string	Condicional	Cidade. Obrigatório se `address` for enviado.

Este endpoint está marcado como deprecated. O campo name é obrigatório mesmo em atualizações. Os demais campos são opcionais, mas subcampos de phone e address tornam-se obrigatórios quando o objeto pai é enviado.

Status	Descrição
200	Cliente atualizado com sucesso
400	Requisição malformada
401	Não autorizado
422	Entidade não processável (inclui cliente não encontrado)

GET /api/v2/customers/document/{document}

Headers

Authorization: Bearer {seu_token}

Buscar cliente por documento (CPF/CNPJ). (Deprecated)

json — response body

{
  "id": 12345,
  "name": "Tony Stark",
  "document": "51190844001",
  "birthdate": "2000-01-01",
  "email": "stark@gmail.com",
  "phone": {
    "countryCode": "+55",
    "areaCode": "48",
    "number": "998870001"
  },
  "address": {
    "id": 1,
    "street": "Rua Jair Hamms",
    "streetNumber": "38",
    "lineTwo": "Sala 101",
    "neighborhood": "Pedra Branca",
    "city": "Palhoca",
    "state": "SC",
    "zipCode": "88137084"
  },
  "registerDate": "2024-01-15T10:30:00.000+00:00"
}

Campo	Tipo	Descrição
`id`	integer	Identificador do cliente
`name`	string	Nome completo
`document`	string	CPF/CNPJ
`birthdate`	string (date)	Data de nascimento (YYYY-MM-DD)
`email`	string	Email
`phone`	object	Telefone do cliente (null se não cadastrado)
`phone.countryCode`	string	Código do país (ex: "+55")
`phone.areaCode`	string	DDD
`phone.number`	string	Número do telefone
`address`	object	Melhor endereço do cliente (null se não cadastrado)
`address.id`	integer	Identificador do endereço
`address.street`	string	Rua
`address.streetNumber`	string	Número
`address.lineTwo`	string	Complemento
`address.neighborhood`	string	Bairro
`address.city`	string	Cidade
`address.state`	string	UF
`address.zipCode`	string	CEP
`registerDate`	string (datetime)	Data de cadastro do cliente

Status	Descrição
200	Cliente retornado com sucesso
401	Não autorizado
422	Entidade não processável (inclui cliente não encontrado)

GET /api/v2/customers/document/{document}/check

Headers

Authorization: Bearer {seu_token}

Verificar se um cliente já existe pelo documento. (Deprecated)

Este endpoint não retorna body. A existência do cliente é indicada pelo status code da resposta.

200 OK = cliente existe. 204 No Content = cliente não existe. Nenhum body é retornado em ambos os casos.

Status	Descrição
200	Cliente existe
204	Cliente não existe (No Content)
401	Não autorizado

Cartões de Crédito #

Gerencie os cartões de crédito associados a um cliente.

POST /api/v2/customers/document/{document}/credit/cards

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Cadastrar um novo cartão de crédito para o cliente. (Deprecated)

json — request body

{
  "cardNumber": "5448280000000007",
  "holder": {
    "name": "Tony Stark",
    "document": "51190844001"
  },
  "expiration": {
    "month": 1,
    "year": 2035
  },
  "cvv": "123"
}

Campo	Tipo	Obrigatório	Descrição
`cardNumber`	string	Sim	Número completo do cartão (apenas dígitos, 11-21 caracteres)
`holder.name`	string	Sim	Nome do titular do cartão
`holder.document`	string	Não	CPF/CNPJ do titular. Se informado, deve ser válido.
`expiration.month`	integer	Sim	Mês de validade (1-12)
`expiration.year`	integer	Sim	Ano de validade (2023-2056)
`cvv`	string	Não	Código de segurança (3 ou 4 dígitos). Se informado, deve ser numérico.

Headers de Resposta

LocationURL do recurso criado

Content-IDID numérico do cartão criado

Status	Descrição
201	Cartao cadastrado com sucesso
400	Requisição malformada
401	Não autorizado
422	Entidade não processável

PUT /api/v2/customers/document/{document}/credit/cards/{id}

Headers

Authorization: Bearer {seu_token}

Definir um cartão como padrão (default) para o cliente. (Deprecated)

Path: document (string) — CPF ou CNPJ do cliente. id (integer) — ID do cartão a ser definido como padrão.

Este endpoint não aceita request body. Apenas os path parameters são utilizados para identificar o cliente e o cartão.

json — response body

{
  "id": 1,
  "bin": "544828",
  "lastFour": "0007",
  "brand": "MASTERCARD",
  "holder": {
    "name": "Tony Stark",
    "document": "51190844001"
  },
  "expiration": {
    "month": "01",
    "year": "2035"
  },
  "token": "tok_abc123",
  "isDefault": true
}

Campo	Tipo	Descrição
`id`	integer	Identificador do cartão
`bin`	string	BIN do cartão (primeiros 6 dígitos)
`lastFour`	string	Últimos 4 dígitos do cartão
`brand`	string	Bandeira (VISA, MASTERCARD, etc.)
`holder.name`	string	Nome do titular
`holder.document`	string	CPF/CNPJ do titular
`expiration.month`	string	Mês de validade
`expiration.year`	string	Ano de validade
`token`	string	Token do cartão (pode ser null)
`isDefault`	boolean	Se é o cartão padrão

Status	Descrição
200	Cartão definido como padrão com sucesso
401	Não autorizado
500	Erro interno (cartão ou cliente não encontrado)

GET /api/v2/customers/document/{document}/credit/cards/best

Headers

Authorization: Bearer {seu_token}

Obter o cartão padrão (preferencial) do cliente. (Deprecated)

json — response body

{
  "id": 1,
  "bin": "544828",
  "lastFour": "0007",
  "brand": "MASTERCARD",
  "holder": {
    "name": "Tony Stark",
    "document": "51190844001"
  },
  "expiration": {
    "month": "01",
    "year": "2035"
  },
  "token": "tok_abc123",
  "isDefault": true
}

Campo	Tipo	Descrição
`id`	integer	Identificador do cartão
`bin`	string	BIN do cartão (primeiros 6 dígitos)
`lastFour`	string	Últimos 4 dígitos do cartão
`brand`	string	Bandeira (VISA, MASTERCARD, etc.)
`holder.name`	string	Nome do titular
`holder.document`	string	CPF/CNPJ do titular
`expiration.month`	string	Mês de validade
`expiration.year`	string	Ano de validade
`token`	string	Token do cartão (pode ser null)
`isDefault`	boolean	Se é o cartão padrão

Status	Descrição
200	Cartão retornado com sucesso
204	Cliente encontrado mas sem cartão cadastrado (No Content)
401	Não autorizado
404	Cliente não encontrado
422	Entidade não processável

GET /api/v2/customers/document/{document}/credit/cards

Headers

Authorization: Bearer {seu_token}

Listar todos os cartões do cliente. (Deprecated)

json — response body

[
  {
    "id": 1,
    "bin": "544828",
    "lastFour": "0007",
    "brand": "MASTERCARD",
    "holder": {
      "name": "Tony Stark",
      "document": "51190844001"
    },
    "expiration": {
      "month": "01",
      "year": "2035"
    },
    "token": "tok_abc123",
    "isDefault": true
  }
]

Campo	Tipo	Descrição
`[].id`	integer	Identificador do cartão
`[].bin`	string	BIN do cartão (primeiros 6 dígitos)
`[].lastFour`	string	Últimos 4 dígitos do cartão
`[].brand`	string	Bandeira (VISA, MASTERCARD, etc.)
`[].holder.name`	string	Nome do titular
`[].holder.document`	string	CPF/CNPJ do titular
`[].expiration.month`	string	Mês de validade
`[].expiration.year`	string	Ano de validade
`[].token`	string	Token do cartão (pode ser null)
`[].isDefault`	boolean	Se é o cartão padrão

Status	Descrição
200	Lista retornada com sucesso
401	Não autorizado
422	Entidade não processável (inclui cliente não encontrado)

Endereços #

Gerencie os endereços associados a um cliente.

POST /api/v2/customers/document/{document}/addresses

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Criar um novo endereço para o cliente. (Deprecated)

json — request body

{
  "street": "Rua Jair Hamms",
  "streetNumber": "38",
  "lineTwo": "Sala 101",
  "neighborhood": "Pedra Branca",
  "city": "Palhoca",
  "state": "SC",
  "zipCode": "88137084"
}

Campo	Tipo	Obrigatório	Descrição
`street`	string	Sim	Nome da rua
`streetNumber`	string	Sim	Número
`lineTwo`	string	Não	Complemento
`neighborhood`	string	Sim	Bairro
`city`	string	Sim	Cidade
`state`	string	Sim	UF (ex: SC)
`zipCode`	string	Sim	CEP (apenas números)

Headers de Resposta

LocationURL do recurso criado

Content-IDID numérico do cliente

Status	Descrição
201	Endereço criado com sucesso
400	Requisição malformada
401	Não autorizado
500	Erro interno (ex: cliente não encontrado)

PUT /api/v2/customers/document/{document}/addresses/{id}

Headers

Authorization: Bearer {seu_token}

Definir um endereço como padrão (default) para o cliente. (Deprecated)

Path: document (string) — CPF ou CNPJ do cliente. id (integer) — ID do endereço a ser definido como padrão.

Este endpoint não aceita request body. Apenas os path parameters são utilizados para identificar o cliente e o endereço.

json — response body

{
  "id": 1,
  "street": "Rua Jair Hamms",
  "streetNumber": "38",
  "lineTwo": "Sala 101",
  "neighborhood": "Pedra Branca",
  "city": "Palhoca",
  "state": "SC",
  "zipCode": "88137084"
}

Campo	Tipo	Descrição
`id`	integer	Identificador do endereço
`street`	string	Rua
`streetNumber`	string	Número
`lineTwo`	string	Complemento
`neighborhood`	string	Bairro
`city`	string	Cidade
`state`	string	UF
`zipCode`	string	CEP

Status	Descrição
200	Endereço definido como padrão com sucesso
401	Não autorizado
500	Erro interno (endereço ou cliente não encontrado)

GET /api/v2/customers/document/{document}/addresses/best

Headers

Authorization: Bearer {seu_token}

Obter o endereço padrão do cliente. (Deprecated)

json — response body

{
  "id": 1,
  "street": "Rua Jair Hamms",
  "streetNumber": "38",
  "lineTwo": "Sala 101",
  "neighborhood": "Pedra Branca",
  "city": "Palhoca",
  "state": "SC",
  "zipCode": "88137084"
}

Campo	Tipo	Descrição
`id`	integer	Identificador do endereço
`street`	string	Nome da rua
`streetNumber`	string	Número
`lineTwo`	string	Complemento
`neighborhood`	string	Bairro
`city`	string	Cidade
`state`	string	UF
`zipCode`	string	CEP

Status	Descrição
200	Endereço retornado com sucesso
204	Cliente sem endereço cadastrado (No Content)
401	Não autorizado

GET /api/v2/customers/document/{document}/addresses

Headers

Authorization: Bearer {seu_token}

Listar todos os endereços do cliente. (Deprecated)

json — response body

[
  {
    "id": 1,
    "street": "Rua Jair Hamms",
    "streetNumber": "38",
    "lineTwo": "Sala 101",
    "neighborhood": "Pedra Branca",
    "city": "Palhoca",
    "state": "SC",
    "zipCode": "88137084"
  }
]

Campo	Tipo	Descrição
`[].id`	integer	Identificador do endereço
`[].street`	string	Nome da rua
`[].streetNumber`	string	Número
`[].lineTwo`	string	Complemento
`[].neighborhood`	string	Bairro
`[].city`	string	Cidade
`[].state`	string	UF
`[].zipCode`	string	CEP

Status	Descrição
200	Lista retornada com sucesso
204	Cliente sem endereços cadastrados (No Content)
401	Não autorizado

Produtos #

Cadastre e gerencie o catálogo de produtos disponiveis para cobrança.

POST /api/v2/products

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Criar um novo produto.

json — request body

{
  "productType": "ONETIME",
  "affiliateId": 12345,
  "name": "Produto Exemplo",
  "value": 500,
  "softDescriptor": "Product Plus",
  "maxInstallments": 12,
  "active": true,
  "methods": ["CREDIT_CARD", "PIX"],
  "description": "Este e um produto exemplo.",
  "themeId": 1
}

Produto recorrente: Para productType: "RECURRING", inclua também os campos interval (ex: "MONTHLY") e maxCharges (ex: 12), ambos obrigatórios.

Campo	Tipo	Obrigatório	Descrição
`productType`	string	Sim	ONETIME ou RECURRING
`affiliateId`	long	Sim	ID do seller (afiliado)
`name`	string	Sim	Nome do produto (5-45 caracteres)
`value`	long	Sim	Preco em centavos (mínimo 5)
`maxInstallments`	integer	Sim	Número máximo de parcelas
`methods`	array[string]	Sim	CREDIT_CARD, PIX, BANK_SLIP, TRANSFER, NUPAY
`themeId`	long	Sim	ID do tema do produto
`softDescriptor`	string	Não	Descrição na fatura do cartão (1-13 caracteres)
`active`	boolean	Não	Status ativo
`description`	string	Não	Descrição do produto (1-150 caracteres)
`expirationDate`	long	Não	Data de expiração em milissegundos (epoch)
`feePassThrough`	boolean	Não	Indica se a taxa será repassada ao cliente (default: false)
`maxInstallmentsWithoutFees`	integer	Não	Quantidade máxima de parcelas sem taxa (0-99)
`interval`	string	RECURRING	Frequência do plano (ex: MONTHLY). Obrigatório para RECURRING.
`maxCharges`	integer	RECURRING	Número máximo de cobranças. Obrigatório para RECURRING.

Headers de Resposta

LocationURL do recurso criado (ex: /api/v2/products/{id})

LinkURL para upload de imagem do checkout

Status	Descrição
201	Produto criado com sucesso
400	Requisição malformada
401	Não autorizado
404	Seller ou tema não encontrado
422	Entidade não processável (SKU duplicado, parcelas inválidas)
500	Erro interno do servidor

PUT /api/v2/products/{id}

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Editar um produto existente.

json — request body

{
  "productType": "ONETIME",
  "name": "Produto Exemplo",
  "value": 500,
  "maxInstallments": 12,
  "themeId": 1,
  "addressRequired": true,
  "birthDateRequired": false,
  "methods": ["CREDIT_CARD", "PIX"],
  "softDescriptor": "Product Plus",
  "active": true,
  "description": "Este e um produto exemplo."
}

Campo	Tipo	Obrigatório	Descrição
`productType`	string	Sim	ONETIME ou RECURRING
`name`	string	Sim	Nome do produto (5-45 caracteres)
`value`	long	Sim	Preço em centavos (mínimo 5)
`maxInstallments`	integer	Sim	Número máximo de parcelas
`themeId`	long	Sim	ID do tema do produto
`addressRequired`	boolean	Sim	Indica se o endereço é obrigatório
`birthDateRequired`	boolean	Sim	Indica se a data de nascimento é obrigatória
`methods`	array[string]	ONETIME	CREDIT_CARD, PIX, BANK_SLIP, TRANSFER, NUPAY. Obrigatório para ONETIME.
`softDescriptor`	string	Não	Descrição na fatura (1-13 caracteres)
`active`	boolean	Não	Status ativo
`description`	string	Não	Descrição do produto (1-150 caracteres)
`expirationDate`	long	Não	Data de expiração em milissegundos (epoch)
`feePassThrough`	boolean	Não	Indica se a taxa será repassada ao cliente (default: false)
`maxInstallmentsWithoutFees`	integer	Não	Quantidade máxima de parcelas sem taxa (0-99)
`maxCharges`	integer	RECURRING	Número máximo de cobranças. Obrigatório para RECURRING.

Status	Descrição
200	Produto atualizado com sucesso
400	Requisição malformada
401	Não autorizado
404	Produto ou tema não encontrado
500	Erro interno do servidor

GET /api/v2/products/{id}

Headers

Authorization: Bearer {seu_token}

Obter produto por ID.

json — response body

{
  "id": 1,
  "type": "ONETIME",
  "name": "Produto Exemplo",
  "value": 500,
  "softDescriptor": "Product Plus",
  "maxInstallments": 12,
  "maxCharges": null,
  "active": true,
  "checkout": {
    "id": 1,
    "name": "Produto Exemplo",
    "description": "Este e um produto exemplo.",
    "amount": 500,
    "methods": ["CREDIT_CARD", "PIX"],
    "active": true,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "addressRequired": true,
    "birthdateRequired": false,
    "feePassThrough": false,
    "maxInstallmentsWithoutFees": 99
  }
}

Campo	Tipo	Descrição
`id`	integer	Identificador do produto
`type`	string	ONETIME ou RECURRING
`name`	string	Nome do produto
`value`	long	Preco em centavos
`softDescriptor`	string	Descrição na fatura do cartão
`maxInstallments`	integer	Número máximo de parcelas
`maxCharges`	integer	Número máximo de cobranças (RECURRING, null para ONETIME)
`active`	boolean	Status ativo
`checkout`	object	Detalhes do checkout (PagePay) associado ao produto
`checkout.id`	integer	ID do checkout
`checkout.name`	string	Nome do checkout
`checkout.description`	string	Descrição do produto
`checkout.amount`	long	Valor em centavos
`checkout.methods`	array[string]	Métodos de pagamento aceitos
`checkout.active`	boolean	Status ativo do checkout
`checkout.uuid`	string	UUID do checkout
`checkout.addressRequired`	boolean	Indica se endereço é obrigatório
`checkout.birthdateRequired`	boolean	Indica se data de nascimento é obrigatória
`checkout.feePassThrough`	boolean	Indica se a taxa é repassada ao cliente
`checkout.maxInstallmentsWithoutFees`	integer	Máximo de parcelas sem taxa

Status	Descrição
200	Produto retornado com sucesso
401	Não autorizado
404	Produto não encontrado
500	Erro interno do servidor

Tokenização

Proteja dados sensiveis do cartão. Nunca trafegue o PAN diretamente — troque por um token seguro.

Importante: Nunca envie o número completo do cartão na autorização. Sempre tokenize primeiro.

Fluxo de tokenização

1

Cartao

Dados sensiveis do portador

2

API Vault

Armazenamento seguro e criptografado

3

Token Seguro

Referencia segura para uso nas transações

Criar Token #

POST /api/v2/cards/tokens

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Tokenizar um cartão de crédito para uso seguro em transações futuras.

json — request body

{
  "holder": {
    "name": "Tony Stark",
    "document": "51190844001"
  },
  "expiration": {
    "year": 2035,
    "month": 1
  },
  "cardNumber": "5448280000000007"
}

Campo	Tipo	Obrigatório	Descrição
`holder.name`	string	Sim	Nome do titular
`holder.document`	string	Não	CPF/CNPJ do titular. Se informado, deve ser válido (11-14 dígitos numéricos).
`expiration.year`	integer	Sim	Ano de validade (2023-2056)
`expiration.month`	integer	Sim	Mes de validade (1-12)
`cardNumber`	string	Sim	Número completo do cartão (11-21 dígitos, validação Luhn)

Resposta: 201 Created

Headers da resposta

Location URL do token criado (ex: /api/v2/cards/tokens/{token})

Status	Descrição
201	Token criado com sucesso
400	Requisição malformada
401	Não autorizado
422	Entidade não processável

Dica: Faca um GET na URL retornada no header Location para obter o valor do token.

Exemplo de resposta ao consultar o token via GET na URL do header Location:

json — response body

{
  "token": "643c663f3c244f939ef1f9acc6ccd75d",
  "bin": "544828",
  "lastFour": "0007",
  "brand": "MASTERCARD",
  "holder": {
    "name": "Tony Stark",
    "document": "51190844001"
  },
  "expiration": {
    "month": "1",
    "year": "2035"
  }
}

Campo	Tipo	Descrição
`token`	string	Token seguro gerado para o cartão
`bin`	string	BIN do cartão (primeiros 6 dígitos)
`lastFour`	string	Últimos 4 dígitos do cartão
`brand`	string	Bandeira do cartão (ex: MASTERCARD, VISA)
`holder.name`	string	Nome do titular do cartão
`holder.document`	string	CPF/CNPJ do titular (pode ser null)
`expiration.month`	string	Mes de validade
`expiration.year`	string	Ano de validade

Importante: O token retornado deve ser utilizado no campo cardToken.token ao solicitar uma autorização de pagamento.

Consultar Token #

GET /api/v2/cards/tokens/{token}

Headers

Authorization: Bearer {seu_token}

Consultar dados de um token existente.

Parâmetro	Tipo	Obrigatório	Descrição
`token`	string	Sim	Token do cartão a consultar

Exemplo de resposta:

json — response body

{
  "token": "643c663f3c244f939ef1f9acc6ccd75d",
  "bin": "544828",
  "lastFour": "0007",
  "brand": "MASTERCARD",
  "holder": {
    "name": "Tony Stark",
    "document": "51190844001"
  },
  "expiration": {
    "month": "1",
    "year": "2035"
  }
}

Campo	Tipo	Descrição
`token`	string	Token seguro gerado para o cartão
`bin`	string	BIN do cartão (primeiros 6 dígitos)
`lastFour`	string	Últimos 4 dígitos do cartão
`brand`	string	Bandeira do cartão (ex: MASTERCARD, VISA)
`holder.name`	string	Nome do titular do cartão
`holder.document`	string	CPF/CNPJ do titular (pode ser null)
`expiration.month`	string	Mes de validade
`expiration.year`	string	Ano de validade

Status	Descrição
200	Token consultado com sucesso
401	Não autorizado
404	Token não encontrado
422	Entidade não processável

Pagamentos

O motor omnichannel de pagamentos. Processe transações via Cartão de Crédito, PIX ou Boleto.

Fluxo de pagamento com cartão de crédito

1

Tokenizar

Transforme o PAN em token seguro

2

Autorizar

Reserve o valor no cartão

3

Capturar

Efetive o pagamento

Cartão de Crédito — Autorização #

Autorize um pagamento com cartão de crédito utilizando o token gerado anteriormente.

POST /api/v2/sellers/{sellerId}/orders/credit-card/authorize

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Autorizar um pagamento com cartão de crédito.

json — request body

{
  "operationType": "AUTHORIZE_ONLY",
  "orderReference": "TEST_1694314800",
  "amount": 500,
  "customer": {
    "birthdate": "1992-02-29",
    "document": "55375716097",
    "name": "Teste Bempaggo",
    "address": {
      "street": "Rua Jair Hamms",
      "city": "Palhoca",
      "streetNumber": "38",
      "zipCode": "88137084",
      "neighborhood": "Pedra Branca",
      "state": "SC"
    }
  },
  "notificationUrl": "https://meusite.com.br/events",
  "payments": [
    {
      "installments": 1,
      "cardToken": {
        "token": "643c663f...",
        "cvv": "123"
      },
      "amount": 500,
      "paymentMethod": "CREDIT_CARD"
    }
  ],
  "metadata": {
    "erp_id": 9999
  }
}

Campo	Tipo	Obrigatório	Descrição
`operationType`	string	Não	AUTHORIZE_ONLY (padrão) ou AUTHORIZE_AND_CAPTURE
`orderReference`	string	Sim	Referencia unica do pedido
`amount`	integer	Sim	Valor total em centavos
`customer.name`	string	Sim	Nome completo (1-50 caracteres)
`customer.document`	string	Não	CPF/CNPJ. Se informado, deve ser válido.
`customer.birthdate`	string	Não	Data de nascimento (YYYY-MM-DD)
`customer.address.*`	object	Não	Endereco do cliente
`notificationUrl`	string (URI)	Não	URL para webhooks
`softDescriptor`	string	Não	Descrição na fatura do cartão (máx. 10 caracteres)
`payments[].paymentMethod`	string	Sim	CREDIT_CARD
`payments[].amount`	long	Sim	Valor do pagamento em centavos (mínimo 1)
`payments[].installments`	integer	Sim	Número de parcelas (1-12)
`payments[].cardToken.token`	string	Sim	Token do cartão gerado em /v2/cards/tokens
`payments[].cardToken.cvv`	string	Não	CVV do cartão (3-4 dígitos). Opcional.
`payments[].splits`	array	Não	Regras de divisão do recebimento (split)
`metadata`	object	Não	Dados customizados chave-valor

Headers da resposta

Location URL da cobrança

Content-ID ID da cobrança

Link (rel="capture") URL para captura (quando status AUTHORIZED)

Link (rel="refund") URL para estorno (quando status AUTHORIZED ou PAY)

Link (rel="metadata") URL dos metadados do pedido

Link (rel="search") URL para buscar por orderReference (quando informado)

HATEOAS: A API utiliza o padrão HATEOAS. Use os links retornados nos headers para navegar entre as operações. Não construa URLs manualmente.

Status	Descrição
201	Autorização criada com sucesso
400	Requisição malformada
401	Não autorizado
404	Seller não encontrado
422	Entidade não processável (sem estabelecimento, referência duplicada, transação não permitida)

Captura #

Apos a autorização, capture o pagamento utilizando o link retornado no header Link (rel="capture").

POST /api/v2/charges/{id}/credit-card/capture

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Capturar uma cobrança previamente autorizada.

Parâmetro	Tipo	Obrigatório	Descrição
`id`	integer	Sim	ID da cobrança a capturar

Captura parcial: Para capturar apenas parte do valor autorizado, envie um body JSON com o campo amount (valor em centavos). Se nenhum body for enviado, o valor total autorizado será capturado.

Campo (body opcional)	Tipo	Obrigatório	Descrição
`amount`	long	Não	Valor da captura em centavos. Se nulo, captura o valor total autorizado.

Resposta: 201 Created

Headers da resposta

Location URL da cobrança

Content-ID ID da cobrança

Link (rel="refund") URL para estorno (quando status PAY ou AUTHORIZED)

Status	Descrição
201	Captura realizada com sucesso
401	Não autorizado
422	Entidade não processável (cobrança não pode ser capturada, sem estabelecimento)

PIX #

Crie cobranças PIX com QR Code para pagamento instantaneo.

POST /api/v2/sellers/{sellerId}/orders/pix

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Criar um pedido com pagamento via PIX.

Campo	Tipo	Obrigatório	Descrição
`amount`	integer	Sim	Valor total em centavos
`orderReference`	string	Sim	Referencia unica do pedido
`customer.document`	string	Sim	CPF/CNPJ do cliente
`customer.name`	string	Sim	Nome completo
`customer.birthdate`	string	Sim	Data de nascimento (YYYY-MM-DD)
`notificationUrl`	string	Não	URL para webhooks
`payments[].paymentMethod`	string	Sim	PIX
`payments[].amount`	integer	Sim	Valor em centavos

json — request body

{
  "orderReference": "PIX_1694314800",
  "amount": 15000,
  "customer": {
    "birthdate": "1992-02-29",
    "document": "55375716097",
    "name": "Tony Stark"
  },
  "notificationUrl": "https://meusite.com.br/events",
  "payments": [
    {
      "paymentMethod": "PIX",
      "amount": 15000
    }
  ]
}

Resposta: 201 Created

Headers da resposta

Location URL do recurso criado

Content-ID ID numérico do recurso

Exemplo de resposta ao consultar o pedido via GET na URL do header Location:

json — response body

{
  "id": 5678,
  "orderReference": "PIX_1694314800",
  "status": "PENDING",
  "amount": 15000,
  "charges": [
    {
      "id": 1234,
      "status": "PENDING",
      "value": 15000,
      "transactions": [
        {
          "id": "txn_abc123",
          "status": "AWAITING_PAYMENT",
          "pix": {
            "qrCode": "00020126580014br.gov.bcb.pix...",
            "qrCodeBase64": "data:image/png;base64,iVBOR..."
          }
        }
      ]
    }
  ]
}

Campo	Tipo	Descrição
`id`	integer	ID do pedido
`orderReference`	string	Referencia unica do pedido
`status`	string	Status do pedido (ex: PENDING, PAID)
`amount`	integer	Valor total em centavos
`charges[].id`	integer	ID da cobrança
`charges[].status`	string	Status da cobrança
`charges[].transactions[].pix.qrCode`	string	Código copia-e-cola do PIX (EMV)
`charges[].transactions[].pix.qrCodeBase64`	string	Imagem do QR Code em Base64 (PNG)

Status	Descrição
201	Pedido PIX criado com sucesso
400	Requisição malformada
401	Não autorizado
422	Entidade não processável

Boleto #

Gere boletos bancarios com data de vencimento e descrição personalizados.

POST /api/v2/sellers/{sellerId}/orders/boleto

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Criar um pedido com pagamento via Boleto.

Campo	Tipo	Obrigatório	Descrição
`orderReference`	string	Sim	Referencia unica do pedido (4-32 caracteres)
`amount`	integer	Sim	Valor total em centavos. Deve ser igual a soma dos `payments[].amount`
`customer.name`	string	Sim	Nome completo do cliente
`customer.document`	string	Não	CPF/CNPJ. Se informado, deve ser válido.
`customer.birthdate`	string	Não	Data de nascimento (YYYY-MM-DD)
`customer.address.*`	object	Sim	Endereco do cliente. Obrigatorio para boleto.
`notificationUrl`	string (URI)	Não	URL para webhooks
`metadata`	object	Não	Dados customizados chave-valor
`payments[].paymentMethod`	string	Sim	BOLETO
`payments[].amount`	long	Sim	Valor do pagamento em centavos (mínimo 1)
`payments[].dueDate`	integer (timestamp)	Sim	Data de vencimento do boleto (timestamp epoch em milissegundos)
`payments[].paymentLimitDate`	integer (timestamp)	Sim	Data limite de pagamento (timestamp epoch em milissegundos)
`payments[].ourNumber`	string	Não	Número que identifica unicamente um boleto para uma conta (5-15 caracteres)
`payments[].documentNumber`	string	Não	Identificador do boleto
`payments[].instructions`	string	Não	Instruções do boleto
`payments[].splits`	array	Não	Regras de divisão do recebimento (split)
`payments[].fine`	object	Não	Aplicação da multa sobre o boleto
`payments[].fine.days`	integer	Sim	Dias após a expiração do boleto quando a multa deve ser cobrada
`payments[].fine.type`	string	Sim	Tipo de cálculo: `FLAT` (valor fixo) ou `PERCENTAGE` (percentual)
`payments[].fine.amount`	integer	Sim	Valor da multa. Veja a regra de casas decimais abaixo.
`payments[].interest`	object	Não	Aplicação do juros sobre o boleto
`payments[].interest.days`	integer	Sim	Dias após a expiração do boleto quando o juros deve ser cobrado
`payments[].interest.type`	string	Sim	Tipo de cálculo: `FLAT` (valor fixo) ou `PERCENTAGE` (percentual)
`payments[].interest.amount`	integer	Sim	Valor dos juros. Veja a regra de casas decimais abaixo.
`payments[].interest.frequency`	string	Sim	Modo de cobrança dos juros: `DAILY`, `MONTHLY` ou `ANNUAL`

Multa e juros: Os objetos fine e interest são opcionais. Porém, quando enviados, todos os seus campos internos passam a ser obrigatórios.

Casas decimais em fine.amount e interest.amount: O valor depende do type enviado.

Quando type for PERCENTAGE, o valor deve ser enviado como inteiro com 5 casas decimais. Ex.: 2% → 200000.
Quando type for FLAT, o valor deve ser enviado como inteiro com 2 casas decimais (em centavos). Ex.: R$ 2,00 → 200.

json — request body

{
  "orderReference": "BOL_1694314800",
  "amount": 25000,
  "customer": {
    "birthdate": "1992-02-29",
    "document": "55375716097",
    "name": "Tony Stark",
    "address": {
      "street": "Rua Jair Hamms",
      "streetNumber": "38",
      "neighborhood": "Pedra Branca",
      "city": "Palhoca",
      "state": "SC",
      "zipCode": "88137084"
    }
  },
  "notificationUrl": "https://meusite.com.br/events",
  "payments": [
    {
      "paymentMethod": "BOLETO",
      "amount": 25000,
      "dueDate": 1694314800000,
      "paymentLimitDate": 1694746800000,
      "instructions": "Não receber após o vencimento",
      "fine": {
        "days": 1,
        "type": "FLAT",
        "amount": 200
      },
      "interest": {
        "days": 1,
        "type": "PERCENTAGE",
        "amount": 200000,
        "frequency": "MONTHLY"
      }
    }
  ]
}

Resposta: 201 Created — corpo vazio com headers HATEOAS

http response — 201 Created

HTTP/1.1 201 Created
Location: /api/v2/charges/5678
Content-ID: 5678
Link: </api/v2/orders/1234/metadata>; rel="metadata"
Link: </api/v2/charges/5678/boleto/cancel>; rel="cancel"
Link: </api/v2/charges/itau/abc123/boleto/pdf>; rel="boleto-pdf"
Link: </api/v2/public/boleto/abc123/pdf?token=xyz>; rel="public-boleto-pdf"

Headers da resposta

Location URL da cobrança criada — use GET para consultar os detalhes

Content-ID ID numérico da cobrança

Link rel="metadata" URL para acessar os metadados do pedido

Link rel="cancel" URL para cancelar o boleto

Link rel="boleto-pdf" URL para download do PDF do boleto (autenticada)

Link rel="public-boleto-pdf" URL pública para download do PDF do boleto

Exemplo de resposta ao consultar o pedido via GET na URL do header Location:

json — response body

{
  "id": 9012,
  "orderReference": "BOL_1694314800",
  "status": "PENDING",
  "amount": 25000,
  "charges": [
    {
      "id": 5678,
      "status": "PENDING",
      "value": 25000,
      "transactions": [
        {
          "id": "txn_def456",
          "status": "AWAITING_PAYMENT",
          "boleto": {
            "barcode": "23793.38128 60000.000003 00000.000400 1 84340000025000",
            "url": "https://boleto.zoov.com.br/view/abc123"
          }
        }
      ]
    }
  ]
}

Campo	Tipo	Descrição
`id`	integer	ID do pedido
`orderReference`	string	Referencia unica do pedido
`status`	string	Status do pedido (ex: PENDING, PAID)
`amount`	integer	Valor total em centavos
`charges[].id`	integer	ID da cobrança
`charges[].status`	string	Status da cobrança
`charges[].transactions[].boleto.barcode`	string	Linha digitavel do boleto
`charges[].transactions[].boleto.url`	string	URL para visualizacao do boleto

Status	Descrição
201	Pedido com boleto criado com sucesso
400	Requisição malformada
401	Não autorizado
422	Entidade não processável

Gestão de Cobranças

Gerencie o ciclo de vida completo das cobranças: crie, capture, estorne e consulte.

Cobrança Direta com Cartão #

Crie uma cobrança direta passando os dados do cartão sem necessidade de tokenização previa.

POST /api/v2/charges/credit/card

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Criar uma cobrança direta com cartão de crédito.

json — request body

{
  "customer": {
    "document": "97012687096",
    "name": "John Snow"
  },
  "card": {
    "expiration": { "month": "01", "year": "2028" },
    "holder": { "document": "97012687096", "name": "John Snow" },
    "cardNumber": "5356066320271893",
    "cvv": "123"
  },
  "installments": 1,
  "value": 10000,
  "yourReferenceId": 123456,
  "notificationUrl": "https://myserver/events/charges/ORDER0001"
}

Campo	Tipo	Obrigatório	Descrição
`customer.name`	string	Sim	Nome do cliente (1-50 caracteres)
`customer.document`	string	Não	CPF/CNPJ. Se informado, deve ser válido (11-14 dígitos)
`card.cardNumber`	string	Sim	Número do cartão (11-21 dígitos)
`card.cvv`	string	Não	CVV (3-4 dígitos, opcional)
`card.holder.name`	string	Sim	Nome do titular
`card.holder.document`	string	Não	Documento do titular. Se informado, deve ser válido
`card.expiration.month`	string	Sim	Mês (MM)
`card.expiration.year`	string	Sim	Ano (YYYY)
`installments`	integer	Sim	Parcelas (1-12)
`value`	long	Sim	Valor em centavos (mínimo 0)
`yourReferenceId`	long	Não	Referência numérica do lojista (mínimo 1)
`notificationUrl`	string	Não	URL webhook
`affiliateId`	long	Não	ID da loja (mínimo 0)

Sem body na resposta. O endpoint retorna apenas headers. Use o Content-ID para obter o ID da cobrança criada.

Headers de Resposta

LocationURL do recurso criado

Content-IDID numérico da cobrança

Linkrel="refund" — URL para estorno via cartão de crédito

Status	Descrição
201	Cobrança criada com sucesso
400	Requisição malformada
401	Nao autenticado
422	Entidade não processável

Estorno Cartão #

POST /api/v2/charges/{id}/credit-card/refund

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Estornar uma cobrança de cartão de crédito.

Envie no body o motivo do estorno (RefundReason):

DUPLICATE_CHARGE IMPROPER_CHARGE COSTUMER_WITHDRAWAL OTHERS

json — request body

{
  "reason": "DUPLICATE_CHARGE",
  "amount": 5000
}

Campo	Tipo	Obrigatório	Descrição
`reason`	RefundReason	Sim	Motivo do estorno: DUPLICATE_CHARGE, IMPROPER_CHARGE, COSTUMER_WITHDRAWAL ou OTHERS
`amount`	long	Não	Valor parcial em centavos; se omitido, estorna o total

Headers de Resposta

LocationURL do recurso criado

Status	Descrição
201	Estorno criado com sucesso
401	Nao autenticado
404	Cobrança nao encontrada
422	Entidade não processável

Devolução PIX #

POST /api/v2/charges/{id}/pix/return

Headers

Authorization: Bearer {seu_token}

Devolver um pagamento PIX. Devolve sempre o valor total — não aceita body.

Parâmetro	Tipo	Obrigatório	Descrição
`id`	long	Sim	ID da cobrança PIX (path)

Nenhum corpo é necessário.

Headers de Resposta

LocationURL do recurso criado

Status	Descrição
201	Devolução criada com sucesso
401	Não autenticado
422	Entidade não processável (cobrança não encontrada, já cancelada, valor excedido)

Cancelar Boleto #

POST /api/v2/charges/{id}/boleto/cancel

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Cancelar um boleto pendente.

Parâmetro	Tipo	Obrigatório	Descrição
`id`	integer	Sim	ID da cobrança do boleto

Nenhum corpo e necessário.

Status	Descrição
200	Boleto cancelado com sucesso
401	Não autenticado
404	Cobrança não encontrada
422	Entidade não processável
500	Erro interno do servidor

Cancelar QR Code PIX #

POST /api/v2/charges/{id}/pix/cancel

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Cancelar um QR Code PIX pendente.

Parâmetro	Tipo	Obrigatório	Descrição
`id`	integer	Sim	ID da cobrança PIX

Nenhum corpo é necessário. Cancela o QR Code PIX antes do pagamento.

Headers de Resposta

LocationURL do recurso

Status	Descrição
201	QR Code PIX cancelado com sucesso
401	Não autenticado
422	Entidade não processável
500	Erro interno do servidor

Consultar Cobrança #

GET /api/v2/charges/{id}

Headers

Authorization: Bearer {seu_token}

Obter os detalhes de uma cobrança pelo ID.

Parâmetro	Tipo	Obrigatório	Descrição
`id`	integer	Sim	ID da cobrança

json — response body (200)

{
  "id": 12345,
  "status": "PAY",
  "value": 10000,
  "refundedAmount": 0,
  "installments": 1,
  "customer": {
    "id": 101,
    "name": "John Snow",
    "document": "97012687096",
    "email": "john@example.com",
    "phone": null
  },
  "order": {
    "id": 6789,
    "orderReference": "ORDER0001",
    "affiliate": null,
    "orderType": "LOOSE"
  },
  "items": [],
  "transactions": [
    {
      "paymentMethod": "CREDIT_CARD",
      "id": 99001,
      "uuid": "BP1778273165606",
      "status": "APPROVED",
      "type": "LOOSE",
      "value": 10000,
      "paidValue": 10000,
      "refundValue": 0,
      "transactionDate": 1694314800000,
      "transactionReference": "TXN-REF-001",
      "returnCode": "00",
      "returnMessage": "Transação aprovada"
    }
  ]
}

Headers de Resposta

Linkrel="boleto-pdf" — URL do PDF do boleto (quando aplicável)

Linkrel="public-boleto-pdf" — URL pública do PDF do boleto

Campos da resposta (200)

Campo	Tipo	Descrição
`id`	long	ID da cobrança
`status`	ChargeStatus	Status atual
`value`	long	Valor em centavos
`refundedAmount`	long	Valor estornado em centavos
`installments`	integer	Número de parcelas
`customer.id`	integer	ID do cliente
`customer.name`	string	Nome do cliente
`customer.document`	string	CPF/CNPJ do cliente
`customer.email`	string	Email do cliente
`customer.phone`	object	Telefone do cliente (pode ser null)
`order.id`	integer	ID do pedido
`order.orderReference`	string	Referência do pedido
`order.affiliate`	object	Dados da loja (pode ser null)
`order.orderType`	OrderType	Tipo do pedido
`items[]`	array	Itens da cobrança (name, unitPrice, quantity, planId)
`transactions[].id`	long	ID da transação
`transactions[].uuid`	string	Identificador único da transação (prefixo BP)
`transactions[].status`	TransactionStatus	Status da transação
`transactions[].type`	TransactionType	Tipo da transação
`transactions[].paymentMethod`	string	Método de pagamento (CREDIT_CARD, PIX, BOLETO, etc.)
`transactions[].value`	long	Valor da transação em centavos
`transactions[].paidValue`	long	Valor pago em centavos
`transactions[].refundValue`	long	Valor do estorno em centavos
`transactions[].transactionDate`	long	Data da transação (ms epoch)
`transactions[].transactionReference`	string	Referência da transação
`transactions[].returnCode`	string	Código de retorno da adquirente
`transactions[].returnMessage`	string	Mensagem de retorno da adquirente

Status	Descrição
200	Cobrança retornada com sucesso
401	Nao autenticado
404	Cobrança nao encontrada

Listar Cobranças #

GET /api/v2/charges

Headers

Authorization: Bearer {seu_token}

Listar cobranças com filtros.

Parâmetro	Tipo	Obrigatório	Descrição
`orderReference`	string	Não	Filtrar por referência do pedido
`paymentDateFrom`	long	Não	Data início em milissegundos (epoch)
`paymentDateTo`	long	Não	Data fim em milissegundos (epoch)
`status`	ChargeStatus	Não	Filtrar por status (PAY, AUTHORIZED, PENDING, etc.)
`page`	integer	Não	Número da página
`size`	integer	Não	Itens por página

json — response body (200)

[
  {
    "id": 12345,
    "status": "PAY",
    "value": 10000,
    "refundedAmount": 0,
    "installments": 1,
    "customer": { "id": 101, "name": "John Snow", "document": "97012687096" },
    "order": { "id": 6789, "orderReference": "ORDER0001" },
    "transactions": [ "..." ]
  }
]

Resposta é um array simples. O endpoint retorna List<ChargeV2Response> diretamente — não é um objeto paginado. Cada elemento segue a mesma estrutura do endpoint Consultar Cobrança.

Campos da resposta (200)

Campo	Tipo	Descrição
`[]`	array	Array de ChargeV2Response (mesma estrutura de Consultar Cobrança)

Status	Descrição
200	Lista retornada com sucesso
401	Nao autenticado

Faturamento

Crie e gerencie faturas com multiplos métodos de pagamento e envio por email.

Criar Fatura #

POST /api/v2/sellers/{sellerId}/invoices

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Criar uma nova fatura para o cliente.

json — request body

{
  "customerId": 1,
  "invoiceNumber": "FAT-2024-001",
  "dueDate": "1732310753051",
  "notificationUrl": "https://meusite.com.br/events",
  "successUrl": "https://meusite.com.br/sucesso",
  "items": [
    { "productId": 1, "quantity": 1, "unitPriceInCents": 70000 }
  ],
  "acceptedPaymentMethods": [
    {
      "method": "CREDIT_CARD",
      "cardSettings": { "maxInstallments": 10, "feePassThrough": false }
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`customerId`	integer	Sim	ID do cliente
`invoiceNumber`	string	Sim	Número único da fatura
`dueDate`	long	Sim	Data de vencimento (epoch milissegundos)
`paymentLimitDate`	long	Não	Data limite de pagamento (epoch milissegundos)
`notificationUrl`	string (URI)	Não	URL webhook (deve ser URI válida)
`successUrl`	string (URI)	Não	URL de redirecionamento após pagamento (deve ser URI válida)
`items[].productId`	integer	Sim	ID do produto
`items[].quantity`	integer	Sim	Quantidade
`items[].unitPriceInCents`	long	Sim	Preço unitário em centavos
`acceptedPaymentMethods[].method`	PaymentProfiles	Sim	CREDIT_CARD, PIX ou BANK_SLIP
`acceptedPaymentMethods[].amountOff`	long	Não	Desconto em centavos
`acceptedPaymentMethods[].cardSettings.maxInstallments`	integer	Sim	Máximo de parcelas (1-12, obrigatório para CREDIT_CARD)
`acceptedPaymentMethods[].cardSettings.feePassThrough`	boolean	Sim	Repassar taxa ao cliente (obrigatório para CREDIT_CARD)
`acceptedPaymentMethods[].cardSettings.maxInstallmentsWithoutFees`	integer	Não	Máximo de parcelas sem juros (0-99)
`acceptedPaymentMethods[].cardSettings.softDescriptor`	string	Não	Descrição na fatura do cartão (máx. 13 caracteres)
`acceptedPaymentMethods[].pixSettings.expiresIn`	integer	Não	Tempo de expiração do PIX
`acceptedPaymentMethods[].pixSettings.description`	string	Não	Descrição do pagamento PIX
`acceptedPaymentMethods[].boletoSettings.instructions`	string	Não	Instruções do boleto
`fine.value`	long	Não	Valor da multa por atraso
`interest.value`	long	Não	Valor dos juros por atraso
`splits[]`	array	Não	Regras de split de pagamento

Resposta: 201 Created — corpo vazio com headers HATEOAS

http response — 201 Created

HTTP/1.1 201 Created
Location: /api/v2/invoices/789
Link: </api/v2/invoices/789/credit-card/pay>; rel="pay-invoice-credit-card"

Headers da resposta

Location URL da fatura criada — use GET para consultar os detalhes

Link rel="pay-invoice-credit-card" URL para pagamento da fatura com cartão de crédito

Resposta sem body. O POST retorna 201 Created sem corpo — apenas os headers Location e Link. Para obter os dados da fatura criada, faça um GET usando a URL do header Location.

Status	Descrição
201	Fatura criada com sucesso (sem body, apenas headers)
400	Requisição malformada
401	Não autenticado
422	Entidade não processável (cliente não encontrado, afiliado ausente, plano não encontrado, desconto excede valor)
500	Erro interno do servidor

Enviar Fatura por E-mail #

POST /api/v2/invoices/{id}/send-email

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Enviar a fatura por email para o cliente.

Parâmetro	Tipo	Obrigatório	Descrição
`id`	integer	Sim	ID da fatura

Nenhum corpo e necessário. Envia a fatura para o email cadastrado do cliente.

Status	Descrição
200	Email enviado com sucesso
401	Não autenticado
404	Fatura não encontrada
422	Fatura em aberto (InvoiceIsOpenException)
500	Erro interno do servidor

Obter Fatura #

GET /api/v2/invoices/{id}

Headers

Authorization: Bearer {seu_token}

Obter detalhes de uma fatura pelo ID.

Parâmetro	Tipo	Obrigatório	Descrição
`id`	long	Sim	ID da fatura

Headers de Resposta

Linkrel="payment" — URL de pagamento da fatura

json — response body (200)

{
  "id": 1001,
  "invoiceNumber": "FAT-2024-001",
  "status": "PENDING",
  "customer": {
    "id": 1,
    "name": "João Silva",
    "document": "12345678901",
    "email": "joao@email.com",
    "phone": "11999999999"
  },
  "dueDate": 1732310753051,
  "closeDate": null,
  "amount": 70000,
  "paidAmount": null,
  "paymentUrl": "https://pay.zoov.com.br/invoice/abc123",
  "paymentLimitDate": null,
  "successUrl": "https://meusite.com/sucesso",
  "createdAt": 1732210753051,
  "invoiceSequence": 1,
  "acceptedPaymentMethods": [
    {
      "method": "CREDIT_CARD",
      "amountOff": null,
      "cardSettings": {
        "maxInstallments": 12,
        "feePassThrough": false
      },
      "pixSettings": null
    }
  ],
  "affiliate": null,
  "recurrentInvoiceId": null,
  "orderId": null,
  "fine": null,
  "interest": null,
  "userId": 100
}

Campos da resposta (200)

Campo	Tipo	Descrição
`id`	long	ID da fatura
`invoiceNumber`	string	Número único da fatura
`status`	InvoiceStatus	Status da fatura (PENDING, PAID, CANCELLED, etc.)
`customer`	object	Dados do cliente (id, name, document, email, phone)
`customer.id`	integer	ID do cliente
`customer.name`	string	Nome do cliente
`customer.document`	string	CPF/CNPJ do cliente
`customer.email`	string	Email do cliente
`customer.phone`	string	Telefone do cliente
`dueDate`	long	Data de vencimento (epoch ms)
`closeDate`	long	Data de fechamento (epoch ms)
`amount`	long	Valor total em centavos
`paidAmount`	long	Valor pago em centavos
`paymentUrl`	string	URL de pagamento da fatura
`paymentLimitDate`	long	Data limite de pagamento (epoch ms)
`successUrl`	string	URL de redirecionamento após pagamento
`createdAt`	long	Data de criação (epoch ms)
`invoiceSequence`	integer	Sequência da fatura
`acceptedPaymentMethods[]`	array	Métodos de pagamento aceitos (objetos com method, amountOff, cardSettings, pixSettings)
`acceptedPaymentMethods[].method`	PaymentProfiles	Método de pagamento
`acceptedPaymentMethods[].amountOff`	long	Desconto em centavos
`acceptedPaymentMethods[].cardSettings`	object	Configurações do cartão (maxInstallments, feePassThrough)
`acceptedPaymentMethods[].pixSettings`	object	Configurações do PIX
`affiliate`	object	Dados do afiliado
`recurrentInvoiceId`	long	ID da fatura recorrente (se aplicável)
`orderId`	integer	ID do pedido (se aplicável)
`fine`	object	Configuração de multa
`interest`	object	Configuração de juros
`userId`	long	ID do usuário que criou

Status	Descrição
200	Fatura retornada com sucesso
401	Não autenticado
404	Fatura não encontrada
500	Erro interno do servidor

Listar Faturas #

GET /api/v2/invoices

Headers

Authorization: Bearer {seu_token}

Listar faturas com filtros opcionais. Retorna resultado paginado via Spring Data.

Parâmetro	Tipo	Obrigatório	Descrição
`invoiceNumber`	string	Não	Filtrar por número da fatura
`dueDateFrom`	long	Não	Data de vencimento inicial (epoch ms)
`dueDateTo`	long	Não	Data de vencimento final (epoch ms)
`closeDateFrom`	long	Não	Data de fechamento inicial (epoch ms)
`closeDateTo`	long	Não	Data de fechamento final (epoch ms)
`paymentDateFrom`	long	Não	Data de pagamento inicial (epoch ms)
`paymentDateTo`	long	Não	Data de pagamento final (epoch ms)
`status`	InvoiceStatus[]	Não	Filtrar por status (PENDING, PAID, CANCELLED, etc.)
`document`	string	Não	Filtrar por CPF/CNPJ do cliente
`pastDue`	boolean	Não	Filtrar faturas vencidas
`page`	integer	Não	Página (padrão 0)
`size`	integer	Não	Itens por página (padrão 20)
`sort`	string	Não	Ordenação (ex: dueDate,desc)

json — response body (200)

{
  "content": [
    {
      "id": 1001,
      "invoiceNumber": "FAT-2024-001",
      "status": "PENDING",
      "customer": {
        "id": 1,
        "name": "João Silva",
        "document": "12345678901",
        "email": "joao@email.com",
        "phone": "11999999999"
      },
      "dueDate": 1732310753051,
      "closeDate": null,
      "amount": 70000,
      "paidAmount": null,
      "paymentUrl": "https://pay.zoov.com.br/invoice/abc123",
      "successUrl": null,
      "invoiceSequence": 1,
      "pastDue": false,
      "paymentDate": null
    }
  ],
  "pageable": { "pageNumber": 0, "pageSize": 20 },
  "totalElements": 1,
  "totalPages": 1,
  "number": 0,
  "size": 20
}

Campo	Tipo	Descrição
`content[]`	array	Lista de faturas
`content[].id`	long	ID da fatura
`content[].invoiceNumber`	string	Número da fatura
`content[].status`	InvoiceStatus	Status da fatura
`content[].customer`	object	Dados do cliente (id, name, document, email, phone)
`content[].dueDate`	long	Data de vencimento (epoch ms)
`content[].closeDate`	long	Data de fechamento (epoch ms)
`content[].amount`	long	Valor total em centavos
`content[].paidAmount`	long	Valor pago em centavos
`content[].paymentUrl`	string	URL de pagamento
`content[].successUrl`	string	URL de redirecionamento
`content[].invoiceSequence`	integer	Sequência da fatura
`content[].pastDue`	boolean	Se a fatura está vencida
`content[].paymentDate`	long	Data de pagamento (epoch ms)
`pageable`	object	Informações de paginação
`totalElements`	integer	Total de registros
`totalPages`	integer	Total de páginas
`number`	integer	Página atual
`size`	integer	Itens por página

Status	Descrição
200	Lista retornada com sucesso
401	Nao autenticado

Recorrência & Assinaturas

Automatize cobranças recorrentes com faturas periodicas e assinaturas.

Faturas Recorrentes #

Crie faturas que sao geradas automáticamente em intervalos regulares.

POST /api/v2/sellers/{sellerId}/recurring-invoices

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Criar uma fatura recorrente.

json — request body

{
  "customerId": 1,
  "billingCycleStartDate": 1736944528450,
  "daysUntilDue": 7,
  "billingFrequency": "MONTHLY",
  "collectionMethod": "AUTOMATIC_CHARGE",
  "recurringItems": [
    {
      "quantity": 1,
      "productId": 1,
      "maxBillingCycles": 10,
      "unitPriceInCents": 1027
    }
  ],
  "acceptedPaymentMethods": [
    { "method": "CREDIT_CARD", "cardSettings": { "maxInstallments": 10 } },
    { "method": "PIX", "amountOff": 1500 }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`customerId`	integer	Sim	ID do cliente
`billingCycleStartDate`	long	Sim	Início do ciclo (ms epoch)
`daysUntilDue`	integer	Sim	Dias até vencimento
`billingFrequency`	string	Sim	DAILY, WEEKLY, MONTHLY, YEARLY
`collectionMethod`	string	Sim	Como cada fatura do ciclo é cobrada. `AUTOMATIC_CHARGE` ou `SEND_INVOICE` — veja a explicação abaixo.
`recurringItems[].quantity`	integer	Sim	Quantidade
`recurringItems[].productId`	integer	Sim	ID do produto
`recurringItems[].maxBillingCycles`	integer	Sim	Máximo de ciclos
`recurringItems[].unitPriceInCents`	integer	Sim	Preco em centavos

collectionMethod — cobrança automática ou link de pagamento:

AUTOMATIC_CHARGE — Cobrança automática. A cada ciclo, a plataforma tenta liquidar a fatura no vencimento sem ação do cliente. Com cartão de crédito, o débito é feito no cartão já cadastrado; com PIX Automático (após o consentimento na 1ª cobrança), o valor é debitado automaticamente da conta do pagador.
SEND_INVOICE — Envio de link. A cada ciclo, a fatura é gerada, mas o pagamento não é debitado automaticamente. O cliente recebe um link de pagamento (disponível também no header Link da resposta) e precisa acessá-lo para concluir o pagamento manualmente — por exemplo, escolhendo PIX, boleto ou cartão naquele ciclo.

Headers de Resposta

LocationURL do recurso criado

Content-IDID numérico da fatura recorrente

Resposta (após GET no recurso criado)

json — response body

{
  "id": 2001,
  "customerId": 1,
  "status": "ACTIVE",
  "billingFrequency": "MONTHLY",
  "collectionMethod": "AUTOMATIC_CHARGE",
  "billingCycleStartDate": 1736944528450,
  "daysUntilDue": 7,
  "recurringItems": [
    {
      "productId": 1,
      "quantity": 1,
      "unitPriceInCents": 1027,
      "maxBillingCycles": 10,
      "currentCycle": 1
    }
  ],
  "nextBillingDate": 1739622928450
}

Campo	Tipo	Descrição
`id`	integer	ID da fatura recorrente
`customerId`	integer	ID do cliente
`status`	string	Status da fatura (ACTIVE, CANCELLED, etc.)
`billingFrequency`	string	Frequencia de cobrança (DAILY, WEEKLY, MONTHLY, YEARLY)
`collectionMethod`	string	Como cada fatura do ciclo é cobrada: `AUTOMATIC_CHARGE` (automática) ou `SEND_INVOICE` (link de pagamento)
`billingCycleStartDate`	long	Início do ciclo em milissegundos (epoch)
`daysUntilDue`	integer	Dias até o vencimento
`recurringItems[]`	array	Lista de itens recorrentes
`nextBillingDate`	long	Proxima data de cobrança em milissegundos (epoch)

Status	Descrição
201	Fatura recorrente criada com sucesso
400	Requisição malformada
401	Não autorizado
422	Entidade não processável

Assinaturas #

Gerencie assinaturas vinculadas a planos de cobrança recorrente.

POST /api/v2/subscriptions/plans/{planId}/credit/card

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Criar uma assinatura vinculada a um plano, com pagamento via cartao de crédito.

Parâmetro	Tipo	Obrigatório	Descrição
`planId` (path)	integer	Sim	ID do plano de assinatura

json — request body

{
  "customer": {
    "name": "Tony Stark",
    "document": "51190844001",
    "birthdate": "2000-01-01",
    "email": "stark@gmail.com",
    "phone": {
      "countryCode": 55,
      "areaCode": 48,
      "number": 998870001
    }
  },
  "card": {
    "cardNumber": "5448280000000007",
    "cvv": "123",
    "holder": {
      "name": "Tony Stark",
      "document": "51190844001"
    },
    "expiration": {
      "year": 2026,
      "month": 12
    }
  },
  "startDate": 1751500800000
}

Campo	Tipo	Obrigatório	Descrição
`customer.name`	string	Sim	Nome completo do cliente (1-50 caracteres)
`customer.document`	string	Não	CPF/CNPJ do cliente (11-14 dígitos). Se informado, deve ser válido
`customer.birthdate`	string	Não	Data de nascimento (YYYY-MM-DD)
`customer.email`	string	Não	E-mail do cliente
`customer.phone`	object	Não	Telefone do cliente (se informado, sub-campos são obrigatórios)
`customer.phone.countryCode`	integer	Sim	Código do país (ex: 55)
`customer.phone.areaCode`	integer	Sim	DDD (11-99)
`customer.phone.number`	integer	Sim	Número do telefone
`customer.address`	object	Não	Endereço do cliente
`card.cardNumber`	string	Sim	Número do cartão (11-21 dígitos)
`card.cvv`	string	Não	CVV do cartão (3-4 dígitos, opcional)
`card.holder.name`	string	Sim	Nome do titular (1-45 caracteres)
`card.holder.document`	string	Não	CPF/CNPJ do titular. Se informado, deve ser válido
`card.expiration.year`	integer	Sim	Ano de validade (2023-2056)
`card.expiration.month`	integer	Sim	Mês de validade (1-12)
`yourReferenceId`	long	Não	Referência externa numérica (mínimo 1)
`notificationUrl`	string	Não	URL para receber notificações da assinatura
`startDate`	long	Não	Data de início agendado da assinatura em milissegundos desde a época (epoch UTC). Deve ser posterior à data atual. Quando ausente, a primeira cobrança ocorre imediatamente

Resposta: 201 Created — corpo vazio com headers HATEOAS

http response — 201 Created

HTTP/1.1 201 Created
Location: /api/v2/subscriptions/456
Content-ID: 456
Link: </api/v2/transactions/789>; rel="transaction"

Headers da resposta

Location URL da assinatura criada — use GET para consultar os detalhes

Content-ID ID numérico da assinatura

Link rel="transaction" URL da primeira transação da assinatura

Status	Descrição
201	Assinatura criada com sucesso
400	Requisição malformada
401	Não autorizado
404	Plano não encontrado
422	Entidade não processável (sem estabelecimento, referência duplicada)

POST /api/v2/sellers/{sellerId}/subscriptions/plans/{planId}/credit-card

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Criar uma assinatura vinculada a um plano e a um seller específico, com pagamento via cartao de crédito. O affiliate é resolvido a partir do sellerId informado na URL.

Parâmetro	Tipo	Obrigatório	Descrição
`sellerId` (path)	integer	Sim	ID do seller (affiliate) que receberá a assinatura
`planId` (path)	integer	Sim	ID do plano de assinatura

json — request body

{
  "customer": {
    "name": "Tony Stark",
    "document": "51190844001",
    "birthdate": "2000-01-01",
    "email": "stark@gmail.com",
    "phone": {
      "countryCode": 55,
      "areaCode": 48,
      "number": 998870001
    }
  },
  "card": {
    "cardNumber": "5448280000000007",
    "cvv": "123",
    "holder": {
      "name": "Tony Stark",
      "document": "51190844001"
    },
    "expiration": {
      "year": 2026,
      "month": 12
    }
  },
  "startDate": 1751500800000
}

Campo	Tipo	Obrigatório	Descrição
`customer.name`	string	Sim	Nome completo do cliente (1-50 caracteres)
`customer.document`	string	Não	CPF/CNPJ do cliente (11-14 dígitos). Se informado, deve ser válido
`customer.birthdate`	string	Não	Data de nascimento (YYYY-MM-DD)
`customer.email`	string	Não	E-mail do cliente
`customer.phone`	object	Não	Telefone do cliente (se informado, sub-campos são obrigatórios)
`customer.phone.countryCode`	integer	Sim	Código do país (ex: 55)
`customer.phone.areaCode`	integer	Sim	DDD (11-99)
`customer.phone.number`	integer	Sim	Número do telefone
`customer.address`	object	Não	Endereço do cliente
`card.cardNumber`	string	Sim	Número do cartão (11-21 dígitos)
`card.cvv`	string	Não	CVV do cartão (3-4 dígitos, opcional)
`card.holder.name`	string	Sim	Nome do titular (1-45 caracteres)
`card.holder.document`	string	Não	CPF/CNPJ do titular. Se informado, deve ser válido
`card.expiration.year`	integer	Sim	Ano de validade (2023-2056)
`card.expiration.month`	integer	Sim	Mês de validade (1-12)
`yourReferenceId`	long	Não	Referência externa numérica (mínimo 1)
`notificationUrl`	string	Não	URL para receber notificações da assinatura
`startDate`	long	Não	Data de início agendado da assinatura em milissegundos desde a época (epoch UTC). Deve ser posterior à data atual. Quando ausente, a primeira cobrança ocorre imediatamente

Resposta: 201 Created — corpo vazio com headers HATEOAS

http response — 201 Created

HTTP/1.1 201 Created
Location: /api/v2/subscriptions/456
Content-ID: 456
Link: </api/v2/transactions/789>; rel="transaction"

Headers da resposta

Location URL da assinatura criada — use GET para consultar os detalhes

Content-ID ID numérico da assinatura

Link rel="transaction" URL da primeira transação da assinatura

Status	Descrição
201	Assinatura criada com sucesso
400	Requisição malformada
401	Não autorizado
404	Plano ou seller não encontrado
422	Entidade não processável (sem estabelecimento, referência duplicada)

DELETE /api/v2/subscriptions/{id}

Headers

Authorization: Bearer {seu_token}

Cancelar uma assinatura existente.

Parâmetro	Tipo	Obrigatório	Descrição
`id` (path)	integer	Sim	ID da assinatura

Nenhum corpo e necessário. Cancela imediatamente a assinatura e interrompe cobranças futuras.

Status	Descrição
200	Assinatura cancelada com sucesso
401	Não autorizado
404	Assinatura não encontrada
422	Assinatura já cancelada (UnsubscribeException)

GET /api/v2/subscriptions

Headers

Authorization: Bearer {seu_token}

Listar assinaturas com filtros e paginação.

Parâmetro	Tipo	Obrigatório	Descrição
`status`	OrderStatus[]	Não	Filtrar por status (ACTIVE, INACTIVE, OVERDUE, PENDING, CHARGEBACK, COUNTERCHARGE, CANCELED). Pode repetir o parâmetro para múltiplos valores
`orderDateFrom`	long	Não	Data inicial do pedido em epoch ms (deve ser usado junto com `orderDateTo`)
`orderDateTo`	long	Não	Data final do pedido em epoch ms (deve ser usado junto com `orderDateFrom`)
`customerSearch`	string	Não	Busca por nome ou documento do cliente
`customerId`	integer	Não	Filtrar por ID do cliente
`affiliateId`	long	Não	Filtrar por ID do afiliado/loja
`planId`	integer	Não	Filtrar por ID do plano
`orderReference`	string	Não	Filtrar por referência externa do pedido
`limit`	integer	Não	Quantidade de itens por página (padrão: 10)
`offset`	integer	Não	Deslocamento para paginação (padrão: 0)

json — response body (200)

[
  {
    "id": 3001,
    "orderDate": 1694314800000,
    "status": "ACTIVE",
    "valueInCents": 29900,
    "frequency": "MONTHLY",
    "maxCycle": 12,
    "currentCycle": 3,
    "collectionMethod": "AUTOMATIC_CHARGE",
    "chargeStyle": "STREAM",
    "customer": {
      "id": 101,
      "name": "Tony Stark",
      "email": "stark@gmail.com",
      "document": "51190844001",
      "phone": {
        "countryCode": "55",
        "areaCode": "48",
        "number": "998870001"
      }
    },
    "items": [
      { "id": 55, "name": "Plano Premium" }
    ],
    "affiliate": {
      "id": 1,
      "name": "Loja Principal"
    }
  }
]

Campo	Tipo	Descrição
`id`	integer	ID da assinatura
`orderDate`	long	Data do pedido (epoch ms)
`status`	OrderStatus	Status da assinatura (ACTIVE, CANCELLED, etc.)
`valueInCents`	long	Valor em centavos
`frequency`	PlanFrequency	Frequência de cobrança (WEEKLY, BIWEEKLY, MONTHLY, BIMONTHLY, QUARTERLY, SEMESTRAL, YEARLY)
`maxCycle`	integer	Número máximo de ciclos de cobrança
`currentCycle`	integer	Ciclo atual (pode ser null)
`collectionMethod`	CollectionMethodTypes	Método de cobrança (AUTOMATIC_CHARGE, SEND_INVOICE)
`chargeStyle`	ChargeStyles	Estilo de cobrança (STREAM, BOOKLET)
`customer`	object	Dados do cliente
`customer.id`	integer	ID do cliente
`customer.name`	string	Nome do cliente
`customer.email`	string	E-mail do cliente
`customer.document`	string	CPF/CNPJ do cliente
`customer.phone`	object	Telefone do cliente
`items`	array	Planos vinculados à assinatura (id, name)
`affiliate`	object	Dados do afiliado/loja (pode ser null)
`affiliate.id`	long	ID do afiliado
`affiliate.name`	string	Nome do afiliado

Status	Descrição
200	Lista retornada com sucesso
401	Não autorizado

GET /api/v2/subscriptions/{id}

Headers

Authorization: Bearer {seu_token}

Obter os detalhes de uma assinatura.

Parâmetro	Tipo	Obrigatório	Descrição
`id` (path)	integer	Sim	ID da assinatura

json — response body

{
  "id": 3001,
  "orderDate": 1694314800000,
  "cancelationDate": null,
  "status": "ACTIVE",
  "amount": 29900,
  "yourReferenceId": "123456",
  "installments": 1,
  "affiliate": {
    "id": 1,
    "name": "Loja Principal"
  },
  "customer": {
    "id": 101,
    "name": "Tony Stark",
    "email": "stark@gmail.com",
    "document": "51190844001",
    "phone": {
      "countryCode": "55",
      "areaCode": "48",
      "number": "998870001"
    }
  },
  "items": [
    { "id": 55, "name": "Plano Premium" }
  ],
  "frequency": "MONTHLY",
  "maxCycle": 12,
  "currentCycle": 3,
  "collectionMethod": "AUTOMATIC_CHARGE",
  "chargeStyle": "STREAM"

Campo	Tipo	Descrição
`id`	integer	ID da assinatura
`orderDate`	long	Data do pedido (epoch ms)
`cancelationDate`	long	Data de cancelamento (epoch ms, null se ativa)
`status`	OrderStatus	Status da assinatura (ACTIVE, CANCELLED, etc.)
`amount`	long	Valor em centavos
`yourReferenceId`	string	Referência externa
`installments`	integer	Número de parcelas
`affiliate`	object	Dados do afiliado/loja (pode ser null)
`affiliate.id`	long	ID do afiliado
`affiliate.name`	string	Nome do afiliado
`customer`	object	Dados do cliente (pode ser null)
`customer.id`	integer	ID do cliente
`customer.name`	string	Nome do cliente
`customer.email`	string	E-mail do cliente
`customer.document`	string	CPF/CNPJ do cliente
`customer.phone`	object	Telefone do cliente
`items`	array	Planos vinculados à assinatura (id, name)
`frequency`	PlanFrequency	Frequência de cobrança (WEEKLY, BIWEEKLY, MONTHLY, BIMONTHLY, QUARTERLY, SEMESTRAL, YEARLY)
`maxCycle`	integer	Número máximo de ciclos de cobrança
`currentCycle`	integer	Ciclo atual (pode ser null)
`collectionMethod`	CollectionMethodTypes	Método de cobrança (AUTOMATIC_CHARGE, SEND_INVOICE)
`chargeStyle`	ChargeStyles	Estilo de cobrança (STREAM, BOOKLET)

Headers de Resposta

Linkrel="charges" — URL para listar cobranças da assinatura

Linkrel="customer" — URL do cliente vinculado

Status	Descrição
200	Assinatura retornada com sucesso
401	Não autorizado
404	Assinatura não encontrada

PIX Automático

Recorrência nativa do PIX (padrão do Banco Central): o cliente autoriza uma única vez e as cobranças seguintes são debitadas automaticamente, sem novo QR Code a cada ciclo.

Visão Geral #

O PIX Automático é o padrão de recorrência do PIX regulamentado pelo Banco Central. Diferente do PIX comum — em que cada cobrança gera um QR Code que o cliente precisa pagar manualmente — aqui o cliente concede uma autorização de débito recorrente (o consentimento) apenas na primeira cobrança. A partir daí, cada cobrança do ciclo é debitada automaticamente da conta do pagador, sem qualquer ação dele.

Aspecto	PIX comum	PIX Automático
Autorização do cliente	A cada cobrança	Uma única vez (consentimento)
Cobranças seguintes	Novo QR Code manual	Débito automático por ciclo
Ideal para	Pagamento avulso	Mensalidades, assinaturas, planos
Retentativa em caso de falha	Não se aplica	Automática (até 3 tentativas em 7 dias)

Habilitação: o PIX Automático precisa estar liberado para a sua conta. Fale com o time da Zoov Payment para ativar o recurso antes de começar a integração.

Somente novas assinaturas: o PIX Automático vale apenas para assinaturas criadas a partir da adoção deste fluxo (fatura recorrente). Assinaturas existentes que já foram criadas com PIX imediato (QR Code pago a cada ciclo) não migram para o débito recorrente automaticamente e continuam no fluxo antigo. Para usar o PIX Automático com um cliente já existente, crie uma nova assinatura utlizando o fluxo de fatura recorrente.

Como funciona #

Fluxo do PIX Automático

1

Criar autorização

Fatura recorrente aceitando PIX

2

Cliente autoriza

Paga o 1º PIX e aprova o débito recorrente

3

Débitos automáticos

Cada ciclo é debitado sem ação do cliente

4

Webhooks

Você acompanha consentimento e cada liquidação

Ao pagar a primeira fatura via PIX, o cliente recebe um QR Code (copia-e-cola) que faz duas coisas ao mesmo tempo: liquida o primeiro pagamento e concede a autorização de recorrência (jornada de autorização + pagamento em uma etapa única). É nesse momento que a recorrência é registrada no Banco Central. Concluída essa etapa, a Zoov Payment passa a gerar e debitar as cobranças seguintes automaticamente, na frequência definida na fatura recorrente — a primeira cobrança fica pendente e as demais já nascem agendadas.

Criar a autorização #

O PIX Automático é iniciado a partir de uma Fatura Recorrente que aceita PIX em acceptedPaymentMethods. Não há endpoint separado para a recorrência. Com o recurso habilitado na sua conta, a autorização de débito recorrente é registrada automaticamente no momento em que a primeira fatura é paga via PIX — é aí que o QR Code é gerado (veja Como funciona).

O que aciona o PIX Automático: não é o collectionMethod, e sim o recurso estar habilitado na conta somado a uma fatura recorrente paga via PIX. O collectionMethod (AUTOMATIC_CHARGE ou SEND_INVOICE) define apenas como as faturas são operadas — a recorrência PIX funciona com ambos.

POST /api/v2/sellers/{sellerId}/recurring-invoices

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Criar uma fatura recorrente que aceita PIX (base para a recorrência PIX Automático).

json — request body

{
  "customerId": 1,
  "billingCycleStartDate": 1736944528450,
  "daysUntilDue": 7,
  "billingFrequency": "MONTHLY",
  "collectionMethod": "AUTOMATIC_CHARGE",
  "recurringItems": [
    {
      "quantity": 1,
      "productId": 1,
      "maxBillingCycles": 12,
      "unitPriceInCents": 4990
    }
  ],
  "acceptedPaymentMethods": [
    { "method": "PIX" }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`collectionMethod`	string	Sim	Como cada fatura do ciclo é cobrada: `AUTOMATIC_CHARGE` (débito automático) ou `SEND_INVOICE` (link de pagamento a cada ciclo). Não é o que aciona o PIX Automático — a recorrência PIX funciona com qualquer um dos dois. Detalhes em Faturas Recorrentes.
`acceptedPaymentMethods[].method`	string	Sim	Inclua `PIX`. Para PIX, informe apenas `method` (o objeto `cardSettings` só é exigido para `CREDIT_CARD`).
`billingFrequency`	string	Sim	Frequência da recorrência. No PIX Automático: `WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMESTRAL` ou `YEARLY`.
`recurringItems[].maxBillingCycles`	integer	Sim	Número máximo de ciclos a serem cobrados.

Consulte a seção Faturas Recorrentes para a lista completa de campos e resposta. A criação retorna 201 Created com Location e headers Link (assinatura, faturas e link de pagamento) — o QR Code não vem nesta resposta. Ele é gerado quando a primeira fatura é paga via PIX.

Ciclo de vida da autorização #

O consentimento (a autorização de débito recorrente) passa pelos seguintes estados. Importante: a fatura só se torna ativa quando a primeira cobrança é efetivamente paga — aprovar o consentimento sozinho não confirma pagamento.

Estado do consentimento	Significado	Efeito na fatura
Criado	Autorização gerada, aguardando o cliente aprovar/pagar.	Pendente
Aprovado	Cliente concedeu o débito recorrente.	Pendente até a 1ª cobrança ser paga
Rejeitado	Cliente ou banco recusou a autorização.	Cancelada
Expirado	Autorização não foi concluída no prazo.	Cancelada
Cancelado	Recorrência encerrada (pelo cliente ou lojista).	Cancelada

A cada ciclo, uma cobrança é agendada e debitada automaticamente. Se um débito falhar, o PIX Automático faz retentativa automática (até 3 tentativas ao longo de 7 dias) antes de marcar a cobrança como não paga.

Webhooks #

Como as cobranças acontecem sem interação do cliente, os webhooks são a forma de acompanhar a recorrência. As notificações chegam na URL configurada em notificationUrl (mesmo mecanismo descrito em Webhooks & Eventos). Você recebe eventos em dois momentos:

Evento	Quando ocorre	O que fazer
Status do consentimento	Quando a autorização é criada, aprovada, rejeitada, expira ou é cancelada.	Atualize o estado da recorrência no seu sistema (ver tabela acima).
Liquidação da cobrança	Quando uma cobrança do ciclo é efetivamente paga.	Confirme o pagamento e libere/renove o serviço do cliente.

Importante: confirme o pagamento apenas quando a cobrança estiver liquidada (paga). Notificações de agendamento ou de tentativa em andamento não significam que o valor foi debitado. Ao receber o webhook, faça um GET na API para obter o status atualizado antes de liberar o serviço.

Marketplace & Split

Distribua automáticamente os valores entre multiplos vendedores em uma transação.

Exemplo com Split #

json — pedido com split

{
  "orderReference": "ORDER-SPLIT-001",
  "amount": 150000,
  "splitMode": "ACQUIRER",
  "payments": [{
    "paymentMethod": "CREDIT_CARD",
    "cardToken": { "cvv": "123", "token": "9fab5bfd..." },
    "amount": 150000,
    "installments": 10,
    "splits": [
      { "amount": 100000, "sellerId": 1 },
      { "amount": 50000, "sellerId": 2 }
    ]
  }]
}

Importante: A soma dos valores do split DEVE ser igual ao valor total do pedido.

Campo	Tipo	Obrigatório	Descrição
`splitMode`	SplitModes	Sim	Modo do split (DATABASE ou ACQUIRER)
`payments[].splits[].sellerId`	long	Sim	ID do vendedor/recebedor (mínimo 1)
`payments[].splits[].amount`	long	Sim	Valor em centavos para este recebedor (mínimo 1)
`payments[].splits[].absorbFee`	boolean	Não	Se TRUE, o recebedor absorve as taxas de intermediação

Headers de Resposta

LocationURL do recurso criado

Content-IDID numérico do pedido

LinkLinks HATEOAS para recursos relacionados

Status	Descrição
201	Pedido com split criado com sucesso
400	Requisição malformada
401	Não autorizado
422	Entidade não processável

Fatura com Split #

Crie uma fatura distribuindo o valor entre múltiplos vendedores. No split de fatura a divisão é feita por percentual (campo splits[].percentage), diferente do split de pedido que utiliza valor em centavos.

POST /api/v2/sellers/{sellerId}/invoices

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Criar uma fatura avulsa com split de pagamento entre vendedores.

json — fatura com split

{
  "customerId": 1,
  "invoiceNumber": "FAT-2024-SPLIT-001",
  "dueDate": "1732310753051",
  "notificationUrl": "https://meusite.com.br/events",
  "successUrl": "https://meusite.com.br/sucesso",
  "items": [
    { "productId": 1, "quantity": 1, "unitPriceInCents": 100000 }
  ],
  "acceptedPaymentMethods": [
    {
      "method": "CREDIT_CARD",
      "cardSettings": { "maxInstallments": 10, "feePassThrough": false }
    }
  ],
  "splits": [
    { "sellerId": 1, "percentage": 70 }
    { "sellerId": 2, "percentage": 30 }
  ]
}

Importante: A soma dos valores de splits[].percentage DEVE ser igual a 100%.

Campo	Tipo	Obrigatório	Descrição
`splits[]`	array	Não	Regras de split de pagamento da fatura
`splits[].sellerId`	long	Sim	ID do vendedor/recebedor
`splits[].percentage`	decimal	Sim	Percentual destinado ao recebedor (a soma de todos deve ser 100)
`splits[].absorbFee`	boolean	Não	Se TRUE, o recebedor absorve as taxas de intermediação (default: false)

Resposta: 201 Created — corpo vazio com headers HATEOAS

http response — 201 Created

HTTP/1.1 201 Created
Location: /api/v2/invoices/789
Link: </api/v2/invoices/789/credit-card/pay>; rel="pay-invoice-credit-card"

Headers da resposta

Location URL da fatura criada — use GET para consultar os detalhes

Link rel="pay-invoice-credit-card" URL para pagamento da fatura com cartão de crédito

Status	Descrição
201	Fatura com split criada com sucesso
401	Não autorizado
422	Entidade não processável (ex.: soma dos percentuais diferente de 100%)

Sellers e Receivers #

Cadastre vendedores (sellers) e recebedores (receivers) para operar split de pagamento em marketplace.

Vendedor (seller) vs Recebedor (receiver): ambos usam o mesmo formato de cadastro (CPF ou CNPJ), mas com papéis distintos na plataforma:

Vendedor (seller) — pode iniciar uma venda (pedidos, faturas, assinaturas etc.) e também participar do split como recebedor de parte do valor.
Recebedor (receiver) — não pode iniciar uma venda; participa apenas como destinatário de uma parcela do valor em operações de split já iniciadas por um vendedor.

KYC: tanto o vendedor quanto o recebedor passam pelo processo completo de KYC (validação de identidade e dados cadastrais) antes de ficarem aptos a operar. Após a criação via API, o cadastro inicia com status PENDING até a conclusão desse onboarding.

POST /api/v2/sellers/cnpj

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Cadastrar seller por CNPJ.

json — request body

{
  "owner": {
    "name": {
      "firstName": "João",
      "lastName": "Silva"
    },
    "document": "51190844001",
    "birthdate": "1990-01-15",
    "email": "joao@email.com",
    "phone": { "countryCode": "55", "areaCode": "48", "number": "998870001" },
    "address": {
      "street": "Rua Principal", "streetNumber": "100",
      "neighborhood": "Centro", "city": "Florianópolis",
      "state": "SC", "zipCode": "88000000"
    }
  },
  "businessName": "Empresa Exemplo LTDA",
  "document": "12345678000190",
  "openingDate": "2020-03-15",
  "businessEmail": "contato@empresa.com",
  "businessPhone": { "countryCode": "55", "areaCode": "48", "number": "33001234" },
  "businessAddress": {
    "street": "Av Comercial", "streetNumber": "500",
    "neighborhood": "Centro", "city": "Florianópolis",
    "state": "SC", "zipCode": "88000000"
  },
  "mcc": 5411,
  "bankAccount": {
    "bankCode": "001",
    "bankBranch": "1234",
    "accountNumber": "56789",
    "accountCheckDigit": "0",
    "accountType": "CHECKING"
  }
}

Campo	Tipo	Obrigatório	Descrição
`owner.name.firstName`	string	Sim	Primeiro nome do proprietário
`owner.name.lastName`	string	Sim	Sobrenome do proprietário
`owner.document`	string	Sim	CPF do proprietário (11 dígitos numéricos)
`owner.birthdate`	string	Sim	Data de nascimento (YYYY-MM-DD)
`owner.email`	string	Sim	E-mail do proprietário
`owner.phone`	object	Sim	Telefone (countryCode, areaCode, number)
`owner.address`	object	Sim	Endereço do proprietário (street, streetNumber, neighborhood, city, state, zipCode)
`businessName`	string	Sim	Razão social da empresa
`document`	string	Sim	CNPJ (14 caracteres alfanuméricos)
`openingDate`	string	Sim	Data de abertura da empresa (YYYY-MM-DD)
`businessEmail`	string	Sim	E-mail da empresa
`businessPhone`	object	Sim	Telefone da empresa (countryCode, areaCode, number)
`businessAddress`	object	Sim	Endereço comercial (street, streetNumber, neighborhood, city, state, zipCode)
`mcc`	integer	Sim	Código MCC (Merchant Category Code)
`bankAccount`	object	Sim	Conta bancária (bankCode, bankBranch, accountNumber, accountCheckDigit, accountType)
`softDescriptor`	string	Não	Nome exibido na fatura do cartão
`notificationUrl`	string (URI)	Não	URL para receber webhooks de eventos do seller
`webLinks`	object	Não	Links da empresa (websiteUrl, facebookUrl, instagramUrl, socialXUrl)
`monthlyRevenueInCents`	long	Não	Faturamento mensal estimado em centavos

Resposta: 201 Created — corpo vazio

http response — 201 Created

HTTP/1.1 201 Created
Location: /api/v2/sellers/12345

Headers da resposta

Location URL do seller criado — use GET para consultar os detalhes

Status	Descrição
201	Seller criado com sucesso
400	Requisição malformada
401	Não autorizado
422	Entidade não processável (documento duplicado, MCC inválido, etc.)

POST /api/v2/sellers/cpf

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Cadastrar seller por CPF.

json — request body

{
  "name": {
    "firstName": "Tony",
    "lastName": "Stark"
  },
  "document": "51190844001",
  "birthdate": "1990-05-29",
  "email": "tony@email.com",
  "phone": {
    "countryCode": "55",
    "areaCode": "48",
    "number": "998870001"
  },
  "address": {
    "street": "Rua Principal", "streetNumber": "100",
    "neighborhood": "Centro", "city": "Florianópolis",
    "state": "SC", "zipCode": "88000000"
  },
  "mcc": 5411,
  "bankAccount": {
    "bankCode": "001",
    "bankBranch": "1234",
    "accountNumber": "56789",
    "accountCheckDigit": "0",
    "accountType": "CHECKING"
  }
}

Campo	Tipo	Obrigatório	Descrição
`name.firstName`	string	Sim	Primeiro nome
`name.lastName`	string	Sim	Sobrenome
`document`	string	Sim	CPF (11 dígitos numéricos)
`birthdate`	string	Sim	Data de nascimento (YYYY-MM-DD)
`email`	string	Sim	E-mail de contato
`phone.countryCode`	string	Não	Código do país (1-3 dígitos, ex: "55")
`phone.areaCode`	string	Sim	DDD (2 dígitos)
`phone.number`	string	Sim	Número do telefone (6-9 dígitos)
`address`	object	Sim	Endereço (street, streetNumber, neighborhood, city, state, zipCode)
`mcc`	integer	Sim	Código MCC (Merchant Category Code)
`bankAccount.bankCode`	string	Sim	Código do banco (3-4 dígitos, ex: "001")
`bankAccount.bankBranch`	string	Sim	Número da agência (1-9 caracteres)
`bankAccount.bankBranchCheckDigit`	string	Não	Dígito verificador da agência (1-2 caracteres)
`bankAccount.accountNumber`	string	Sim	Número da conta (1-11 caracteres)
`bankAccount.accountCheckDigit`	string	Sim	Dígito verificador da conta (1-2 caracteres)
`bankAccount.accountType`	GatewayAccountTypes	Sim	Tipo da conta (CHECKING, SAVINGS)
`softDescriptor`	string	Não	Nome exibido na fatura do cartão
`notificationUrl`	string (URI)	Não	URL para receber webhooks de eventos do seller
`webLinks`	object	Não	Links da empresa (websiteUrl, facebookUrl, instagramUrl, socialXUrl)
`monthlyRevenueInCents`	long	Não	Faturamento mensal estimado em centavos

Resposta: 201 Created — corpo vazio

http response — 201 Created

HTTP/1.1 201 Created
Location: /api/v2/sellers/12345

Headers da resposta

Location URL do seller criado — use GET para consultar os detalhes

Status	Descrição
201	Seller criado com sucesso
400	Requisição malformada
401	Não autorizado
422	Entidade não processável (documento duplicado, MCC inválido, etc.)

POST /api/v2/receivers/cnpj

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Cadastrar receiver por CNPJ. Utiliza o mesmo formato de corpo do seller CNPJ.

Resposta: 201 Created — corpo vazio

http response — 201 Created

HTTP/1.1 201 Created
Location: /api/v2/receivers/12345

Headers da resposta

Location URL do receiver criado — use GET para consultar os detalhes

Status	Descrição
201	Receiver criado com sucesso
400	Requisição malformada
401	Não autorizado
422	Entidade não processável (documento duplicado, MCC inválido, etc.)

POST /api/v2/receivers/cpf

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Cadastrar receiver por CPF. Utiliza o mesmo formato de corpo do seller CPF.

Resposta: 201 Created — corpo vazio

http response — 201 Created

HTTP/1.1 201 Created
Location: /api/v2/receivers/12345

Headers da resposta

Location URL do receiver criado — use GET para consultar os detalhes

Status	Descrição
201	Receiver criado com sucesso
400	Requisição malformada
401	Não autorizado
422	Entidade não processável (documento duplicado, MCC inválido, etc.)

GET /api/v2/sellers

Headers

Authorization: Bearer {seu_token}

Listar sellers cadastrados com paginação e filtros opcionais.

Parâmetro	Tipo	Obrigatório	Descrição
`searchField` (query)	string	Não	Busca por nome ou documento
`status` (query)	array	Não	Filtrar por status: `ACTIVE`, `PENDING`, `INACTIVE`, `CANCELED`
`document` (query)	string	Não	Filtrar por CPF ou CNPJ
`limit` (query)	integer	Não	Itens por página (default: 10)
`offset` (query)	integer	Não	Deslocamento da paginação (default: 0)

json — response body

[
  {
    "id": 1,
    "name": "Tony Stark",
    "email": "tony@email.com",
    "document": "51190844001",
    "status": "ACTIVE",
    "mcc": 5411,
    "bank": {
      "bankCode": "001",
      "name": "Banco do Brasil"
    }
  }
]

Campo	Tipo	Descrição
`[].id`	long	ID do seller
`[].name`	string	Nome do seller
`[].email`	string	E-mail de contato
`[].document`	string	CPF ou CNPJ
`[].status`	AffiliateStatus	Status: `ACTIVE`, `PENDING`, `INACTIVE`, `CANCELED`
`[].mcc`	integer	Código MCC
`[].bank`	object	Banco vinculado (bankCode, name)

Status	Descrição
200	Lista retornada com sucesso
401	Não autorizado

GET /api/v2/sellers/{id}

Headers

Authorization: Bearer {seu_token}

Obter seller por ID.

Parâmetro	Tipo	Obrigatório	Descrição
`id` (path)	integer	Sim	ID do seller

json — response body

{
  "id": 1,
  "name": "Tony Stark",
  "businessName": "Empresa Exemplo LTDA",
  "document": "12345678000190",
  "address": {
    "street": "Av Comercial",
    "streetNumber": "500",
    "neighborhood": "Centro",
    "city": "Florianópolis",
    "state": "SC",
    "zipCode": "88000000"
  },
  "isSeller": true,
  "status": "ACTIVE"
}

Campo	Tipo	Descrição
`id`	long	ID do seller
`name`	string	Nome do seller
`businessName`	string	Razão social
`document`	string	CPF ou CNPJ
`address`	object	Endereço (street, streetNumber, lineTwo, neighborhood, zipCode, city, state)
`isSeller`	boolean	Se é vendedor (true para sellers)
`status`	AffiliateStatus	Status: `ACTIVE`, `PENDING`, `INACTIVE`, `CANCELED`

Status	Descrição
200	Seller retornado com sucesso
401	Não autorizado
404	Seller não encontrado

GET /api/v2/receivers

Headers

Authorization: Bearer {seu_token}

Listar receivers cadastrados com paginação e filtros opcionais.

Parâmetro	Tipo	Obrigatório	Descrição
`searchField` (query)	string	Não	Busca por nome ou documento
`status` (query)	array	Não	Filtrar por status: `ACTIVE`, `PENDING`, `INACTIVE`, `CANCELED`
`document` (query)	string	Não	Filtrar por CPF ou CNPJ
`limit` (query)	integer	Não	Itens por página (default: 10)
`offset` (query)	integer	Não	Deslocamento da paginação (default: 0)

json — response body

[
  {
    "id": 2,
    "name": "Parceiro Exemplo",
    "email": "parceiro@email.com",
    "document": "12345678000190",
    "status": "PENDING",
    "mcc": 5411,
    "bank": {
      "bankCode": "001",
      "name": "Banco do Brasil"
    }
  }
]

Campo	Tipo	Descrição
`[].id`	long	ID do receiver
`[].name`	string	Nome do receiver
`[].email`	string	E-mail de contato
`[].document`	string	CPF ou CNPJ
`[].status`	AffiliateStatus	Status: `ACTIVE`, `PENDING`, `INACTIVE`, `CANCELED`
`[].mcc`	integer	Código MCC
`[].bank`	object	Banco vinculado (bankCode, name)

Status	Descrição
200	Lista retornada com sucesso
401	Não autorizado

GET /api/v2/receivers/{id}

Headers

Authorization: Bearer {seu_token}

Obter receiver por ID.

Parâmetro	Tipo	Obrigatório	Descrição
`id` (path)	integer	Sim	ID do receiver

json — response body

{
  "id": 1,
  "name": "Tony Stark",
  "businessName": "Empresa Exemplo LTDA",
  "document": "12345678000190",
  "address": {
    "street": "Av Comercial",
    "streetNumber": "500",
    "neighborhood": "Centro",
    "city": "Florianópolis",
    "state": "SC",
    "zipCode": "88000000"
  },
  "isSeller": false,
  "status": "ACTIVE"
}

Campo	Tipo	Descrição
`id`	long	ID do receiver
`name`	string	Nome do receiver
`businessName`	string	Razão social
`document`	string	CPF ou CNPJ
`address`	object	Endereço (street, streetNumber, lineTwo, neighborhood, zipCode, city, state)
`isSeller`	boolean	Se é vendedor (false para receivers)
`status`	AffiliateStatus	Status: `ACTIVE`, `PENDING`, `INACTIVE`, `CANCELED`

Status	Descrição
200	Receiver retornado com sucesso
401	Não autorizado
404	Receiver não encontrado

Split Pós-Venda #

Aplique ou cancele a divisão de recebimento em cobranças já realizadas, sem precisar criar um novo pedido. O split opera sobre a última transação da cobrança.

Regras de negócio

Pré-condições para gerar o split — a API retorna 422 se qualquer uma das condições abaixo não for atendida:

A cobrança deve ter a última transação com status APPROVED.
Cada sellerId deve existir e ter CPF/CNPJ cadastrado.
Cada amount deve ser maior que zero.
A soma de todos os amount deve ser exatamente igual ao valor da transação.
Exatamente um recebedor deve ter main: true.
Ao menos um recebedor deve ter liableFee: true.
Exatamente um recebedor deve ter liableChargeback: true.
O mesmo sellerId não pode aparecer em mais de uma regra.

O cancelamento (DELETE) só é possível se o split tiver sido gerado com sucesso anteriormente. Caso contrário, a API retorna 422.

Listar Splits de uma Cobrança #

GET /api/v2/charges/{id}/splits

Headers

Authorization: Bearer {seu_token}

Retorna a lista de splits configurados para a cobrança informada.

Parâmetro	Tipo	Descrição
`id` (path)	long	ID da cobrança

Resposta 200 OK — lista de splits:

json — 200 OK

[
  {
    "affiliate": {
      "id": 42,
      "name": "Loja Principal",
      "businessName": "Empresa Exemplo LTDA",
      "document": "12345678000190",
      "isSeller": true,
      "status": "ACTIVE"
    },
    "amount": 100000,
    "absorbFee": true
  },
  {
    "affiliate": {
      "id": 99,
      "name": "Parceiro Secundário",
      "businessName": "Parceiro LTDA",
      "document": "98765432000111",
      "isSeller": true,
      "status": "ACTIVE"
    },
    "amount": 50000,
    "absorbFee": false
  }
]

Campo	Tipo	Descrição
`affiliate.id`	long	ID do seller/recebedor
`affiliate.name`	string	Nome do seller/recebedor
`affiliate.businessName`	string	Razão social
`affiliate.document`	string	CPF ou CNPJ
`affiliate.isSeller`	boolean	Indica se é um seller
`affiliate.status`	string	Status do seller (ACTIVE, INACTIVE, etc.)
`amount`	long	Valor destinado ao recebedor, em centavos
`absorbFee`	boolean	Se o recebedor absorve as taxas de intermediação

Status	Descrição
200	Lista de splits retornada com sucesso
204	Cobrança não possui splits configurados
401	Não autorizado
404	Cobrança não encontrada

Gerar Split de uma Transação Existente #

POST /api/v2/charges/{id}/split

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Envia as regras de divisão da última transação da cobrança para a MovingPay.

json — request body

{
  "splits": [
    {
      "sellerId": 42,
      "amount": 100000,
      "main": true,
      "liableFee": true,
      "liableChargeback": true
    },
    {
      "sellerId": 99,
      "amount": 50000,
      "main": false,
      "liableFee": false,
      "liableChargeback": false
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`splits[]`	array	Sim	Lista de regras de divisão (mínimo 1 item)
`splits[].sellerId`	long	Sim	ID do seller/recebedor (mínimo 1)
`splits[].amount`	long	Sim	Valor destinado ao recebedor, em centavos (mínimo 1)
`splits[].main`	boolean	Sim	Indica o recebedor principal da transação. Apenas um pode ser `true`
`splits[].liableFee`	boolean	Sim	Define se o recebedor arcará com as taxas (MDR) da transação
`splits[].liableChargeback`	boolean	Sim	Define se o recebedor será responsável em caso de chargeback

Resposta 201 Created:

json — 201 Created

{
  "processKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Campo	Tipo	Descrição
`processKey`	string	Chave do processo de split na MovingPay, usada para rastreio e cancelamento

Resposta 422 Unprocessable Entity (erros de validação):

json — 422 Unprocessable Entity

[
  {
    "code": "422",
    "message": "A soma dos valores do split deve ser igual ao valor da transação."
  }
]

Status	Descrição
201	Split gerado com sucesso
401	Não autorizado
404	Cobrança não encontrada
422	Regras de divisão inválidas
502	Erro de comunicação com a MovingPay

Cancelar Split de uma Transação #

DELETE /api/v2/charges/{id}/split

Headers

Authorization: Bearer {seu_token}

Cancela o split da última transação da cobrança na MovingPay e limpa o estado local.

Parâmetro	Tipo	Descrição
`id` (path)	long	ID da cobrança cujo split deve ser cancelado

Status	Descrição
200	Split cancelado com sucesso
401	Não autorizado
404	Cobrança não encontrada
422	Não foi possível cancelar o split
502	Erro de comunicação com a MovingPay

Segurança

Adicione uma camada extra de seguranca com autenticação 3D Secure.

Fluxo 3DS #

Fluxo de autenticação 3DS

1

Autorizar

Envie dados do dispositivo com 3DS

2

Challenge

Redirecione o cliente se necessário

3

Webhook

Receba a confirmacao via notificação

Autorização com 3DS #

POST /api/v2/sellers/{sellerId}/orders/credit-card/three-d-secure/authorize

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Autorizar pagamento com autenticação 3D Secure.

json — request body

{
  "mode": "DEBIT",
  "value": 10000,
  "installments": 1,
  "orderReference": "3DS_1694314800",
  "notificationUrl": "https://meusite.com.br/events",
  "customer": {
    "name": "Tony Stark",
    "document": "51190844001",
    "birthdate": "2000-01-01",
    "email": "stark@gmail.com",
    "phone": {
      "countryCode": 55,
      "areaCode": 48,
      "number": 998870001
    },
    "address": {
      "street": "Rua Jair Hamms",
      "streetNumber": "38",
      "neighborhood": "Pedra Branca",
      "city": "Palhoca",
      "state": "SC",
      "zipCode": "88137084"
    }
  },
  "card": {
    "cardNumber": "4918019199883839",
    "cvv": "123",
    "expiration": { "month": 12, "year": 2034 },
    "holder": { "name": "Tony Stark", "document": "51190844001" }
  },
  "threeDSecure": {
    "device": {
      "deviceType3ds": "BROWSER",
      "screenWidth": 1920,
      "screenHeight": 1080,
      "colorDepth": 24,
      "javaEnabled": false,
      "javascriptEnabled": true,
      "language": "pt-BR",
      "timeZoneOffset": -3
    },
    "onFailure": "CONTINUE",
    "ipAddress": "192.168.1.100",
    "userAgent": "Mozilla/5.0...",
    "embedded": false,
    "successUrl": "https://meusite.com.br/sucesso",
    "failureUrl": "https://meusite.com.br/falha",
    "billing": {
      "address": {
        "street": "Rua Jair Hamms", "streetNumber": "38",
        "zipCode": "88137084", "neighborhood": "Pedra Branca",
        "city": "Palhoca", "state": "SC"
      },
      "phone": { "country": "BRAZIL", "areaCode": "48", "number": "998870001" },
      "email": "stark@gmail.com"
    }
  }
}

Campos principais da requisição

Campo	Tipo	Obrigatório	Descrição
`mode`	GatewayTransactionDeployTypes	Sim	Modo da transação (DEBIT ou CREDIT)
`value`	long	Sim	Valor em centavos (mínimo 0)
`installments`	integer	Sim	Número de parcelas (1-12, use 1 para débito)
`orderReference`	string	Sim	Referência única do pedido (4-32 caracteres)
`notificationUrl`	string (URI)	Sim	URL de notificação webhook (deve ser URI válida)
`softDescriptor`	string	Não	Descrição na fatura do cartão (máx. 10 caracteres)
`splits[]`	array	Não	Regras de split (soma dos amounts deve ser igual ao value)

Campos do cartão (objeto `card`)

Campo	Tipo	Obrigatório	Descrição
`card.cardNumber`	string	Sim	Número do cartão (11-21 dígitos)
`card.cvv`	string	Não	Código de segurança (3-4 dígitos, opcional)
`card.expiration.month`	integer	Sim	Mês de expiração (1-12)
`card.expiration.year`	integer	Sim	Ano de expiração (2023-2056)
`card.holder.name`	string	Sim	Nome do titular (1-45 caracteres)
`card.holder.document`	string	Não	CPF/CNPJ do titular. Se informado, deve ser válido

Campos 3DS adicionais (objeto `threeDSecure`)

Campo	Tipo	Obrigatório	Descrição
`device.deviceType3ds`	ThreeDSecurityDeviceTypes	Sim	Tipo do dispositivo (BROWSER)
`device.screenWidth`	integer	Sim	Largura da tela em pixels (mínimo 0)
`device.screenHeight`	integer	Sim	Altura da tela em pixels (mínimo 0)
`device.colorDepth`	integer	Sim	Profundidade de cor
`device.javaEnabled`	boolean	Sim	Java habilitado no navegador
`device.javascriptEnabled`	boolean	Sim	JavaScript habilitado no navegador
`device.language`	string	Sim	Idioma do navegador (RFC BCP47, ex: "pt-BR")
`device.timeZoneOffset`	integer	Sim	Offset UTC em horas
`device.deviceFingerprint`	string	Não	Fingerprint do dispositivo
`onFailure`	OnFailureTypes	Sim	Ação em caso de falha (CONTINUE ou DECLINE)
`ipAddress`	string	Sim	IP do cliente (IPv4)
`userAgent`	string	Sim	User agent do navegador
`successUrl`	string (URL)	Sim	URL de redirecionamento em caso de sucesso
`failureUrl`	string (URL)	Sim	URL de redirecionamento em caso de falha
`embedded`	boolean	Não	Se o challenge será embutido na página (opcional)
`billing.address.*`	object	Sim	Endereço de cobrança (street, streetNumber, zipCode, neighborhood, city, state)
`billing.phone.country`	GatewayCountryTypes	Sim	País (ex: BRAZIL)
`billing.phone.areaCode`	string	Sim	DDD
`billing.phone.number`	string	Sim	Número do telefone
`billing.email`	string	Sim	E-mail de cobrança

Headers de Resposta

LocationURL da cobrança criada

LinkURL do challenge, se necessário (redirecione o cliente para esta URL)

Response body (201)

Campo	Tipo	Descrição
`creq`	string	Token do challenge request
`authenticationTransactionId`	string	ID da transação de autenticação 3DS
`jwt`	string	JWT token
`transactionId`	string	Identificador do pedido/transação
`acsUrl`	string	URL do ACS para challenge
`validateUrl`	object	URL para validação/confirmação

Status	Descrição
201	Autorização 3DS criada com sucesso (retorna ThreeDSecureV2Response)
400	Requisição malformada
401	Não autorizado
404	Seller não encontrado
422	Entidade não processável

Sandbox: No sandbox, use mode: "DEBIT". Os cartões 4918019199883839 (challenge) e 4918019160034602 (frictionless) podem ser usados para testes.

Pré-autorização com 3DS #

POST /api/v2/sellers/{sellerId}/orders/credit-card/three-d-secure/pre-authorize

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Pré-autorizar pagamento com autenticação 3D Secure. Reserva o valor no cartão sem capturar — a captura deve ser feita posteriormente.

O request body é idêntico ao endpoint de autorização 3DS (OnetimeChargeThreeDSecureV2Request). A diferença é que a pré-autorização apenas reserva o valor — a captura é feita em uma etapa posterior.

Headers de Resposta

LocationURL da cobrança criada

Response body (201)

Campo	Tipo	Descrição
`creq`	string	Token do challenge request
`authenticationTransactionId`	string	ID da transação de autenticação 3DS
`jwt`	string	JWT token
`transactionId`	string	Identificador do pedido/transação
`acsUrl`	string	URL do ACS para challenge
`validateUrl`	object	URL para validação/confirmação

Status	Descrição
201	Pré-autorização 3DS criada com sucesso (retorna ThreeDSecureV2Response)
400	Requisição malformada
401	Não autorizado
404	Seller não encontrado
422	Entidade não processável

Webhooks & Eventos

Receba notificações em tempo real sobre mudancas de status.

Como funciona #

Quando o status de um pedido ou cobrança muda, a Zoov Payment envia uma requisição POST via HTTPS para a URL configurada no campo notificationUrl.

Protocolo POST HTTPS com Content-Type: text/plain e body "Bempaggo"
Payload minimo O payload nao contem dados do pedido. Consulte a API para verificar a mudanca de status.
Recomendacao de URL Use IDs únicos na URL (ex: https://meusite.com/events/ORDER123) para identificar o recurso.

Importante: Ao receber o webhook, faca uma consulta GET na API para obter o status atualizado do recurso. Nao confie apenas no recebimento do webhook.

Recebendo Webhooks #

Quando o status de uma cobrança muda, a Zoov Payment envia uma requisição POST para a URL configurada no campo notificationUrl. O corpo da requisição e uma string simples.

HTTP

POST https://meusite.com.br/api/eventos/cobranças/12345
Content-Type: text/plain

Bempaggo

Abaixo um exemplo de como receber e processar o webhook no seu backend (Node.js):

JavaScript

app.post('/api/eventos/cobranças/:chargeId', async (req, res) => {
  const chargeId = req.params.chargeId;

  // Consultar a API para obter o status atualizado
  const response = await fetch(
    `https://api.zoov.com.br/api/v2/charges/${chargeId}`,
    { headers: { 'Authorization': `Bearer ${API_TOKEN}` } }
  );
  const charge = await response.json();

  // Atualizar seu sistema com o novo status
  await updateChargeStatus(chargeId, charge.status);

  res.sendStatus(200);
});

O webhook NAO contem dados do evento. Sempre consulte a API para obter o status atualizado. Retorne HTTP 200 para confirmar o recebimento.

Enviar evento por ID #

POST /api/v2/events/{eventId}

Headers

Authorization: Bearer {seu_token}

Reenvia um evento específico para a URL de notificação configurada.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`eventId`	long	Sim	ID do evento a reenviar

Resposta: 201 Created — corpo vazio

http response — 201 Created

HTTP/1.1 201 Created
Location: /api/v2/events/5001
Content-ID: 5001

Headers da resposta

Location URL do evento reenviado — use GET para consultar o resultado

Content-ID ID do evento

Códigos de resposta

Código	Descrição
201	Evento reenviado com sucesso (sem body)
401	Não autorizado — token inválido ou ausente
404	Evento não encontrado

Enviar eventos do pedido #

POST /api/v2/events/orders/{orderId}

Headers

Authorization: Bearer {seu_token}

Dispara um novo evento de webhook para o pedido informado. O pedido deve ter uma notificationUrl configurada.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`orderId`	integer	Sim	ID do pedido

Headers de Resposta

LocationURL do evento criado

Códigos de resposta

Código	Descrição
201	Evento criado e enviado com sucesso (sem body)
401	Não autorizado — token inválido ou ausente
422	Pedido sem notificationUrl configurada

Redisparo de eventos #

POST /api/v2/events?orderId={orderId}

Headers

Authorization: Bearer {seu_token}

Reenvia todos os eventos pendentes de webhook associados a um pedido.

Parâmetros de query

Parâmetro	Tipo	Obrigatório	Descrição
`orderId`	integer	Sim	ID do pedido cujos eventos serão reenviados

Resposta: 201 Created — corpo vazio com links para cada evento reenviado

http response — 201 Created

HTTP/1.1 201 Created
Location: /api/v2/events/5001
Link: </api/v2/events/5001>; rel="5001"
Link: </api/v2/events/5002>; rel="5002"
Link: </api/v2/events/5003>; rel="5003"

Headers da resposta

Location URL do primeiro evento reenviado

Link rel="{eventId}" Um link para cada evento reenviado — use GET para consultar cada resultado

Códigos de resposta

Código	Descrição
201	Eventos reenviados com sucesso (sem body)
200	Nenhum evento pendente para reenviar
401	Não autorizado — token inválido ou ausente

Obter evento #

GET /api/v2/events/{eventId}

Headers

Authorization: Bearer {seu_token}

Retorna os detalhes de um evento específico.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`eventId`	long	Sim	ID do evento

Exemplo de resposta

JSON

{
  "eventId": 5001,
  "eventCreated": "2024-09-10T03:00:00.000+00:00",
  "eventResultCreated": "2024-09-10T03:00:01.000+00:00",
  "httpCode": 200,
  "orderDate": "2024-09-09T18:00:00.000+00:00"
}

Campos da resposta (WebEventResponse)

Campo	Tipo	Descrição
`eventId`	long	Identificador único do evento
`eventCreated`	Date	Data/hora de criação do evento
`eventResultCreated`	Date	Data/hora em que o webhook foi executado
`httpCode`	integer	Código HTTP retornado pelo endpoint de destino
`orderDate`	Date	Data/hora do pedido associado

Códigos de resposta

Código	Descrição
200	Evento retornado com sucesso
401	Não autorizado — token inválido ou ausente

Listar eventos #

GET /api/v2/events?orderReferenceOrId={value}

Headers

Authorization: Bearer {seu_token}

Retorna a lista de eventos filtrados pelo ID ou referência do pedido.

Parâmetros de query

Parâmetro	Tipo	Obrigatório	Descrição
`orderReferenceOrId`	string	Sim	ID ou código de referência do pedido

Exemplo de resposta

JSON

[
  {
    "eventId": 5001,
    "eventCreated": "2024-09-10T03:00:00.000+00:00",
    "eventResultCreated": "2024-09-10T03:00:01.000+00:00",
    "httpCode": 200,
    "orderDate": "2024-09-09T18:00:00.000+00:00"
  },
  {
    "eventId": 5002,
    "eventCreated": "2024-09-10T04:00:00.000+00:00",
    "eventResultCreated": "2024-09-10T04:00:02.000+00:00",
    "httpCode": 500,
    "orderDate": "2024-09-09T18:00:00.000+00:00"
  }
]

Campo	Tipo	Descrição
`eventId`	long	Identificador único do evento
`eventCreated`	Date	Data/hora de criação do evento
`eventResultCreated`	Date	Data/hora em que o webhook foi executado
`httpCode`	integer	Código HTTP retornado pelo endpoint de destino
`orderDate`	Date	Data/hora do pedido associado

Códigos de resposta

Código	Descrição
200	Lista de eventos retornada com sucesso
401	Não autorizado — token inválido ou ausente

Eventos por pedido #

GET /api/v2/events/order/{orderId}

Headers

Authorization: Bearer {seu_token}

Retorna todos os eventos associados a um pedido específico.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`orderId`	string	Sim	ID do pedido

Exemplo de resposta

JSON

[
  {
    "eventId": 5001,
    "eventCreated": "2024-09-10T03:00:00.000+00:00",
    "eventResultCreated": "2024-09-10T03:00:01.000+00:00",
    "httpCode": 200,
    "orderDate": "2024-09-09T18:00:00.000+00:00"
  }
]

Campo	Tipo	Descrição
`eventId`	long	Identificador único do evento
`eventCreated`	Date	Data/hora de criação do evento
`eventResultCreated`	Date	Data/hora em que o webhook foi executado
`httpCode`	integer	Código HTTP retornado pelo endpoint de destino
`orderDate`	Date	Data/hora do pedido associado

Códigos de resposta

Código	Descrição
200	Eventos do pedido retornados com sucesso
401	Não autorizado — token inválido ou ausente

Webhooks — Seller & Transfer

Sistema de notificações v2 baseado em configuração via API. Envie eventos de vendedores e transferências com payload estruturado para qualquer URL com autenticação flexível.

Configuração de Webhook #

Configure uma URL de destino para receber notificações de eventos específicos. Cada configuração é vinculada a um tipo de evento e à empresa do usuário autenticado.

POST /api/v2/webhook-configurations

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Cria uma nova configuração de webhook para a empresa associada ao usuário autenticado.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`event`	string (enum)	Sim	Tipo de evento: `SELLER_CREATED`, `SELLER_STATUS_UPDATED`, `TRANSFER_CREATED`, `TRANSFER_STATUS_UPDATED`
`notificationUrl`	string (URI)	Sim	URL HTTPS que receberá as notificações via POST
`authType`	string (enum)	Sim	Tipo de autenticação: `NONE`, `BEARER`, `BASIC`, `API_KEY`, `CUSTOM`
`authorizationHeader`	string	Não	Valor do header Authorization (para authType `BEARER`)
`apiKey`	string	Não	Chave de API (para authType `API_KEY`)
`username`	string	Não	Usuário (para authType `BASIC`)
`password`	string	Não	Senha (para authType `BASIC`)
`customHeaders`	string (JSON)	Não	Headers adicionais em formato JSON (para authType `CUSTOM`)
`timeoutSeconds`	integer	Não	Timeout em segundos por chamada (padrão: `30`)
`retryCount`	integer	Não	Número máximo de tentativas em caso de falha (padrão: `3`)

Exemplo de requisição

JSON

{
  "event": "SELLER_CREATED",
  "notificationUrl": "https://meusite.com.br/webhooks/seller",
  "authType": "BEARER",
  "authorizationHeader": "meu-token-secreto",
  "timeoutSeconds": 30,
  "retryCount": 3
}

Resposta: 201 Created — corpo vazio com header Location apontando para a configuração criada.

Códigos de resposta

Código	Descrição
201	Configuração criada com sucesso (sem body)
401	Não autorizado — token inválido ou ausente
422	Já existe uma configuração para esse evento nesta empresa

GET /api/v2/webhook-configurations/{id}

Headers

Authorization: Bearer {seu_token}

Retorna os detalhes de uma configuração de webhook.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`id`	long	Sim	ID da configuração de webhook

Exemplo de resposta

JSON

{
  "id": 42,
  "event": "SELLER_CREATED",
  "notificationUrl": "https://meusite.com.br/webhooks/seller",
  "authType": "BEARER",
  "timeoutSeconds": 30,
  "retryCount": 3,
  "isActive": true
}

Campos da resposta

Campo	Tipo	Descrição
`id`	long	Identificador único da configuração
`event`	string	Tipo de evento configurado
`notificationUrl`	string	URL de destino das notificações
`authType`	string	Tipo de autenticação configurado
`timeoutSeconds`	integer	Timeout em segundos
`retryCount`	integer	Número máximo de tentativas
`isActive`	boolean	Se a configuração está ativa

Códigos de resposta

Código	Descrição
200	Configuração retornada com sucesso
401	Não autorizado — token inválido ou ausente
404	Configuração não encontrada

DELETE /api/v2/webhook-configurations/{id}

Headers

Authorization: Bearer {seu_token}

Remove uma configuração de webhook da empresa do usuário autenticado.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`id`	long	Sim	ID da configuração de webhook a remover

Códigos de resposta

Código	Descrição
200	Configuração removida com sucesso
401	Não autorizado — token inválido ou ausente
404	Configuração não encontrada

Eventos Seller #

Notificações disparadas automaticamente quando um vendedor é criado ou tem seu status alterado na plataforma.

SELLER_CREATED Disparado quando um novo vendedor é cadastrado com sucesso.
SELLER_STATUS_UPDATED Disparado quando o status de um vendedor é alterado (ex.: de PENDING para ACTIVE).

Payload do evento (SellerWebhookPayload)

Campo	Tipo	Descrição
`affiliateMasterId`	long	ID interno do vendedor na plataforma
`affiliateId`	long	ID do afiliado no tenant
`document`	string	CPF ou CNPJ do vendedor
`name`	string	Nome ou razão social do vendedor
`status`	string	Status atual: `ACTIVE`, `PENDING`, `INACTIVE`, `CANCELED`
`personType`	string	Tipo de pessoa: `CPF` ou `CNPJ`
`event`	string	Nome do evento disparado
`timestamp`	string (ISO 8601)	Data/hora em que o evento foi gerado (UTC)

Exemplo — SELLER_CREATED

JSON

{
  "affiliateMasterId": 1001,
  "affiliateId": 2001,
  "document": "12345678000190",
  "name": "Empresa Exemplo LTDA",
  "status": "PENDING",
  "personType": "CNPJ",
  "event": "SELLER_CREATED",
  "timestamp": "2025-06-11T12:00:00.000Z"
}

Exemplo — SELLER_STATUS_UPDATED

JSON

{
  "affiliateMasterId": 1001,
  "affiliateId": 2001,
  "document": "12345678000190",
  "name": "Empresa Exemplo LTDA",
  "status": "ACTIVE",
  "personType": "CNPJ",
  "event": "SELLER_STATUS_UPDATED",
  "timestamp": "2025-06-11T14:30:00.000Z"
}

O evento SELLER_STATUS_UPDATED é disparado pelo serviço de sincronização de afiliados. Configure esse webhook para ser notificado em tempo real quando a Zoov aprovar ou rejeitar um vendedor.

Eventos Transfer #

Notificações disparadas quando uma transferência (repasse financeiro) é criada ou tem seu status alterado. O processamento é assíncrono.

TRANSFER_CREATED Disparado quando uma nova transferência é identificada pela Zoov.
TRANSFER_STATUS_UPDATED Disparado quando o status de uma transferência muda (ex.: de PENDENTE para LIQUIDADO). O campo previousSituacao indica o status anterior.

Payload do evento (TransferWebhookPayload)

Campo	Tipo	Descrição
`externalId`	string	ID externo da transferência
`mid`	long	ID do merchant (vendedor) associado
`situacao`	string	Status atual da transferência
`previousSituacao`	string	Status anterior (presente em `TRANSFER_STATUS_UPDATED`, `null` em `TRANSFER_CREATED`)
`valorBruto`	decimal	Valor bruto da transferência
`valorLiquido`	decimal	Valor líquido após descontos
`previsaoCredito`	string (YYYY-MM-DD)	Data prevista para o crédito
`dataCredito`	string (YYYY-MM-DD)	Data efetiva do crédito (quando disponível)
`bancoDestino`	string	Código do banco de destino
`nomeBancoDestino`	string	Nome do banco de destino
`razaoSocial`	string	Razão social do beneficiário
`cpfCnpj`	string	CPF ou CNPJ do beneficiário
`tipoProcessamento`	string	Tipo de processamento da transferência
`arranjoPagamento`	string	Arranjo de pagamento utilizado
`chavePix`	string	Chave PIX do beneficiário (quando aplicável)
`tipoChavePix`	string	Tipo da chave PIX: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`
`event`	string	Nome do evento disparado
`timestamp`	string (ISO 8601)	Data/hora em que o evento foi gerado (UTC)

Exemplo — TRANSFER_CREATED

JSON

{
  "externalId": "TRF-2025-001234",
  "mid": 5001,
  "situacao": "PENDENTE",
  "previousSituacao": null,
  "valorBruto": 1500.00,
  "valorLiquido": 1425.00,
  "previsaoCredito": "2025-06-15",
  "dataCredito": null,
  "bancoDestino": "0001",
  "nomeBancoDestino": "Banco do Brasil",
  "razaoSocial": "Empresa Exemplo LTDA",
  "cpfCnpj": "12345678000190",
  "tipoProcessamento": "PIX",
  "arranjoPagamento": "PIX",
  "chavePix": "12345678000190",
  "tipoChavePix": "CNPJ",
  "event": "TRANSFER_CREATED",
  "timestamp": "2025-06-11T12:00:00.000Z"
}

Exemplo — TRANSFER_STATUS_UPDATED

JSON

{
  "externalId": "TRF-2025-001234",
  "mid": 5001,
  "situacao": "LIQUIDADO",
  "previousSituacao": "PENDENTE",
  "valorBruto": 1500.00,
  "valorLiquido": 1425.00,
  "previsaoCredito": "2025-06-15",
  "dataCredito": "2025-06-15",
  "bancoDestino": "0001",
  "nomeBancoDestino": "Banco do Brasil",
  "razaoSocial": "Empresa Exemplo LTDA",
  "cpfCnpj": "12345678000190",
  "tipoProcessamento": "PIX",
  "arranjoPagamento": "PIX",
  "chavePix": "12345678000190",
  "tipoChavePix": "CNPJ",
  "event": "TRANSFER_STATUS_UPDATED",
  "timestamp": "2025-06-15T09:15:00.000Z"
}

Os eventos de transferência são processados de forma assíncrona. O campo previousSituacao estará preenchido apenas em TRANSFER_STATUS_UPDATED — em TRANSFER_CREATED o valor será null.

Banking / BaaS

Consulte saldo, transferências, ajustes, recebíveis e antecipações da conta do vendedor.

Pré-requisito. Todos os endpoints exigem que o vendedor (sellerId) tenha configuração BaaS ativa. Caso contrário, a API responde 404 Not Found.

Obter Saldo do Vendedor #

GET /api/v2/baas/{sellerId}/balance

Headers

Authorization: Bearer {seu_token}

Obtém o saldo da conta do vendedor (disponível, bloqueado e futuro).

Parâmetro	Tipo	Obrigatório	Descrição
`sellerId`	long	Sim	ID do vendedor (path)

json — response body (200)

{
  "currentAvailableBalance": 125000,
  "blockedBalance": 5000,
  "futureBalance": 80000,
  "balance": 125000,
  "availableBalance": 80000
}

Campos da resposta (200)

Campo	Tipo	Descrição
`currentAvailableBalance`	long	Saldo disponível atual em centavos
`blockedBalance`	long	Saldo bloqueado em centavos
`futureBalance`	long	Saldo futuro em centavos
`balance`	long	Deprecated — espelha `currentAvailableBalance`. Use o novo campo.
`availableBalance`	long	Deprecated — espelha `futureBalance`. Use o novo campo.

Status	Descrição
200	Saldo retornado com sucesso
401	Não autenticado
404	Vendedor não encontrado ou sem configuração BaaS
500	Erro interno do servidor

Listar Parcelas de Transação por UUID #

GET /api/v2/baas/{sellerId}/transactions/{uuid}/installments

Headers

Authorization: Bearer {seu_token}

Lista as parcelas (settlement) de uma transação a partir do UUID da transação.

Parâmetro	Tipo	Obrigatório	Descrição
`sellerId`	long	Sim	ID do vendedor (path)
`uuid`	string	Sim	UUID da transação (path)

json — response body (200)

{
  "transactions": [
    {
      "id": 987654321,
      "transactionId": 7891011,
      "businessName": "Loja Exemplo LTDA",
      "paymentDate": "2024-12-08",
      "installment": 1,
      "grossAmount": 10000,
      "mdr": 400,
      "antecipationFee": 200,
      "additionalCost": 0,
      "netAmount": 9400,
      "status": "paid",
      "splitRuleId": null
    }
  ],
  "hasSplit": false
}

Campos da resposta (200)

Campo	Tipo	Descrição
`hasSplit`	boolean	Indica se a transação possui split de pagamento
`transactions`	array	Lista de parcelas
`transactions[].id`	long	ID externo da parcela
`transactions[].transactionId`	long	ID externo da transação
`transactions[].businessName`	string	Razão social do recebedor
`transactions[].paymentDate`	string	Data prevista/efetiva de pagamento
`transactions[].installment`	integer	Número da parcela
`transactions[].grossAmount`	integer	Valor bruto em centavos
`transactions[].mdr`	integer	MDR em centavos
`transactions[].antecipationFee`	integer	Taxa de antecipação em centavos
`transactions[].additionalCost`	integer	Custos adicionais em centavos
`transactions[].netAmount`	integer	Valor líquido em centavos
`transactions[].status`	enum	Status da parcela. Valores possíveis: `paid`, `waiting_funds`, `refunded`, `blocked`, `splited`
`transactions[].splitRuleId`	string	ID da regra de split (preenchido apenas quando `hasSplit = true`)

Status	Descrição
200	Parcelas retornadas com sucesso
401	Não autenticado
404	Transação não encontrada ou vendedor sem BaaS
500	Erro interno do servidor

Listar Transferências do Vendedor #

GET /api/v2/baas/{sellerId}/transfers

Headers

Authorization: Bearer {seu_token}

Lista as transferências (sacados) da conta do vendedor. Por padrão filtra do último ano até hoje.

Parâmetro	Tipo	Obrigatório	Descrição
`sellerId`	long	Sim	ID do vendedor (path)
`page`	integer	Não	Número da página (default 0)
`size`	integer	Não	Itens por página (default 10)

json — response body (200)

[
  {
    "id": null,
    "transferExpectedOn": "2024-11-08T18:46:08Z",
    "transferDate": null,
    "type": null,
    "description": "Pagamento de vendas via POS / E-commerce",
    "resource": "transfer",
    "transferNumber": "TR-000123",
    "bankAccount": {
      "bankName": null,
      "bankCode": "260",
      "type": "conta_corrente",
      "accountNumber": "999999-9",
      "agencyNumber": "0001",
      "agencyCheckDigit": null,
      "holderName": null
    },
    "status": "pendente",
    "grossAmount": 10000,
    "amount": 9392,
    "discounts": 608,
    "createdAt": "2024-11-08T18:46:08Z"
  }
]

Campos da resposta (200)

Campo	Tipo	Descrição
`[].id`	string	Identificador da transferência (pode ser nulo)
`[].transferExpectedOn`	instant	Previsão de crédito
`[].transferDate`	instant	Data efetiva do crédito (nulo enquanto pendente)
`[].type`	string	Tipo da transferência
`[].description`	string	Descrição
`[].resource`	string	Recurso (sempre `transfer`)
`[].transferNumber`	string	Código da transferência
`[].bankAccount`	object	Dados da conta destino
`[].bankAccount.bankName`	string	Nome do banco
`[].bankAccount.bankCode`	string	Código do banco destino
`[].bankAccount.type`	enum	Tipo de conta. Valores possíveis: `conta_pagamento`, `conta_corrente`
`[].bankAccount.accountNumber`	string	Número da conta com dígito (formato `NNNNNN-D`)
`[].bankAccount.agencyNumber`	string	Número da agência
`[].bankAccount.agencyCheckDigit`	string	Dígito da agência
`[].bankAccount.holderName`	string	Nome do titular
`[].status`	enum	Situação da transferência. Valores possíveis: `pendente`, `agendado`, `processando`, `enviado`, `gerando`, `gerado`, `cancelado`, `concluido`, `devolvido`, `falha`, `outros`
`[].grossAmount`	long	Valor bruto em centavos
`[].amount`	long	Valor líquido em centavos
`[].discounts`	long	Descontos em centavos
`[].createdAt`	instant	Data de criação

Status	Descrição
200	Lista retornada com sucesso (array vazio quando não houver transferências)
401	Não autenticado
404	Vendedor não encontrado ou sem configuração BaaS
500	Erro interno do servidor

Obter Transferência por ID #

GET /api/v2/baas/{sellerId}/transfers/{transferId}

Headers

Authorization: Bearer {seu_token}

Detalha as parcelas que compõem uma transferência específica, com dados de cada item (taxas, bandeira, split, etc.).

Parâmetro	Tipo	Obrigatório	Descrição
`sellerId`	long	Sim	ID do vendedor (path)
`transferId`	string	Sim	ID da transferência (path) — obtido em `transferNumber` de Listar Transferências

json — response body (200)

[
  {
    "orderReference": "ORDER0001",
    "installmentNsu": 987654321,
    "transactionNsu": "123456",
    "tefNsu": "000000123",
    "grossAmount": 10000,
    "amount": 9392,
    "mdr": 408,
    "rav": 200,
    "fee": 0,
    "installment": 1,
    "totalInstallments": 1,
    "paymentDate": "2024-11-08T18:46:08Z",
    "originalPaymentDate": "2024-11-08T18:46:08Z",
    "paymentMethod": "CREDIT_CARD",
    "cardBrand": "VISA",
    "isSplitTransaction": false,
    "isMainAffiliate": false,
    "isParticipantAffiliate": false,
    "captureType": "ONLINE",
    "transactionId": 7891011
  }
]

Campos da resposta (200)

Campo	Tipo	Descrição
`[].orderReference`	string	Referência do pedido
`[].installmentNsu`	long	NSU da parcela
`[].transactionNsu`	string	NSU da transação
`[].tefNsu`	string	TEF NSU
`[].grossAmount`	long	Valor bruto em centavos
`[].amount`	integer	Valor líquido em centavos
`[].mdr`	integer	MDR (taxa) em centavos
`[].rav`	integer	RAV — taxa de antecipação em centavos
`[].fee`	integer	Taxa de serviço adicional em centavos
`[].installment`	integer	Número da parcela liquidada
`[].totalInstallments`	integer	Total de parcelas da venda
`[].paymentDate`	offsetDateTime	Data em que foi liquidado
`[].originalPaymentDate`	offsetDateTime	Data prevista originalmente
`[].paymentMethod`	enum	Método de pagamento. Valores possíveis: `CREDIT_CARD`, `PIX`, `BANK_SLIP`
`[].cardBrand`	enum	Bandeira do cartão. Valores possíveis: `VISA`, `MASTERCARD`, `ELO`, `AMEX`
`[].isSplitTransaction`	boolean	Indica se a transação tem split
`[].isMainAffiliate`	boolean	Indica se o seller é o principal (dono da transação)
`[].isParticipantAffiliate`	boolean	Indica se o seller é um participante do split
`[].captureType`	enum	Forma de captura: `ONLINE` ou `POINT_OF_SALE`
`[].transactionId`	long	ID externo da transação

Status	Descrição
200	Itens da transferência retornados com sucesso
401	Não autenticado
404	Transferência ou vendedor não encontrados
500	Erro interno do servidor

Listar Ajustes do Vendedor #

GET /api/v2/baas/{sellerId}/adjustments

Headers

Authorization: Bearer {seu_token}

Lista os lançamentos / ajustes contábeis do vendedor (créditos, débitos, vencidos e a vencer).

Parâmetro	Tipo	Obrigatório	Descrição
`sellerId`	long	Sim	ID do vendedor (path)
`page`	integer	Não	Número da página (default 0)
`size`	integer	Não	Itens por página (default 10)

json — response body (200)

{
  "total": 42,
  "perPage": 10,
  "page": 1,
  "lastPage": 5,
  "lancamentos": {
    "credito": 25,
    "debito": 12,
    "vencidos": 2,
    "aVencer": 3
  },
  "data": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "origemLancamento": "VENDA",
      "transactionNsu": "123456",
      "installment": 1,
      "installments": 1,
      "tipoLancamento": "credito",
      "adjustDate": "2024-11-08",
      "dueDate": "2024-12-08",
      "dataLancamento": "2024-11-08T18:46:08Z",
      "paymentDate": "2024-11-08T18:46:08Z",
      "updatedAt": "2024-11-08T18:46:08Z",
      "codigoLancamento": "L0001",
      "totalAmount": "10000",
      "netAmount": "9392",
      "paidAmount": 9392,
      "description": "Crédito de venda",
      "situation": "PAGO",
      "orderReference": "ORDER0001",
      "chargeId": 12345,
      "transactionId": 7891011,
      "externalTransactionId": 99887766
    }
  ]
}

Campos da resposta (200)

Campo	Tipo	Descrição
`total`	integer	Total de itens
`perPage`	integer	Itens por página
`page`	integer	Página atual
`lastPage`	integer	Última página
`lancamentos`	object	Resumo de contadores por categoria
`lancamentos.credito`	integer	Quantidade de créditos
`lancamentos.debito`	integer	Quantidade de débitos
`lancamentos.vencidos`	integer	Quantidade de itens vencidos
`lancamentos.aVencer`	integer	Quantidade de itens a vencer
`data`	array	Lista de ajustes (AdjustmentItemResponse)
`data[].uuid`	string	UUID do ajuste
`data[].origemLancamento`	string	Origem do lançamento
`data[].transactionNsu`	string	NSU da transação
`data[].installment`	integer	Número da parcela
`data[].installments`	integer	Total de parcelas
`data[].tipoLancamento`	enum	Tipo do lançamento. Valores possíveis: `credito`, `debito`
`data[].adjustDate`	string	Data do ajuste
`data[].dueDate`	string	Data de vencimento
`data[].dataLancamento`	offsetDateTime	Data do lançamento
`data[].paymentDate`	offsetDateTime	Data de pagamento
`data[].updatedAt`	offsetDateTime	Última atualização
`data[].codigoLancamento`	string	Código do lançamento
`data[].totalAmount`	string	Valor total
`data[].netAmount`	string	Valor líquido
`data[].paidAmount`	integer	Valor pago
`data[].description`	string	Descrição
`data[].situation`	string	Situação
`data[].orderReference`	string	Referência do pedido (quando vinculado)
`data[].chargeId`	long	ID da cobrança
`data[].transactionId`	long	ID da transação interna
`data[].externalTransactionId`	long	ID externo da transação

Status	Descrição
200	Ajustes retornados com sucesso
401	Não autenticado
404	Vendedor não encontrado ou sem BaaS
500	Erro interno do servidor
502	Falha de comunicação com o serviço de pagamento

Listar Transferências Futuras #

GET /api/v2/baas/{sellerId}/future-transfers

Headers

Authorization: Bearer {seu_token}

Lista as transferências futuras (recebíveis a vencer) do vendedor. Suporta filtro opcional por intervalo de data de pagamento.

Parâmetro	Tipo	Obrigatório	Descrição
`sellerId`	long	Sim	ID do vendedor (path)
`page`	integer	Não	Número da página (default 0)
`size`	integer	Não	Itens por página (default 10)
`paymentDateStart`	long	Não	Início do intervalo de data de pagamento (Unix ms). Obrigatório se `paymentDateEnd` for enviado.
`paymentDateEnd`	long	Não	Fim do intervalo de data de pagamento (Unix ms). Obrigatório se `paymentDateStart` for enviado.

json — response body (200)

{
  "availableAmount": 125000,
  "anticipationCost": 300,
  "mdr": 400,
  "totalValue": 150000,
  "blockedValue": 5000,
  "totalItems": 42,
  "perPage": 10,
  "page": 1,
  "lastPage": 5,
  "items": [
    {
      "transactionNsu": "123456",
      "installmentNsu": 987654321,
      "installments": 1,
      "installment": 1,
      "saleAmount": 10000,
      "installmentAmount": 10000,
      "fee": 400,
      "anticipationFee": 200,
      "brandFee": 50,
      "interchangeFee": "1.50",
      "settlementNetAmount": 9400,
      "settlementStatus": "waiting_funds",
      "paymentDate": "2024-12-08",
      "originalPaymentDate": null,
      "saleDate": "2024-11-08",
      "finishDate": null,
      "cardBrand": "VISA",
      "splitRuleId": null,
      "transactionId": 7891011,
      "chargeId": 12345,
      "orderReference": "ORDER0001"
    }
  ]
}

Campos da resposta (200)

Campo	Tipo	Descrição
`availableAmount`	long	Total disponível em centavos
`anticipationCost`	long	Custo total da antecipação em centavos
`mdr`	long	MDR consolidado em centavos
`totalValue`	long	Valor total em centavos
`blockedValue`	long	Valor bloqueado em centavos
`totalItems`	long	Total de itens encontrados
`perPage`	integer	Itens por página
`page`	integer	Página atual
`lastPage`	integer	Última página
`items`	array	Lista de recebíveis futuros
`items[].transactionNsu`	string	NSU da transação
`items[].installmentNsu`	long	NSU da parcela
`items[].installments`	integer	Total de parcelas
`items[].installment`	integer	Número da parcela
`items[].saleAmount`	long	Valor da venda em centavos
`items[].installmentAmount`	long	Valor da parcela em centavos
`items[].fee`	long	Taxa em centavos
`items[].anticipationFee`	long	Taxa de antecipação em centavos
`items[].brandFee`	long	Taxa de bandeira em centavos
`items[].interchangeFee`	string	Taxa de intercâmbio
`items[].settlementNetAmount`	long	Valor líquido em centavos
`items[].settlementStatus`	enum	Status da liquidação. Valores possíveis: `paid`, `waiting_funds`, `refunded`, `blocked`, `splited`
`items[].paymentDate`	string	Data prevista de pagamento
`items[].originalPaymentDate`	string	Data original de pagamento
`items[].saleDate`	string	Data da venda
`items[].finishDate`	string	Data de finalização
`items[].cardBrand`	string	Bandeira do cartão
`items[].splitRuleId`	string	ID da regra de split (quando aplicável)
`items[].transactionId`	long	ID da transação
`items[].chargeId`	long	ID da cobrança
`items[].orderReference`	string	Referência do pedido

Status	Descrição
200	Transferências futuras retornadas com sucesso
400	Filtro de data inconsistente (apenas um de `paymentDateStart`/`paymentDateEnd` enviado)
401	Não autenticado
404	Vendedor não encontrado ou sem BaaS
500	Erro interno do servidor

Totalizadores do Saldo Pago #

GET /api/v2/baas/{sellerId}/receivables/totals

Headers

Authorization: Bearer {seu_token}

Retorna apenas os totalizadores agregados do saldo pago do vendedor (sem listar os itens).

Parâmetro	Tipo	Obrigatório	Descrição
`sellerId`	long	Sim	ID do vendedor (path)

json — response body (200)

{
  "availableAmount": 125000,
  "anticipationCost": 300,
  "mdr": 400,
  "totalValue": 150000,
  "blockedValue": 5000,
  "totalItems": 42
}

Campos da resposta (200)

Campo	Tipo	Descrição
`availableAmount`	long	Total disponível em centavos
`anticipationCost`	long	Custo total de antecipação em centavos
`mdr`	long	MDR consolidado em centavos
`totalValue`	long	Valor total em centavos
`blockedValue`	long	Valor bloqueado em centavos
`totalItems`	long	Quantidade total de itens

Status	Descrição
200	Totalizadores retornados com sucesso
401	Não autenticado
404	Vendedor não encontrado, sem BaaS ou sem saldo pago
500	Erro interno do servidor

Chargeback — Alertas

Consulte os alertas de chargeback recebidos dos provedores de prevenção (Ethoca, Verifi) para as transações da sua empresa.

Listar alertas #

GET /api/v2/chargeback-alerts

Headers

Authorization: Bearer {seu_token}

Retorna, de forma paginada, os alertas de chargeback da empresa autenticada. O escopo é sempre a empresa vinculada ao token — não é possível consultar alertas de outra empresa. Os resultados são ordenados por data de criação do alerta, do mais recente para o mais antigo.

Parâmetros de query

Parâmetro	Tipo	Obrigatório	Descrição
`status`	array<enum>	Não	Um ou mais status a filtrar. Repita o parâmetro para múltiplos valores (`?status=NEW&status=CONCILIATED`). Valores: `NEW`, `CONCILIATED`, `NOT_FOUND`, `REFUNDED`, `RESOLVED`
`conciliated`	boolean	Não	Filtra apenas alertas conciliados (`true`) ou não conciliados (`false`) com uma transação
`refunded`	boolean	Não	Filtra apenas alertas com estorno efetuado (`true`) ou sem estorno (`false`)
`cardBrand`	string	Não	Bandeira do cartão. Comparação exata, ex.: `MASTERCARD`, `VISA`
`referenceId`	string	Não	Código de referência do pedido informado na venda. Comparação exata
`alertStartDate`	long	Não	Início do período de recebimento do alerta, em timestamp Unix (milissegundos). Só o dia é considerado, a hora é ignorada
`alertEndDate`	long	Não	Fim do período de recebimento do alerta, em timestamp Unix (milissegundos). Só o dia é considerado, a hora é ignorada
`page`	integer	Não	Página desejada, começando em `0`. Padrão: `0`
`size`	integer	Não	Quantidade de alertas por página. Padrão: `15`

alertStartDate e alertEndDate devem ser enviados juntos. Informar apenas um dos dois retorna 400 Bad Request. O intervalo é inclusivo nas duas pontas.

Exemplo de requisição

cURL

curl -X GET \
  'https://api.zoov.com.br/api/v2/chargeback-alerts?status=NEW&status=CONCILIATED&cardBrand=MASTERCARD&page=0&size=15' \
  -H 'Authorization: Bearer {seu_token}'

Exemplo de resposta

JSON

{
  "content": [
    {
      "id": 10482,
      "alertId": "cb_9f3a21e0",
      "alertType": "CONFIRMED_FRAUD",
      "provider": "CHARGEBLAST",
      "subprovider": "ETHOCA",
      "status": "RESOLVED",
      "conciliated": true,
      "refunded": true,
      "resolved": true,
      "transactionId": 884213,
      "chargeId": 551097,
      "amount": 149.90,
      "currency": "BRL",
      "cardBrand": "MASTERCARD",
      "cardBin": "516292",
      "cardLastFour": "4417",
      "externalOrder": "PEDIDO-2024-8871",
      "descriptor": "ZOOV*LOJA EXEMPLO",
      "transactionDate": "2024-09-08T14:22:31.000+00:00",
      "createdAt": "2024-09-10T03:11:00.000+00:00",
      "updatedAt": "2024-09-10T03:12:04.000+00:00",
      "message": "Alerta conciliado e estornado com sucesso"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "number": 0,
  "size": 15,
  "numberOfElements": 1,
  "first": true,
  "last": true,
  "empty": false
}

Campos de `content[]`

Campo	Tipo	Descrição
`id`	long	Identificador do alerta na Zoov Payment
`alertId`	string	Identificador do alerta no provedor de origem
`alertType`	string	Tipo do alerta informado pelo provedor (ex.: fraude confirmada, disputa de cliente)
`provider`	string	Provedor que enviou o alerta
`subprovider`	string	Rede de origem do alerta (ex.: `ETHOCA`, `VERIFI`)
`status`	enum	Situação atual do alerta. Veja a tabela abaixo
`conciliated`	boolean	Indica se o alerta foi associado a uma transação da sua empresa
`refunded`	boolean	Indica se o estorno da transação foi efetuado
`resolved`	boolean	Indica se o alerta foi encerrado junto ao provedor
`transactionId`	long	ID da transação conciliada. `null` enquanto não houver conciliação
`chargeId`	long	ID da cobrança da transação conciliada. `null` enquanto não houver conciliação
`amount`	decimal	Valor do alerta
`currency`	string	Moeda do valor, ex.: `BRL`
`cardBrand`	string	Bandeira do cartão
`cardBin`	string	BIN (primeiros dígitos) do cartão
`cardLastFour`	string	Últimos quatro dígitos do cartão
`externalOrder`	string	Código de referência do pedido — o mesmo valor aceito no filtro `referenceId`
`descriptor`	string	Descritor exibido na fatura do portador
`transactionDate`	Date	Data/hora da transação que originou o alerta
`createdAt`	Date	Data/hora em que o alerta foi recebido
`updatedAt`	Date	Data/hora da última atualização do alerta
`message`	string	Mensagem do último processamento do alerta, útil para diagnóstico

Status do alerta

Status	Descrição
NEW	Alerta recebido, ainda não conciliado
CONCILIATED	Alerta associado a uma transação da sua empresa
NOT_FOUND	Nenhuma transação correspondente foi encontrada
REFUNDED	Transação estornada em decorrência do alerta
RESOLVED	Alerta estornado e encerrado junto ao provedor

Códigos de resposta

Código	Descrição
200	Lista de alertas retornada com sucesso. Sem resultados, `content` vem vazio
400	Parâmetros inválidos — ex.: apenas uma das datas do período informada
401	Não autorizado — token inválido ou ausente

Referência Técnica

Dicionario de dados, status, enums e códigos de retorno.

Status e Enums #

OrderStatus

Valor	Descrição
ACTIVE	Pedido ativo
INACTIVE	Pedido inativo
OVERDUE	Inadimplente
PENDING	Pendente
CHARGEBACK	Chargeback
COUNTERCHARGE	Contestação
CANCELED	Cancelado

ChargeStatus

Valor	Descrição
PAY	Paga (autorizada e capturada)
PENDING	Pendente
SCHEDULE	Agendada
ACCREDIT	Abonada
REFUND	Estornada
MANUAL_DISCHARGE	Baixa manual
CHARGEBACK	Chargeback
COUNTERCHARGE	Contestação
IN_PROGRESS	Em processamento
AUTHORIZED	Autorizada (aguardando captura)
FAIL	Falha
CANCELED	Cancelada

TransactionStatus

Valor	Descrição
IN_PROGRESS	Em andamento
APPROVED	Aprovada
REFUND	Estornada
AUTHORIZED	Autorizada
MANUAL_DISCHARGE	Baixa manual
MANUAL_REFUND	Estorno manual
NOT_AUTHORIZED	Não autorizada pelo emissor
NOT_APPROVED	Não aprovada (falha na captura)
CHARGEBACK	Chargeback
COUNTERCHARGE	Contestação
CANCELED	Cancelada
AWAITING_PAYMENT	Aguardando pagamento (PIX/Boleto)
UNDER_PAYMENT	Pagamento menor que o valor esperado
OVER_PAYMENT	Pagamento maior que o valor esperado
FAIL	Falha
INVALID	Transação inválida

RefundReason

Valor	Descrição
`DUPLICATE_CHARGE`	Cobrança duplicada
`IMPROPER_CHARGE`	Cobrança indevida
`COSTUMER_WITHDRAWAL`	Desistencia do cliente
`OTHERS`	Outros

Cartões de Teste #

Utilize os cartões abaixo para testar diferentes cenarios no ambiente Sandbox.

Cenário	Bandeira	Número	Validade	CVV
Aprovado (a vista)	Visa	`4548812049400004`	12/34	123
Aprovado (parcelado)	Mastercard	`5067230000009011`	01/28	123
Aprovado (parcelado)	Visa	`4761120000000148`	01/28	123
Recusado	Visa	`1111111111111117`	12/34	123
3DS Challenge	Visa	`4918019199883839`	12/34	123
3DS Frictionless	Visa	`4918019160034602`	12/34	123
Tokenização	—	`5448280000000007`	01/35	123

Códigos ABECS #

Códigos de retorno padronizados pela ABECS (Associação Brasileira das Empresas de Cartões de Crédito e Serviços).

Código	Descrição	Tipo
`55`	PIN inválido	REVERSÍVEL
`63`	Violação de segurança	IRREVERSÍVEL
`59`	Suspeita de fraude	REVERSÍVEL
`14`	Cartão inválido	IRREVERSÍVEL
`54`	Cartão expirado	IRREVERSÍVEL
`41`	Cartão perdido	IRREVERSÍVEL
`43`	Cartão roubado	IRREVERSÍVEL
`51`	Saldo insuficiente	REVERSÍVEL
`57`	Transação não permitida	IRREVERSÍVEL

Ferramentas para Desenvolvedores

Tudo que você precisa para acelerar a integração.

Coleção Postman

Clique para baixar. Contém todos os 49 endpoints organizados em 14 pastas na ordem lógica de integração, com exemplos de request prontos para uso.

Download ZIP

SDK Android

Biblioteca oficial Zoov para pagamentos via NFC (Tap on Phone), cartão de crédito, débito e PIX em aplicações Android.

Ver documentação →

App de Exemplo

Aplicação Android completa de referência. Clone, configure as credenciais e teste os fluxos de pagamento NFC e PIX.

Abrir no GitHub

Sandbox

Ambiente seguro para testes. Simule transações sem movimentar valores reais.

Simuladores

Simule pagamentos PIX e Boleto no ambiente sandbox para validar sua integração.

Endpoints de Simulação #

Utilize os endpoints abaixo no ambiente Sandbox para simular pagamentos e testar webhooks.

POST /api/v2/simulations/charges/{id}/payment

Headers

Authorization: Bearer {seu_token}

Simula o pagamento de uma cobrança de boleto no ambiente sandbox. Atualiza o status da transação para APPROVED e da cobrança para PAY.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`id`	long	Sim	ID da cobrança de boleto a simular

Nenhum corpo é necessário. Basta enviar a requisição POST com o ID da cobrança. A cobrança deve ser do tipo boleto.

Códigos de resposta

Código	Descrição
202	Pagamento de boleto simulado com sucesso
401	Não autorizado — token inválido ou ausente
404	Retornado em ambiente de produção (endpoint indisponível)

POST /api/v2/simulations/charges/{id}/payment/pix

Headers

Authorization: Bearer {seu_token}

Simula o pagamento de uma cobrança PIX no ambiente sandbox. Atualiza a transação PIX como paga.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`id`	long	Sim	ID da cobrança PIX a simular

Nenhum corpo é necessário. Basta enviar a requisição POST com o ID da cobrança. A cobrança deve ser do tipo PIX.

Códigos de resposta

Código	Descrição
202	Pagamento PIX simulado com sucesso
401	Não autorizado — token inválido ou ausente
404	Retornado em ambiente de produção (endpoint indisponível)

Os endpoints de simulação de pagamento estão disponíveis apenas no ambiente sandbox. Em produção, retornam 404.

POST /api/v2/sellers/{sellerId}/simulation

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Simulador de taxas. Exibe as taxas de intermediação cobradas para todas as formas de pagamento (PIX, Boleto e Cartão de Crédito) com base no valor informado.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`sellerId`	long	Sim	ID do seller

Request body

json — request body

{
  "grossAmount": 10000
}

Campo	Tipo	Obrigatório	Descrição
`grossAmount`	long	Sim	Valor da cobrança em centavos

Response body (SimulationV2Response)

Campo	Tipo	Descrição
`pix`	object	Simulação de taxas para PIX
`pix.totalPercentageFee`	BigDecimal	Taxa percentual total
`pix.totalFixFeeCents`	integer	Taxa fixa em centavos
`pix.sellerTakingFees`	object	Valores quando o seller absorve as taxas
`pix.customerTakingFees`	object	Valores quando o cliente absorve as taxas
`boleto`	object	Simulação de taxas para Boleto (mesma estrutura do pix)
`creditCard`	array	Lista de simulações por parcela/bandeira
`creditCard[].totalPercentageFee`	BigDecimal	Taxa percentual total
`creditCard[].installments`	integer	Número de parcelas
`creditCard[].brand`	GatewayBrandTypes	Bandeira do cartão
`creditCard[].sellerTakingFees`	object	Valores quando o seller absorve as taxas
`creditCard[].customerTakingFees`	object	Valores quando o cliente absorve as taxas

Estrutura de SellerTakingFees / CustomerTakingFees

Campo	Tipo	Descrição
`saleAmount`	long	Valor da venda em centavos
`installmentAmount`	long	Valor da parcela em centavos
`amountToReceive`	long	Valor líquido a receber em centavos
`feeAmount`	long	Valor da taxa em centavos

Códigos de resposta

Código	Descrição
200	Simulação retornada com sucesso
401	Não autorizado — token inválido ou ausente
422	Erro ao processar a simulação

SDK de Pagamentos Android #

Biblioteca oficial Zoov para integrar pagamentos presenciais em aplicações Android. Suporta Tap on Phone (NFC) para cartões de crédito e débito, além de PIX via QR Code.

Requisitos: Android Studio Arctic Fox+, Java 17, dispositivo com NFC (API 30+).

SETUP Instalação

Copie o arquivo zoovlib-release.aar para app/libs/ e adicione as dependências ao build.gradle.

Estrutura do projeto

text

zoov-payment/
├── app/
│   ├── libs/
│   │   └── zoovlib-release.aar
│   └── src/main/
│       ├── java/.../MainActivity.kt
│       └── AndroidManifest.xml
├── docs/
└── README.md

Dependências (build.gradle)

gradle

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.aar'])
    implementation 'com.google.android.play:integrity:1.3.0'
    implementation 'com.squareup.okhttp3:okhttp-dnsoverhttps:3.14.9'
    implementation 'com.google.code.gson:gson:2.10.1'
    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
    implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
    implementation 'com.squareup.okhttp3:logging-interceptor:4.10.0'
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.1'
    implementation 'androidx.lifecycle:lifecycle-runtime-ktx:2.6.1'
    implementation 'org.bouncycastle:bcprov-jdk15to18:1.80'
    implementation 'org.bouncycastle:bcpkix-jdk15to18:1.80'
    implementation 'org.apache.commons:commons-lang3:3.14.0'
}

Permissões (AndroidManifest.xml)

xml

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.NFC" />
<uses-permission android:name="android.permission.CAMERA" />

SETUP Configuração

Adicione as credenciais do terminal ao build.gradle.kts do módulo app. Em produção, substitua pelos valores fornecidos pela Zoov.

kotlin

android {
    defaultConfig {
        buildConfigField("String", "ZOOV_CLIENT_TOKEN", "\"your_token\"")
        buildConfigField("String", "ZOOV_CLIENT_ID", "\"your_id\"")
        buildConfigField("String", "ZOOV_AUTH_ID", "\"your_auth_id\"")
        buildConfigField("String", "ZOOV_TERMINAL_ID", "\"terminal_id\"")
        buildConfigField("String", "ZOOV_TAX_PAYER_ID", "\"cnpj\"")
        buildConfigField("String", "ZOOV_NETWORK_ID", "\"network_id\"")
        buildConfigField("String", "ZOOV_NETWORK_PWD", "\"network_pwd\"")
        buildConfigField("String", "ZOOV_MERCHANT_ID", "\"merchant_id\"")
        buildConfigField("String", "ZOOV_HOSTNAME_SERVER", "\"api.zoov.com.br\"")
        buildConfigField("String", "ZOOV_TCP_PORT", "\"443\"")
        buildConfigField("String", "PIX_BASE_URL", "\"https://api.zoov.com.br/pix/v2\"")
        buildConfigField("String", "PIX_JWT", "\"jwt_token\"")
        buildConfigField("String", "PIX_SELLER_ID", "\"1\"")
    }
}

Parâmetros de configuração

Parâmetro	Obrigatório	Descrição
`ZOOV_CLIENT_TOKEN`	Sim	Token de autenticação do cliente
`ZOOV_CLIENT_ID`	Sim	Identificador do cliente
`ZOOV_AUTH_ID`	Sim	ID de autenticação
`ZOOV_TERMINAL_ID`	Sim	Identificador do terminal
`ZOOV_TAX_PAYER_ID`	Sim	CNPJ do estabelecimento
`ZOOV_NETWORK_ID`	Sim	ID da rede adquirente
`ZOOV_NETWORK_PWD`	Sim	Senha da rede
`ZOOV_MERCHANT_ID`	Sim	Identificador do lojista
`ZOOV_HOSTNAME_SERVER`	Sim	Hostname do servidor
`ZOOV_TCP_PORT`	Sim	Porta TCP do servidor
`PIX_BASE_URL`	PIX	URL base da API PIX
`PIX_JWT`	PIX	Token JWT para PIX
`PIX_SELLER_ID`	PIX	ID do seller para PIX

Os parâmetros PIX_* são obrigatórios apenas se o método PIX estiver habilitado em enabledPaymentMethods.

CODE Iniciar Pagamento

Use ZoovPaymentActivity.createIntent() para iniciar o fluxo de pagamento. O SDK exibe a interface de pagamento e retorna o resultado via ActivityResult.

kotlin

import com.zoov.lib.ZoovPaymentActivity
import com.zoov.lib.data.enums.ZoovPaymentMethod

class MainActivity : ComponentActivity() {

    private val paymentLauncher = registerForActivityResult(
        ActivityResultContracts.StartActivityForResult()
    ) { result ->
        handlePaymentResult(result.resultCode, result.data)
    }

    private fun iniciarPagamento(amountInCents: Long) {
        val intent = ZoovPaymentActivity.createIntent(
            activity = this,
            clientToken = BuildConfig.ZOOV_CLIENT_TOKEN,
            clientId = BuildConfig.ZOOV_CLIENT_ID,
            authId = BuildConfig.ZOOV_AUTH_ID,
            terminalId = BuildConfig.ZOOV_TERMINAL_ID,
            taxPayerId = BuildConfig.ZOOV_TAX_PAYER_ID,
            networkId = BuildConfig.ZOOV_NETWORK_ID,
            networkPwd = BuildConfig.ZOOV_NETWORK_PWD,
            merchantId = BuildConfig.ZOOV_MERCHANT_ID,
            hostnameServer = BuildConfig.ZOOV_HOSTNAME_SERVER,
            tcpPort = BuildConfig.ZOOV_TCP_PORT,
            amountInCents = amountInCents,
            enabledPaymentMethods = setOf(
                ZoovPaymentMethod.CREDIT_CARD,
                ZoovPaymentMethod.DEBIT_CARD,
                ZoovPaymentMethod.PIX
            ),
            pixBaseUrl = BuildConfig.PIX_BASE_URL,
            pixJwt = BuildConfig.PIX_JWT,
            pixSellerId = BuildConfig.PIX_SELLER_ID
        )
        paymentLauncher.launch(intent)
    }
}

Parâmetros de createIntent()

Parâmetro	Tipo	Obrigatório	Descrição
`activity`	Activity	Sim	Activity que inicia o pagamento
`clientToken`	String	Sim	Token de autenticação do cliente
`clientId`	String	Sim	Identificador do cliente
`authId`	String	Sim	ID de autenticação
`terminalId`	String	Sim	Identificador do terminal
`taxPayerId`	String	Sim	CNPJ do estabelecimento
`networkId`	String	Sim	ID da rede adquirente
`networkPwd`	String	Sim	Senha da rede
`merchantId`	String	Sim	Identificador do lojista
`hostnameServer`	String	Sim	Hostname do servidor
`tcpPort`	String	Sim	Porta TCP do servidor
`amountInCents`	Long?	Não	Valor em centavos (`null` = input manual)
`enabledPaymentMethods`	Set?	Não	Métodos habilitados (padrão: todos)
`pixBaseUrl`	String?	PIX	URL base da API PIX
`pixJwt`	String?	PIX	Token JWT para PIX
`pixSellerId`	String?	PIX	ID do seller para PIX

Métodos de pagamento

Enum	Descrição
`ZoovPaymentMethod.CREDIT_CARD`	Cartão de crédito via NFC (parcelamento até 12x)
`ZoovPaymentMethod.DEBIT_CARD`	Cartão de débito via NFC
`ZoovPaymentMethod.PIX`	PIX via QR Code

CODE Resultado do Pagamento

Trate o resultado do pagamento via ActivityResult ou BroadcastReceiver.

Via ActivityResult

kotlin

private fun handlePaymentResult(resultCode: Int, data: Intent?) {
    when (resultCode) {
        ZoovPaymentActivity.RESULT_PAYMENT_SUCCESS -> {
            val amount = data?.getLongExtra(
                ZoovPaymentActivity.EXTRA_RESULT_AMOUNT, 0L)
            val authCode = data?.getStringExtra(
                ZoovPaymentActivity.EXTRA_RESULT_AUTH_CODE)
            val transactionId = data?.getStringExtra(
                ZoovPaymentActivity.EXTRA_RESULT_TRANSACTION_ID)
            // Pagamento aprovado — salve os dados no backend
        }
        ZoovPaymentActivity.RESULT_PAYMENT_ERROR -> {
            val errorCode = data?.getIntExtra(
                ZoovPaymentActivity.EXTRA_RESULT_ERROR_CODE, 0)
            val errorMessage = data?.getStringExtra(
                ZoovPaymentActivity.EXTRA_RESULT_ERROR_MESSAGE)
            // Erro — exiba mensagem ao usuário
        }
        ZoovPaymentActivity.RESULT_PAYMENT_CANCELLED -> {
            // Usuário cancelou o pagamento
        }
    }
}

Via BroadcastReceiver

kotlin

private val paymentReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
        if (intent?.action == ZoovPaymentActivity.ACTION_PAYMENT_RESULT) {
            val resultType = intent.getIntExtra(
                ZoovPaymentActivity.EXTRA_RESULT_TYPE, 0)
            when (resultType) {
                ZoovPaymentActivity.RESULT_PAYMENT_SUCCESS -> {
                    // Pagamento aprovado
                }
                ZoovPaymentActivity.RESULT_PAYMENT_ERROR -> {
                    // Erro no pagamento
                }
            }
        }
    }
}

Códigos de resultado

Constante	Valor	Descrição
`RESULT_PAYMENT_SUCCESS`	1	Pagamento aprovado
`RESULT_PAYMENT_ERROR`	2	Erro no pagamento
`RESULT_PAYMENT_CANCELLED`	3	Cancelado pelo usuário

Extras do Intent

Constante	Tipo	Descrição
`EXTRA_RESULT_AMOUNT`	Long	Valor em centavos
`EXTRA_RESULT_AUTH_CODE`	String	Código de autorização
`EXTRA_RESULT_TRANSACTION_ID`	String	ID da transação
`EXTRA_RESULT_RECEIPT`	String	Comprovante
`EXTRA_RESULT_ERROR_CODE`	Int	Código do erro
`EXTRA_RESULT_ERROR_MESSAGE`	String	Mensagem do erro

REF Códigos de Erro

Referência completa dos códigos de erro retornados pelo SDK.

Código	Descrição	Ação recomendada
`-1`	Erro de comunicação	Verifique a conexão com a internet
`-2`	Timeout	Tente novamente
`-3`	Timeout de processamento	Tente novamente
`-4`	Operação cancelada	Usuário cancelou
`-5`	Permissão de câmera negada	Solicite acesso à câmera
`-6`	SDK não inicializado	Verifique as credenciais
`-7`	SDK não ativado	Verifique configuração do terminal
`-8`	Exceção na inicialização	Verifique as credenciais
`-9`	Exceção na ativação	Verifique a configuração
`-10`	Erro no cartão/pinpad	Verifique o cartão
`-11`	QR Code PIX expirado	Gere novo QR Code
`-12`	Cliente PIX não configurado	Configure credenciais PIX
`-13`	Dados PIX inválidos	Verifique resposta da API
`-14`	Erro ao criar pedido PIX	Verifique credenciais PIX
`-15`	Pagamento PIX cancelado	Pagamento cancelado pelo usuário
`-16`	Pagamento PIX estornado	Pagamento foi devolvido

Debug: Use adb logcat -s MainActivity para monitorar os logs de pagamento em tempo real.

Cadastros & Fundações

Motor de Pagamentos

Operações Avancadas

Primeiros Passos

Ambientes #

Autenticação #

Como gerar seu token

Exemplo de requisição autenticada

Convenções da API #

Resposta de criação (POST)

Formatos de dados

Respostas de erro

Cadastros & Fundações

Clientes #

Headers de Resposta

Cartões de Crédito #

Headers de Resposta

Endereços #

Headers de Resposta

Produtos #

Headers de Resposta

Tokenização

Criar Token #

Headers da resposta

Consultar Token #

Pagamentos

Cartão de Crédito — Autorização #

Headers da resposta

Captura #

Headers da resposta

PIX #

Headers da resposta

Boleto #

Headers da resposta

Gestão de Cobranças

Cobrança Direta com Cartão #

Headers de Resposta

Estorno Cartão #

Headers de Resposta

Devolução PIX #

Headers de Resposta

Cancelar Boleto #

Cancelar QR Code PIX #

Headers de Resposta

Consultar Cobrança #

Headers de Resposta

Campos da resposta (200)

Listar Cobranças #

Campos da resposta (200)

Faturamento

Criar Fatura #

Headers da resposta

Enviar Fatura por E-mail #

Obter Fatura #

Headers de Resposta

Campos da resposta (200)

Listar Faturas #

Recorrência & Assinaturas

Faturas Recorrentes #

Headers de Resposta

Resposta (após GET no recurso criado)

Assinaturas #

Headers da resposta

Headers da resposta

Headers de Resposta

PIX Automático

Visão Geral #

Como funciona #

Criar a autorização #

Ciclo de vida da autorização #

Webhooks #

Marketplace & Split

Exemplo com Split #

Headers de Resposta

Fatura com Split #

Headers da resposta

Sellers e Receivers #

Headers da resposta

Headers da resposta

Campos do cartão (objeto `card`)

Campos 3DS adicionais (objeto `threeDSecure`)