Desenvolvedores
Três chamadas e um webhook.
O Gateway é um checkout hospedado, então a integração é propositalmente enxuta: crie um pedido, envie o cliente para a página e verifique o resultado assinado. Isso é toda a superfície — a interface de pagamento, a lógica dos métodos, o 3-D Secure, as carteiras e os recibos ficam por nossa conta, do desenvolvimento à atualização.
Visão geral
Com o que você vai integrar.
- REST sobre HTTPS
- JSON na entrada, JSON na saída
- Chaves de API Bearer
- Chaves de idempotência
- Webhooks assinados
- Proteção contra replay
- Modos de teste e produção
- SDKs para iOS e Android
- Plugins para lojas
- Campos incorporados
Quickstart
Do zero ao pedido pago.
Todo o caminho feliz. Os valores estão em unidades menores, as referências são suas, e a URL de checkout é para onde você redireciona o cliente. A URL base da API é emitida junto com suas chaves do sandbox — exporte-a como PROTOCORE_API_BASE e as chamadas abaixo funcionam exatamente como estão.
Crie o pedido
Uma chamada com o valor, a moeda e a sua própria referência. A chave de idempotência é gerada por você — uma requisição repetida devolve o pedido original em vez de criar um segundo.
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"
}'Envie o cliente para o checkout
A resposta traz a URL de checkout no seu próprio host de checkout — o emitido com o seu sandbox ou o seu domínio, depois que você o apontar para nós. Redirecione para ela ou abra-a no SDK; é nessa página que ficam os métodos, as carteiras e o 3-D Secure, então 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"
}Verifique o resultado assinado
Quando o pagamento é concluído, um evento assinado chega ao seu endpoint. Verifique a assinatura com o seu segredo de webhook antes de confiar em qualquer coisa e, então, processe o pedido pela referência que você 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 você realmente vai 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 recebe.
Todo evento traz a referência do pedido que você criou, então o seu handler pode ser um switch no tipo e uma consulta no seu próprio sistema.
Confira a assinatura antes de confiar no corpo.
Toda entrega traz um timestamp e uma assinatura HMAC sobre o corpo bruto. Compare em tempo constante, rejeite qualquer coisa mais antiga que a sua janela de tolerância e trate um id de evento duplicado como já processado — tentamos de novo em respostas diferentes de 2xx, então 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 sobre as quais você pode construir.
Criações idempotentes
Toda criação de pedido aceita uma chave de idempotência. Uma requisição repetida — após um timeout, um deploy ou uma reentrega de fila — devolve o pedido 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, então uma janela de deploy não faz você perder um pagamento.
Uma referência, de ponta a ponta
A referência que você informa na criação aparece no checkout, no recibo, no webhook, no repasse 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 os mesmos fluxos em sessões de teste. O que passa no teste é o que vai para produção — a diferença está nas chaves que você envia, não nos endpoints que você chama.
Dados de teste
Como exercitar os caminhos que importam.
Cada caminho abaixo tem um cartão de teste associado, listado junto com suas chaves quando o sandbox é emitido — os números são por sandbox e não são publicados aqui, para continuarem corretos conforme as faixas de teste das bandeiras mudam. O comportamento é determinístico de qualquer forma: um teste valida uma recusa tão facilmente quanto uma aprovação.
Pegue as chaves e comece.
Um merchant sandbox com chaves de API, segredos de webhook e todos os métodos ativados — mais a referência completa, para seu time integrar antes de qualquer assinatura.