Crie intenções, consulte eventos e tentativas sem confundir aceite com liquidação.

Pagamentos e checkout

A chave deve ter o scope payments:write para criar e payments:read para consultar. A chave define a conta e o ambiente; a API não aceita tenant, conta ou ambiente no corpo. Só MZN é aceite e amount_minor é inteiro em centavos: 10000 representa 100,00 MT.

Criar intenção de pagamento

POST/v1/payments

Cria uma intenção idempotente e grava uma tentativa na outbox para envio assíncrono ao Payment Master. Campos: amount_minor positivo na moeda-base MZN/USD/EUR da conta, method=emola|mpesa e phone; customer_id, reference e description são opcionais. Para os providers móveis, o backend converte o valor para MZN com a taxa configurada. O telefone é cifrado na base de dados. Se reference não for enviada, a API gera uma; trans_id é sempre gerado pela API. O padrão de comissão é 7%; 100,00 MT resulta em 7,00 MT de taxa e 93,00 MT líquidos. A taxa aplicada e o valor líquido ficam registados na intenção. A API de parceiro não altera a política.

curl -i -X POST \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: integration-order-0001' \
  --data '{"amount_minor":10000,"currency":"MZN","method":"emola","phone":"861234567"}' \
  "https://api-pay.edutecka.com/v1/payments"

HTTP/1.1 202 Accepted
Content-Type: application/json
X-Request-Id: req_…

{
  "data": {
    "id": "pay_…",
    "reference": "RF…",
    "trans_id": "TX…",
    "amount_minor": 10000,
    "currency": "MZN",
    "method": "emola",
    "status": "pending",
    "platform_fee_bps": 700,
    "platform_fee_minor": 700,
    "receiver_net_minor": 9300
  },
  "meta": { "request_id": "req_…" }
}

202 não significa que o Master/provider aceitou o pedido nem que o pagamento foi concluído. Significa que a API persistiu a intenção e colocou o pedido na outbox para processamento assíncrono. `pending`, `processing` e `unknown` não confirmam liquidação. Esta versão ainda não tem callback/reconciliação oficial para confirmar o sucesso nem lançamento no ledger. Em resultado incerto, consulte pelo mesmo ID; não crie uma nova cobrança. Repetir o mesmo POST com a mesma chave de idempotência e os mesmos dados devolve a intenção existente.

Listar e consultar pagamentos

GET/v1/payments?limit=50

Lista até 100 intenções do ambiente da chave (padrão 50). Campos monetários incluem comissão aplicada e valor líquido; não inclui telefone.

GET/v1/payments/{id}

Obtém uma intenção apenas se pertencer ao tenant e ambiente da chave. ID pertencente a outra conta ou ambiente responde como não encontrado.

Consultar eventos e tentativas

GET/v1/payments/{id}/events

Mostra eventos sanitizados da tentativa, sem telefone nem payload bruto do provider.

GET/v1/payments/{id}/attempts

Lista até 100 tentativas da intenção, por ordem de criação. Inclui estado, método e datas. A resposta omite o telefone, códigos internos, a chave de idempotência do Master e o corpo recebido do provider. Exige scope payments:read e oculta intenções de outra conta/ambiente como não encontradas.

Submeter pagamento no checkout

POST/checkout/v1/payment-links/{id}/payments

Submete o pagamento iniciado na página pública. O corpo aceita apenas method e phone; montante, conta e ambiente vêm do link armazenado. Envie Idempotency-Key com 16–128 caracteres seguros. São permitidos cinco pedidos por telefone e link em cada janela de quinze minutos. Apenas links Sandbox são aceites; links de Produção respondem production_checkout_disabled. Uma resposta HTTP 202 significa intenção gravada e enviada à outbox; não significa pagamento concluído.

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: checkout-order-0001' \
  --data '{"method":"emola","phone":"861234567"}' \
  "https://api-pay.edutecka.com/checkout/v1/payment-links/plink_0123456789abcdef0123456789abcdef/payments"

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "data": {
    "id": "pay_…",
    "status": "pending",
    "method": "emola",
    "notice": "accepted_for_processing_not_payment_confirmation"
  },
  "meta": { "request_id": "req_…" }
}

O checkout público de Produção permanece desligado. A plataforma ainda precisa de callback autenticado, reconciliação e lançamento no ledger antes de aceitar pagamentos reais. Não trate `pending`, `processing` nem `unknown` como pagamento concluído.