Fast Track-betalinger

Betaleren åbner URL'en og godkender i sin bank. Bag kulisserne oprettes den samme uforanderlige betalingsintention som i resten af API'et: beløb, modtager og betalingstekst fastlægges, før noget når browseren, og headeren Idempotency-Key forhindrer en dobbelt opkrævning, hvis kaldet afbrydes.

Opret betalingen

POST /payments/?action=fast-track

Påkrævede headers: Content-Type: application/json, X-API-Key og Idempotency-Key. Nøglen er på 16 til 128 tegn, begynder med et bogstav eller et tal og må kun indeholde bogstaver, tal og . _ : -; et UUID v4 er gyldigt. Hvis den mangler, eller længden er ugyldig, er svaret 400 idempotency_key_required; hvis den indeholder andre tegn, 422 invalid_customer_reference. Nøglen er også forhandlerreferencen: den skal ikke sendes i body. Hvis du gentager den samme nøgle med den samme body, får du den samme URL igen. Hvis du genbruger den med andre data, er svaret 409 idempotency_conflict.

Alle felter er påkrævede undtagen logo. Body er en hvidliste. Et ekstra felt eller et manglende påkrævet felt giver 422 invalid_request. logo er en del af betalingen: at gentage den samme Idempotency-Key med et andet logo giver også 409 idempotency_conflict.

En straksbetaling har ikke sin egen beløbsgrænse i dette API. Banken afviser den betaling, den ikke kan acceptere, også på grund af beløbet, og afvisningen 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øglen allerede fandtes, indeholder URL'en og betalingens identifikator:

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

Omdiriger betaleren til URL'en. Tokenet ligger i fragmentet, udløber sammen med widgetten (normalt efter 15 minutter) og må ikke registreres i dine logfiler. Gem payment_intent_id sammen med din ordre.

Besked om OK eller KO

Når Wealthreader kontrollerer betalingens status og finder den i en endelig tilstand, sender den 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 kun ok, hvis banken har afregnet betalingen (settled). rejected, cancelled, expired og failed giver besked med ko. Et tvetydigt resultat (reconciliation_required) er ikke endeligt, og der gives ikke besked om det.
• customer_reference er din Idempotency-Key, og payment_intent_id er den identifikator, der blev returneret, da betalingen blev oprettet.
• Svar med 2xx for at markere beskeden som leveret. Wealthreader venter højst 3 sekunder og følger ikke omdirigeringer.
• Den samme besked kan komme mere end én gang: behandl customer_reference plus outcome som idempotent.
• En URL, der ikke er en offentlig https-URL, afvises, når betalingen oprettes, og kontrolleres igen før hver afsendelse.

Hvornår den kommer. Status kontrolleres, mens betaleren stadig er på betalingssiden, som forespørger den, indtil der foreligger et endeligt resultat, eller betalingssessionen udløber, og hver gang du kalder POST /payments/?action=status. Der er ingen separat planlagt afsendelse: hvis betaleren lukker siden, før banken er færdig, eller hvis din server ikke svarer med 2xx, sendes beskeden ved næste kontrol. Hvis du ikke har modtaget beskeden et par minutter efter, at du har omdirigeret betaleren, bør du derfor forespørge status med payment_intent_id; den forespørgsel udløser også den ventende besked. Se Status, polling og afstemning.

Beskeden er ikke signeret. Før du leverer en vare eller tjeneste af værdi, skal du bekræfte resultatet med POST /payments/?action=status med din X-API-Key og payment_intent_id: kun payment_status: settled i det svar er en finansiel bekræftelse.