Payment lifecycle guide

Understand how Safepay Raast processes RTP and QR payments end to end.

Every Raast payment is asynchronous. Use this guide to reason about customer experience, backend orchestration, and webhook handling for each flow.

Subscribe to webhooks for real-time updates and use polling only as a backup for dashboards.

Payment webhook events

Event	Description
payment.created	A new payment request was created (initiated by customer).
payment.pending_authorization	Payment is awaiting authorization (for example, Pay Later checks).
payment.authorized	Payment has been authorized and funds are on hold.
payment.completed	Payment has been captured or charged successfully.
payment.settled	Payment funds have been settled to the merchant.
payment.refunded	Payment was fully refunded.
payment.refund_partial	Payment was partially refunded.
payment.rejected	Payment was rejected before authorization.
payment.failed	Payment processing failed.
payment.reversed	Payment was reversed after completion.
payment.voided	Payment authorization was voided.

RTP Now

Endpoints

• POST /v1/aggregators/{{aggregator_id}}/payments
• GET /v1/aggregators/{{aggregator_id}}/payments/{{payment_id}} (optional polling)

1. Create the payment

   Call POST /v1/aggregators/{{aggregator_id}}/payments with type: "RTP_NOW", debtor details, amount, and a unique request_id.

2. Poll or wait for webhook

   Your frontend polls your backend, which either polls Safepay or waits for a webhook event.

3. Customer approves or rejects

   Their bank sends a push notification prompting approval.

4. Safepay forwards the status

   Webhooks contain the final decision; update your systems and UI accordingly.

5. Acknowledge outcome

   Show a success page on accept or prompt the customer to retry on reject.

Webhook events to expect

Expect payment.created, payment.pending_authorization, and a terminal state such as payment.completed, payment.settled, payment.rejected, or payment.failed.

RTP Later

Endpoints

• POST /v1/aggregators/{{aggregator_id}}/payments
• GET /v1/aggregators/{{aggregator_id}}/payments/{{payment_id}} (optional polling)

1. Create the payment

   Submit the same endpoint with type: "RTP_LATER" and any desired expiry settings.

2. Expose refresh options

   Customers may take longer to act, so offer manual refresh buttons or background polling.

3. Await customer action

   Their bank notification may arrive hours later.

4. Process Safepay webhook

   When the result arrives, mark the invoice paid or keep it outstanding.

5. Reconcile

   Update accounting systems; allow retriable submissions using the same request_id if needed.

Webhook events to expect

Expect payment.created, payment.pending_authorization, and a terminal state such as payment.completed, payment.settled, payment.rejected, or payment.failed.

Dynamic QR

Endpoints

• POST /v1/aggregators/{{aggregator_id}}/qrs
• GET /v1/aggregators/{{aggregator_id}}/payments/{{payment_id}} (optional polling)

1. Generate QR per transaction

   Call POST /v1/aggregators/{{aggregator_id}}/qrs with type: "DYNAMIC" and the amount.

2. Display to the customer

   Render the QR on your POS or checkout screen.

3. Customer scans and pays

   The banking app handles authentication. You do not know the debtor until the webhook arrives.

4. Safepay notifies you

   Webhooks include payer details so you can issue receipts and reconcile.

Webhook events to expect

Expect payment.created, payment.completed, and payment.settled, plus payment.failed or payment.rejected when the customer abandons or cancels.

Static QR

Endpoints

• POST /v1/aggregators/{{aggregator_id}}/qrs
• GET /v1/aggregators/{{aggregator_id}}/qrs/{{qr_id}}/payments (list QR payments)

1. Create once

   Call POST /v1/aggregators/{{aggregator_id}}/qrs without specifying an amount. Store the QR for reuse.

2. Customer scans and enters amount

   They type the amount in their banking app.

3. Safepay notifies you per payment

   Use the webhook payload to match against the expected amount. Static QRs can receive multiple payments.

4. Reconcile partial payments

   Handle cases where the customer underpays or overpays compared to your invoice.

Combine webhooks with periodic polling of GET /v1/aggregators/{{aggregator_id}}/payments when building dashboards; polling is still helpful if your webhook endpoint is temporarily unavailable.

Webhook events to expect

Expect payment.created, payment.completed, and payment.settled for each payment made against the QR.

See also

• RTP Now use case
• RTP Later use case
• Dynamic QR use case
• Static QR use case
• Webhooks