Visão geral

O Spolly Payments recebe pagamentos para a tua loja online, num checkout alojado por nós: o teu servidor cria uma sessão de pagamento, manda o comprador para a página do checkout, e o dinheiro fica no teu saldo, de onde o sacas para o banco. O comprador paga por Multicaixa Express, referência, BAI Paga ou cartão.

Não há formulários de pagamento para embutir nem cobranças diretas pela API: a sessão de checkout é a única porta de entrada do dinheiro. Isso quer dizer que a tua integração é pequena: uma chamada para criar a sessão, e um endpoint que recebe os eventos.

1. O teu servidor chama POST /v1/checkout/sessions com a tua chave secreta, o valor e a moeda, e recebe o url do checkout.
2. O comprador abre esse endereço, vê o nome e a marca da tua loja, e escolhe como paga.
3. Quando o gateway confirma, nós confirmamos de novo junto dele, registamos o pagamento, e enviamos o evento payment.succeeded, assinado, para o endpoint que configuraste no painel.
4. O comprador volta ao teu success_url. Esse regresso não prova o pagamento: quem prova é o webhook (ou um GET da sessão feito pelo teu servidor). Ver Confirmar o pagamento.
5. O valor líquido (o pago menos a nossa taxa) entra no teu saldo, e pedes o saque no painel.

A API fala JSON, com o dinheiro sempre em unidades menores inteiras (15.000,00 Kz é {"amount": 1500000, "currency": "AOA"}), e responde aos erros com um código estável e uma mensagem em português.

Tudo existe em dois modos que não se misturam: teste e produção. O modo é o da chave: uma sk_test_ cria sessões de teste, que se pagam com os botões Aprovar e Recusar do checkout, sem dinheiro nenhum; uma sk_live_ cobra a sério, e só existe depois de a tua empresa estar verificada.