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.

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
}

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>

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"
}

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>

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"
}

Respostas

Status: 201 Created

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "frequency": "ONE_TIME",
    "recurrenceIntervalDays": null,
    "url": "https://pay.zorinpay.com/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "PENDING",
    "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 cobrança recorrente.

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"
}

Respostas

Status: 201 Created

{
  "data": {
    "id": "e5f6a7b8-c9d0-1234-ef56-789012345678",
    "frequency": "MULTIPLE_TIMES",
    "recurrenceIntervalDays": 30,
    "url": "https://pay.zorinpay.com/e5f6a7b8-c9d0-1234-ef56-789012345678",
    "status": "PENDING",
    "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.

Query: customerId?, page?, limit?

Headers

Authorization: Bearer <sua_api_key>

Respostas

Status: 200 OK

{
  "data": {
    "billings": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "status": "PAID",
        "amount": 9990,
        "frequency": "ONE_TIME",
        "methods": ["PIX"],
        "paidAt": "2025-01-15T10:05:00.000Z",
        "createdAt": "2025-01-15T10:00:00.000Z"
      }
    ],
    "total": 1,
    "limit": 20,
    "page": 1
  },
  "error": null
}

GET/billings/search/metadatabilling.search

Busca cobranças por chave/valor em metadata.

Query: key, value, page?, limit?

Headers

Authorization: Bearer <sua_api_key>

Respostas

Status: 200 OK

{
  "data": {
    "billings": [],
    "total": 5,
    "limit": 20,
    "page": 1
  },
  "error": null
}

GET/billings/:idbilling.read

Retorna uma cobrança pelo ID.

Headers

Authorization: Bearer <sua_api_key>

Respostas

Status: 200 OK

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "frequency": "ONE_TIME",
    "url": "https://pay.zorinpay.com/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "PAID",
    "devMode": false,
    "methods": ["PIX"],
    "amount": 9990,
    "feeAmount": 199,
    "netAmount": 9791,
    "currency": "BRL",
    "products": [],
    "customer": {  },
    "metadata": {  },
    "qrCode": "00020126...",
    "qrCodeBase64": "data:image/png;base64,...",
    "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"
}

Carteira

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

GET/walletwallet.read

Resumo da carteira (saldo, moeda).

Query: currency?

Headers

Authorization: Bearer <sua_api_key>

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>

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>

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>

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>

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"
}

Respostas

Status: 201 Created

{
  "data": {
    "id": "7a8b9c0d-1e2f-3456-789a-bcdef0123456",
    "amount": 50000,
    "status": "PROCESSING",
    "pixKey": "[email protected]",
    "pixKeyType": "EMAIL",
    "externalId": "saque-001",
    "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>

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>

Respostas

Status: 200 OK

{
  "data": {
    "id": "7a8b9c0d-1e2f-3456-789a-bcdef0123456",
    "amount": 50000,
    "status": "COMPLETED",
    "pixKey": "[email protected]",
    "pixKeyType": "EMAIL",
    "externalId": "saque-001",
    "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"
}

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>

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>

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"
  ]
}

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.

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"
}

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"
}

GET/pixQrCode/check/:idpixqrcode.check

Verifica status do pagamento PIX (billingId).

Headers

Authorization: Bearer <sua_api_key>

Respostas

Status: 200 OK

{
  "data": {
    "id": "8b9c0d1e-2f3a-4567-89ab-cdef01234567",
    "status": "PAID",
    "amount": 5000,
    "paidAt": "2025-01-15T11:05:00.000Z"
  },
  "error": null
}

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)

{
  "code": "PROMO10",
  "type": "PERCENTAGE",
  "value": 10,
  "maxUses": 100,
  "expiresAt": "2025-12-31T23:59:59.000Z"
}

Respostas

Status: 201 Created

{
  "data": {
    "id": "9c0d1e2f-3a4b-5678-9abc-def012345678",
    "code": "PROMO10",
    "type": "PERCENTAGE",
    "value": 10,
    "maxUses": 100,
    "usedCount": 0,
    "expiresAt": "2025-12-31T23:59:59.000Z",
    "createdAt": "2025-01-15T10:00:00.000Z"
  },
  "error": null
}

GET/couponscoupon.list

Lista cupons.

Query: page?, limit?

Headers

Authorization: Bearer <sua_api_key>

Respostas

Status: 200 OK

{
  "data": {
    "coupons": [
      {
        "id": "9c0d1e2f-3a4b-5678-9abc-def012345678",
        "code": "PROMO10",
        "type": "PERCENTAGE",
        "value": 10,
        "maxUses": 100,
        "usedCount": 5,
        "expiresAt": "2025-12-31T23:59:59.000Z"
      }
    ],
    "total": 1,
    "limit": 20,
    "page": 1
  },
  "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>

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
}

Split de Cobranças

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

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" }
}

Respostas

Status: 201 Created

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "frequency": "ONE_TIME",
    "recurrenceIntervalDays": null,
    "url": "https://pay.zorinpay.com/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "PENDING",
    "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"
}

Respostas

Status: 201 Created

{
  "data": {
    "id": "e5f6a7b8-c9d0-1234-ef56-789012345678",
    "frequency": "MULTIPLE_TIMES",
    "recurrenceIntervalDays": 30,
    "url": "https://pay.zorinpay.com/e5f6a7b8-c9d0-1234-ef56-789012345678",
    "status": "PENDING",
    "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
}

POST/pixQrCode-splitpixqrcode.createIdempotency-Key

Gera QR Code PIX com split de pagamento entre múltiplos recebedores.

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" }
}

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"
}

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 sem gerar eventos reais, use a área Testar Webhook no Dashboard (Configurações → Testar Webhook): informe a URL do seu backend, escolha o tipo de evento (ex.: billing.paid, pixqrcode.paid) e envie. O sistema enviará um POST com dados fake no mesmo formato de produção (incluindo header X-Webhook-Signature e query webhookSecret).

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.cancelled

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.

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.

billing.failed— Cobrança falhou.

billing.refunded— Cobrança estornada.

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 estornado.

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).

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

Respostas de erro