Pagamentos enviados
Enviar dinheiro para um destinatário que indica. Concebido para recusar em vez de adivinhar.
Um pagamento enviado privilegia a recusa
Um pagamento recebido que falha custa-lhe uma venda. Um pagamento enviado errado é dinheiro perdido, para alguém que ninguém controla, normalmente irrecuperável. Todos os casos ambíguos desta API recusam, retêm ou esperam por uma pessoa — se os pagamentos enviados lhe parecem mais cautelosos do que a API de cobrança, é essa a intenção e não um defeito.
Os pagamentos enviados estão disponíveis em Sandbox hoje. Ainda não existe um canal real: uma implantação Live não tem nenhum adaptador activo e todos os pagamentos aí falham em segurança com provider_unavailable.
Duas barreiras antes de uma aplicação poder pagar
A capacidade de enviar pagamentos é concedida por cliente e por ambiente, pela equipa da Baraka Pay, e está desligada por omissão. A ausência de configuração significa não — todas as chaves de API que existiam antes desta funcionalidade continuam incapazes de enviar dinheiro.
O comerciante precisa de saldo. Um pagamento enviado sai das suas cobranças e não há descoberto: um pagamento superior ao saldo disponível é recusado e nada fica reservado.
Em Live, dinheiro acabado de chegar não pode sair imediatamente — um pagamento recebido cumpre primeiro um período de retenção. O comerciante não perde acesso a nada; o seu saldo e a sua liquidação ficam inalterados. Isto rege apenas o que pode financiar uma transferência irreversível para terceiros, porque um pagamento recebido que é enviado e depois revertido é dinheiro que foi para onde ninguém controla. O sandbox põe a retenção a zero para poder testar entrada e saída de uma vez; não assuma que Live se comporta da mesma forma.
Criar um pagamento enviado
Envie o montante em unidades menores, o método, a sua própria referência e um destino. Use a sua merchantReference como Idempotency-Key, tal e qual.
201 à primeira vez. 200 com o pagamento ORIGINAL se essa referência já tiver sido usada — essa diferença é toda a defesa contra um levantamento repetido pagar duas vezes a alguém, por isso verifique o código de estado em vez de o ignorar.
Um pagamento enviado exige uma chave de API, não uma sessão de portal
Criar e repetir um pagamento recusam uma sessão do portal do Merchant com api_key_required. Ler, listar e cancelar continuam a funcionar com uma sessão.
Uma sessão de portal é um token assente apenas numa palavra-passe. Uma chave de API é um segredo do lado do servidor. Um pagamento enviado vai para onde quem chama indicar, por isso é autorizado pela mais forte das duas — e uma palavra-passe de portal obtida por phishing não se transforma no poder de enviar dinheiro. Os reembolsos permitem deliberadamente uma sessão de portal, porque um reembolso regressa ao pagador original e não pode ser desviado.
A aprovação é normal, não é um erro
Um pagamento acima do limite de aprovação automática da plataforma — e, por omissão, todos os primeiros pagamentos para um destino que este comerciante nunca pagou com sucesso — regressa como requires_approval e espera por um membro da equipa da Baraka Pay.
O limite é um número único para toda a implantação, por moeda, definido pelo back office. Pagamentos iguais ou inferiores seguem directamente. Uma implantação sem qualquer configuração retém todos os pagamentos por mais pequenos que sejam: uma plataforma que ninguém configurou não deve ser uma plataforma que envia dinheiro sem ninguém a ver.
O período de espera para um destino novo não é desconfiança da sua aplicação. Um destino nunca visto para um destinatário já existente é o pagamento clássico de tomada de conta: o atacante não aumenta o montante, muda para onde o dinheiro vai. Preveja a espera — levantamento submetido e em análise é um estado normal.
O destino regressa sempre mascarado
A Baraka Pay guarda o identificador completo porque não se pode entregar um destino mascarado a um canal, e não o devolve a ninguém — nem a si, nem à fila de aprovação da equipa, nem ao registo de auditoria.
holderName é obrigatório e não é decoração. É o único campo que apanha um número trocado antes de o dinheiro sair, e onde um canal verifica nomes, uma divergência recusa o pagamento. Envie o nome que a conta do destinatário realmente tem, não o que consta do seu próprio registo.
payout.returned é a regra que as integrações esquecem
Eventos: payout.pending, payout.approved, payout.processing, payout.succeeded, payout.failed, payout.cancelled, payout.returned. Mesma assinatura e mesmo verificador dos webhooks de cobrança — reutilize-os byte a byte, e releia o pagamento em vez de confiar no corpo.
Pagamentos por dinheiro móvel e por banco são devolvidos. Uma carteira encerrada, um nome divergente detectado a jusante, uma transferência revogada — dias depois de a sua aplicação ter dito ao utilizador que o dinheiro seguiu. O pagamento passa de succeeded para returned, um lançamento compensatório repõe o valor, e payout.returned é entregue. A sua aplicação tem de lidar com a reversão de dinheiro que já creditou.
A Baraka Pay nunca converte num pagamento enviado: a moeda do destino tem de ser a do pagamento, e um pagamento em moeda diferente é recusado, não convertido.