Protocore
Ota yhteyttä

Kehittäjille

Kolme kutsua ja webhook.

Gateway on hostattu checkout, joten integraatio on tarkoituksella pieni: luo tilaus, ohjaa asiakas sivulle, tarkista allekirjoitettu tulos. Tässä on koko pinta — maksukäyttöliittymä, maksutapojen logiikka, 3-D Secure, lompakot ja kuitit rakennamme ja pidämme ajan tasalla me.

Pyydä sandbox-käyttöoikeusKokeile checkoutia

Rakenne

Mitä vasten integroit.

  • REST HTTPS-yhteyden yli
  • JSON sisään, JSON ulos
  • Bearer-API-avaimet
  • Idempotenssiavaimet
  • Allekirjoitetut webhookit
  • Toistosuojaus
  • Testi- ja tuotantotila
  • iOS- ja Android-SDK:t
  • Verkkokauppalisäosat
  • Upotettavat kentät

Pikaopas

Tyhjästä maksettuun tilaukseen.

Koko onnistunut polku. Summat annetaan pienimmissä yksiköissä, viitteet ovat omiasi, ja checkout-URL on osoite, johon asiakas ohjataan. API:n perus-URL annetaan sandbox-avainten mukana — vie se muuttujaan PROTOCORE_API_BASE, niin alla olevat kutsut toimivat sellaisinaan.

01

Luo tilaus

Yksi kutsu: summa, valuutta ja oma viitteesi. Idempotenssiavaimen generoit itse — uudelleen lähetetty pyyntö palauttaa alkuperäisen tilauksen eikä luo toista.

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

Ohjaa asiakas checkoutiin

Vastaus sisältää checkout-URL:n omalla checkout-hostillasi — sandboxin mukana annetulla tai omalla domainillasi, kun osoitat sen meille. Ohjaa asiakas sinne tai avaa sivu SDK:ssa; maksutavat, lompakot ja 3-D Secure löytyvät tältä sivulta, joten omalla puolellasi ei ole mitään rakennettavaa.

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

Tarkista allekirjoitettu tulos

Kun maksu on valmis, allekirjoitettu tapahtuma saapuu päätepisteeseesi. Tarkista allekirjoitus webhook-salaisuutta vasten ennen kuin luotat mihinkään, ja toimita sitten tilaus viitteen perusteella, jonka jo tunnet.

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" }
  }
}

Referenssi

Päätepisteet, joita oikeasti käytät.

Dokumentaatiossa on enemmän, mutta tämä on joukko, jonka pidemmälle useimmat integraatiot eivät koskaan kasva.

POST /v1/orders
Luo tilaus ja saat sen checkout-URL:n. Vaatii idempotenssiavaimen.
GET /v1/orders/:id
Tilauksen nykytila — status, maksutapa, selvitys ja hyvitykset.
POST /v1/orders/:id/refunds
Hyvitä tilaus kokonaan tai osittain; syy on pakollinen.
POST /v1/orders/:id/void
Vapauta valtuutus ennen selvitystä, jolloin rahaa ei liiku lainkaan.
POST /v1/links
Luo maksulinkki — kertakäyttöinen tai keräävä, valinnaisella vanhenemisajalla.
GET /v1/payouts/:id
Selvityserä ja tilaukset, joista se muodostui, kulut eriteltyinä.
POST /v1/customers/:id/cards
Tallenna kortti holviin yhden klikkauksen ja toistuvia veloituksia varten; palauttaa token-viitteen.
POST /v1/subscriptions
Veloita holviin tallennettua korttia aikataulun mukaan; jokainen jakso tuottaa oman tilauksen.

Webhookit

Mistä taustajärjestelmäsi saa tiedon.

Jokaisessa tapahtumassa on luomasi tilauksen viite, joten käsittelijäsi voi olla pelkkä switch tyypin mukaan ja haku omasta järjestelmästäsi.

order.paid
Valtuutus ja veloitus onnistuivat — toimita viitteen perusteella.
order.failed
Maksu ei onnistunut; syy ilmoitetaan niin, että operaattori voi toimia sen pohjalta.
order.refunded
Hyvitys tehtiin kokonaan tai osittain, syyn ja huomautuksen kanssa.
order.disputed
Maksuriita (chargeback) avattiin, ja todisteet on jo liitetty tilaukseen.
payout.settled
Selvityserä lähti tilillesi, mukana sen taustalla olevat tilaukset.
subscription.charged
Toistuva jakso tuotti oman tilauksen ja kuitin.
Tarkista

Tarkista allekirjoitus, ennen kuin luotat sisältöön.

Jokaisessa toimituksessa on aikaleima ja raakasisällön yli laskettu HMAC-allekirjoitus. Vertaa vakioajassa, hylkää kaikki toleranssi-ikkunaasi vanhempi ja käsittele päällekkäinen tapahtuma-id jo käsiteltynä — yritämme uudelleen, jos vastaus ei ole 2xx, joten myös käsittelijäsi on oltava idempotentti.

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

Takuut

Ominaisuudet, joiden varaan voit rakentaa.

01

Idempotentit luonnit

Jokainen tilauksen luonti ottaa idempotenssiavaimen. Uudelleen lähetetty pyyntö — aikakatkaisun, julkaisun tai jonon uudelleentoimituksen jälkeen — palauttaa alkuperäisen tilauksen eikä veloita kahdesti.

02

Allekirjoitetut, toistosuojatut tapahtumat

Webhookeissa on aikaleimattu HMAC-allekirjoitus ja pysyvä tapahtuma-id. Toimitukset yritetään uudelleen backoffilla, kunnes päätepisteesi vastaa 2xx, joten julkaisuikkuna ei hävitä maksua.

03

Yksi viite alusta loppuun

Luontivaiheessa antamasi viite näkyy checkoutissa, kuitissa, webhookissa, selvityksessä ja myöhemmässä hyvityksessä. Järjestelmien välillä ei tarvitse yhdistää toista tunnistetta.

04

Testitila käyttää samaa koodipolkua

Testiavaimet ajavat täsmälleen samat prosessit testisessioita vasten. Mikä läpäisee testissä, menee tuotantoon — ero on lähetettävissä avaimissa, ei kutsuttavissa päätepisteissä.

Kokeile checkoutia

Testidata

Näin harjoitat tärkeät polut.

Jokaisen alla olevan polun takana on testikortti, joka luetellaan avaintesi mukana, kun sandbox otetaan käyttöön. Numerot ovat sandbox-kohtaisia eikä niitä julkaista tässä, jotta ne pysyvät oikein korttiyhtiöiden testinumerovälien muuttuessa. Toiminta on joka tapauksessa determinististä: testi voi varmistaa hylkäyksen yhtä helposti kuin onnistuneen maksun.

Hyväksytty suoraan
Valtuuttaa ja veloittaa ilman 3-D Secure -haastetta – onnistunut perusskenaario.
3-D Secure -haaste
Pakottaa haasteen, jonka voit käydä läpi, jotta pääset testaamaan paluuvaiheen.
Tilapäinen hylkäys
Hylkää katteen puutteen vuoksi ja yrittää sitten uudelleen vaihtoehtoista reittiä pitkin.
Lopullinen hylkäys
Hylkää pysyvästi vanhentuneena korttina, eikä uudelleenyritystä tehdä.
USDC-testiverkot
Testiverkon USDC Ethereumissa, Basessa ja Solanassa kiinteällä kurssilla.
Siirron simulointi
Merkitse vIBAN-testisiirto saapuneeksi, niin tilaus siirtyy tilaan maksettu.

Hae avaimet ja aloita.

Sandbox-kauppias, jolla on API-avaimet, webhook-salaisuudet ja kaikki maksutavat käytössä – sekä täydet viitedokumentit, jotta tiimisi voi integroida ennen kuin mitään on allekirjoitettu.

Pyydä sandbox-käyttöoikeuscontact@protocore.io