API ZorinPay

Esta documentação descreve todas as rotas que utilizam API Key para integração externa. Use sua chave API no header Authorization: Bearer <sua_api_key> em cada requisição.

Base URL: https://api.zorinpay.com/v1

Autenticação com API Key

Como autenticar

Todas as rotas documentadas aqui exigem uma API Key válida. Crie e gerencie suas chaves em Dashboard → API Keys (após login).

Envie a API Key no header Authorization com o esquema Bearer:

Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxx

Chaves de teste têm prefixo sk_test_ e podem usar simulação de pagamentos. Chaves de produção usam sk_live_.

Escopos (Scopes)

Cada API Key possui um conjunto de escopos. A rota só é autorizada se a chave tiver o escopo necessário. Os escopos disponíveis são carregados do backend quando você está logado.

Não foi possível carregar os escopos. Verifique sua conexão ou tente novamente.

Idempotência

Para rotas de criação (POST) que suportam idempotência, envie o header Idempotency-Key ou X-Idempotency-Key com um valor único (ex.: UUID). Assim, requisições duplicadas retornam o mesmo resultado sem criar registros duplicados.

Rotas da API

Todas as rotas abaixo usam o prefixo base https://api.zorinpay.com/v1.

Health Check

Base: https://api.zorinpay.com/v1/health

GET/health

Verifica se a API está online. Não requer autenticação.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
status	string	Sim	Estado da API ("ok" quando online).
timestamp	string	Sim	Data/hora da verificação (ISO 8601).

Respostas

Status: 200 OK

{
  "status": "ok",
  "timestamp": "2025-01-15T10:00:00.000Z"
}

Clientes

Base: https://api.zorinpay.com/v1/customer

POST/customer/createcustomer.create

Cria um novo cliente.

Headers

Authorization: Bearer <sua_api_key>
Content-Type: application/json

Body (JSON)

{
  "name": "João Silva",
  "cellphone": "+5511999999999",
  "email": "[email protected]",
  "taxId": "12345678900",
  "address": null
}

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome completo do cliente.
cellphone	string	Sim	Telefone do cliente no formato E.164 (ex.: +5511999999999).
email	string	Sim	E-mail do cliente.
taxId	string	Sim	CPF ou CNPJ do cliente (somente dígitos).
address	object \| null	Não	Endereço do cliente (opcional).

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador do cliente gerado pela Zorinpay.
metadata	object	Sim	Dados cadastrais do cliente.
metadata.name	string	Sim	Nome completo do cliente.
metadata.cellphone	string	Sim	Telefone do cliente no formato E.164.
metadata.email	string	Sim	E-mail do cliente.
metadata.taxId	string	Sim	CPF ou CNPJ do cliente.

Respostas

Status: 201 Created

{
  "data": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "metadata": {
      "name": "João Silva",
      "cellphone": "+5511999999999",
      "email": "[email protected]",
      "taxId": "12345678900"
    }
  },
  "error": null
}

Status: 400 Bad Request

{
  "statusCode": 400,
  "message": ["Nome é obrigatório", "Email deve ser um endereço de email válido"],
  "error": "Bad Request"
}

GET/customer/listcustomer.list

Lista clientes com paginação.

Query: page?, limit?

Headers

Authorization: Bearer <sua_api_key>

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
page	number	Não	Número da página (começa em 1).
limit	number	Não	Quantidade de itens por página.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
customers[].id	string	Sim	Identificador do cliente.
customers[].metadata.name	string	Sim	Nome completo do cliente.
customers[].metadata.cellphone	string	Sim	Telefone do cliente no formato E.164.
customers[].metadata.email	string	Sim	E-mail do cliente.
customers[].metadata.taxId	string	Sim	CPF ou CNPJ do cliente.
customers[].createdAt	string	Sim	Data/hora de criação do cliente (ISO 8601).
total	number	Sim	Total de clientes encontrados.
limit	number	Sim	Itens por página aplicado.
page	number	Sim	Página atual.

Respostas

Status: 200 OK

{
  "data": {
    "customers": [
      {
        "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "metadata": {
          "name": "João Silva",
          "cellphone": "+5511999999999",
          "email": "[email protected]",
          "taxId": "12345678900"
        },
        "createdAt": "2025-01-15T10:00:00.000Z"
      }
    ],
    "total": 1,
    "limit": 20,
    "page": 1
  },
  "error": null
}

PUT/customer/:idcustomer.update

Atualiza dados de um cliente.

Headers

Authorization: Bearer <sua_api_key>
Content-Type: application/json

Body (JSON)

{
  "name": "João da Silva Santos",
  "cellphone": "+5511988888888"
}

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ID do cliente a ser atualizado (parâmetro de URL).
name	string	Não	Novo nome completo do cliente.
cellphone	string	Não	Novo telefone do cliente no formato E.164.
email	string	Não	Novo e-mail do cliente.
taxId	string	Não	Novo CPF ou CNPJ do cliente (somente dígitos).
address	object \| null	Não	Novo endereço do cliente.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador do cliente.
metadata	object	Sim	Dados cadastrais atualizados do cliente.
metadata.name	string	Sim	Nome completo do cliente.
metadata.cellphone	string	Sim	Telefone do cliente no formato E.164.
metadata.email	string	Sim	E-mail do cliente.
metadata.taxId	string	Sim	CPF ou CNPJ do cliente.

Respostas

Status: 200 OK

{
  "data": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "metadata": {
      "name": "João da Silva Santos",
      "cellphone": "+5511988888888",
      "email": "[email protected]",
      "taxId": "12345678900"
    }
  },
  "error": null
}

Status: 404 Not Found

{
  "statusCode": 404,
  "message": "Cliente não encontrado",
  "error": "Not Found"
}

DELETE/customer/:idcustomer.delete

Remove um cliente.

Headers

Authorization: Bearer <sua_api_key>

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ID do cliente a ser removido (parâmetro de URL).

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
data	null	Sim	Em caso de sucesso, data é null (nenhum conteúdo retornado).

Respostas

Status: 200 OK

{
  "data": null,
  "error": null
}

Status: 404 Not Found

{
  "statusCode": 404,
  "message": "Cliente não encontrado",
  "error": "Not Found"
}

Cobranças

Base: https://api.zorinpay.com/v1/billings

POST/billings/one-timebilling.createIdempotency-Key

Cria cobrança avulsa (pagamento único).

Headers

Authorization: Bearer <sua_api_key>
Content-Type: application/json
Idempotency-Key: <uuid> (recomendado)

Body (JSON)

{
  "customer": {
    "name": "João Silva",
    "cellphone": "+5511999999999",
    "email": "[email protected]",
    "taxId": "12345678900"
  },
  "products": [
    {
      "name": "Plano Pro",
      "description": "Assinatura mensal",
      "quantity": 1,
      "price": 9990
    }
  ],
  "methods": ["PIX"],
  "returnUrl": "https://minhaapp.com/return",
  "completionUrl": "https://minhaapp.com/obrigado",
  "metadata": { "orderId": "pedido-123" },
  "externalId": "pedido-123"
}

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
customerId	string	Não	ID de um cliente já cadastrado, para reaproveitá-lo na cobrança. Alternativa ao objeto customer; se enviado, o objeto customer é ignorado.
customer	object	Não	Dados do pagador, usados para cadastrar um cliente novo. Alternativa ao customerId. Se o e-mail ou o CPF/CNPJ já pertencerem a um cliente seu, a requisição falha com 409 — nesse caso envie customerId. Omitindo os dois, a cobrança é criada sem cliente vinculado.
customer.name	string	Não	Nome completo do pagador. Obrigatório quando customer é enviado.
customer.cellphone	string	Não	Telefone do pagador no formato E.164 (ex.: +5511999999999). Obrigatório quando customer é enviado.
customer.email	string	Não	E-mail do pagador. Obrigatório quando customer é enviado.
customer.taxId	string	Não	CPF ou CNPJ do pagador (somente dígitos). Obrigatório quando customer é enviado.
products	object[]	Sim	Lista de produtos/itens da cobrança.
products[].name	string	Sim	Nome do produto.
products[].description	string	Não	Descrição do produto.
products[].quantity	number	Sim	Quantidade do produto.
products[].price	number	Sim	Preço unitário em centavos (ex.: 9990 = R$ 99,90).
methods	string[]	Sim	Métodos de pagamento aceitos (ex.: ["PIX"]).
returnUrl	string	Sim	URL de retorno após o pagamento.
completionUrl	string	Sim	URL de conclusão exibida ao final do fluxo.
metadata	object	Não	Objeto livre de dados adicionais, devolvido nos webhooks e na consulta.
externalId	string	Não	Identificador único da cobrança no seu sistema.
allowCoupons	boolean	Não	Permite aplicar cupons de desconto nesta cobrança.
coupons	string[]	Não	Lista de códigos de cupom aplicáveis.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador da cobrança gerado pela Zorinpay.
frequency	enum	Sim	Frequência da cobrança (ONE_TIME para avulsa).
recurrenceIntervalDays	number \| null	Não	Intervalo em dias da recorrência (null para avulsa).
url	string	Sim	URL da página de pagamento da cobrança.
status	enum	Sim	Status atual da cobrança: PENDING, PAID, FAILED, REFUNDED ou CANCELLED.
billingOrigin	enum	Sim	Origem do registro: CHARGE (cobrança) ou PIX_QR_CODE.
devMode	boolean	Sim	Indica se a cobrança foi criada em modo de testes (sandbox).
methods	string[]	Sim	Métodos de pagamento aceitos.
amount	number	Sim	Valor total da cobrança em centavos.
feeAmount	number	Sim	Taxa aplicada em centavos.
netAmount	number	Sim	Valor líquido a receber em centavos.
currency	string	Sim	Moeda da cobrança (ex.: BRL).
products[].id	string	Sim	Identificador do produto.
products[].name	string	Sim	Nome do produto.
products[].description	string	Não	Descrição do produto.
products[].quantity	number	Sim	Quantidade do produto.
products[].price	number	Sim	Preço unitário em centavos.
customer.id	string	Sim	Identificador do pagador.
customer.name	string	Sim	Nome do pagador.
customer.email	string	Sim	E-mail do pagador.
customer.document	string	Sim	Documento do pagador (CPF/CNPJ).
customer.documentType	enum	Sim	Tipo do documento (CPF ou CNPJ).
customer.personType	enum	Sim	Tipo de pessoa (PF ou PJ).
metadata	object	Não	Metadados da cobrança, incluindo URLs e dados livres informados.
allowCoupons	boolean	Sim	Indica se a cobrança aceita cupons.
coupons	object[]	Sim	Cupons aplicados à cobrança.
qrCode	string \| null	Não	Código PIX copia e cola, quando disponível.
qrCodeBase64	string \| null	Não	Imagem do QR Code em base64, quando disponível.
paidAt	string \| null	Não	Data/hora do pagamento (ISO 8601), se paga.
createdAt	string	Sim	Data/hora de criação (ISO 8601).
updatedAt	string	Sim	Data/hora da última atualização (ISO 8601).

Respostas

Status: 201 Created

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "frequency": "ONE_TIME",
    "recurrenceIntervalDays": null,
    "url": "https://zorinpay.com/pay/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "PENDING",
    "billingOrigin": "CHARGE",
    "devMode": false,
    "methods": ["PIX"],
    "amount": 9990,
    "feeAmount": 0,
    "netAmount": 9990,
    "currency": "BRL",
    "products": [
      {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "Plano Pro",
        "description": "Assinatura mensal",
        "quantity": 1,
        "price": 9990
      }
    ],
    "customer": {
      "id": "b3c4d5e6-f7a8-9012-bcde-f34567890123",
      "name": "João Silva",
      "email": "[email protected]",
      "document": "12345678900",
      "documentType": "CPF",
      "personType": "PF"
    },
    "metadata": {
      "fee": 0,
      "returnUrl": "https://minhaapp.com/return",
      "completionUrl": "https://minhaapp.com/obrigado",
      "orderId": "pedido-123"
    },
    "allowCoupons": false,
    "coupons": [],
    "qrCode": null,
    "qrCodeBase64": null,
    "paidAt": null,
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z"
  },
  "error": null
}

Status: 400 Bad Request

{
  "statusCode": 400,
  "message": ["Produtos são obrigatórios", "URL de retorno é obrigatória"],
  "error": "Bad Request"
}

POST/billings/recurringbilling.createIdempotency-Key

Cria uma assinatura recorrente. IMPORTANTE: não é débito automático — a cada recurrenceIntervalDays uma NOVA cobrança com um novo QR Code PIX é gerada e enviada por e-mail ao pagador, que precisa pagar ativamente cada ciclo. Não há autorização/mandato (PIX Automático) nem tokenização de cartão. Cada renovação é uma cobrança nova, com id próprio, ligada à original por parentBillingId — use esse campo para distinguir a primeira cobrança (ausente) de uma renovação (preenchido). Deixar de pagar não encerra a assinatura: use POST /billings/:id/recurring/cancel. Cupons aplicam desconto em TODOS os ciclos, não apenas no primeiro.

Headers

Authorization: Bearer <sua_api_key>
Content-Type: application/json
Idempotency-Key: <uuid> (recomendado)

Body (JSON)

{
  "customer": {
    "name": "João Silva",
    "cellphone": "+5511999999999",
    "email": "[email protected]",
    "taxId": "12345678900"
  },
  "products": [
    {
      "name": "Plano Pro",
      "quantity": 1,
      "price": 9990
    }
  ],
  "recurrenceIntervalDays": 30,
  "methods": ["PIX"],
  "returnUrl": "https://minhaapp.com/return",
  "completionUrl": "https://minhaapp.com/obrigado"
}

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
customerId	string	Não	ID de um cliente já cadastrado, para reaproveitá-lo na cobrança. Alternativa ao objeto customer; se enviado, o objeto customer é ignorado.
customer	object	Não	Dados do pagador, usados para cadastrar um cliente novo. Alternativa ao customerId. Se o e-mail ou o CPF/CNPJ já pertencerem a um cliente seu, a requisição falha com 409 — nesse caso envie customerId. Omitindo os dois, a cobrança é criada sem cliente vinculado.
customer.name	string	Não	Nome completo do pagador. Obrigatório quando customer é enviado.
customer.cellphone	string	Não	Telefone do pagador no formato E.164 (ex.: +5511999999999). Obrigatório quando customer é enviado.
customer.email	string	Não	E-mail do pagador. Obrigatório quando customer é enviado.
customer.taxId	string	Não	CPF ou CNPJ do pagador (somente dígitos). Obrigatório quando customer é enviado.
products	object[]	Sim	Lista de produtos/itens da cobrança.
products[].name	string	Sim	Nome do produto.
products[].quantity	number	Sim	Quantidade do produto.
products[].price	number	Sim	Preço unitário em centavos (ex.: 9990 = R$ 99,90).
recurrenceIntervalDays	number	Sim	Intervalo em dias entre cada cobrança recorrente. Número inteiro, mínimo 1 (não aceita frações de dia).
methods	string[]	Sim	Métodos de pagamento aceitos. PIX é obrigatório; o enum é MAIÚSCULO (["pix"] retorna 400).
returnUrl	string	Sim	URL de retorno após o pagamento.
completionUrl	string	Sim	URL de conclusão exibida ao final do fluxo.
metadata	object	Não	Objeto livre de dados adicionais, devolvido nos webhooks e na consulta. Copiado para todas as renovações.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador da cobrança gerado pela Zorinpay. Cada renovação recebe um id novo.
frequency	enum	Sim	Frequência da cobrança (MULTIPLE_TIMES para recorrente).
recurrenceIntervalDays	number	Sim	Intervalo em dias entre cada cobrança.
parentBillingId	string	Não	Cobrança-raiz da série. Ausente na primeira cobrança e preenchido em toda renovação — é o discriminador entre 1ª cobrança e renovação, e a identidade da assinatura.
url	string	Sim	URL da página de pagamento da cobrança.
status	enum	Sim	Status atual da cobrança: PENDING, PAID, FAILED, REFUNDED ou CANCELLED.
billingOrigin	enum	Sim	Origem do registro: CHARGE (cobrança) ou PIX_QR_CODE.
devMode	boolean	Sim	Indica se a cobrança foi criada em modo de testes (sandbox).
methods	string[]	Sim	Métodos de pagamento aceitos.
amount	number	Sim	Valor total da cobrança em centavos.
feeAmount	number	Sim	Taxa aplicada em centavos.
netAmount	number	Sim	Valor líquido a receber em centavos.
currency	string	Sim	Moeda da cobrança (ex.: BRL).
products	object[]	Sim	Produtos da cobrança (mesma estrutura enviada na criação, com id).
nextBilling	string \| null	Não	Data/hora da próxima cobrança (ISO 8601), calculada como createdAt + recurrenceIntervalDays. null para cobranças avulsas e para assinaturas canceladas.
recurrenceCancelledAt	string \| null	Não	Data/hora do cancelamento da assinatura (ISO 8601). null enquanto ativa. Preenchido em todas as cobranças da série após o cancelamento.
allowCoupons	boolean	Sim	Indica se a cobrança aceita cupons.
coupons	object[]	Sim	Cupons aplicados à cobrança.
createdAt	string	Sim	Data/hora de criação (ISO 8601).
updatedAt	string	Sim	Data/hora da última atualização (ISO 8601).

Respostas

Status: 201 Created

{
  "data": {
    "id": "e5f6a7b8-c9d0-1234-ef56-789012345678",
    "frequency": "MULTIPLE_TIMES",
    "recurrenceIntervalDays": 30,
    "url": "https://zorinpay.com/pay/e5f6a7b8-c9d0-1234-ef56-789012345678",
    "status": "PENDING",
    "billingOrigin": "CHARGE",
    "devMode": false,
    "methods": ["PIX"],
    "amount": 9990,
    "feeAmount": 0,
    "netAmount": 9990,
    "currency": "BRL",
    "products": [],
    "nextBilling": "2025-02-14T10:00:00.000Z",
    "allowCoupons": false,
    "coupons": [],
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z"
  },
  "error": null
}

GET/billingsbilling.list

Lista cobranças com filtros. Por padrão retorna apenas registros de origem CHARGE — use origin=PIX_QR_CODE para listar PIX QR Codes. Paginação por offset/limit (limit padrão 50).

Query: customerId?, status?, origin? (padrão CHARGE), offset? (padrão 0), limit? (padrão 50)

Headers

Authorization: Bearer <sua_api_key>

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
customerId	string	Não	Filtra cobranças de um cliente específico.
status	enum	Não	Filtra por status: PENDING, PAID, FAILED, REFUNDED ou CANCELLED. Valor fora dessa lista retorna 400.
origin	enum	Não	Filtra pela origem: CHARGE (padrão) ou PIX_QR_CODE. Valor fora dessa lista retorna 400.
offset	number	Não	Deslocamento de paginação (padrão 0).
limit	number	Não	Quantidade de itens por página (padrão 50).

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
data[].id	string	Sim	Identificador da cobrança.
data[].frequency	enum	Sim	Frequência da cobrança (ONE_TIME ou MULTIPLE_TIMES).
data[].url	string	Sim	URL da página de pagamento.
data[].status	enum	Sim	Status atual da cobrança: PENDING, PAID, FAILED, REFUNDED ou CANCELLED.
data[].billingOrigin	enum	Sim	Origem do registro: CHARGE (cobrança) ou PIX_QR_CODE.
data[].devMode	boolean	Sim	Indica se a cobrança é de modo de testes.
data[].methods	string[]	Sim	Métodos de pagamento aceitos.
data[].amount	number	Sim	Valor total em centavos.
data[].feeAmount	number	Sim	Taxa aplicada em centavos.
data[].netAmount	number	Sim	Valor líquido em centavos.
data[].currency	string	Sim	Moeda da cobrança (ex.: BRL).
data[].products	object[]	Sim	Produtos/itens da cobrança.
data[].customer	object	Sim	Dados do pagador.
data[].metadata	object	Não	Metadados da cobrança.
data[].nextBilling	string \| null	Não	Próxima cobrança (ISO 8601), para recorrentes.
data[].allowCoupons	boolean	Sim	Indica se aceita cupons.
data[].coupons	object[]	Sim	Cupons aplicados.
data[].paidAt	string \| null	Não	Data/hora do pagamento (ISO 8601), se paga.
data[].createdAt	string	Sim	Data/hora de criação (ISO 8601).
data[].updatedAt	string	Sim	Data/hora da última atualização (ISO 8601).
total	number	Sim	Total de cobranças encontradas.
limit	number	Sim	Itens por página aplicado.
offset	number	Sim	Deslocamento de paginação aplicado.

Respostas

Status: 200 OK

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "frequency": "ONE_TIME",
      "url": "https://zorinpay.com/pay/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "PAID",
      "billingOrigin": "CHARGE",
      "devMode": false,
      "methods": ["PIX"],
      "amount": 9990,
      "feeAmount": 199,
      "netAmount": 9791,
      "currency": "BRL",
      "products": [],
      "customer": {  },
      "metadata": {  },
      "nextBilling": null,
      "allowCoupons": false,
      "coupons": [],
      "paidAt": "2025-01-15T10:05:00.000Z",
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-01-15T10:05:00.000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0,
  "error": null
}

Status: 400 Bad Request

{
  "statusCode": 400,
  "message": "Status inválido: \"EXPIRED\". Valores aceitos: PENDING, PAID, FAILED, REFUNDED, CANCELLED",
  "error": "Bad Request"
}

GET/billings/search/metadatabilling.search

Busca cobranças por chave/valor em metadata. Paginação por offset/limit (limit padrão 50).

Query: key, value, offset? (padrão 0), limit? (padrão 50)

Headers

Authorization: Bearer <sua_api_key>

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
key	string	Sim	Chave a buscar dentro do metadata da cobrança (ex.: orderId).
value	string	Sim	Valor correspondente à chave informada.
offset	number	Não	Deslocamento de paginação (padrão 0).
limit	number	Não	Quantidade de itens por página (padrão 50).

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
data[]	object	Sim	Cobrança encontrada (mesma estrutura do item de GET /billings).
total	number	Sim	Total de cobranças encontradas.
limit	number	Sim	Itens por página aplicado.
offset	number	Sim	Deslocamento de paginação aplicado.

Respostas

Status: 200 OK

{
  "data": [],
  "total": 5,
  "limit": 50,
  "offset": 0,
  "error": null
}

GET/billings/:idbilling.read

Retorna uma cobrança pelo ID.

Headers

Authorization: Bearer <sua_api_key>

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ID da cobrança (parâmetro de URL).

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador da cobrança.
frequency	enum	Sim	Frequência da cobrança (ONE_TIME ou MULTIPLE_TIMES).
url	string	Sim	URL da página de pagamento.
status	enum	Sim	Status atual da cobrança: PENDING, PAID, FAILED, REFUNDED ou CANCELLED.
billingOrigin	enum	Sim	Origem do registro: CHARGE (cobrança) ou PIX_QR_CODE.
devMode	boolean	Sim	Indica se a cobrança é de modo de testes.
methods	string[]	Sim	Métodos de pagamento aceitos.
amount	number	Sim	Valor total em centavos.
feeAmount	number	Sim	Taxa aplicada em centavos.
netAmount	number	Sim	Valor líquido em centavos.
currency	string	Sim	Moeda da cobrança (ex.: BRL).
products	object[]	Sim	Produtos/itens da cobrança.
customer	object	Sim	Dados do pagador.
metadata	object	Não	Metadados da cobrança.
qrCode	string \| null	Não	Código PIX copia e cola, quando disponível.
qrCodeBase64	string \| null	Não	Imagem do QR Code em base64, quando disponível.
e2eId	string \| null	Não	Identificador end-to-end da transação PIX, quando paga.
clientName	string \| null	Não	Nome do pagador (capturado via adquirente), quando pago.
clientDocument	string \| null	Não	Documento (CPF/CNPJ) do pagador, quando pago.
paidAt	string \| null	Não	Data/hora do pagamento (ISO 8601), se paga.
createdAt	string	Sim	Data/hora de criação (ISO 8601).
updatedAt	string	Sim	Data/hora da última atualização (ISO 8601).

Respostas

Status: 200 OK

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "frequency": "ONE_TIME",
    "url": "https://zorinpay.com/pay/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "PAID",
    "billingOrigin": "CHARGE",
    "devMode": false,
    "methods": ["PIX"],
    "amount": 9990,
    "feeAmount": 199,
    "netAmount": 9791,
    "currency": "BRL",
    "products": [],
    "customer": {  },
    "metadata": {  },
    "qrCode": "00020126...",
    "qrCodeBase64": "data:image/png;base64,...",
    "e2eId": "E12345678202401151005TESTPIXBR01",
    "clientName": "João Silva",
    "clientDocument": "12345678900",
    "paidAt": "2025-01-15T10:05:00.000Z",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:05:00.000Z"
  },
  "error": null
}

Status: 404 Not Found

{
  "statusCode": 404,
  "message": "Cobrança não encontrada",
  "error": "Not Found"
}

POST/billings/:id/refundbilling.refund

Reembolsa uma cobrança paga (disponível apenas para cobranças elegíveis a reembolso PIX). O valor bruto é debitado da carteira do cliente e devolvido ao pagador via PIX. A taxa de processamento NÃO é restituída — o cliente assume esse custo. Dispara o webhook billing.refunded (ou pixqrcode.refunded para PIX QR Code).

Headers

Authorization: Bearer <sua_api_key>
Content-Type: application/json

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ID da cobrança a ser reembolsada (parâmetro de URL).
reason	string	Não	Motivo do reembolso (opcional), para registro.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
billingId	string	Sim	Identificador da cobrança reembolsada.
status	enum	Sim	Novo status da cobrança (REFUNDED).
refundId	string	Sim	Identificador do reembolso PIX (endToEndId).
refundedAt	string	Sim	Data/hora do reembolso (ISO 8601).
amountRefunded	number	Sim	Valor reembolsado em centavos.

Respostas

Status: 200 OK

{
  "billingId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "REFUNDED",
  "refundId": "E18236120202610061226...",
  "refundedAt": "2026-05-13T17:25:31.000Z",
  "amountRefunded": 9990
}

Status: 400 Bad Request

{
  "statusCode": 400,
  "message": "Apenas cobranças pagas podem ser reembolsadas (status atual: PENDING)",
  "error": "Bad Request"
}

Status: 403 Forbidden

{
  "statusCode": 403,
  "message": "Você não tem permissão para reembolsar esta cobrança",
  "error": "Forbidden"
}

Status: 404 Not Found

{
  "statusCode": 404,
  "message": "Cobrança não encontrada",
  "error": "Not Found"
}

POST/billings/:id/recurring/cancelbilling.cancel

Cancela uma assinatura recorrente. Aceita o id de QUALQUER cobrança da série — o ciclo atual serve, não é preciso guardar o id da cobrança original. Interrompe os ciclos futuros e cancela a fatura em aberto, disparando billing.cancelled com motivo recurrence_cancelled. Não reembolsa o que já foi pago (use POST /billings/:id/refund). Necessário porque deixar de pagar NÃO encerra a assinatura: o processo de recorrência cancela a fatura vencida e emite a próxima indefinidamente.

Headers

Authorization: Bearer <sua_api_key>

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ID de qualquer cobrança da série recorrente (parâmetro de URL).

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
rootBillingId	string	Sim	Cobrança-raiz da série: a identidade da assinatura cancelada.
cancelledAt	string	Sim	Data/hora do cancelamento (ISO 8601).
cancelledPendingBillingId	string \| null	Sim	Fatura em aberto que foi cancelada junto. null se não havia nenhuma.

Respostas

Status: 200 OK

{
  "rootBillingId": "3f8c2b1a-4d5e-4f60-9a2b-7c1d8e5f0a34",
  "cancelledAt": "2026-08-07T10:30:00.000Z",
  "cancelledPendingBillingId": "8b1e77c9-a04e-4f2e-b3a0-5c8916f2ad3e"
}

Status: 400 Bad Request

{
  "statusCode": 400,
  "message": "Esta assinatura já está cancelada",
  "error": "Bad Request"
}

Status: 403 Forbidden

{
  "statusCode": 403,
  "message": "Você não tem permissão para cancelar esta assinatura",
  "error": "Forbidden"
}

Status: 404 Not Found

{
  "statusCode": 404,
  "message": "Cobrança não encontrada",
  "error": "Not Found"
}

POST/billings/:id/recurring/advancebilling.create

Força a renovação de uma assinatura de teste sem esperar o recurrenceIntervalDays correr. Executa o mesmo caminho do processo horário de recorrência: encerra a fatura em aberto, dispara billing.cancelled e gera o próximo ciclo com um novo QR Code — dá para percorrer vários ciclos em minutos e validar os webhooks na ordem real. Restrito a cobranças criadas com chave sk_test_ (devMode); em produção retorna 400, já que cancelaria uma fatura legítima antes da hora. Existe porque o devMode troca o provedor de PIX por um sandbox, mas não o relógio.

Headers

Authorization: Bearer <sua_api_key_de_teste>

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ID da fatura em aberto da série recorrente (parâmetro de URL).

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
cancelledBillingId	string	Sim	Fatura encerrada por este avanço.
nextBillingId	string \| null	Sim	Nova fatura gerada. null quando a série não pôde continuar — nesse caso um billing.recurring_failed é disparado com o motivo.

Respostas

Status: 200 OK

{
  "cancelledBillingId": "3f8c2b1a-4d5e-4f60-9a2b-7c1d8e5f0a34",
  "nextBillingId": "9d2f4a10-6b3c-4e81-8f52-1a7c9e0b3d64"
}

Status: 400 Bad Request

{
  "statusCode": 400,
  "message": "Avanço manual só é permitido em cobranças de teste (devMode). Use uma chave de API sk_test_ para criar a assinatura.",
  "error": "Bad Request"
}

Status: 404 Not Found

{
  "statusCode": 404,
  "message": "Cobrança não encontrada",
  "error": "Not Found"
}

POST/billings/one-time-splitbilling.createIdempotency-Key

Cria cobrança avulsa (pagamento único) com split de pagamento entre múltiplos recebedores.

Headers

Authorization: Bearer <sua_api_key>
Content-Type: application/json
Idempotency-Key: <uuid> (recomendado)

Body (JSON)

{
  "customer": {
    "name": "João Silva",
    "cellphone": "+5511999999999",
    "email": "[email protected]",
    "taxId": "12345678900"
  },
  "products": [
    {
      "name": "Plano Pro",
      "description": "Assinatura mensal",
      "quantity": 1,
      "price": 9990
    }
  ],
  "splits": [
    {
      "recipientEmail": "[email protected]",
      "type": "percentage",
      "value": 30
    }
  ],
  "methods": ["PIX"],
  "returnUrl": "https://minhaapp.com/return",
  "completionUrl": "https://minhaapp.com/obrigado",
  "metadata": { "orderId": "pedido-123" }
}

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
customerId	string	Não	ID de um cliente já cadastrado, para reaproveitá-lo na cobrança. Alternativa ao objeto customer; se enviado, o objeto customer é ignorado.
customer	object	Não	Dados do pagador, usados para cadastrar um cliente novo. Alternativa ao customerId. Se o e-mail ou o CPF/CNPJ já pertencerem a um cliente seu, a requisição falha com 409 — nesse caso envie customerId. Omitindo os dois, a cobrança é criada sem cliente vinculado.
customer.name	string	Não	Nome completo do pagador. Obrigatório quando customer é enviado.
customer.cellphone	string	Não	Telefone do pagador no formato E.164 (ex.: +5511999999999). Obrigatório quando customer é enviado.
customer.email	string	Não	E-mail do pagador. Obrigatório quando customer é enviado.
customer.taxId	string	Não	CPF ou CNPJ do pagador (somente dígitos). Obrigatório quando customer é enviado.
products	object[]	Sim	Lista de produtos/itens da cobrança.
products[].name	string	Sim	Nome do produto.
products[].description	string	Não	Descrição do produto.
products[].quantity	number	Sim	Quantidade do produto.
products[].price	number	Sim	Preço unitário em centavos (ex.: 9990 = R$ 99,90).
splits	object[]	Sim	Regras de divisão do pagamento entre recebedores.
splits[].recipientEmail	string	Sim	E-mail do recebedor do split (deve ser uma conta Zorinpay).
splits[].type	enum	Sim	Tipo do split: "percentage" (percentual) ou "fixed" (valor fixo).
splits[].value	number	Sim	Valor do split: percentual (ex.: 30) ou valor fixo em centavos.
methods	string[]	Sim	Métodos de pagamento aceitos (ex.: ["PIX"]).
returnUrl	string	Sim	URL de retorno após o pagamento.
completionUrl	string	Sim	URL de conclusão exibida ao final do fluxo.
metadata	object	Não	Objeto livre de dados adicionais, devolvido nos webhooks e na consulta.
externalId	string	Não	Identificador único da cobrança no seu sistema.
allowCoupons	boolean	Não	Permite aplicar cupons de desconto nesta cobrança.
coupons	string[]	Não	Lista de códigos de cupom aplicáveis.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador da cobrança gerado pela Zorinpay.
frequency	enum	Sim	Frequência da cobrança (ONE_TIME para avulsa).
recurrenceIntervalDays	number \| null	Não	Intervalo em dias da recorrência (null para avulsa).
url	string	Sim	URL da página de pagamento da cobrança.
status	enum	Sim	Status atual da cobrança: PENDING, PAID, FAILED, REFUNDED ou CANCELLED.
billingOrigin	enum	Sim	Origem do registro: CHARGE (cobrança) ou PIX_QR_CODE.
devMode	boolean	Sim	Indica se a cobrança é de modo de testes.
methods	string[]	Sim	Métodos de pagamento aceitos.
amount	number	Sim	Valor total em centavos.
feeAmount	number	Sim	Taxa aplicada em centavos.
netAmount	number	Sim	Valor líquido em centavos.
currency	string	Sim	Moeda da cobrança (ex.: BRL).
products	object[]	Sim	Produtos da cobrança (com id).
customer	object	Sim	Dados do pagador.
metadata	object	Não	Metadados da cobrança.
allowCoupons	boolean	Sim	Indica se a cobrança aceita cupons.
coupons	object[]	Sim	Cupons aplicados à cobrança.
qrCode	string \| null	Não	Código PIX copia e cola, quando disponível.
qrCodeBase64	string \| null	Não	Imagem do QR Code em base64, quando disponível.
paidAt	string \| null	Não	Data/hora do pagamento (ISO 8601), se paga.
createdAt	string	Sim	Data/hora de criação (ISO 8601).
updatedAt	string	Sim	Data/hora da última atualização (ISO 8601).

Respostas

Status: 201 Created

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "frequency": "ONE_TIME",
    "recurrenceIntervalDays": null,
    "url": "https://zorinpay.com/pay/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "PENDING",
    "billingOrigin": "CHARGE",
    "devMode": false,
    "methods": ["PIX"],
    "amount": 9990,
    "feeAmount": 0,
    "netAmount": 9990,
    "currency": "BRL",
    "products": [
      {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "Plano Pro",
        "description": "Assinatura mensal",
        "quantity": 1,
        "price": 9990
      }
    ],
    "customer": {
      "id": "b3c4d5e6-f7a8-9012-bcde-f34567890123",
      "name": "João Silva",
      "email": "[email protected]",
      "document": "12345678900",
      "documentType": "CPF",
      "personType": "PF"
    },
    "metadata": { "orderId": "pedido-123" },
    "allowCoupons": false,
    "coupons": [],
    "qrCode": "00020126...",
    "qrCodeBase64": "data:image/png;base64,...",
    "paidAt": null,
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z"
  },
  "error": null
}

Status: 400 Bad Request

{
  "statusCode": 400,
  "message": "Não é possível incluir a si mesmo como recebedor do split.",
  "error": "Bad Request"
}

POST/billings/recurring-splitbilling.createIdempotency-Key

Cria cobrança recorrente com split de pagamento entre múltiplos recebedores.

Headers

Authorization: Bearer <sua_api_key>
Content-Type: application/json
Idempotency-Key: <uuid> (recomendado)

Body (JSON)

{
  "customer": {
    "name": "João Silva",
    "cellphone": "+5511999999999",
    "email": "[email protected]",
    "taxId": "12345678900"
  },
  "products": [
    {
      "name": "Plano Pro",
      "quantity": 1,
      "price": 9990
    }
  ],
  "splits": [
    {
      "recipientEmail": "[email protected]",
      "type": "percentage",
      "value": 30
    },
    {
      "recipientEmail": "[email protected]",
      "type": "fixed",
      "value": 500
    }
  ],
  "recurrenceIntervalDays": 30,
  "methods": ["PIX"],
  "returnUrl": "https://minhaapp.com/return",
  "completionUrl": "https://minhaapp.com/obrigado"
}

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
customerId	string	Não	ID de um cliente já cadastrado, para reaproveitá-lo na cobrança. Alternativa ao objeto customer; se enviado, o objeto customer é ignorado.
customer	object	Não	Dados do pagador, usados para cadastrar um cliente novo. Alternativa ao customerId. Se o e-mail ou o CPF/CNPJ já pertencerem a um cliente seu, a requisição falha com 409 — nesse caso envie customerId. Omitindo os dois, a cobrança é criada sem cliente vinculado.
customer.name	string	Não	Nome completo do pagador. Obrigatório quando customer é enviado.
customer.cellphone	string	Não	Telefone do pagador no formato E.164 (ex.: +5511999999999). Obrigatório quando customer é enviado.
customer.email	string	Não	E-mail do pagador. Obrigatório quando customer é enviado.
customer.taxId	string	Não	CPF ou CNPJ do pagador (somente dígitos). Obrigatório quando customer é enviado.
products	object[]	Sim	Lista de produtos/itens da cobrança.
products[].name	string	Sim	Nome do produto.
products[].quantity	number	Sim	Quantidade do produto.
products[].price	number	Sim	Preço unitário em centavos (ex.: 9990 = R$ 99,90).
splits	object[]	Sim	Regras de divisão do pagamento entre recebedores.
splits[].recipientEmail	string	Sim	E-mail do recebedor do split (deve ser uma conta Zorinpay).
splits[].type	enum	Sim	Tipo do split: "percentage" (percentual) ou "fixed" (valor fixo).
splits[].value	number	Sim	Valor do split: percentual (ex.: 30) ou valor fixo em centavos.
recurrenceIntervalDays	number	Sim	Intervalo em dias entre cada cobrança recorrente. Número inteiro, mínimo 1 (não aceita frações de dia).
methods	string[]	Sim	Métodos de pagamento aceitos. PIX é obrigatório; o enum é MAIÚSCULO (["pix"] retorna 400).
returnUrl	string	Sim	URL de retorno após o pagamento.
completionUrl	string	Sim	URL de conclusão exibida ao final do fluxo.
metadata	object	Não	Objeto livre de dados adicionais, devolvido nos webhooks e na consulta. Copiado para todas as renovações.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador da cobrança gerado pela Zorinpay. Cada renovação recebe um id novo.
frequency	enum	Sim	Frequência da cobrança (MULTIPLE_TIMES para recorrente).
recurrenceIntervalDays	number	Sim	Intervalo em dias entre cada cobrança.
parentBillingId	string	Não	Cobrança-raiz da série. Ausente na primeira cobrança e preenchido em toda renovação — é o discriminador entre 1ª cobrança e renovação, e a identidade da assinatura.
url	string	Sim	URL da página de pagamento da cobrança.
status	enum	Sim	Status atual da cobrança: PENDING, PAID, FAILED, REFUNDED ou CANCELLED.
billingOrigin	enum	Sim	Origem do registro: CHARGE (cobrança) ou PIX_QR_CODE.
devMode	boolean	Sim	Indica se a cobrança é de modo de testes.
methods	string[]	Sim	Métodos de pagamento aceitos.
amount	number	Sim	Valor total em centavos.
feeAmount	number	Sim	Taxa aplicada em centavos.
netAmount	number	Sim	Valor líquido em centavos.
currency	string	Sim	Moeda da cobrança (ex.: BRL).
products	object[]	Sim	Produtos da cobrança (com id).
allowCoupons	boolean	Sim	Indica se a cobrança aceita cupons.
coupons	object[]	Sim	Cupons aplicados à cobrança.
createdAt	string	Sim	Data/hora de criação (ISO 8601).
updatedAt	string	Sim	Data/hora da última atualização (ISO 8601).

Respostas

Status: 201 Created

{
  "data": {
    "id": "e5f6a7b8-c9d0-1234-ef56-789012345678",
    "frequency": "MULTIPLE_TIMES",
    "recurrenceIntervalDays": 30,
    "url": "https://zorinpay.com/pay/e5f6a7b8-c9d0-1234-ef56-789012345678",
    "status": "PENDING",
    "billingOrigin": "CHARGE",
    "devMode": false,
    "methods": ["PIX"],
    "amount": 9990,
    "feeAmount": 0,
    "netAmount": 9990,
    "currency": "BRL",
    "products": [],
    "allowCoupons": false,
    "coupons": [],
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z"
  },
  "error": null
}

Carteira

Base: https://api.zorinpay.com/v1/wallet

GET/walletwallet.read

Resumo da carteira (saldo, moeda).

Query: currency?

Headers

Authorization: Bearer <sua_api_key>

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
currency	string	Não	Moeda da carteira a consultar (ex.: BRL). Padrão: BRL.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
availableBalance	number	Sim	Saldo disponível em centavos.
lockedBalance	number	Sim	Saldo bloqueado/em liberação em centavos.
currency	string	Sim	Moeda da carteira (ex.: BRL).

Respostas

Status: 200 OK

{
  "data": {
    "availableBalance": 150000,
    "lockedBalance": 25000,
    "currency": "BRL"
  },
  "error": null
}

GET/wallet/balancewallet.read

Saldo detalhado por moeda.

Query: currency?

Headers

Authorization: Bearer <sua_api_key>

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
currency	string	Não	Moeda da carteira a consultar (ex.: BRL). Padrão: BRL.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
availableBalance	number	Sim	Saldo disponível em centavos.
lockedBalance	number	Sim	Saldo bloqueado/em liberação em centavos.
totalBalance	number	Sim	Saldo total (disponível + bloqueado) em centavos.
currency	string	Sim	Moeda da carteira (ex.: BRL).

Respostas

Status: 200 OK

{
  "data": {
    "availableBalance": 150000,
    "lockedBalance": 25000,
    "totalBalance": 175000,
    "currency": "BRL"
  },
  "error": null
}

GET/wallet/releaseswallet.read

Lista de liberações de saldo.

Query: currency?

Headers

Authorization: Bearer <sua_api_key>

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
currency	string	Não	Moeda da carteira a consultar (ex.: BRL). Padrão: BRL.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
releases[].amount	number	Sim	Valor a ser liberado em centavos.
releases[].releaseAt	string	Sim	Data/hora da liberação do saldo (ISO 8601).
releases[].billingId	string	Sim	Identificador da cobrança que originou a liberação.

Respostas

Status: 200 OK

{
  "data": {
    "releases": [
      {
        "amount": 10000,
        "releaseAt": "2025-01-16T10:00:00.000Z",
        "billingId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    ]
  },
  "error": null
}

GET/wallet/historywallet.read

Histórico de movimentações.

Query: page?, limit?

Headers

Authorization: Bearer <sua_api_key>

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
page	number	Não	Número da página (começa em 1).
limit	number	Não	Quantidade de itens por página.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
transactions[].id	string	Sim	Identificador da movimentação.
transactions[].type	enum	Sim	Tipo da movimentação (ex.: CREDIT, DEBIT).
transactions[].amount	number	Sim	Valor da movimentação em centavos.
transactions[].description	string	Sim	Descrição da movimentação.
transactions[].createdAt	string	Sim	Data/hora da movimentação (ISO 8601).
total	number	Sim	Total de movimentações encontradas.
limit	number	Sim	Itens por página aplicado.
page	number	Sim	Página atual.

Respostas

Status: 200 OK

{
  "data": {
    "transactions": [
      {
        "id": "c4d5e6f7-a8b9-0123-cdef-456789012345",
        "type": "CREDIT",
        "amount": 10000,
        "description": "Pagamento recebido",
        "createdAt": "2025-01-15T10:05:00.000Z"
      }
    ],
    "total": 1,
    "limit": 20,
    "page": 1
  },
  "error": null
}

GET/wallet/statementwallet.read

Extrato detalhado.

Query: page?, limit?

Headers

Authorization: Bearer <sua_api_key>

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
page	number	Não	Número da página (começa em 1).
limit	number	Não	Quantidade de itens por página.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
entries[].id	string	Sim	Identificador do lançamento.
entries[].type	enum	Sim	Tipo do lançamento (ex.: CREDIT, DEBIT).
entries[].amount	number	Sim	Valor do lançamento em centavos.
entries[].balanceAfter	number	Sim	Saldo resultante após o lançamento em centavos.
entries[].description	string	Sim	Descrição do lançamento.
entries[].createdAt	string	Sim	Data/hora do lançamento (ISO 8601).
total	number	Sim	Total de lançamentos encontrados.
limit	number	Sim	Itens por página aplicado.
page	number	Sim	Página atual.

Respostas

Status: 200 OK

{
  "data": {
    "entries": [
      {
        "id": "d5e6f7a8-b9c0-1234-def5-678901234567",
        "type": "CREDIT",
        "amount": 10000,
        "balanceAfter": 160000,
        "description": "Pagamento recebido",
        "createdAt": "2025-01-15T10:05:00.000Z"
      }
    ],
    "total": 1,
    "limit": 20,
    "page": 1
  },
  "error": null
}

Saques

Base: https://api.zorinpay.com/v1/withdrawals

POST/withdrawalswithdrawal.createIdempotency-Key

Cria um saque. Não permitido em devMode.

Headers

Authorization: Bearer <sua_api_key>
Content-Type: application/json
Idempotency-Key: <uuid> (recomendado)

Body (JSON)

{
  "amount": 50000,
  "pixKey": "[email protected]",
  "pixKeyType": "EMAIL",
  "externalId": "saque-001",
  "description": "Pagamento fornecedor"
}

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
amount	number	Sim	Valor do saque em centavos (ex.: 50000 = R$ 500,00).
pixKey	string	Sim	Chave PIX de destino do saque.
pixKeyType	enum	Sim	Tipo da chave PIX (ex.: EMAIL, CPF, CNPJ, PHONE, EVP).
externalId	string	Não	Identificador único do saque no seu sistema.
description	string	Não	Descrição do PIX enviada à instituição financeira, exibida no comprovante do destinatário (máx. 140 caracteres). Se omitido, é usada uma descrição padrão.
metadata	object	Não	Objeto livre de dados adicionais.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador do saque gerado pela Zorinpay.
amount	number	Sim	Valor do saque em centavos.
status	enum	Sim	Status do saque (ex.: PROCESSING, COMPLETED, FAILED).
pixKey	string	Sim	Chave PIX de destino do saque.
pixKeyType	enum	Sim	Tipo da chave PIX.
externalId	string \| null	Não	O externalId informado na criação, se houver.
description	string	Não	A descrição informada na criação, se houver.
createdAt	string	Sim	Data/hora de criação (ISO 8601).
updatedAt	string	Sim	Data/hora da última atualização (ISO 8601).

Respostas

Status: 201 Created

{
  "data": {
    "id": "7a8b9c0d-1e2f-3456-789a-bcdef0123456",
    "amount": 50000,
    "status": "PROCESSING",
    "pixKey": "[email protected]",
    "pixKeyType": "EMAIL",
    "externalId": "saque-001",
    "description": "Pagamento fornecedor",
    "createdAt": "2025-01-15T12:00:00.000Z",
    "updatedAt": "2025-01-15T12:00:00.000Z"
  },
  "error": null
}

Status: 400 Bad Request

{
  "statusCode": 400,
  "message": "Saques não são permitidos em modo de teste",
  "error": "Bad Request"
}

GET/withdrawalswithdrawal.list

Lista saques.

Query: page?, limit?

Headers

Authorization: Bearer <sua_api_key>

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
page	number	Não	Número da página (começa em 1).
limit	number	Não	Quantidade de itens por página.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
withdrawals[].id	string	Sim	Identificador do saque.
withdrawals[].amount	number	Sim	Valor do saque em centavos.
withdrawals[].status	enum	Sim	Status do saque (ex.: PROCESSING, COMPLETED, FAILED).
withdrawals[].pixKey	string	Sim	Chave PIX de destino do saque.
withdrawals[].pixKeyType	enum	Sim	Tipo da chave PIX.
withdrawals[].createdAt	string	Sim	Data/hora de criação (ISO 8601).
withdrawals[].updatedAt	string	Sim	Data/hora da última atualização (ISO 8601).
total	number	Sim	Total de saques encontrados.
limit	number	Sim	Itens por página aplicado.
page	number	Sim	Página atual.

Respostas

Status: 200 OK

{
  "data": {
    "withdrawals": [
      {
        "id": "7a8b9c0d-1e2f-3456-789a-bcdef0123456",
        "amount": 50000,
        "status": "COMPLETED",
        "pixKey": "[email protected]",
        "pixKeyType": "EMAIL",
        "createdAt": "2025-01-15T12:00:00.000Z",
        "updatedAt": "2025-01-15T12:01:00.000Z"
      }
    ],
    "total": 1,
    "limit": 20,
    "page": 1
  },
  "error": null
}

GET/withdrawals/:idwithdrawal.read

Consulta um saque pelo ID.

Headers

Authorization: Bearer <sua_api_key>

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ID do saque (parâmetro de URL).

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador do saque.
amount	number	Sim	Valor do saque em centavos.
status	enum	Sim	Status do saque (ex.: PROCESSING, COMPLETED, FAILED).
pixKey	string	Sim	Chave PIX de destino do saque.
pixKeyType	enum	Sim	Tipo da chave PIX.
externalId	string \| null	Não	O externalId informado na criação, se houver.
e2eId	string \| null	Não	Identificador end-to-end da transação PIX (presente quando concluído).
clientName	string \| null	Não	Nome de quem recebeu o valor.
clientDocument	string \| null	Não	Documento (CPF/CNPJ) de quem recebeu o valor.
metadata	object \| null	Não	Metadados informados na criação, se houver.
createdAt	string	Sim	Data/hora de criação (ISO 8601).
updatedAt	string	Sim	Data/hora da última atualização (ISO 8601).

Respostas

Status: 200 OK

{
  "data": {
    "id": "7a8b9c0d-1e2f-3456-789a-bcdef0123456",
    "amount": 50000,
    "status": "COMPLETED",
    "pixKey": "[email protected]",
    "pixKeyType": "EMAIL",
    "externalId": "saque-001",
    "e2eId": "E12345678202401151201TESTPIXBR01",
    "clientName": "João da Silva",
    "clientDocument": "12345678900",
    "metadata": null,
    "createdAt": "2025-01-15T12:00:00.000Z",
    "updatedAt": "2025-01-15T12:01:00.000Z"
  },
  "error": null
}

Status: 404 Not Found

{
  "statusCode": 404,
  "message": "Saque não encontrado",
  "error": "Not Found"
}

POST/withdrawals/qrcode/infowithdrawal.qrcode.info

Consulta um QR Code PIX (copia e cola) antes de pagar: devolve o tipo do código, o valor, o recebedor e se ele pode ser pago. Leitura pura — nada é reservado e nenhum saldo se move.

Headers

Authorization: Bearer <sua_api_key>
Content-Type: application/json

Body (JSON)

{
  "qrCode": "00020126580014br.gov.bcb.pix0136...6304ABCD"
}

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
qrCode	string	Sim	O código PIX Copia e Cola completo, de até 4096 caracteres.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
kind	enum	Sim	Tipo do código: STATIC, DYNAMIC, DYNAMIC_DUE_DATE ou UNKNOWN (a adquirente não informou o tipo). Informativo — o tipo não decide a pagabilidade.
amountCents	number \| null	Não	Valor em centavos, resolvido pela adquirente. null quando ela não devolveu valor, caso em que o código não é pagável.
receiverName	string \| null	Não	Nome do recebedor lido do código.
receiverCity	string \| null	Não	Cidade do recebedor.
receiverDocument	string \| null	Não	CPF/CNPJ do recebedor, quando o código o traz.
pixKey	string \| null	Não	Chave PIX que recebe o pagamento.
transactionId	string \| null	Não	Identificador da cobrança no recebedor (txid), quando houver.
expiresAt	string \| null	Não	Quando o código deixa de ser pagável (ISO 8601). null num código sem expiração.
url	string \| null	Não	Endereço onde a cobrança dinâmica é resolvida. null num código estático, que não a carrega.
currency	string \| null	Não	Moeda como a adquirente a devolve (ex.: 986 para o real).
countryCode	string \| null	Não	País do recebedor (ex.: BR).
merchantCategoryCode	string \| null	Não	Merchant Category Code do recebedor.
endToEndId	string \| null	Não	EndToEndId da cobrança, quando a adquirente já o resolve na consulta.
description	string \| null	Não	Descrição/mensagem que o recebedor colocou no código.
payable	boolean	Sim	Se este código pode ser pago em POST /withdrawals/qrcode: exige valor resolvido pela adquirente e código não expirado.
unpayableReason	string \| null	Não	Por que o código não é pagável. null quando payable é true.

Respostas

Status: 200 OK

{
  "kind": "STATIC",
  "amountCents": 15000,
  "receiverName": "FRANCISCO DA SILVA",
  "receiverCity": "RECIFE",
  "receiverDocument": null,
  "pixKey": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
  "transactionId": "3252890112011017889597792",
  "expiresAt": null,
  "url": null,
  "currency": "986",
  "countryCode": "BR",
  "merchantCategoryCode": "0000",
  "endToEndId": "E082535392025020714090799201365d",
  "description": null,
  "payable": true,
  "unpayableReason": null
}

Status: 200 OK (código não pagável)

{
  "kind": "DYNAMIC",
  "amountCents": null,
  "receiverName": "LOJA EXEMPLO LTDA",
  "receiverCity": "SAO PAULO",
  "receiverDocument": null,
  "pixKey": "[email protected]",
  "transactionId": "a1b2c3d4e5f6",
  "expiresAt": "2025-01-15T13:00:00.000Z",
  "url": "pix.exemplo.com.br/qr/v3/at/a1b2c3d4",
  "currency": "986",
  "countryCode": "BR",
  "merchantCategoryCode": "0000",
  "endToEndId": null,
  "description": null,
  "payable": false,
  "unpayableReason": "A adquirente não devolveu o valor deste QR Code. Só é possível pagar um código cujo valor venha resolvido pela adquirente."
}

Status: 400 Bad Request

{
  "statusCode": 400,
  "message": "O pagamento por QR Code PIX não está liberado para sua conta. Entre em contato com o suporte.",
  "error": "Bad Request"
}

POST/withdrawals/qrcodewithdrawal.qrcode.payIdempotency-Key

Paga um QR Code PIX (copia e cola), estático ou dinâmico. Quem lê o código e resolve o valor é a adquirente: o valor não pode ser informado na requisição. O fluxo é o do saque — o valor e a taxa ficam bloqueados no saldo até a adquirente confirmar ou recusar a liquidação. Antes de enviar, o valor é reconferido na adquirente e o pagamento é recusado se ele tiver mudado desde a reserva. Não permitido em devMode.

Headers

Authorization: Bearer <sua_api_key>
Content-Type: application/json
Idempotency-Key: <uuid> (recomendado)

Body (JSON)

{
  "qrCode": "00020126580014br.gov.bcb.pix0136...6304ABCD",
  "description": "Pagamento fornecedor"
}

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
qrCode	string	Sim	O código PIX Copia e Cola completo, de até 4096 caracteres. A adquirente precisa conseguir resolver um valor para ele — consulte antes em POST /withdrawals/qrcode/info.
description	string	Não	Descrição do PIX enviada à instituição financeira, exibida no comprovante do destinatário (máx. 140 caracteres).

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador do pagamento gerado pela Zorinpay. Use-o em GET /withdrawals/:id para acompanhar.
amount	number	Sim	Valor em centavos, lido do próprio QR Code.
status	enum	Sim	Status do pagamento (ex.: PENDING, PROCESSING, COMPLETED, FAILED).
pixKey	string	Sim	O código PIX Copia e Cola pago, como enviado.
pixKeyType	enum	Sim	Sempre COPYPASTE nesta rota.
clientName	string \| null	Não	Nome do recebedor lido do QR Code.
clientDocument	string \| null	Não	Documento do recebedor, quando o código o traz.
description	string	Não	A descrição informada na criação, se houver.
createdAt	string	Sim	Data/hora de criação (ISO 8601).
updatedAt	string	Sim	Data/hora da última atualização (ISO 8601).

Respostas

Status: 201 Created

{
  "data": {
    "id": "7a8b9c0d-1e2f-3456-789a-bcdef0123456",
    "amount": 15000,
    "status": "PENDING",
    "pixKey": "00020126580014br.gov.bcb.pix0136...6304ABCD",
    "pixKeyType": "COPYPASTE",
    "clientName": "FRANCISCO DA SILVA",
    "clientDocument": null,
    "description": "Pagamento fornecedor",
    "createdAt": "2025-01-15T12:00:00.000Z",
    "updatedAt": "2025-01-15T12:00:00.000Z"
  },
  "error": null
}

Status: 400 Bad Request (código dinâmico)

{
  "statusCode": 400,
  "message": "Este QR Code PIX está expirado e não pode mais ser pago.",
  "error": "Bad Request"
}

Status: 400 Bad Request (código sem valor)

{
  "statusCode": 400,
  "message": "A adquirente não devolveu o valor deste QR Code. Só é possível pagar um código cujo valor venha resolvido pela adquirente.",
  "error": "Bad Request"
}

Status: 400 Bad Request (recurso não liberado)

{
  "statusCode": 400,
  "message": "O pagamento por QR Code PIX não está liberado para sua conta. Entre em contato com o suporte.",
  "error": "Bad Request"
}

MED (infrações PIX)

Base: https://api.zorinpay.com/v1/meds

GET/medsmed.list

Lista infrações MED (Mecanismo Especial de Devolução) do titular da API Key, com paginação por offset/limit.

Query: limit? (padrão 50), offset? (padrão 0), status? (ex.: WAITING_PSP, DEFENDED)

Headers

Authorization: Bearer <sua_api_key>

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
limit	number	Não	Quantidade de itens por página (padrão 50).
offset	number	Não	Deslocamento de paginação (padrão 0).
status	string	Não	Filtra por status da infração (ex.: WAITING_PSP, DEFENDED).

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
data[].id	string	Sim	Identificador da infração MED.
data[].userId	string	Sim	Identificador do titular da conta.
data[].externalId	string \| null	Não	Identificador da infração no provedor PIX.
data[].transactionId	string \| null	Não	Identificador da transação relacionada.
data[].billingId	string \| null	Não	Identificador da cobrança relacionada.
data[].accountId	number \| null	Não	Identificador da conta no provedor.
data[].type	enum	Sim	Tipo da infração (ex.: FRAUD).
data[].reportedBy	string \| null	Não	Participante que reportou a infração.
data[].reportDetails	string \| null	Não	Detalhes do relato do pagador.
data[].status	enum	Sim	Status da infração (ex.: WAITING_PSP, DEFENDED, CLOSED).
data[].debitParticipant	string \| null	Não	Participante de débito.
data[].creditParticipant	string \| null	Não	Participante de crédito.
data[].analysisResult	string \| null	Não	Resultado da análise da infração.
data[].analysisDetails	string \| null	Não	Detalhes da análise da infração.
data[].payerName	string \| null	Não	Nome do pagador.
data[].payerDocument	string \| null	Não	Documento do pagador (mascarado).
data[].msgEndToEndId	string \| null	Não	endToEndId da transação PIX.
data[].fraudType	string \| null	Não	Tipo de fraude, quando aplicável.
data[].contactEmail	string \| null	Não	E-mail de contato relacionado à infração.
data[].contactPhone	string \| null	Não	Telefone de contato relacionado à infração.
data[].infractionAmount	number	Sim	Valor da infração em centavos.
data[].createdAt	string	Sim	Data/hora de criação (ISO 8601).
data[].updatedAt	string	Sim	Data/hora da última atualização (ISO 8601).
data[].defenses	object[]	Sim	Defesas enviadas para a infração.
meta.total	number	Sim	Total de infrações encontradas.
meta.page	number	Sim	Página atual.
meta.limit	number	Sim	Itens por página aplicado.
meta.totalPages	number	Sim	Total de páginas disponíveis.

Respostas

Status: 200 OK

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "userId": "user-uuid",
      "externalId": "ext-123",
      "transactionId": "tx-uuid",
      "billingId": "billing-uuid",
      "accountId": 987654,
      "type": "FRAUD",
      "reportedBy": "Participante XYZ",
      "reportDetails": "Relato do pagador",
      "status": "WAITING_PSP",
      "debitParticipant": null,
      "creditParticipant": null,
      "analysisResult": null,
      "analysisDetails": null,
      "payerName": "Maria Pagadora",
      "payerDocument": "***",
      "msgEndToEndId": "E123456782024...",
      "fraudType": null,
      "contactEmail": null,
      "contactPhone": null,
      "infractionAmount": 10050,
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-01-15T10:00:00.000Z",
      "defenses": []
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 50,
    "totalPages": 1
  }
}

GET/meds/:idmed.read

Retorna o detalhe de uma infração MED pelo ID (apenas se pertencer à sua conta).

Headers

Authorization: Bearer <sua_api_key>

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ID da infração MED (parâmetro de URL).

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador da infração MED.
userId	string	Sim	Identificador do titular da conta.
externalId	string \| null	Não	Identificador da infração no provedor PIX.
transactionId	string \| null	Não	Identificador da transação relacionada.
billingId	string \| null	Não	Identificador da cobrança relacionada.
accountId	number \| null	Não	Identificador da conta no provedor.
type	enum	Sim	Tipo da infração (ex.: FRAUD).
status	enum	Sim	Status da infração (ex.: WAITING_PSP, DEFENDED, CLOSED).
infractionAmount	number	Sim	Valor da infração em centavos.
createdAt	string	Sim	Data/hora de criação (ISO 8601).
updatedAt	string	Sim	Data/hora da última atualização (ISO 8601).
defenses	object[]	Sim	Defesas enviadas para a infração.

Respostas

Status: 200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "userId": "user-uuid",
  "externalId": "ext-123",
  "transactionId": "tx-uuid",
  "billingId": "billing-uuid",
  "accountId": 987654,
  "type": "FRAUD",
  "status": "WAITING_PSP",
  "infractionAmount": 10050,
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T10:00:00.000Z",
  "defenses": []
}

Status: 404 Not Found

{
  "statusCode": 404,
  "message": "Infração não encontrada",
  "error": "Not Found"
}

POST/meds/:id/defensemed.respond

Envia defesa à adquirente. Exige infração em status WAITING_PSP, sem defesa já enviada. O corpo usa URLs públicas em proofs (1 a 10), como no dashboard.

Headers

Authorization: Bearer <sua_api_key>
Content-Type: application/json

Body (JSON)

{
  "analise": "rejeitado",
  "justificativa": "O serviço foi entregue conforme combinado com o cliente.",
  "proofs": [
    "https://exemplo.com/comprovante-entrega.pdf"
  ]
}

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ID da infração MED a defender (parâmetro de URL).
analise	enum	Sim	Posição da defesa: "rejeitado" (contesta) ou "aceito" (aceita a infração).
justificativa	string	Sim	Texto da justificativa da defesa (mínimo 10 caracteres).
proofs	string[]	Sim	Lista de URLs públicas das provas (1 a 10).
proofs[]	string	Sim	URL pública de um documento de prova.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
infraction.id	string	Sim	Identificador da infração.
infraction.status	enum	Sim	Novo status da infração (ex.: DEFENDED).
infraction.infractionAmount	number	Sim	Valor da infração em centavos.
infraction.updatedAt	string	Sim	Data/hora da última atualização da infração (ISO 8601).
defense.id	string	Sim	Identificador da defesa criada.
defense.infractionId	string	Sim	Identificador da infração defendida.
defense.externalId	string \| null	Não	Identificador da defesa no provedor PIX.
defense.status	enum	Sim	Status da defesa (ex.: DEFENDED).
defense.defense	string	Sim	Texto da justificativa enviada.
defense.attachments	object[]	Sim	Anexos da defesa.
defense.attachments[].url	string	Sim	URL do anexo enviado.
defense.attachments[].fileName	string	Sim	Nome do anexo.
defense.attachments[].mimeType	string	Sim	Tipo do anexo (ex.: url).
defense.createdAt	string	Sim	Data/hora de criação da defesa (ISO 8601).
defense.updatedAt	string	Sim	Data/hora da última atualização da defesa (ISO 8601).

Respostas

Status: 201 Created

{
  "infraction": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "DEFENDED",
    "infractionAmount": 10050,
    "updatedAt": "2025-01-15T11:00:00.000Z"
  },
  "defense": {
    "id": "defense-uuid",
    "infractionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "externalId": "12345",
    "status": "DEFENDED",
    "defense": "O serviço foi entregue conforme combinado com o cliente.",
    "attachments": [
      { "url": "https://exemplo.com/comprovante-entrega.pdf", "fileName": "prova-1", "mimeType": "url" }
    ],
    "createdAt": "2025-01-15T11:00:00.000Z",
    "updatedAt": "2025-01-15T11:00:00.000Z"
  }
}

Status: 400 Bad Request

{
  "statusCode": 400,
  "message": "Não é possível responder infração com status \"CLOSED\". Apenas infrações com status WAITING_PSP podem ser respondidas.",
  "error": "Bad Request"
}

Status: 409 Conflict

{
  "statusCode": 409,
  "message": "Já existe uma defesa enviada para esta infração",
  "error": "Conflict"
}

PIX QR Code

Base: https://api.zorinpay.com/v1/pixQrCode

POST/pixQrCodepixqrcode.createIdempotency-Key

Gera um QR Code PIX para pagamento. No objeto customer, apenas name e taxId são obrigatórios; cellphone e email são opcionais.

Headers

Authorization: Bearer <sua_api_key>
Content-Type: application/json
Idempotency-Key: <uuid> (recomendado)

Body (JSON)

{
  "amount": 5000,
  "customer": {
    "name": "João Silva",
    "cellphone": "+5511999999999",
    "email": "[email protected]",
    "taxId": "12345678900"
  },
  "expiresIn": 3600,
  "description": "Pagamento de pedido",
  "externalId": "pix-001"
}

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
amount	number	Sim	Valor da cobrança em centavos (ex.: 5000 = R$ 50,00).
customer	object	Sim	Dados do pagador da cobrança.
customer.name	string	Sim	Nome completo do pagador.
customer.taxId	string	Sim	CPF ou CNPJ do pagador (somente dígitos).
customer.cellphone	string	Não	Telefone do pagador no formato E.164 (ex.: +5511999999999).
customer.email	string	Não	E-mail do pagador.
expiresIn	number	Não	Tempo de expiração do QR Code em segundos. Padrão: 3 dias.
description	string	Não	Descrição livre da cobrança, exibida no extrato.
externalId	string	Não	Identificador único da cobrança no seu sistema (idempotência por usuário).
metadata	object	Não	Objeto livre de dados adicionais, devolvido nos webhooks e na consulta.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador da cobrança (billingId) gerado pela Zorinpay.
amount	number	Sim	Valor da cobrança em centavos.
status	string	Sim	Status atual da cobrança (ex.: PENDING, PAID, EXPIRED).
devMode	boolean	Sim	Indica se a cobrança foi criada em modo de testes (sandbox).
copyPaste	string	Sim	Código PIX copia e cola (BR Code) para pagamento.
qrCodeBase64	string	Sim	Imagem do QR Code em base64 (data URI) para exibição.
platformFee	number	Sim	Taxa da plataforma em centavos aplicada nesta cobrança.
externalId	string \| null	Não	O externalId informado na criação, se houver.
metadata	object \| null	Não	O metadata informado na criação, se houver.
createdAt	string	Sim	Data/hora de criação (ISO 8601).
updatedAt	string	Sim	Data/hora da última atualização (ISO 8601).
expiresAt	string	Sim	Data/hora de expiração do QR Code (ISO 8601).

Respostas

Status: 201 Created

{
  "data": {
    "id": "8b9c0d1e-2f3a-4567-89ab-cdef01234567",
    "amount": 5000,
    "status": "PENDING",
    "devMode": false,
    "copyPaste": "00020126360014BR.GOV.BCB.PIX...",
    "qrCodeBase64": "data:image/png;base64,...",
    "platformFee": 49,
    "externalId": "pix-001",
    "metadata": null,
    "createdAt": "2025-01-15T11:00:00.000Z",
    "updatedAt": "2025-01-15T11:00:00.000Z",
    "expiresAt": "2025-01-15T12:00:00.000Z"
  },
  "error": null
}

Status: 400 Bad Request

{
  "statusCode": 400,
  "message": ["Valor é obrigatório", "Dados do cliente são obrigatórios"],
  "error": "Bad Request"
}

POST/pixQrCode-splitpixqrcode.createIdempotency-Key

Gera QR Code PIX com split de pagamento entre múltiplos recebedores. No objeto customer, apenas name e taxId são obrigatórios; cellphone e email são opcionais.

Headers

Authorization: Bearer <sua_api_key>
Content-Type: application/json
Idempotency-Key: <uuid> (recomendado)

Body (JSON)

{
  "amount": 15000,
  "splits": [
    {
      "recipientEmail": "[email protected]",
      "type": "percentage",
      "value": 40
    }
  ],
  "customer": {
    "name": "Maria Santos",
    "cellphone": "+5511988888888",
    "email": "[email protected]",
    "taxId": "98765432100"
  },
  "description": "Pagamento com split",
  "expiresIn": 3600,
  "metadata": { "ref": "abc-123" }
}

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
amount	number	Sim	Valor da cobrança em centavos (ex.: 15000 = R$ 150,00).
splits	object[]	Sim	Regras de divisão do pagamento entre recebedores.
splits[].recipientEmail	string	Sim	E-mail do recebedor do split (deve ser uma conta Zorinpay).
splits[].type	enum	Sim	Tipo do split: "percentage" (percentual) ou "fixed" (valor fixo).
splits[].value	number	Sim	Valor do split: percentual (ex.: 40) ou valor fixo em centavos.
customer	object	Sim	Dados do pagador da cobrança.
customer.name	string	Sim	Nome completo do pagador.
customer.taxId	string	Sim	CPF ou CNPJ do pagador (somente dígitos).
customer.cellphone	string	Não	Telefone do pagador no formato E.164 (ex.: +5511999999999).
customer.email	string	Não	E-mail do pagador.
description	string	Não	Descrição livre da cobrança, exibida no extrato.
externalId	string	Não	Identificador único da cobrança no seu sistema (idempotência por usuário).
metadata	object	Não	Objeto livre de dados adicionais, devolvido nos webhooks e na consulta.
expiresIn	number	Não	Tempo de expiração do QR Code em segundos. Padrão: 3 dias.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador da cobrança (billingId) gerado pela Zorinpay.
amount	number	Sim	Valor da cobrança em centavos.
status	string	Sim	Status atual da cobrança (ex.: PENDING, PAID, EXPIRED).
devMode	boolean	Sim	Indica se a cobrança foi criada em modo de testes (sandbox).
copyPaste	string	Sim	Código PIX copia e cola (BR Code) para pagamento.
qrCodeBase64	string	Sim	Imagem do QR Code em base64 (data URI) para exibição.
platformFee	number	Sim	Taxa da plataforma em centavos aplicada nesta cobrança.
externalId	string \| null	Não	O externalId informado na criação, se houver.
metadata	object \| null	Não	O metadata informado na criação, se houver.
createdAt	string	Sim	Data/hora de criação (ISO 8601).
updatedAt	string	Sim	Data/hora da última atualização (ISO 8601).
expiresAt	string	Sim	Data/hora de expiração do QR Code (ISO 8601).

Respostas

Status: 201 Created

{
  "data": {
    "id": "f1a2b3c4-d5e6-7890-abcd-123456789012",
    "amount": 15000,
    "status": "PENDING",
    "devMode": false,
    "copyPaste": "00020126...",
    "qrCodeBase64": "data:image/png;base64,...",
    "platformFee": 300,
    "externalId": null,
    "metadata": { "ref": "abc-123" },
    "createdAt": "2025-01-15T14:00:00.000Z",
    "updatedAt": "2025-01-15T14:00:00.000Z",
    "expiresAt": "2025-01-15T15:00:00.000Z"
  },
  "error": null
}

Status: 404 Not Found

{
  "statusCode": 404,
  "message": "Recebedor do split não encontrado: [email protected]",
  "error": "Not Found"
}

GET/pixQrCode/check/:idpixqrcode.check

Verifica status do pagamento PIX (billingId).

Headers

Authorization: Bearer <sua_api_key>

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ID da cobrança PIX (billingId) a consultar (parâmetro de URL).

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador da cobrança (billingId).
status	string	Sim	Status atual da cobrança (ex.: PENDING, PAID, EXPIRED).
amount	number	Sim	Valor da cobrança em centavos.
e2eId	string \| null	Não	Identificador end-to-end da transação PIX, quando paga.
clientName	string \| null	Não	Nome do pagador (capturado via adquirente), quando pago.
clientDocument	string \| null	Não	Documento (CPF/CNPJ) do pagador, quando pago.
paidAt	string \| null	Não	Data/hora do pagamento (ISO 8601), se paga.

Respostas

Status: 200 OK

{
  "data": {
    "id": "8b9c0d1e-2f3a-4567-89ab-cdef01234567",
    "status": "PAID",
    "amount": 5000,
    "e2eId": "E12345678202401151105TESTPIXBR01",
    "clientName": "João Silva",
    "clientDocument": "12345678900",
    "paidAt": "2025-01-15T11:05:00.000Z"
  },
  "error": null
}

POST/pixQrCode/:id/refundpixqrcode.refund

Reembolsa um PIX QR Code já pago (disponível apenas para cobranças elegíveis a reembolso PIX). O valor bruto é debitado da carteira do cliente e devolvido ao pagador via PIX. A taxa de processamento NÃO é restituída — o cliente assume esse custo. Dispara o webhook pixqrcode.refunded.

Headers

Authorization: Bearer <sua_api_key>
Content-Type: application/json

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	ID do PIX QR Code (billingId) a ser reembolsado (parâmetro de URL).
reason	string	Não	Motivo do reembolso (opcional), para registro.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
billingId	string	Sim	Identificador da cobrança reembolsada.
status	enum	Sim	Novo status da cobrança (REFUNDED).
refundId	string	Sim	Identificador do reembolso PIX (endToEndId).
refundedAt	string	Sim	Data/hora do reembolso (ISO 8601).
amountRefunded	number	Sim	Valor reembolsado em centavos.

Respostas

Status: 200 OK

{
  "billingId": "8b9c0d1e-2f3a-4567-89ab-cdef01234567",
  "status": "REFUNDED",
  "refundId": "E18236120202610061226...",
  "refundedAt": "2026-05-13T17:25:31.000Z",
  "amountRefunded": 5000
}

Status: 400 Bad Request

{
  "statusCode": 400,
  "message": "Este recurso não é um PIX QR Code. Use POST /v1/billings/:id/refund.",
  "error": "Bad Request"
}

Status: 403 Forbidden

{
  "statusCode": 403,
  "message": "Você não tem permissão para reembolsar esta cobrança",
  "error": "Forbidden"
}

Status: 404 Not Found

{
  "statusCode": 404,
  "message": "Cobrança não encontrada",
  "error": "Not Found"
}

Cupons

Base: https://api.zorinpay.com/v1/coupons

POST/couponscoupon.createIdempotency-Key

Cria um cupom de desconto.

Headers

Authorization: Bearer <sua_api_key>
Content-Type: application/json
Idempotency-Key: <uuid> (recomendado)

Body (JSON)

{
  "data": {
    "code": "PROMO10",
    "discountKind": "PERCENTAGE",
    "discount": 10,
    "notes": "Promo de lançamento",
    "maxRedeems": 100
  }
}

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
data	object	Sim	Objeto que envolve os dados do cupom.
data.code	string	Sim	Código do cupom; também é usado como identificador (id).
data.discountKind	enum	Sim	Tipo do desconto: PERCENTAGE (percentual) ou FIXED (valor fixo).
data.discount	number	Sim	Valor do desconto: percentual de 0 a 100 (PERCENTAGE) ou valor fixo em centavos (FIXED).
data.notes	string	Não	Observações livres sobre o cupom.
data.maxRedeems	number	Não	Número máximo de resgates. Padrão: -1 (ilimitado).
data.metadata	object	Não	Objeto livre de dados adicionais.

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador do cupom (igual ao code informado).
discountKind	enum	Sim	Tipo do desconto (PERCENTAGE ou FIXED).
discount	number	Sim	Valor do desconto (percentual ou valor fixo em centavos).
status	enum	Sim	Status do cupom (ex.: ACTIVE).
createdAt	string	Sim	Data/hora de criação (ISO 8601).
updatedAt	string	Sim	Data/hora da última atualização (ISO 8601).
notes	string \| null	Não	Observações do cupom, se houver.
maxRedeems	number	Sim	Número máximo de resgates (-1 = ilimitado).
redeemsCount	number	Sim	Quantidade de resgates já realizados.
devMode	boolean	Sim	Indica se o cupom é de modo de testes (sandbox).
metadata	object \| null	Não	Metadata informado na criação, se houver.

Respostas

Status: 201 Created

{
  "data": {
    "id": "PROMO10",
    "discountKind": "PERCENTAGE",
    "discount": 10,
    "status": "ACTIVE",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z",
    "notes": "Promo de lançamento",
    "maxRedeems": 100,
    "redeemsCount": 0,
    "devMode": false,
    "metadata": null
  },
  "error": null
}

GET/couponscoupon.list

Lista os cupons da conta, com paginação por limit/offset.

Query: limit? (padrão 50), offset? (padrão 0)

Headers

Authorization: Bearer <sua_api_key>

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
limit	number	Não	Quantidade de itens por página (padrão 50).
offset	number	Não	Deslocamento de paginação (padrão 0).

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
data[].id	string	Sim	Identificador do cupom (igual ao code).
data[].discountKind	enum	Sim	Tipo do desconto (PERCENTAGE ou FIXED).
data[].discount	number	Sim	Valor do desconto (percentual ou valor fixo em centavos).
data[].status	enum	Sim	Status do cupom (ex.: ACTIVE).
data[].createdAt	string	Sim	Data/hora de criação (ISO 8601).
data[].updatedAt	string	Sim	Data/hora da última atualização (ISO 8601).
data[].notes	string \| null	Não	Observações do cupom, se houver.
data[].maxRedeems	number	Sim	Número máximo de resgates (-1 = ilimitado).
data[].redeemsCount	number	Sim	Quantidade de resgates já realizados.
data[].devMode	boolean	Sim	Indica se o cupom é de modo de testes (sandbox).
data[].metadata	object \| null	Não	Metadata do cupom, se houver.

Respostas

Status: 200 OK

{
  "data": [
    {
      "id": "PROMO10",
      "discountKind": "PERCENTAGE",
      "discount": 10,
      "status": "ACTIVE",
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-01-15T10:00:00.000Z",
      "notes": "Promo de lançamento",
      "maxRedeems": 100,
      "redeemsCount": 5,
      "devMode": false,
      "metadata": null
    }
  ],
  "error": null
}

Taxas

Base: https://api.zorinpay.com/v1/fees

GET/feesfees.read

Retorna a configuração de taxas da conta. A alteração de taxas é restrita ao admin.

Headers

Authorization: Bearer <sua_api_key>

Campos da resposta (data)

Campo	Tipo	Obrigatório	Descrição
fees[].type	enum	Sim	Tipo da taxa (ex.: PIX_CASH_IN, PIX_CASH_OUT).
fees[].percentage	number	Sim	Percentual aplicado sobre o valor da transação (ex.: 1.99 = 1,99%).
fees[].fixed	number	Sim	Valor fixo cobrado por transação em centavos.

Respostas

Status: 200 OK

{
  "data": {
    "fees": [
      {
        "type": "PIX_CASH_IN",
        "percentage": 1.99,
        "fixed": 0
      },
      {
        "type": "PIX_CASH_OUT",
        "percentage": 0,
        "fixed": 200
      }
    ]
  },
  "error": null
}

Exemplo de requisição

Exemplo completo para POST /customer/create (criar cliente): requisição com headers, body e resposta da API.

Requisição

Método e URL: POST https://api.zorinpay.com/v1/customer/create

Headers obrigatórios:

Authorization: Bearer <sua_api_key>
Content-Type: application/json
Idempotency-Key: <uuid> (recomendado em criações)

Body (JSON):

{
  "name": "João Silva",
  "cellphone": "+5511999999999",
  "email": "[email protected]",
  "taxId": "12345678900"
}

curl -X POST https://api.zorinpay.com/v1/customer/create \
  -H "Authorization: Bearer sk_test_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"name":"João Silva","cellphone":"+5511999999999","email":"[email protected]","taxId":"12345678900"}'

Resposta (sucesso)

Status: 201 Created

{
  "data": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "metadata": {
      "name": "João Silva",
      "cellphone": "+5511999999999",
      "email": "[email protected]",
      "taxId": "12345678900"
    }
  },
  "error": null
}

Resposta (erro — ex.: API Key inválida)

Status: 401 Unauthorized

{
  "statusCode": 401,
  "message": "Chave API não existe",
  "error": "Unauthorized"
}

Webhooks

Webhooks permitem que sua aplicação receba notificações em tempo real quando eventos ocorrem na sua conta (cobrança paga, saque concluído, cliente criado, etc.). Configure a URL de destino no Dashboard e escolha os eventos que deseja receber.

Para testar a integração, crie um webhook no Dashboard apontando para a URL do seu backend e aguarde eventos reais ou utilize ferramentas de teste como curl para simular chamadas. Todas as notificações incluem o header X-Webhook-Signature com assinatura HMAC-SHA256 hex.

Eventos disponíveis

Você pode assinar os seguintes eventos por webhook. Cada evento é enviado como POST para a URL configurada.

Cobranças (billing)

billing.createdbilling.updatedbilling.paidbilling.failedbilling.refundedbilling.cancelledbilling.recurring_failed

PIX QR Code (pixqrcode)

pixqrcode.createdpixqrcode.updatedpixqrcode.deletedpixqrcode.paidpixqrcode.failedpixqrcode.refundedpixqrcode.cancelled

Saques (withdraw)

withdraw.createdwithdraw.updatedwithdraw.donewithdraw.failed

Clientes (customer)

customer.createdcustomer.updatedcustomer.deleted

API Key (apiKey)

apiKey.createdapiKey.updatedapiKey.deleted

Usuário (user)

user.createduser.updated

MED (infrações PIX)

med.createdmed.updated

Formato do payload

Todo webhook segue o mesmo envelope. O campo data contém uma única chave por recurso: billing, pixqrcode, transaction, customer, apiKey, user ou med (infrações MED / PIX).

Em eventos pixqrcode.*, o objeto em data.pixqrcode pode incluir campos adicionais quando existirem na cobrança, por exemplo externalId, copyPaste (código PIX copia e cola) e qrCodeBase64.

id — identificador único do evento (use para idempotência)
event — tipo do evento (ex.: billing.paid, pixqrcode.created)
data — objeto com os dados do recurso afetado
devMode — indica se o evento ocorreu em ambiente de teste
createdAt — data/hora do disparo (ISO 8601)

Nos eventos billing.paid, pixqrcode.paid e withdraw.done, o recurso em data inclui e2eId (identificador end-to-end do PIX) quando o provedor informa esse valor; caso contrário vem null. Nos eventos billing.paid e pixqrcode.paid, o objeto payer traz o nome e o documento do pagador informados pela adquirente (ou null em cada campo quando não disponíveis); isso é distinto do customer da cobrança, quando existir.

Exemplos de payload por evento

Abaixo estão exemplos do payload enviado para cada tipo de evento. Use o campo data conforme o recurso: billing, pixqrcode, transaction (saques), customer, apiKey, user ou med.

Boas práticas

Responda com status 2xx o mais rápido possível; processe tarefas pesadas em background.
Use o campo id do evento para evitar processar o mesmo webhook mais de uma vez (idempotência).
Verifique devMode se precisar tratar eventos de teste de forma diferente.
Configure retentativas no Dashboard conforme a necessidade da sua aplicação.

Verificação de assinatura

Toda notificação enviada pelo ZorinPay inclui o header X-Webhook-Signature contendo a assinatura HMAC-SHA256 (hex) do body da requisição. Você deve verificar essa assinatura no seu endpoint para garantir que a notificação é legítima e não foi alterada em trânsito.

Como funciona

Ao criar um webhook no Dashboard, você recebe um secret. Ele continua acessível depois, na tela de detalhe do webhook (Webhooks → selecione o webhook). Guarde-o com segurança no seu servidor (ex.: variável de ambiente) e nunca o exponha no front-end.
A cada notificação, o ZorinPay gera um HMAC-SHA256 do body JSON usando o seu secret como chave e envia o resultado hexadecimal no header X-Webhook-Signature.
No seu endpoint, recalcule o HMAC-SHA256 do body recebido usando o mesmo secret e compare com o valor do header. Se forem iguais, a requisição é autêntica.

Importante: Use comparação de tempo constante (timing-safe comparison) para evitar ataques de temporização. Nunca compare as strings diretamente com ===.

Exemplos de implementação

// Node.js (Express / Fastify / qualquer framework)
const crypto = require('crypto');

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;
// ex.: "a1B2c3D4e5F6g7H8i9J0..."

function verifyWebhookSignature(rawBody, signatureHeader) {
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(rawBody, 'utf8')
    .digest('hex');

  // Comparação timing-safe para evitar ataques de temporização
  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(signatureHeader, 'utf8');

  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

// Exemplo com Express (use express.raw para obter o body como Buffer)
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const rawBody = req.body.toString('utf8');

  if (!signature || !verifyWebhookSignature(rawBody, signature)) {
    return res.status(401).json({ error: 'Assinatura inválida' });
  }

  const payload = JSON.parse(rawBody);
  console.log('Evento recebido:', payload.event);
  // Processar o evento...

  res.status(200).json({ received: true });
});

Resumo dos headers

Header	Valor	Descrição
`Content-Type`	`application/json`	Formato do body
`X-Webhook-Signature`	`HMAC-SHA256 (hex)`	Assinatura do body usando o secret do webhook. Compare com o HMAC que você calcular localmente.

Respostas de erro

A API retorna JSON com statusCode, message e opcionalmente error.

401 Unauthorized — API Key ausente, inválida, revogada ou expirada.
403 Forbidden — API Key válida mas sem o escopo necessário para a rota.
400 Bad Request — Dados de entrada inválidos ou regra de negócio (ex.: saque em devMode).
404 Not Found — Recurso não encontrado ou não pertence à sua conta.

API ZorinPay

Autenticação com API Key

Escopos (Scopes)

Idempotência

Rotas da API

Exemplo de requisição

Requisição

Resposta (sucesso)

Resposta (erro — ex.: API Key inválida)

Webhooks

Eventos disponíveis

Formato do payload

Exemplos de payload por evento

billing.created— Cobrança criada.

billing.updated— Cobrança atualizada.

billing.paid— Cobrança paga. Em séries recorrentes, parentBillingId ausente = primeira cobrança, preenchido = renovação (e o valor é a identidade da assinatura). Não use externalId como heurística: ele é zerado nas renovações, mas é opcional na primeira cobrança.

billing.failed— Cobrança falhou. failureReason traz o motivo informado pelo adquirente e é null quando ele não informa nada.

billing.refunded— Cobrança estornada. Disparado após o adquirente (AssetFinance) aceitar o PUT /pix/{e2eid}/devolucao/{id}. O bloco "refund" identifica quem solicitou (cliente via API/dashboard ou admin), o motivo e o rtrId.

billing.cancelled— Cobrança cancelada.

pixqrcode.created— QR Code PIX criado.

pixqrcode.updated— QR Code PIX atualizado.

pixqrcode.deleted— QR Code PIX removido (apenas id em data).

pixqrcode.paid— Pagamento PIX recebido.

pixqrcode.failed— Pagamento PIX falhou.

pixqrcode.refunded— Pagamento PIX (QR Code) estornado. Mesmo formato do billing.refunded, mas no envelope pixqrcode. Inclui o bloco "refund" com rtrId, motivo, autor e data.

pixqrcode.cancelled— QR Code PIX cancelado.

withdraw.created— Saque criado (data.transaction).

withdraw.updated— Saque em processamento no provedor (data.transaction).

withdraw.done— Saque concluído (data.transaction).

withdraw.failed— Saque falhou (data.transaction). failureReason traz o motivo informado pelo adquirente e é null quando ele não informa nada.

customer.created— Cliente criado.

customer.updated— Cliente atualizado.

customer.deleted— Cliente removido (apenas id em data).

apiKey.created— API Key criada.

apiKey.updated— API Key atualizada.

apiKey.deleted— API Key removida (apenas id em data).

user.created— Usuário criado.

user.updated— Usuário atualizado.

med.created— Nova infração MED registrada (PIX).

med.updated— Infração MED atualizada (status, defesa ou análise).

Boas práticas

Verificação de assinatura

Respostas de erro