ZoryCash — Infraestrutura de Pagamentos PIX & Cripto para Operadores

================================================================================ZORYCASH API - GUIA DE INTEGRACAO PARA LLMs (v1)================================================================================ Produto: ZoryCashSite base: https://zorycash.com.brAPI base URL: https://api.zorycash.com.br/api/v1Formato: REST sobre HTTPS, request e response em JSONMercado principal: BrasilMoeda: BRLUnidade monetaria: centavos inteiros. Exemplo: 5000 = R$ 50,00 OBJETIVO DESTE ARQUIVOUse este arquivo para gerar codigo de integracao confiavel para a API ZoryCash.Nao invente endpoints, parametros ou status fora desta especificacao. Quando ousuario pedir exemplos, prefira codigo simples, com tratamento de erro, timeout,idempotencia via external_ref e logs sem expor x-api-key. ================================================================================1. AUTENTICACAO================================================================================ Todas as chamadas em /api/v1 exigem uma chave privada de API. Header recomendado:x-api-key: <SUA_CHAVE_PRIVADA> Tambem aceito:Authorization: Bearer <SUA_CHAVE_PRIVADA> Padrao das chaves:ak_live_... para producaoak_test_... para teste, quando habilitado na conta Nunca coloque a chave na URL, em query string, em frontend publico, em logs,em analytics ou em mensagens de erro exibidas para clientes finais. ================================================================================2. CORS, RATE LIMIT E RESPOSTAS================================================================================ CORS:Access-Control-Allow-Origin: *Access-Control-Allow-Methods: GET, POST, OPTIONSAccess-Control-Allow-Headers: Content-Type, Authorization, x-api-key Rate limit atual:Operacoes financeiras usam limites adaptativos por conta, canal e nivel operacional.Contas novas comecam com menor cadencia e evoluem somente com pagamentos liquidados.Ao receber 429, respeite o cabecalho Retry-After antes de tentar novamente.Rota Black: PIX entrada/saida R$ 2 a R$ 1.000; cripto saida R$ 10 a R$ 1.000; cripto entrada R$ 10 a R$ 3.000.O nivel da conta pode reduzir o teto, nunca ampliar o teto da rota. Content-Type:Enviar Content-Type: application/json em chamadas POST. Codigos comuns:200 OK - leitura ou operacao aceita201 Created - recurso criado202 Accepted - operacao enviada, mas atualizacao local ainda pendente400 Bad Request - validacao ou payload invalido401 Unauthorized - chave ausente, invalida ou revogada402 Payment Required - saldo insuficiente404 Not Found - recurso nao pertence a chave ou nao existe429 Too Many Requests - limite excedido500 Internal Error - falha interna502 Bad Gateway - processamento externo recusado/indisponivel503 Service Unavailable - autenticacao temporariamente indisponivel Formato de erro:{  "error": "codigo_ou_mensagem",  "details": []} ================================================================================3. IDEMPOTENCIA================================================================================ Use external_ref em operacoes financeiras sempre que possivel. Para POST /pix/charge:Se a mesma chave criar uma cobranca com o mesmo external_ref, a API retorna acobranca existente com "idempotent": true. Para POST /pix/withdraw:Se a mesma chave solicitar um saque com o mesmo external_ref, a API retorna osaque existente com "idempotent": true. Recomendacao:external_ref deve ser o ID unico do pedido/saque no sistema do integrador.Nao reutilize external_ref para operacoes diferentes. ================================================================================4. ENDPOINT: CRIAR COBRANCA PIX================================================================================ POST /pix/charge Cria uma cobranca PIX e retorna QR Code e copia e cola. Body:{  "amount_cents": 5000,  "external_ref": "pedido_123",  "description": "Pagamento de Fatura",  "payer_name": "Joao Silva",  "payer_doc": "12345678909",  "payer_email": "joao@exemplo.com",  "splits": [    {      "recipient_pix_key": "49000000000",      "percentage": 10    },    {      "recipient_pix_key": "financeiro@exemplo.com",      "fixed_cents": 500    }  ]} Campos:amount_cents: inteiro obrigatorio, minimo 500, maximo 10000000.external_ref: string opcional, maximo 120 caracteres, usada para idempotencia.description: string opcional, maximo 200 caracteres.payer_name: string opcional, maximo 120 caracteres.payer_doc: string opcional, maximo 20 caracteres.payer_email: e-mail opcional, maximo 255 caracteres.splits: array opcional com ate 10 recebedores.splits[].recipient_pix_key: chave PIX do recebedor do split.splits[].percentage: percentual de 0 a 100.splits[].fixed_cents: valor fixo em centavos. Response 200:{  "id": "uuid-da-transacao",  "status": "pending",  "amount_cents": 5000,  "pix": {    "qr_code_image": "data:image/png;base64,...",    "copy_paste": "000201...",    "expires_at": "2026-08-30T12:00:00.000Z"  },  "external_ref": "pedido_123",  "splits": [    {      "id": "uuid-do-split-aplicado",      "recipient_pix_key": "49000000000",      "amount_cents": 500,      "status": "pending"    }  ],  "created_at": "2026-08-30T12:00:00.000Z"} Status de transacao mais comuns:pending, paid, expired, failed, canceled, refunded. ================================================================================5. ENDPOINT: REALIZAR SAQUE PIX================================================================================ POST /pix/withdraw Solicita um saque PIX debitando o saldo disponivel da conta autenticada.Esta operacao pode movimentar dinheiro real em producao. Body:{  "amount_cents": 2000,  "pix_key": "12345678909",  "pix_key_type": "cpf",  "external_ref": "saque_123"} Campos:amount_cents: inteiro obrigatorio, minimo 500, maximo 10000000.pix_key: string obrigatoria, minimo 3 e maximo 200 caracteres.pix_key_type: cpf, cnpj, email, phone ou random.external_ref: string opcional, maximo 120 caracteres, usada para idempotencia. Response 200:{  "id": "uuid-do-saque",  "status": "processing",  "amount_cents": 2000,  "fee_cents": 200,  "created_at": "2026-08-30T12:00:00.000Z"} Response 402:{  "error": "insufficient_balance"} Status de saque mais comuns:pending, processing, completed, rejected, failed. ================================================================================6. ENDPOINT: CONSULTAR SALDO================================================================================ GET /balance Consulta o saldo da conta autenticada. Antes de responder, a API tenta sincronizartransacoes pendentes recentes. Response 200:{  "available_cents": 154000,  "total_received_cents": 500000,  "total_withdrawn_cents": 346000} Campos:available_cents: saldo disponivel para saque.total_received_cents: total recebido historico.total_withdrawn_cents: total sacado historico. ================================================================================7. ENDPOINT: CONSULTAR TRANSACAO================================================================================ GET /transactions/:id Consulta uma transacao especifica pertencente a chave autenticada.Se a transacao estiver pending e tiver external_id, a API tenta sincronizar ostatus antes de retornar. Response 200:{  "id": "uuid-da-transacao",  "status": "paid",  "amount_cents": 5000,  "net_cents": 4800,  "atlas_fee_cents": 100,  "acquirer_fee_cents": 100,  "description": "Pagamento de Fatura",  "external_id": "id-no-provedor",  "pix_copy_paste": "000201...",  "pix_qr": "data:image/png;base64,...",  "expires_at": "2026-08-30T12:30:00.000Z",  "paid_at": "2026-08-30T12:05:00.000Z",  "created_at": "2026-08-30T12:00:00.000Z"} Response 404:{  "error": "not_found"} ================================================================================8. ENDPOINTS: SPLITS DE PAGAMENTO================================================================================ GET /splits Lista splits cadastrados na conta autenticada. Response 200:{  "data": [    {      "id": "uuid-do-split",      "name": "Socio",      "recipient_pix_key": "49000000000",      "recipient_pix_key_type": "cpf",      "percentage": 10,      "fixed_cents": 0,      "active": true,      "created_at": "2026-08-30T12:00:00.000Z"    }  ]} POST /splits Cria uma regra de split. Body:{  "name": "Socio",  "recipient_pix_key": "49000000000",  "recipient_pix_key_type": "cpf",  "recipient_doc": "49000000000",  "percentage": 10,  "fixed_cents": 0} Regras:percentage ou fixed_cents deve ser maior que zero.percentage deve ficar entre 0 e 100.fixed_cents deve ser inteiro em centavos. GET /splits/:id Consulta uma regra de split e as ultimas 50 aplicacoes em transacoes. POST /splits/:id Atualiza ou remove uma regra de split. Body para atualizar:{  "active": false,  "percentage": 5,  "fixed_cents": 100} Body para remover:{  "deleted": true} ================================================================================9. WEBHOOKS ENVIADOS PELA ZORYCASH================================================================================ A ZoryCash envia eventos para as URLs cadastradas no painel do usuario.O backend do integrador deve responder 2xx rapidamente. Headers enviados:Content-Type: application/jsonX-ZoryCash-Event: <nome_do_evento>X-ZoryCash-Delivery: <id_unico_da_entrega>X-ZoryCash-Signature: sha256=<hmac_sha256_hex> Assinatura:Calcule HMAC-SHA256 sobre o corpo JSON bruto usando o segredo do endpoint.Compare em tempo constante com o valor depois de "sha256=". Nunca registre osegredo em logs. Payload:{  "id": "uuid-da-entrega",  "event": "payment.confirmed",  "created_at": "2026-08-30T12:05:00.000Z",  "data": {    "id": "uuid-da-transacao",    "status": "paid",    "amount_cents": 5000,    "net_cents": 4800,    "external_ref": "pedido_123"  }} Eventos de pagamento:payment.createdpayment.confirmedpayment.partialpayment.failedpayment.refundedpayment.chargeback Eventos de saque:withdrawal.completedwithdrawal.failedwithdrawal.refunded Eventos MED:med.openedmed.updatedmed.acceptedmed.rejectedmed.cancelledmed.closed Boas praticas:Responda 200 OK antes de tarefas demoradas.Use X-ZoryCash-Delivery como chave de idempotencia no seu sistema.A ZoryCash faz ate 6 tentativas com intervalos progressivos.Nao confie apenas no webhook para liberar produto se precisar de confirmacaoforte: consulte GET /transactions/:id quando necessario. ================================================================================10. EXEMPLOS DE CODIGO================================================================================ cURL - criar cobranca PIX:curl -X POST https://api.zorycash.com.br/api/v1/pix/charge \  -H "x-api-key: SUA_CHAVE" \  -H "Content-Type: application/json" \  -d '{"amount_cents":5000,"external_ref":"pedido_123","description":"Pedido 123"}' cURL - consultar saldo:curl -X GET https://api.zorycash.com.br/api/v1/balance \  -H "x-api-key: SUA_CHAVE" Node.js - criar cobranca PIX:const res = await fetch("https://api.zorycash.com.br/api/v1/pix/charge", {  method: "POST",  headers: {    "Content-Type": "application/json",    "x-api-key": process.env.ZORYCASH_API_KEY  },  body: JSON.stringify({    amount_cents: 5000,    external_ref: "pedido_123",    description: "Pedido 123"  })});const data = await res.json();if (!res.ok) throw new Error(data.error || "Falha ao criar cobranca"); Python - criar cobranca PIX:import osimport requests res = requests.post(    "https://api.zorycash.com.br/api/v1/pix/charge",    headers={        "Content-Type": "application/json",        "x-api-key": os.environ["ZORYCASH_API_KEY"],    },    json={        "amount_cents": 5000,        "external_ref": "pedido_123",        "description": "Pedido 123",    },    timeout=15,)data = res.json()res.raise_for_status() PHP - criar cobranca PIX com Guzzle:$client = new \GuzzleHttp\Client(["timeout" => 15]);$response = $client->post("https://api.zorycash.com.br/api/v1/pix/charge", [    "headers" => [        "Content-Type" => "application/json",        "x-api-key" => getenv("ZORYCASH_API_KEY"),    ],    "json" => [        "amount_cents" => 5000,        "external_ref" => "pedido_123",        "description" => "Pedido 123",    ],]);$data = json_decode((string) $response->getBody(), true); ================================================================================11. PROMPT RECOMENDADO PARA OUTRAS IAs================================================================================ Use a documentacao da ZoryCash acima. Gere uma integracao usando a linguagemsolicitada pelo usuario. Inclua:1. variavel de ambiente ZORYCASH_API_KEY;2. funcao para criar cobranca PIX com external_ref;3. funcao para consultar saldo;4. handler de webhook idempotente para payment.confirmed com validacao HMAC;5. tratamento de erro para 400, 401, 402, 429 e 5xx;6. cuidado para nunca logar a x-api-key. ================================================================================FIM================================================================================