POST /checkout/order-api-gateway

Em produtos API Gateway o preço é definido em cada pedido. A Zenofy devolve um URL de checkout; o comprador paga em pay.zenofy.io. Os webhooks configuram-se no produto, não no corpo da API.

URL base: o host da API Zenofy (por exemplo https://api.zenofy.io). Caminho: <code>/checkout/order-api-gateway</code> (POST).

Use a mesma chave de API de checkout dos outros endpoints (app comerciante → Definições → Chave de API de checkout). Cabeçalho: <code>Api-Key</code> (texto simples, não Bearer).

O produto tem de ser do tipo API payment gateway, pertencer à sua conta, ter URL de webhook guardado no produto e estar activo. Não há página pública do produto — checkout só via API.

Configuração do produto (painel)

Crie um produto e escolha API payment gateway. Na secção de webhook indique o URL do webhook (obrigatório) e o Segredo do webhook opcional para HMAC. Active os métodos de pagamento no produto. Valor e moeda variam em cada chamada à API.

Autenticação

Cabeçalho Api-Key: o segredo completo da API de checkout. Chave em falta ou inválida devolve HTTP 401.

Pedido HTTP

POST · Content-Type: application/json · Api-Key

Exemplo de pedido (ilustrativo)

POST /checkout/order-api-gateway HTTP/1.1
Host: api.zenofy.io
Api-Key: YOUR_CHECKOUT_API_KEY
Content-Type: application/json

{ ... }

Corpo JSON (campos)

Campo	Tipo	Notas
`productId`	string	Obrigatório. Id do produto API Gateway.
`amount`	integer	Obrigatório. Valor em unidades menores (ex.: `2500` = 25,00).
`currency`	string	Opcional. ISO 4217 (3 letras). Por omissão, moeda principal do produto.
`reference`	string	Opcional. O seu id (guardado na encomenda; repetido em webhooks).
`description`	string	Opcional. Descrição no checkout; por omissão, nome do produto.
`customer`	object	Obrigatório. `name`, `email`, `phone` (E.164, ex. +258840000000).
`payment_methods`	array	Opcional. Alias: `card`, `mpesa`, `emola`, `emis`, `payfast`, `stripe`, `flutterwave`. Omitir para todos os gateways activos no produto.
`success_url`	string	Opcional. HTTPS após pagamento. Usado exactamente como envia (inclua a query string que precisar).
`cancel_url`	string	Opcional. HTTPS para o botão Cancelar. Usado exactamente como envia.
`language`	string	Opcional. Idioma do checkout (ex. `en`, `pt`).

Exemplo de corpo JSON

{
  "productId": "507f1f77bcf86cd799439011",
  "amount": 2500,
  "currency": "MZN",
  "reference": "inv-2026-0042",
  "description": "Pro plan — March 2026",
  "customer": {
    "name": "João Silva",
    "email": "buyer@example.com",
    "phone": "+258840000000"
  },
  "payment_methods": ["mpesa", "card"],
  "success_url": "https://your-app.com/paid?ref=inv-2026-0042",
  "cancel_url": "https://your-app.com/cancelled",
  "language": "pt"
}

Resposta em caso de sucesso

HTTP 200 JSON: checkout_id (igual ao id da encomenda), checkout_url (URL absoluto, caminho /c/{checkout_id}) e expires_at (ISO 8601 UTC). Erros devolvem JSON com success: false e message (muitas vezes HTTP 400).

HTTP 200 — success

{
  "checkout_id": "673f92b2c3d94a0012abcd01",
  "checkout_url": "https://pay.zenofy.io/c/673f92b2c3d94a0012abcd01",
  "expires_at": "2026-05-20T14:30:00.0000000Z"
}

Página de pagamento e redirects

Abra checkout_url para o comprador. Com cancel_url, a página mostra cancelar e envia o comprador para esse URL sem alterações (encomenda pendente). Após pagamento, com success_url, redirect para esse URL sem alterações. Confirme via webhooks ou GET /checkout/order-status?orderId={checkout_id}.

Guias relacionados

Todos os tutoriais