Developers
Três chamadas e um webhook.
O Gateway é um checkout alojado, por isso a integração é deliberadamente pequena: criar uma encomenda, enviar o cliente para a página, verificar o resultado assinado. Tudo o que se segue é a superfície completa — a interface de pagamento, a lógica dos métodos, o 3-D Secure, as wallets e os recibos ficam a nosso cargo, construídos e sempre atualizados.
Em resumo
Aquilo com que vai integrar.
- REST sobre HTTPS
- JSON à entrada, JSON à saída
- Chaves de API Bearer
- Chaves de idempotência
- Webhooks assinados
- Proteção contra replay
- Modos de teste e produção
- SDKs iOS e Android
- Plugins para lojas
- Campos incorporados
Quickstart
Do zero a uma encomenda paga.
O fluxo completo, sem desvios. Os montantes estão em unidades menores, as referências são suas e o URL de checkout é para onde redireciona o cliente. O URL base da API é emitido com as chaves da sandbox — exporte-o como PROTOCORE_API_BASE e as chamadas abaixo funcionam exatamente como estão escritas.
Criar a encomenda
Uma chamada com o montante, a moeda e a sua própria referência. A chave de idempotência é gerada por si — um pedido repetido devolve a encomenda original em vez de criar uma segunda.
curl -X POST "$PROTOCORE_API_BASE/v1/orders" \
-H "Authorization: Bearer $PROTOCORE_API_KEY" \
-H "Idempotency-Key: 9F21-0716" \
-H "Content-Type: application/json" \
-d '{
"amount": 4900,
"currency": "EUR",
"reference": "9F21-0716",
"line_items": [
{ "name": "Brand identity sprint", "amount": 3850 },
{ "name": "Typeface licensing", "amount": 600 },
{ "name": "Rush delivery", "amount": 400 }
],
"return_url": "https://arcstudio.ro/thanks"
}'Enviar o cliente para o checkout
A resposta traz um URL de checkout no seu próprio host de checkout — o emitido com a sandbox ou o seu domínio, assim que o apontar para nós. Redirecione para lá ou abra-o no SDK; é nessa página que vivem os métodos, as wallets e o 3-D Secure, por isso não há nada para construir do seu lado.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Verificar o resultado assinado
Quando o pagamento termina, um evento assinado chega ao seu endpoint. Verifique a assinatura com o segredo do webhook antes de confiar no que quer que seja e só depois dê seguimento à encomenda, com base na referência que já conhece.
{
"type": "order.paid",
"id": "evt_7Ka2Lm",
"created": "2026-07-23T09:41:02Z",
"data": {
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"method": "usdc",
"settlement": { "currency": "EUR", "amount": 4900, "rate": "0.9184" }
}
}Referência
Os endpoints que vai realmente usar.
Há mais na documentação, mas este é o conjunto além do qual a maioria das integrações nunca cresce.
Webhooks
O que o seu backend fica a saber.
Cada evento traz a referência da encomenda que criou, pelo que o seu handler pode resumir-se a um switch sobre o tipo e uma consulta do seu lado.
Confirme a assinatura antes de confiar no corpo.
Cada entrega traz um timestamp e uma assinatura HMAC sobre o corpo em bruto. Compare em tempo constante, rejeite tudo o que seja mais antigo do que a sua janela de tolerância e trate um id de evento duplicado como já processado — repetimos o envio perante respostas não 2xx, pelo que o seu handler também deve ser idempotente.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(rawBody, header, secret) {
const [ts, sig] = header.split(",").map((p) => p.split("=")[1]);
const expected = createHmac("sha256", secret)
.update(`${ts}.${rawBody}`)
.digest("hex");
const a = Buffer.from(sig, "hex");
const b = Buffer.from(expected, "hex");
if (a.length !== b.length || !timingSafeEqual(a, b)) return false;
// Reject replays outside a five-minute window.
return Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}Garantias
As propriedades em que se pode apoiar.
Criações idempotentes
Cada criação de encomenda aceita uma chave de idempotência. Um pedido repetido — após um timeout, um deploy ou uma reentrega de fila — devolve a encomenda original em vez de cobrar duas vezes.
Eventos assinados e protegidos contra replay
Os webhooks trazem uma assinatura HMAC com timestamp e um id de evento estável. As entregas são repetidas com backoff até o seu endpoint responder 2xx, por isso uma janela de deploy não faz perder um pagamento.
Uma só referência, de ponta a ponta
A referência que indica na criação surge no checkout, no recibo, no webhook, no payout e em qualquer reembolso posterior. Não existe um segundo identificador para mapear entre sistemas.
O modo de teste usa o mesmo código
As chaves de teste executam exatamente os mesmos fluxos sobre sessões de teste. O que passa em teste é o que vai para produção — a diferença está nas chaves que envia, não nos endpoints que chama.
Dados de teste
Como exercitar os fluxos que importam.
Cada um dos percursos abaixo tem um cartão de teste associado, indicado junto das suas chaves quando a sandbox é emitida — os números são por sandbox e não são publicados aqui, para se manterem corretos quando os intervalos de teste das schemes mudarem. O comportamento é determinístico em qualquer caso: um teste valida uma recusa tão facilmente como um sucesso.
Obtenha as chaves e comece.
Um merchant de sandbox com chaves de API, segredos de webhook e todos os métodos ativos — mais a referência completa, para a sua equipa integrar antes de qualquer assinatura.