Protocore
Kontakt os

Udviklere

Tre kald og en webhook.

Gateway er et hostet checkout, så integrationen er bevidst lille: opret en ordre, send kunden til siden, verificér det signerede resultat. Det her er hele overfladen — betalings-UI'et, metodelogikken, 3-D Secure, wallets og kvitteringer er vores at bygge og holde ajour.

Anmod om sandbox-adgangPrøv checkouten

Overblik

Det, du integrerer mod.

  • REST over HTTPS
  • JSON ind, JSON ud
  • Bearer API-nøgler
  • Idempotensnøgler
  • Signerede webhooks
  • Replay-beskyttelse
  • Test- og live-tilstand
  • iOS- og Android-SDK'er
  • Butiksplugins
  • Embedded felter

Quickstart

Fra ingenting til en betalt ordre.

Hele happy path. Beløb er i mindste enhed, referencer er dine egne, og checkout-URL'en er dér, du sender kunden hen. API-basis-URL'en udleveres sammen med dine sandbox-nøgler — eksportér den som PROTOCORE_API_BASE, så kører kaldene nedenfor præcis som skrevet.

01

Opret ordren

Ét kald med beløb, valuta og din egen reference. Idempotensnøglen genererer du selv — en gentaget anmodning returnerer den oprindelige ordre i stedet for at oprette en ny.

POST /v1/orders
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"
      }'
02

Send kunden til checkout

Svaret indeholder en checkout-URL på din egen checkout-host — den, der blev udstedt med din sandbox, eller dit eget domæne, når du har peget det på os. Omdirigér til den, eller åbn den i SDK'et; på den side bor metoderne, wallets og 3-D Secure, så der er intet at bygge hos dig.

201 Created
{
  "id": "ord_2h4Kq9wRz",
  "reference": "9F21-0716",
  "amount": 4900,
  "currency": "EUR",
  "status": "pending",
  "checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}
03

Verificér det signerede resultat

Når betalingen er gennemført, når en signeret hændelse dit endpoint. Verificér signaturen mod din webhook-secret, før du stoler på noget, og levér derefter mod den reference, du allerede kender.

POST /your/webhook — order.paid
{
  "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" }
  }
}

Reference

De endpoints, du faktisk får brug for.

Der er mere i dokumentationen, men dette er det sæt, de fleste integrationer aldrig vokser ud over.

POST /v1/orders
Opret en ordre og modtag dens checkout-URL. Tager en idempotensnøgle.
GET /v1/orders/:id
Ordrens aktuelle tilstand — status, metode, afregning og refunderinger.
POST /v1/orders/:id/refunds
Refundér ordren, helt eller delvist, med en obligatorisk begrundelse.
POST /v1/orders/:id/void
Frigiv autorisationen før afregning, så der slet ikke flyttes penge.
POST /v1/links
Opret et betalingslink — til engangsbrug eller indsamlende, med valgfri udløbsdato.
GET /v1/payouts/:id
Et afregningsbatch og de ordrer, der finansierede det, med specificerede gebyrer.
POST /v1/customers/:id/cards
Gem et kort i vault til one-click- og tilbagevendende betalinger; returnerer en token-reference.
POST /v1/subscriptions
Træk på et gemt kort efter en tidsplan; hver cyklus giver sin egen ordre.

Webhooks

Det, dit backend hører om.

Hver hændelse bærer den ordrereference, du oprettede, så din handler kan være en switch på typen og et opslag hos dig selv.

order.paid
Autorisation og capture lykkedes — levér mod referencen.
order.failed
Betalingen blev ikke gennemført, med en årsag, en operatør kan handle på.
order.refunded
En refundering er udstedt, hel eller delvis, med begrundelse og note.
order.disputed
En chargeback er åbnet, med dokumentationen allerede knyttet til ordren.
payout.settled
Et afregningsbatch er afsendt til din konto, med oversigt over de ordrer, der ligger bag.
subscription.charged
En tilbagevendende cyklus har givet sin egen ordre og kvittering.
Verificér

Tjek signaturen, før du stoler på body'en.

Hver levering har et tidsstempel og en HMAC-signatur over den rå body. Sammenlign i konstant tid, afvis alt ældre end dit tolerancevindue, og behandl et duplikeret hændelses-id som allerede håndteret — vi forsøger igen ved svar uden for 2xx, så din handler bør også være idempotent.

Node — signaturverifikation
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;
}

Garantier

De egenskaber, du kan bygge på.

01

Idempotente oprettelser

Enhver ordreoprettelse tager en idempotensnøgle. En gentaget anmodning — efter timeout, deploy eller genlevering fra en kø — returnerer den oprindelige ordre i stedet for at trække penge to gange.

02

Signerede, replay-beskyttede hændelser

Webhooks bærer en tidsstemplet HMAC-signatur og et stabilt hændelses-id. Leveringer forsøges igen med backoff, indtil dit endpoint svarer 2xx, så et deploy-vindue ikke koster en betaling.

03

Én reference, hele vejen

Den reference, du angiver ved oprettelsen, optræder på checkout, kvittering, webhook, udbetaling og enhver senere refundering. Der er ingen anden identifikator at mappe mellem systemer.

04

Testtilstand er samme kodesti

Testnøgler kører de identiske flows mod testsessioner. Det, der består i test, er det, der går i produktion — forskellen er, hvilke nøgler du sender, ikke hvilke endpoints du kalder.

Prøv checkouten

Testdata

Sådan afprøver du de stier, der betyder noget.

Bag hver sti herunder ligger et testkort, som fremgår sammen med dine nøgler, når sandboxen udstedes — numrene er per sandbox og offentliggøres ikke her, så de forbliver korrekte, når schemes' testintervaller ændres. Adfærden er under alle omstændigheder deterministisk: En test kan lige så let asserte på et afslag som på en succes.

Godkendt direkte
Autoriserer og capturer uden 3-D Secure-udfordring — den lykkelige vej.
3-D Secure-udfordring
Fremtvinger en udfordring, du kan gennemgå, så du kan teste returforløbet.
Soft decline
Afvises på grund af manglende dækning og forsøges derefter igen via en alternativ rute.
Hard decline
Afvises permanent som udløbet kort, uden nyt forsøg.
USDC-testnetværk
Testnet-USDC på Ethereum, Base og Solana, prissat til en fast kurs.
Overførselssimulering
Markér en vIBAN-testoverførsel som modtaget for at flytte ordren til betalt.

Hent nøgler og kom i gang.

En sandbox-forhandler med API-nøgler, webhook-secrets og alle betalingsmetoder aktiveret — plus den fulde reference, så dit team kan integrere, før noget er underskrevet.

Anmod om sandbox-adgangcontact@protocore.io