Fast Track-betalingen

De betaler opent die URL en autoriseert de betaling bij zijn bank. Op de achtergrond wordt dezelfde onveranderlijke betaalintentie aangemaakt als in de rest van de API: het bedrag, de begunstigde en de omschrijving liggen vast voordat ze de browser bereiken, en de header Idempotency-Key voorkomt een tweede afschrijving als de aanroep wordt onderbroken.

De betaling aanmaken

POST /payments/?action=fast-track

Verplichte headers: Content-Type: application/json, X-API-Key en Idempotency-Key. De sleutel is 16 tot 128 tekens lang, begint met een letter of cijfer en staat alleen letters, cijfers en . _ : - toe; een UUID v4 volstaat. Als hij ontbreekt of de lengte ongeldig is, is het antwoord 400 idempotency_key_required; als hij andere tekens gebruikt, 422 invalid_customer_reference. Die sleutel is ook de handelaarsreferentie: je hoeft hem niet in de body mee te sturen. Als je dezelfde sleutel met dezelfde body herhaalt, ontvang je opnieuw dezelfde URL. Als je hem met andere gegevens hergebruikt, is het antwoord 409 idempotency_conflict.

Alle velden zijn verplicht behalve logo. De body is een allowlist. Een extra veld, of een ontbrekend verplicht veld, geeft 422 invalid_request. logo maakt deel uit van de betaling: dezelfde Idempotency-Key herhalen met een ander logo geeft ook 409 idempotency_conflict.

Een instantbetaling heeft in deze API geen eigen maximum. De bank weigert wat ze niet kan accepteren, ook vanwege het bedrag, en die weigering komt als KO aan bij de 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"
  }'

Het antwoord, met 201 de eerste keer en 200 als de sleutel al bestond, bevat de URL en de identificatie van de betaling:

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

Stuur de betaler door naar de URL. Het token staat in het fragment, verloopt met de widget (meestal na 15 minuten) en mag niet in je logs worden vastgelegd. Bewaar payment_intent_id bij je bestelling.

Melding van OK of KO

Wanneer Wealthreader de status van de betaling controleert en die in een eindstatus aantreft, stuurt het een POST naar notification_url met Content-Type: application/json en 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 is alleen ok als de bank de betaling heeft afgewikkeld (settled). rejected, cancelled, expired en failed worden gemeld als ko. Een dubbelzinnig resultaat (reconciliation_required) is niet definitief en wordt niet gemeld.
• customer_reference is je Idempotency-Key, en payment_intent_id de identificatie die is teruggegeven bij het aanmaken van de betaling.
• Antwoord met 2xx om de melding als afgeleverd te laten gelden. Wealthreader wacht maximaal 3 seconden en volgt geen omleidingen.
• Dezelfde melding kan meer dan eens aankomen: behandel customer_reference plus outcome als idempotent.
• Een URL die geen openbare https-URL is, wordt geweigerd bij het aanmaken van de betaling en vóór elke verzending opnieuw gecontroleerd.

Wanneer ze aankomt. De status wordt gecontroleerd zolang de betaler op de betaalpagina blijft, die hem opvraagt tot het eindresultaat of tot de betaalsessie verloopt, en telkens wanneer je POST /payments/?action=status aanroept. Er is geen aparte geplande verzending: als de betaler de pagina sluit voordat de bank klaar is, of als je server niet met 2xx antwoordt, wordt de melding bij de volgende controle verzonden. Als je de melding enkele minuten na het doorsturen van de betaler nog niet hebt ontvangen, vraag dan de status op met de payment_intent_id; die opvraging activeert ook de openstaande melding. Zie Status, periodieke statusopvraging en betalingsafstemming.

De melding is niet ondertekend. Bevestig het resultaat met POST /payments/?action=status met je X-API-Key en de payment_intent_id voordat je een waardevol goed of een waardevolle dienst levert: alleen payment_status: settled in dat antwoord is een financiële bevestiging.