> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rc.cleverhub.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Accept Instant Payments with AUD PayID

> Collect real-time bank payments over the NPP using one-time and static PayIDs, with instant webhooks on settlement.

## What you’ll build

PayID payments let a customer pay you in real time from their own banking app over the New Payments Platform (NPP). You create a payment request, hand the customer a PayID to pay to, and Hello Clever notifies you the instant funds arrive: no cards, no chargebacks, near-instant settlement.

Two patterns are available:

<CardGroup cols={2}>
  <Card title="One-time PayID" icon="receipt">
    A fresh PayID per transaction, e.g. a checkout order.
  </Card>

  <Card title="Static Open PayID" icon="infinity">
    A durable PayID tied to a customer that accepts multiple / any-amount payments, e.g. a persistent top-up address or wallet reference.
  </Card>
</CardGroup>

<Info>
  This is an **AUD-only (v1)** capability.
</Info>

## Prerequisites

* Merchant account and `app-id` / `secret-key`.
* Sandbox `https://api.cleverhub.co`; production `https://api-merchant.helloclever.co`.
* A webhook endpoint (TLS 1.2, public, commercial cert) for payment status callbacks.

## Pattern A: One-time payment request

<Steps>
  <Step title="Create the payment request">
    Call **create-payment-request**. Required: `name`, `gst` (boolean, `true` only for AU merchants charging GST), `amount`, `description`, `emails` (comma-separated, **lowercase only**), and a `payment_request_notification` webhook block (`endpoint_url` + `authorization_header`): Hello Clever calls this endpoint every time the transaction status changes. Useful optionals: `expired_at` (UTC, ≥15 minutes ahead), `external_id`, and `metadata` (any custom key-value object, returned unchanged on the transaction). `prefix_static_payid` is still accepted but is now **deprecated**; omit it for new integrations.

    ```json Create payment request theme={null}
    {
      "name": "Luyx",
      "gst": true,
      "amount": 1000,
      "description": "Order 4821",
      "emails": "customer@gmail.com",
      "expired_at": "2026-01-31T06:00:00.000+0000",
      "external_id": "order_4821",
      "payment_request_notification": {
        "endpoint_url": "https://yoursite.com/webhooks/payid",
        "authorization_header": "SECRET"
      },
      "metadata": {
        "custom_note": "Priority customer"
      }
    }
    ```

    The response includes the generated `request_payid` (the PayID the customer pays to), the `total` (amount + GST), `expired_at`, a `nonce`, and `status: pending`.
  </Step>

  <Step title="Show the PayID to your customer">
    Display `request_payid` and the exact `total`. The customer opens their banking app, pays to that PayID, and the transfer clears over NPP.
  </Step>

  <Step title="Get notified / poll status">
    When funds arrive, Hello Clever POSTs your webhook with the updated payload (`status: received`, `paid_at`, `cashback_amount`, `sender_details`). You can also poll **Get payment request status** with the `id` and `payid`.
  </Step>
</Steps>

### Payment request statuses

| Status            | Meaning                                |
| ----------------- | -------------------------------------- |
| `pending`         | Customer hasn’t paid yet               |
| `received`        | Paid successfully                      |
| `expired`         | Request lapsed                         |
| `return_pending`  | A refund has been triggered            |
| `return_received` | Refund transferred to the payer        |
| `return_expired`  | Refund request lapsed (10-day expiry)  |
| `return_rejected` | Refund failed at destination; no retry |

### Cancel a pending request

Call **cancel-a-payid** with `{ "payid": "abc.xyz@example.co" }`. This deregisters the PayID and marks the transaction `expired`.

## Pattern B: Static Open PayID

Use this to give a customer a permanent PayID that accepts payments over time.

<Steps>
  <Step title="Create the Static Open PayID">
    Call **create-static-open-payid**, required: `name`, `email`, `prefix_static_payid` (3–35 chars, lowercase/digits/dots), and a `customer_notification` webhook block (`endpoint_url` + `authorization_header`). Optional: `address`, `phone`, `city`, `zip_code`, `state`, `external_id`. The response returns the durable `static_payid` and `status: active`.

    The generated address takes the form `prefix@example.com`. Each incoming payment fires your webhook with the payment payload (amount, `paid_at`, `sender_details`, cashback).
  </Step>

  <Step title="List / look them up">
    Call **list-static-open-payids**, filterable by `email`, `payid`, or `customer_id`, with pagination.
  </Step>
</Steps>

## Querying and reconciliation

* **Get payment requests in a period**: pass `from_date` / `to_date` (UTC, `YYYY-MM-DDThh:mm:ss` or `DD/MM/YY`) and `page` (20 records/page). Up to a 1-year window.
* **Get payment request statistics**: returns summary totals across all payment requests: gross amount, completed transaction count, and pending count.
* Match against your own records with `external_id` and the returned `nonce`.

## Refunds

Call **refund-a-payment**: supply `payment_request_id`, optional `refund_amount` (defaults to the full total), and a `reason` (≥5 chars). A refund PayID is generated; top up your balance if needed so the payer can be refunded. Track via `return_pending` → `return_received`.

<Warning>
  * Emails must be **lowercase** or the request is rejected.
  * `expired_at` is **UTC** and must be at least 15 minutes in the future.
  * `gst: true` is for AU merchants charging GST on AUD only.
  * Return `200 OK` to every webhook and handle duplicate deliveries idempotently. Failed deliveries are retried 3× at 15-minute intervals. Use a unique `authorization_header` per request.
</Warning>


## Related topics

- [Hello Clever Developer Documentation](/index.md)
- [Real-time Payin Service](/services/real-time-payin.md)
- [Payment APIs for AUD (v1)](/api/v1/introduction.md)