Valores e dados
O campoamountCents é um inteiro em centavos. Cobranças aceitam de R 2.000,00. payerName deve ter de 2 a 100 caracteres; description pode ter até 200 caracteres e pode ser uma string vazia.
Idempotência
Cada criação exigerequestKey, um UUID gerado pela sua aplicação. Repetir a mesma requisição com o mesmo UUID retorna a mesma operação. Reutilizar o UUID com outro valor ou outros dados gera erro. Isso evita cobrar duas vezes após timeout ou perda de resposta.
Estados
Uma resposta
pending pode conter copyPaste e qrCodeBase64 (data URL PNG). Esses campos são opcionais: use a operação retornada e consulte novamente quando necessário. paymentMethod é pix; expiresAt informa a expiração quando retornada pela liquidante e é null quando ela não fornece esse prazo. paidAt e endToEnd podem aparecer após a liquidação. A Master não inventa uma data de expiração.
Consultas
GET /payments/{id} busca uma operação da sua conta. GET /payments retorna até 100 operações recentes. O webhook é a primeira fonte de atualização. Após 5 segundos sem atualização, a Master agenda GET /payments/{paymentId} autenticado na Z.PAY. O processo funciona mesmo sem consultas do seu aplicativo; erros usam espera crescente e consultas têm limite compartilhado. GET /payments/{id} retorna o último estado conciliado e também tenta atualizar quando a consulta está vencida. Consultar o status não confirma manualmente a cobrança e não exige código de e-mail. Nunca marque um pedido como pago apenas porque o Pix foi gerado.
Todas essas rotas utilizam o negócio indicado por X-Master-Operation, ou a principal quando omitido. O pagamento retorna operationId; mantenha o mesmo header na criação e nas consultas. Não reutilize um requestKey em outro negócio.