Zoov Payment API

Plataforma completa de pagamentos. Infraestrutura financeira via API REST, desde cadastro de clientes até operações complexas de Banking as a Service e Split de Pagamentos.

Começar agora Ver convenções

Cadastros & Fundações

Base para todas as operações. Gerencie clientes, cartões, endereços e produtos.

Clientes (PF e PJ)
Cartoes tokenizados
Endereços de cobrança
Catalogo de produtos

Motor de Pagamentos

Processe pagamentos com multiplos métodos e seguranca de nivel bancario.

Cartão de Crédito/Debito
PIX instantaneo
Boleto bancario
Faturas e 3DS 2.0

Operações Avancadas

Recursos enterprise para marketplaces, recorrencia e gestao financeira.

Banking as a Service
Split de Pagamento
Cobrança recorrente
Gestao financeira

Fluxo de pagamento com cartão

Tokenizar

Transforme dados sensiveis em token seguro

Autorizar

Crie a cobrança e reserve o valor

Capturar

Confirme e efetive o pagamento

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://sandbox-api.zoov.com.br/api/v2`	sandbox-painel.zoov.com.br
Produção	`https://api.zoov.com.br/api/v2`	painel.zoov.com.br

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	Sim	CPF ou CNPJ (apenas números)
`birthdate`	string (date)	Sim	Data de nascimento (YYYY-MM-DD)
`email`	string	Não	Email do cliente
`phone.countryCode`	integer	Não	Código do país (ex: 55)
`phone.areaCode`	integer	Não	DDD
`phone.number`	integer	Não	Número do telefone
`address.street`	string	Não	Rua
`address.streetNumber`	string	Não	Número
`address.lineTwo`	string	Não	Complemento
`address.neighborhood`	string	Não	Bairro
`address.state`	string	Não	UF (ex: SC)
`address.zipCode`	string	Não	CEP
`address.city`	string	Não	Cidade

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. Atualização parcial — envie apenas os campos que deseja alterar.

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	Não	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	Não	Código do país
`phone.areaCode`	integer	Não	DDD
`phone.number`	integer	Não	Número do telefone
`address.street`	string	Não	Rua
`address.streetNumber`	string	Não	Número
`address.lineTwo`	string	Não	Complemento
`address.neighborhood`	string	Não	Bairro
`address.state`	string	Não	UF
`address.zipCode`	string	Não	CEP
`address.city`	string	Não	Cidade

Envie apenas os campos que deseja atualizar. Campos omitidos permanecerão inalterados.

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

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

Headers

Authorization: Bearer {seu_token}

Buscar cliente por documento (CPF/CNPJ).

json — response body

{
  "id": 12345,
  "document": "51190844001",
  "name": "Tony Stark",
  "email": "stark@gmail.com",
  "phoneNumber": "5548998870001",
  "birthdate": "2000-01-01",
  "creditCards": [
    {
      "id": 1,
      "cardNumber": "544828******0007",
      "brand": "MASTERCARD",
      "isDefault": true
    }
  ],
  "addresses": [
    {
      "id": 1,
      "street": "Rua Jair Hamms",
      "number": "38",
      "neighborhood": "Pedra Branca",
      "city": "Palhoca",
      "state": "SC",
      "zipCode": "88137084",
      "isDefault": true
    }
  ]
}

Campo	Tipo	Descrição
`id`	integer	Identificador do cliente
`document`	string	CPF/CNPJ
`name`	string	Nome completo
`email`	string	Email
`phoneNumber`	string	Telefone completo (pais + DDD + número)
`birthdate`	string (date)	Data de nascimento (YYYY-MM-DD)
`creditCards[]`	array	Cartões de crédito associados
`creditCards[].id`	integer	Identificador do cartão
`creditCards[].cardNumber`	string	Número do cartão mascarado
`creditCards[].brand`	string	Bandeira (VISA, MASTERCARD, etc.)
`creditCards[].isDefault`	boolean	Se e o cartão padrão
`addresses[]`	array	Endereços cadastrados
`addresses[].id`	integer	Identificador do endereço
`addresses[].street`	string	Rua
`addresses[].number`	string	Número
`addresses[].neighborhood`	string	Bairro
`addresses[].city`	string	Cidade
`addresses[].state`	string	UF
`addresses[].zipCode`	string	CEP
`addresses[].isDefault`	boolean	Se e o endereço padrão

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

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

Headers

Authorization: Bearer {seu_token}

Verificar se um cliente já existe pelo documento.

json — response body

{
  "exists": true
}

Campo	Tipo	Descrição
`exists`	boolean	Indica se o cliente existe na base

Status	Descrição
200	Verificação realizada com sucesso
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.

json — request body

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

Campo	Tipo	Obrigatório	Descrição
`cardNumber`	string	Sim	Número completo do cartão
`holder.name`	string	Sim	Nome do titular do cartão
`holder.document`	string	Sim	CPF/CNPJ do titular
`expiration.month`	string	Sim	Mes de validade (01-12)
`expiration.year`	string	Sim	Ano de validade (ex: 2035)
`cvv`	string	Sim	Código de seguranca (3 ou 4 digitos)

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}

Content-Type: application/json

Atualizar dados de um cartão cadastrado.

json — request body

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

Campo	Tipo	Obrigatório	Descrição
`cardNumber`	string	Não	Número do cartão
`holder.name`	string	Não	Nome do titular
`holder.document`	string	Não	CPF/CNPJ do titular
`expiration.month`	string	Não	Mês de validade (MM)
`expiration.year`	string	Não	Ano de validade (YYYY)
`cvv`	string	Não	Código de segurança

Status	Descrição
200	Cartao atualizado com sucesso
400	Requisição malformada
401	Não autorizado
404	Cartao não encontrado
422	Entidade não processável

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

Headers

Authorization: Bearer {seu_token}

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

json — response body

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

Campo	Tipo	Descrição
`id`	integer	Identificador do cartão
`cardNumber`	string	Número do cartão mascarado
`brand`	string	Bandeira (VISA, MASTERCARD, etc.)
`holder.name`	string	Nome do titular
`holder.document`	string	CPF/CNPJ do titular
`expiration.month`	string	Mes de validade
`expiration.year`	string	Ano de validade
`isDefault`	boolean	Se e o cartão padrão

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

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

Headers

Authorization: Bearer {seu_token}

Listar todos os cartões do cliente.

json — response body

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

Campo	Tipo	Descrição
`[].id`	integer	Identificador do cartão
`[].cardNumber`	string	Número do cartão mascarado
`[].brand`	string	Bandeira (VISA, MASTERCARD, etc.)
`[].holder.name`	string	Nome do titular
`[].holder.document`	string	CPF/CNPJ do titular
`[].expiration.month`	string	Mes de validade
`[].expiration.year`	string	Ano de validade
`[].isDefault`	boolean	Se e o cartão padrão

Status	Descrição
200	Lista retornada com sucesso
401	Não autorizado
404	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.

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 endereço criado

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

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

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Atualizar um endereço existente.

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	Não	Rua
`streetNumber`	string	Não	Número
`lineTwo`	string	Não	Complemento
`neighborhood`	string	Não	Bairro
`city`	string	Não	Cidade
`state`	string	Não	UF
`zipCode`	string	Não	CEP

Status	Descrição
200	Endereco atualizado com sucesso
400	Requisição malformada
401	Não autorizado
404	Endereco não encontrado
422	Entidade não processável

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

Headers

Authorization: Bearer {seu_token}

Obter o endereço padrão do cliente.

json — response body

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

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
`isDefault`	boolean	Se e o endereço padrão

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

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

Headers

Authorization: Bearer {seu_token}

Listar todos os endereços do cliente.

json — response body

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

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
`[].isDefault`	boolean	Se e o endereço padrão

Status	Descrição
200	Lista retornada com sucesso
401	Não autorizado
404	Cliente não encontrado

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",
  "name": "Produto Exemplo",
  "value": 500,
  "softDescriptor": "Product Plus",
  "maxInstallments": 12,
  "active": true,
  "methods": ["CREDIT_CARD", "PIX"],
  "description": "Este e um produto exemplo."
}

Campo	Tipo	Obrigatório	Descrição
`productType`	string	Sim	ONETIME ou RECURRING
`name`	string	Sim	Nome do produto
`value`	integer	Sim	Preco em centavos
`softDescriptor`	string	Não	Descrição na fatura do cartão
`maxInstallments`	integer	Não	Máximo de parcelas
`active`	boolean	Não	Status ativo
`methods`	array[string]	Não	CREDIT_CARD, PIX, BANK_SLIP
`description`	string	Não	Descrição do produto

Headers de Resposta

LocationURL do recurso criado

Content-IDID numérico do produto criado

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

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,
  "softDescriptor": "Product Plus",
  "maxInstallments": 12,
  "active": true,
  "methods": ["CREDIT_CARD", "PIX"],
  "description": "Este e um produto exemplo."
}

Campo	Tipo	Obrigatório	Descrição
`productType`	string	Não	ONETIME ou RECURRING
`name`	string	Não	Nome do produto
`value`	integer	Não	Preço em centavos
`softDescriptor`	string	Não	Descrição na fatura
`maxInstallments`	integer	Não	Máximo de parcelas
`active`	boolean	Não	Status ativo
`methods`	array	Não	CREDIT_CARD, PIX, BANK_SLIP
`description`	string	Não	Descrição do produto

Status	Descrição
200	Produto atualizado com sucesso
400	Requisição malformada
401	Não autorizado
404	Produto não encontrado
422	Entidade não processável

GET /api/v2/products/{id}

Headers

Authorization: Bearer {seu_token}

Obter produto por ID.

json — response body

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

Campo	Tipo	Descrição
`id`	integer	Identificador do produto
`productType`	string	ONETIME ou RECURRING
`name`	string	Nome do produto
`value`	integer	Preco em centavos
`softDescriptor`	string	Descrição na fatura do cartão
`maxInstallments`	integer	Máximo de parcelas
`active`	boolean	Status ativo
`methods`	array[string]	Métodos aceitos (CREDIT_CARD, PIX, BANK_SLIP)
`description`	string	Descrição do produto

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

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

Cartao

Dados sensiveis do portador

API Vault

Armazenamento seguro e criptografado

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	Sim	CPF/CNPJ do titular
`expiration.year`	integer	Sim	Ano de validade (YYYY)
`expiration.month`	integer	Sim	Mes de validade (1-12)
`cardNumber`	string	Sim	Número completo do cartão

Resposta: 201 Created

Headers da resposta

Location URL do token criado

Content-ID ID do 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",
  "cardNumber": "544828******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
`cardNumber`	string	Número mascarado 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
`expiration.month`	integer	Mes de validade (1-12)
`expiration.year`	integer	Ano de validade (YYYY)

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",
  "cardNumber": "544828******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
`cardNumber`	string	Número mascarado 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
`expiration.month`	integer	Mes de validade (1-12)
`expiration.year`	integer	Ano de validade (YYYY)

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

Tokenizar

Transforme o PAN em token seguro

Autorizar

Reserve o valor no cartão

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.birthdate`	string	Sim	Data de nascimento (YYYY-MM-DD)
`customer.document`	string	Sim	CPF/CNPJ
`customer.name`	string	Sim	Nome completo
`customer.address.*`	object	Não	Endereco do cliente
`notificationUrl`	string	Não	URL para webhooks
`payments[].installments`	integer	Sim	Número de parcelas
`payments[].cardToken.token`	string	Sim	Token do cartão
`payments[].cardToken.cvv`	string	Sim	CVV do cartão
`payments[].amount`	integer	Sim	Valor do pagamento em centavos
`payments[].paymentMethod`	string	Sim	CREDIT_CARD
`metadata`	object	Não	Dados customizados chave-valor

Headers da resposta

Location URL da cobrança

Link (rel="capture") URL para captura

Link (rel="refund") URL para estorno

Link (rel="metadata") URL dos metadados

Content-ID ID da cobrança

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
422	Entidade não processável

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

Nota: Nenhum corpo e necessário. Use a URL do header Link (rel="capture") retornado na autorização.

Resposta: 201 Created

Headers da resposta

Location URL do recurso criado

Content-ID ID numérico do recurso

Status	Descrição
201	Captura realizada com sucesso
401	Não autorizado
404	Cobrança nao encontrada
422	Entidade não processável

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
`amount`	integer	Sim	Valor total em centavos
`orderReference`	string	Sim	Referencia unica do pedido
`customer.*`	object	Sim	Dados do cliente (document, name, birthdate)
`dueDate`	string	Sim	Data de vencimento do boleto
`description`	string	Não	Descrição do boleto
`notificationUrl`	string	Não	URL para webhooks

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": "BANK_SLIP",
      "amount": 25000,
      "dueDate": 1694314800000
    }
  ]
}

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": 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" },
    "brand": "MASTER",
    "cardNumber": "5356066320271893",
    "cvv": "123"
  },
  "installments": 1,
  "value": 10000,
  "yourReferenceId": "ORDER0001",
  "notificationUrl": "https://myserver/events/charges/ORDER0001"
}

Campo	Tipo	Obrigatório	Descrição
`customer.document`	string	Sim	CPF/CNPJ
`customer.name`	string	Sim	Nome
`card.cardNumber`	string	Sim	Número do cartão
`card.cvv`	string	Sim	CVV
`card.brand`	string	Sim	VISA, MASTER, ELO, AMEX
`card.holder.name`	string	Sim	Nome do titular
`card.holder.document`	string	Sim	Documento do titular
`card.expiration.month`	string	Sim	Mes (MM)
`card.expiration.year`	string	Sim	Ano (YYYY)
`installments`	integer	Sim	Parcelas
`value`	integer	Sim	Valor em centavos
`yourReferenceId`	string	Não	Referência do lojista
`notificationUrl`	string	Não	URL webhook

Campos da resposta (201)

Campo	Tipo	Descrição
`id`	integer	ID da cobrança
`status`	ChargeStatus	Status atual
`value`	integer	Valor em centavos
`refundedAmount`	integer	Valor estornado
`transactions`	array	Lista de transações
`installments`	integer	Parcelas

json — response body (201)

{
  "id": 12345,
  "status": "PAY",
  "value": 10000,
  "refundedAmount": 0,
  "installments": 1,
  "customer": {
    "document": "97012687096",
    "name": "John Snow"
  },
  "order": {
    "id": 6789,
    "orderReference": "ORDER0001"
  },
  "transactions": [
    {
      "id": "txn_abc123",
      "status": "APPROVED",
      "type": "LOOSE",
      "value": 10000,
      "createdAt": 1694314800000
    }
  ]
}

Headers de Resposta

LocationURL do recurso criado

Content-IDID numérico do recurso

Linkrel="refund" — URL para estorno

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`	string	Sim	Motivo do estorno: DUPLICATE_CHARGE, IMPROPER_CHARGE, COSTUMER_WITHDRAWAL ou OTHERS
`amount`	integer	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}

Content-Type: application/json

Devolver um pagamento PIX.

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

json — request body (opcional)

{
  "amount": 5000
}

Campo	Tipo	Obrigatório	Descrição
`amount`	integer	Não	Valor parcial em centavos; se omitido, devolve o total

Headers de Resposta

LocationURL do recurso criado

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

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	Nao autenticado
404	Cobrança nao encontrada
422	Entidade não processável

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 e necessário. Cancela o QR Code PIX antes do pagamento.

Status	Descrição
200	QR Code PIX cancelado com sucesso
401	Nao autenticado
404	Cobrança nao encontrada
422	Entidade não processável

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": {
    "document": "97012687096",
    "name": "John Snow"
  },
  "order": {
    "id": 6789,
    "orderReference": "ORDER0001"
  },
  "transactions": [
    {
      "id": "txn_abc123",
      "status": "APPROVED",
      "type": "LOOSE",
      "value": 10000,
      "createdAt": 1694314800000
    }
  ]
}

Campos da resposta (200)

Campo	Tipo	Descrição
`id`	integer	ID da cobrança
`status`	ChargeStatus	Status atual
`value`	integer	Valor em centavos
`refundedAmount`	integer	Valor estornado em centavos
`installments`	integer	Número de parcelas
`customer.document`	string	CPF/CNPJ do cliente
`customer.name`	string	Nome do cliente
`order.id`	integer	ID do pedido
`order.orderReference`	string	Referência do pedido
`transactions[].id`	string	ID da transação
`transactions[].status`	string	Status da transação
`transactions[].type`	string	Tipo da transação
`transactions[].value`	integer	Valor da transação em centavos
`transactions[].createdAt`	long	Data de criação (ms epoch)

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`	string	Não	Data início (YYYY-MM-DD)
`paymentDateTo`	string	Não	Data fim (YYYY-MM-DD)
`status`	string	Não	Filtrar por status
`page`	integer	Não	Número da página
`size`	integer	Não	Itens por página

json — response body (200)

{
  "content": [
    {
      "id": 12345,
      "status": "PAY",
      "value": 10000,
      "refundedAmount": 0,
      "installments": 1
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1
}

Campos da resposta (200)

Campo	Tipo	Descrição
`content[]`	array	Lista de cobranças
`page`	integer	Página atual
`size`	integer	Itens por página
`totalElements`	integer	Total de registros
`totalPages`	integer	Total de páginas

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`	string	Sim	Data limite (ms timestamp)
`notificationUrl`	string	Não	URL webhook
`successUrl`	string	Não	URL de redirecionamento após pagamento
`items[].productId`	integer	Sim	ID do produto
`items[].quantity`	integer	Sim	Quantidade
`items[].unitPriceInCents`	integer	Sim	Preco unitario em centavos
`acceptedPaymentMethods[].method`	string	Sim	CREDIT_CARD, PIX ou BANK_SLIP
`acceptedPaymentMethods[].cardSettings.maxInstallments`	integer	Não	Máximo de parcelas
`acceptedPaymentMethods[].amountOff`	integer	Não	Desconto em centavos (PIX/Boleto)

Headers de Resposta

LocationURL do recurso criado

Content-IDID numérico da fatura

Linkrel="payment" — URL da fatura para pagamento

json — response body (GET após criação)

{
  "id": 1001,
  "invoiceNumber": "FAT-2024-001",
  "status": "PENDING",
  "customerId": 1,
  "dueDate": 1732310753051,
  "items": [
    {
      "productId": 1,
      "quantity": 1,
      "unitPriceInCents": 70000,
      "totalInCents": 70000
    }
  ],
  "acceptedPaymentMethods": ["CREDIT_CARD"],
  "paymentUrl": "https://pay.zoov.com.br/invoice/abc123",
  "totalInCents": 70000
}

Campos da resposta

Campo	Tipo	Descrição
`id`	integer	ID da fatura
`invoiceNumber`	string	Número único da fatura
`status`	string	Status da fatura (PENDING, PAID, etc.)
`customerId`	integer	ID do cliente
`dueDate`	long	Data de vencimento (ms epoch)
`items[]`	array	Lista de itens da fatura
`acceptedPaymentMethods`	array	Métodos de pagamento aceitos
`paymentUrl`	string	URL de pagamento da fatura
`totalInCents`	integer	Valor total em centavos

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

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
201	Email enviado com sucesso
401	Nao autenticado
404	Fatura nao encontrada

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`	integer	Sim	ID da fatura

json — response body (200)

{
  "id": 1001,
  "invoiceNumber": "FAT-2024-001",
  "status": "PENDING",
  "customerId": 1,
  "dueDate": 1732310753051,
  "items": [
    {
      "productId": 1,
      "quantity": 1,
      "unitPriceInCents": 70000,
      "totalInCents": 70000
    }
  ],
  "acceptedPaymentMethods": ["CREDIT_CARD"],
  "paymentUrl": "https://pay.zoov.com.br/invoice/abc123",
  "totalInCents": 70000
}

Campos da resposta (200)

Campo	Tipo	Descrição
`id`	integer	ID da fatura
`invoiceNumber`	string	Número único da fatura
`status`	string	Status da fatura (PENDING, PAID, etc.)
`customerId`	integer	ID do cliente
`dueDate`	long	Data de vencimento (ms epoch)
`items[]`	array	Lista de itens da fatura
`acceptedPaymentMethods`	array	Métodos de pagamento aceitos
`paymentUrl`	string	URL de pagamento da fatura
`totalInCents`	integer	Valor total em centavos

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

Listar Faturas #

GET /api/v2/invoices

Headers

Authorization: Bearer {seu_token}

Listar todas as faturas.

json — response body (200)

{
  "content": [
    {
      "id": 1001,
      "invoiceNumber": "FAT-2024-001",
      "status": "PENDING",
      "customerId": 1,
      "totalInCents": 70000
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1
}

Campo	Tipo	Descrição
`content[]`	array	Lista de faturas
`content[].id`	integer	ID da fatura
`content[].invoiceNumber`	string	Número da fatura
`content[].status`	string	Status da fatura
`content[].totalInCents`	integer	Valor total em centavos
`page`	integer	Página atual
`size`	integer	Itens por página
`totalElements`	integer	Total de registros
`totalPages`	integer	Total de páginas

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	AUTOMATIC_CHARGE ou SEND_INVOICE
`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

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	Método de cobrança (AUTOMATIC_CHARGE ou SEND_INVOICE)
`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)	string	Sim	ID do plano de assinatura

json — request body

{
  "customer": {
    "document": "51190844001",
    "name": "Tony Stark",
    "birthdate": "2000-01-01",
    "email": "stark@gmail.com",
    "phone": {
      "countryCode": 55,
      "areaCode": 48,
      "number": 998870001
    }
  },
  "cardToken": {
    "token": "643c663f3c244f939ef1f9acc6ccd75d",
    "cvv": "123"
  }
}

Campo	Tipo	Obrigatório	Descrição
`customer.document`	string	Sim	CPF do cliente (somente números)
`customer.name`	string	Sim	Nome completo do cliente
`customer.birthdate`	string	Sim	Data de nascimento (YYYY-MM-DD)
`customer.email`	string	Sim	E-mail do cliente
`customer.phone.countryCode`	integer	Sim	Código do país (ex: 55)
`customer.phone.areaCode`	integer	Sim	DDD
`customer.phone.number`	integer	Sim	Número do telefone
`cardToken.token`	string	Sim	Token do cartão gerado previamente
`cardToken.cvv`	string	Sim	CVV do cartão

Headers de Resposta

LocationURL do recurso criado

Content-IDID numérico da assinatura

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

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 nao encontrada

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,
  "planId": 1,
  "status": "ACTIVE",
  "customer": {
    "id": 12345,
    "document": "51190844001",
    "name": "Tony Stark"
  },
  "creditCard": {
    "id": 1,
    "cardNumber": "544828******0007",
    "brand": "MASTERCARD"
  },
  "createdAt": 1694314800000,
  "nextChargeDate": 1696906800000
}

Campo	Tipo	Descrição
`id`	integer	ID da assinatura
`planId`	integer	ID do plano vinculado
`status`	string	Status da assinatura (ACTIVE, CANCELLED, etc.)
`customer.id`	integer	ID do cliente
`customer.document`	string	CPF do cliente
`customer.name`	string	Nome do cliente
`creditCard.id`	integer	ID do cartão armazenado
`creditCard.cardNumber`	string	Número do cartão mascarado
`creditCard.brand`	string	Bandeira do cartão (VISA, MASTERCARD, etc.)
`createdAt`	long	Data de criação em milissegundos (epoch)
`nextChargeDate`	long	Proxima data de cobrança em milissegundos (epoch)

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

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`	string	Sim	Modo do split. Deve ser "ACQUIRER"
`payments[].splits[].sellerId`	integer	Sim	ID do vendedor/recebedor
`payments[].splits[].amount`	integer	Sim	Valor em centavos para este recebedor

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

Sellers e Receivers #

Cadastre vendedores (sellers) e recebedores (receivers) que participarao do split de pagamento.

POST /api/v2/sellers/cnpj

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Cadastrar seller por CNPJ.

json — request body

{
  "name": "Empresa Exemplo LTDA",
  "document": "12345678000190",
  "email": "contato@empresa.com",
  "phone": {
    "countryCode": 55,
    "areaCode": 48,
    "number": 998870001
  },
  "bankAccount": {
    "bank": "001",
    "agency": "1234",
    "accountNumber": "56789-0",
    "accountType": "CHECKING"
  }
}

POST /api/v2/sellers/cpf

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Cadastrar seller por CPF.

json — request body

{
  "name": "Tony Stark",
  "document": "51190844001",
  "email": "tony@email.com",
  "phone": {
    "countryCode": 55,
    "areaCode": 48,
    "number": 998870001
  },
  "bankAccount": {
    "bank": "001",
    "agency": "1234",
    "accountNumber": "56789-0",
    "accountType": "CHECKING"
  }
}

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.

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.

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome ou razao social
`document`	string	Sim	CPF ou CNPJ (somente números)
`email`	string	Sim	E-mail de contato
`phone.countryCode`	integer	Sim	Código do país (ex: 55)
`phone.areaCode`	integer	Sim	DDD
`phone.number`	integer	Sim	Número do telefone
`bankAccount.bank`	string	Sim	Código do banco (ex: "001")
`bankAccount.agency`	string	Sim	Número da agencia
`bankAccount.accountNumber`	string	Sim	Número da conta com digito
`bankAccount.accountType`	string	Sim	Tipo da conta: CHECKING ou SAVINGS

Headers de Resposta

LocationURL do recurso criado

Content-IDID numérico do seller/receiver

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

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": "Empresa Exemplo LTDA",
  "document": "12345678000190",
  "email": "contato@empresa.com",
  "status": "ACTIVE"
}

Campo	Tipo	Descrição
`id`	integer	ID do seller
`name`	string	Nome ou razao social
`document`	string	CPF ou CNPJ
`email`	string	E-mail de contato
`status`	string	Status do seller (ACTIVE, INACTIVE, etc.)

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

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": "Empresa Exemplo LTDA",
  "document": "12345678000190",
  "email": "contato@empresa.com",
  "status": "ACTIVE"
}

Campo	Tipo	Descrição
`id`	integer	ID do receiver
`name`	string	Nome ou razao social
`document`	string	CPF ou CNPJ
`email`	string	E-mail de contato
`status`	string	Status do receiver (ACTIVE, INACTIVE, etc.)

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

Segurança

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

Fluxo 3DS #

Fluxo de autenticação 3DS

Autorizar

Envie dados do dispositivo com 3DS

Challenge

Redirecione o cliente se necessário

Webhook

Receba a confirmacao via notificação

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",
    "brand": "VISA",
    "expiration": { "month": "12", "year": "2034" },
    "holder": { "name": "Tony Stark", "document": "51190844001" }
  },
  "threeDSecure": {
    "deviceType3ds": "BROWSER",
    "screenWidth": 1920,
    "screenHeight": 1080,
    "colorDepth": 24,
    "javaEnabled": false,
    "javascriptEnabled": true,
    "language": "pt-BR",
    "timeZoneOffset": -3,
    "ipAddress": "192.168.1.100",
    "userAgent": "Mozilla/5.0...",
    "embedded": false,
    "billing": {
      "address": {
        "street": "Rua Jair Hamms",
        "streetNumber": "38",
        "zipCode": "88137084",
        "neighborhood": "Pedra Branca",
        "city": "Palhoca",
        "state": "SC"
      },
      "phone": {
        "areaCode": 48,
        "number": 998870001,
        "country": "BRAZIL"
      },
      "email": "stark@gmail.com"
    }
  }
}

Campos principais da requisição

Campo	Tipo	Obrigatório	Descrição
`mode`	string	Sim	Modo da transação (DEBIT ou CREDIT)
`value`	integer	Sim	Valor em centavos
`installments`	integer	Sim	Número de parcelas (1 para débito)
`orderReference`	string	Sim	Referencia unica do pedido
`notificationUrl`	string	Sim	URL de notificação (webhook)

Campos do cartão (objeto `card`)

Campo	Tipo	Obrigatório	Descrição
`card.cardNumber`	string	Sim	Número do cartão
`card.cvv`	string	Sim	Código de seguranca
`card.brand`	string	Sim	Bandeira (VISA, MASTERCARD, etc.)
`card.expiration.month`	string	Sim	Mes de expiração (ex: "12")
`card.expiration.year`	string	Sim	Ano de expiração (ex: "2034")
`card.holder.name`	string	Sim	Nome do titular do cartão
`card.holder.document`	string	Sim	CPF do titular

Campos 3DS adicionais (objeto `threeDSecure`)

Campo	Tipo	Obrigatório	Descrição
`deviceType3ds`	string	Sim	"BROWSER"
`screenWidth`	integer	Sim	Largura da tela
`screenHeight`	integer	Sim	Altura da tela
`colorDepth`	integer	Sim	Profundidade de cor
`javaEnabled`	boolean	Sim	Java habilitado
`javascriptEnabled`	boolean	Sim	JS habilitado
`language`	string	Sim	Idioma do navegador
`timeZoneOffset`	integer	Sim	Offset UTC
`ipAddress`	string	Sim	IP do cliente (IPv4)
`userAgent`	string	Sim	User agent do navegador
`embedded`	boolean	Sim	Se o challenge será embutido na página
`billing.address.*`	object	Sim	Endereço de cobrança (street, streetNumber, zipCode, neighborhood, city, state)
`billing.phone.*`	object	Sim	Telefone de cobrança (areaCode, number, country)
`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)

Status	Descrição
201	Autorização 3DS criada com sucesso
400	Requisição malformada
401	Não autorizado
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.

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}

Content-Type: application/json

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

Parâmetros de caminho

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

Códigos de resposta

Código	Descrição
`200`	Evento reenviado com sucesso
`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}

Content-Type: application/json

Reenvia todos os eventos associados ao pedido.

Parâmetros de caminho

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

Códigos de resposta

Código	Descrição
`200`	Eventos reenviados com sucesso
`401`	Não autorizado — token inválido ou ausente
`404`	Pedido não encontrado

Redisparo de eventos #

POST /api/v2/events

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Dispara o reenvio de eventos pendentes.

Códigos de resposta

Código	Descrição
`200`	Eventos redisparados com sucesso
`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`	integer	Sim	ID do evento

Exemplo de resposta

JSON

{
  "id": 5001,
  "type": "CHARGE_STATUS_CHANGED",
  "orderId": 6789,
  "chargeId": 12345,
  "status": "DELIVERED",
  "notificationUrl": "https://meusite.com.br/api/eventos/cobranças/12345",
  "createdAt": 1694314800000,
  "deliveredAt": 1694314801000,
  "attempts": 1
}

Campos da resposta

Campo	Tipo	Descrição
`id`	integer	Identificador único do evento
`type`	string	Tipo do evento (ex: `CHARGE_STATUS_CHANGED`)
`orderId`	integer	ID do pedido associado
`chargeId`	integer	ID da cobrança associada
`status`	string	Status de entrega do evento (`DELIVERED`, `PENDING`, `FAILED`)
`notificationUrl`	string	URL para a qual o evento foi enviado
`createdAt`	long	Timestamp de criação do evento (epoch ms)
`deliveredAt`	long	Timestamp de entrega do evento (epoch ms)
`attempts`	integer	Número de tentativas de envio realizadas

Códigos de resposta

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

Listar eventos #

GET /api/v2/events

Headers

Authorization: Bearer {seu_token}

Retorna a lista de todos os eventos registrados.

Exemplo de resposta

JSON

[
  {
    "id": 5001,
    "type": "CHARGE_STATUS_CHANGED",
    "orderId": 6789,
    "chargeId": 12345,
    "status": "DELIVERED",
    "notificationUrl": "https://meusite.com.br/api/eventos/cobranças/12345",
    "createdAt": 1694314800000,
    "deliveredAt": 1694314801000,
    "attempts": 1
  },
  {
    "id": 5002,
    "type": "CHARGE_STATUS_CHANGED",
    "orderId": 6790,
    "chargeId": 12346,
    "status": "PENDING",
    "notificationUrl": "https://meusite.com.br/api/eventos/cobranças/12346",
    "createdAt": 1694315000000,
    "deliveredAt": 0,
    "attempts": 3
  }
]

Campo	Tipo	Descrição
`id`	integer	ID do evento
`type`	string	Tipo do evento
`orderId`	integer	ID do pedido
`chargeId`	integer	ID da cobrança
`status`	string	Status de entrega
`notificationUrl`	string	URL de notificação
`createdAt`	long	Data de criação (ms epoch)
`deliveredAt`	long	Data de entrega (ms epoch)
`attempts`	integer	Tentativas de envio

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`	integer	Sim	ID do pedido

Exemplo de resposta

JSON

[
  {
    "id": 5001,
    "type": "CHARGE_STATUS_CHANGED",
    "orderId": 6789,
    "chargeId": 12345,
    "status": "DELIVERED",
    "notificationUrl": "https://meusite.com.br/api/eventos/cobranças/12345",
    "createdAt": 1694314800000,
    "deliveredAt": 1694314801000,
    "attempts": 1
  }
]

Campo	Tipo	Descrição
`id`	integer	ID do evento
`type`	string	Tipo do evento
`orderId`	integer	ID do pedido
`chargeId`	integer	ID da cobrança
`status`	string	Status de entrega
`notificationUrl`	string	URL de notificação
`createdAt`	long	Data de criação (ms epoch)
`deliveredAt`	long	Data de entrega (ms epoch)
`attempts`	integer	Tentativas de envio

Códigos de resposta

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

Referência Técnica

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

Status e Enums #

OrderStatus

Valor	Descrição
ACTIVE	Pedido ativo
OVERDUE	Cobrança pendente
CANCELED	Cancelado
PENDING	Nao concluido
COUNTERCHARGE	Contestacao
CHARGEBACK	Chargeback

ChargeStatus

Valor	Descrição
PAY	Autorizado e capturado
AUTHORIZED	Aguardando captura
PENDING	Pendente
SCHEDULE	Agendado
REFUND	Estornado
COUNTERCHARGE	Contestacao
CHARGEBACK	Chargeback
FAIL	Falha
CANCELED	Cancelado
IN_PROGRESS	Processando

TransactionStatus

Valor	Descrição
IN_PROGRESS	Processando
APPROVED	Aprovada
REFUND	Estornada
AUTHORIZED	Autorizada
NOT_AUTHORIZED	Negada pelo emissor
NOT_APPROVED	Falha na captura
CHARGEBACK	Chargeback
COUNTERCHARGE	Contestacao
FAIL	Falha
AWAITING_PAYMENT	Aguardando pagamento (PIX/Boleto)

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.

Colecao Postman

Pronta para importacao e testes. Contém todos os endpoints documentados com exemplos de request e response.

SDK Android

Aplicação nativa com exemplo completo de integração para plataforma Android.

Sandbox

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

Simuladores

Simule pagamentos PIX e cartao 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}

Content-Type: application/json

Simula o pagamento de uma cobrança PIX ou Boleto no ambiente sandbox. Use este endpoint para testar o fluxo completo sem pagamento real.

Parâmetros de caminho

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

Nenhum corpo e necessário. Basta enviar a requisição POST para o endpoint com o ID da cobrança.

Códigos de resposta

Código	Descrição
`200`	Pagamento simulado com sucesso
`401`	Não autorizado — token inválido ou ausente
`404`	Cobrança nao encontrada

Disponível apenas no ambiente sandbox. Nao funciona em produção.

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

Headers

Authorization: Bearer {seu_token}

Content-Type: application/json

Simula uma transação de cartão de crédito no ambiente sandbox.

Parâmetros de caminho

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

Nenhum corpo e necessário. Basta enviar a requisição POST para o endpoint com o ID da cobrança.

Códigos de resposta

Código	Descrição
`200`	Transação simulada com sucesso
`401`	Não autorizado — token inválido ou ausente
`404`	Cobrança nao encontrada

Disponível apenas no ambiente sandbox. Nao funciona em produção.

Zoov Payment API

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 #

Campos da resposta (201)

Headers de Resposta

Estorno Cartão #

Headers de Resposta

Devolução PIX #

Headers de Resposta

Cancelar Boleto #

Cancelar QR Code PIX #

Consultar Cobrança #

Campos da resposta (200)

Listar Cobranças #

Campos da resposta (200)

Faturamento

Criar Fatura #

Headers de Resposta

Campos da resposta

Enviar Fatura por E-mail #

Obter Fatura #

Campos da resposta (200)

Listar Faturas #

Recorrência & Assinaturas

Faturas Recorrentes #

Headers de Resposta

Resposta (após GET no recurso criado)

Assinaturas #

Headers de Resposta

Marketplace & Split

Exemplo com Split #

Headers de Resposta

Sellers e Receivers #

Headers de Resposta

Segurança

Fluxo 3DS #

Campos principais da requisição

Campos do cartão (objeto card)

Campos 3DS adicionais (objeto threeDSecure)

Headers de Resposta

Webhooks & Eventos

Como funciona #

Recebendo Webhooks #

Enviar evento por ID #

Parâmetros de caminho

Códigos de resposta

Campos do cartão (objeto `card`)

Campos 3DS adicionais (objeto `threeDSecure`)