Fast Track-betalinger

Betaleren åpner denne URL-en og godkjenner betalingen i sin egen bank. I bakgrunnen opprettes den samme uforanderlige betalingsintensjonen som i resten av API-et: beløp, mottaker og betalingsbeskrivelse låses før de når nettleseren, og Idempotency-Key-hodet hindrer en dobbel belastning hvis kallet brytes.

Opprette betalingen

POST /payments/?action=fast-track

Obligatoriske hoder: Content-Type: application/json, X-API-Key og Idempotency-Key. Nøkkelen har 16 til 128 tegn, begynner med en bokstav eller et tall og tillater bare bokstaver, tall og . _ : -; en UUID v4 fungerer. Hvis den mangler eller lengden er ugyldig, er svaret 400 idempotency_key_required; hvis den inneholder andre tegn, 422 invalid_customer_reference. Denne nøkkelen er også brukerstedets referanse: du trenger ikke å sende den i kroppen. Hvis du gjentar den samme nøkkelen med den samme kroppen, får du den samme URL-en på nytt. Hvis du gjenbruker den med andre data, er svaret 409 idempotency_conflict.

Alle feltene er obligatoriske unntatt logo. Kroppen følger en liste over tillatte felt. Et ekstra felt, eller et obligatorisk felt som mangler, gir 422 invalid_request. logo er en del av betalingen: å gjenta den samme Idempotency-Key med en annen logo gir også 409 idempotency_conflict.

En straksbetaling har ingen egen øvre grense i dette API-et. Banken avviser betalinger den ikke kan godta, også på grunn av beløpet, og avvisningen kommer som KO til notification_url.

: "${WR_API_KEY:?Defina WR_API_KEY en el entorno seguro de su backend}"
: "${WR_PAYMENT_IDEMPOTENCY_KEY:?Genere un UUID v4 para este pago}"

curl --request POST 'https://api.wealthreader.com/payments/?action=fast-track' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${WR_API_KEY}" \
  --header "Idempotency-Key: ${WR_PAYMENT_IDEMPOTENCY_KEY}" \
  --data '{
    "amount": "15.50",
    "currency": "EUR",
    "beneficiary": {
      "name": "Comercio Online S.L.",
      "iban": "ES9121000418450200051332"
    },
    "reference": "Pedido 78901",
    "priority": "normal",
    "notification_url": "https://tienda.example.com/pagos/aviso",
    "logo": "https://tienda.example.com/marca/logo.svg"
  }'

Svaret, med 201 første gang og 200 hvis nøkkelen allerede fantes, inneholder URL-en og identifikatoren for betalingen:

{
  "url": "https://widget.wealthreader.com/payments/pay/#payment_intent_id=…&widget_token=…&api_origin=https%3A%2F%2Fapi.wealthreader.com",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

Videresend betaleren til URL-en. Tokenet ligger i fragmentet, utløper sammen med widgeten (vanligvis etter 15 minutter) og skal ikke logges i loggene dine. Lagre payment_intent_id sammen med bestillingen din.

Varsel om OK eller KO

Når Wealthreader sjekker betalingsstatusen og finner den i en endelig status, sender den et POST til notification_url med Content-Type: application/json og User-Agent: WealthReader-Payments:

{
  "outcome": "ok",
  "payment_status": "settled",
  "customer_reference": "11111111-1111-4111-8111-111111111111",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

• outcome er ok bare hvis banken har gjort opp betalingen (settled). rejected, cancelled, expired og failed varsles som ko. Et tvetydig resultat (reconciliation_required) er ikke endelig og varsles ikke.
• customer_reference er din Idempotency-Key, og payment_intent_id er identifikatoren som ble returnert da betalingen ble opprettet.
• Svar med 2xx for at varselet skal regnes som levert. Wealthreader venter i maksimalt 3 sekunder og følger ikke omdirigeringer.
• Det samme varselet kan komme mer enn én gang: behandle customer_reference pluss outcome som idempotente.
• En URL som ikke er en offentlig https-URL, avvises når betalingen opprettes, og kontrolleres på nytt før hver sending.

Når det kommer. Statusen sjekkes mens betaleren fortsatt er på betalingssiden, som spør etter den til det endelige resultatet foreligger eller betalingsøkten utløper, og hver gang du kaller POST /payments/?action=status. Det finnes ingen egen planlagt sending: hvis betaleren lukker siden før banken er ferdig, eller hvis serveren din ikke svarer med 2xx, sendes varselet ved neste kontroll. Hvis du ikke har mottatt varselet noen minutter etter at du videresendte betaleren, bør du derfor hente statusen med payment_intent_id; denne forespørselen utløser også det ventende varselet. Se Statuser, polling og avstemming.

Varselet er ikke signert. Før du leverer en vare eller tjeneste av verdi, må du bekrefte resultatet med POST /payments/?action=status med din X-API-Key og payment_intent_id: bare payment_status: settled i dette svaret er en finansiell bekreftelse.