> ## Documentation Index
> Fetch the complete documentation index at: https://safepay.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Callout type="info">Subscribe to webhooks for real-time updates and use polling only as a backup for dashboards.</Callout>

## 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)

<Steps>
  <Step title="Create the payment">
    Call `POST /v1/aggregators/{{aggregator_id}}/payments` with `type: "RTP_NOW"`, debtor details, amount, and a unique `request_id`.
  </Step>

  <Step title="Poll or wait for webhook">
    Your frontend polls your backend, which either polls Safepay or waits for a webhook event.
  </Step>

  <Step title="Customer approves or rejects">
    Their bank sends a push notification prompting approval.
  </Step>

  <Step title="Safepay forwards the status">
    Webhooks contain the final decision; update your systems and UI accordingly.
  </Step>

  <Step title="Acknowledge outcome">
    Show a success page on accept or prompt the customer to retry on reject.
  </Step>
</Steps>

### 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)

<Steps>
  <Step title="Create the payment">
    Submit the same endpoint with `type: "RTP_LATER"` and any desired expiry settings.
  </Step>

  <Step title="Expose refresh options">
    Customers may take longer to act, so offer manual refresh buttons or background polling.
  </Step>

  <Step title="Await customer action">
    Their bank notification may arrive hours later.
  </Step>

  <Step title="Process Safepay webhook">
    When the result arrives, mark the invoice paid or keep it outstanding.
  </Step>

  <Step title="Reconcile">
    Update accounting systems; allow retriable submissions using the same `request_id` if needed.
  </Step>
</Steps>

### 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)

<Steps>
  <Step title="Generate QR per transaction">
    Call `POST /v1/aggregators/{{aggregator_id}}/qrs` with `type: "DYNAMIC"` and the amount.
  </Step>

  <Step title="Display to the customer">
    Render the QR on your POS or checkout screen.
  </Step>

  <Step title="Customer scans and pays">
    The banking app handles authentication. You do not know the debtor until the webhook arrives.
  </Step>

  <Step title="Safepay notifies you">
    Webhooks include payer details so you can issue receipts and reconcile.
  </Step>
</Steps>

### 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)

<Steps>
  <Step title="Create once">
    Call `POST /v1/aggregators/{{aggregator_id}}/qrs` without specifying an amount. Store the QR for reuse.
  </Step>

  <Step title="Customer scans and enters amount">
    They type the amount in their banking app.
  </Step>

  <Step title="Safepay notifies you per payment">
    Use the webhook payload to match against the expected amount. Static QRs can receive multiple payments.
  </Step>

  <Step title="Reconcile partial payments">
    Handle cases where the customer underpays or overpays compared to your invoice.
  </Step>
</Steps>

<Callout type="tip">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.</Callout>

### 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](/use-cases/rtp_now)
* [RTP Later use case](/use-cases/rtp_later)
* [Dynamic QR use case](/use-cases/dynamic_qr)
* [Static QR use case](/use-cases/static_qr)
* [Webhooks](/concepts/webhooks)