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

# Issue and Manage Card Payments

> Accept and manage card payments end to end: create, authorise, capture, void, refund, and tokenise via SDK or server-to-server.

<Warning>
  **Scope note:** Hello Clever’s Card APIs are for **accepting and managing card payments** (create, authorise, capture, void, refund, tokenise), not for issuing physical/virtual cards to your users. This guide covers the full card acceptance and management lifecycle.
</Warning>

## What you’ll build

The **Card APIs** give you end-to-end control of the card payment flow: create a payment, capture authorised funds, void before capture, refund after capture, tokenise cards for repeat use, and reconcile via list/detail endpoints. Webhooks notify you on status changes, and post-purchase flows support upsell scenarios.

Accepted schemes include Visa, Mastercard, and other major providers, plus Apple Pay and Google Pay. Funds settle into per-currency Treasury Accounts with automatic reconciliation.

## Choose an integration method

<CardGroup cols={2}>
  <Card title="SDK (client-side)" icon="browser">
    Web/mobile frontend via the Hello Clever JavaScript SDK. Supports **USD and AUD**. Best for a drop-in checkout without handling raw card data.
  </Card>

  <Card title="Server-to-Server (S2S)" icon="server">
    Your backend submits raw `card_info`. Supports **AUD**. For PCI DSS-compliant systems wanting full control of auth/capture.
  </Card>
</CardGroup>

<Tip>
  Pick the SDK unless you are PCI DSS-compliant and specifically need raw card handling. The SDK keeps card data off your servers.
</Tip>

## 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 changes.
* For S2S: a PCI DSS-compliant environment.

## The card endpoints

| Endpoint                                      | Purpose                                                                                                      |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Create Payment via Card Information (S2S)** | Create a payment intent from raw card info (server-side, AUD).                                               |
| **Create Payment via Tokenisation**           | Create a payment using a previously tokenised card or a newly provided one.                                  |
| **Capture Payment**                           | Capture a previously authorised payment (full amount).                                                       |
| **Void Payment**                              | Cancel an authorised payment **before** capture (full amount).                                               |
| **Refund Payment**                            | Refund a **captured** payment, full or partial.                                                              |
| **Delete Token**                              | Deactivate/delete a stored `token_id`.                                                                       |
| **List Payment**                              | Fetch card transactions for your `app-id`, filterable by date range and status, paginated (default 20/page). |
| **Detail Payment**                            | Full details of one card transaction.                                                                        |

## The payment lifecycle

<Steps>
  <Step title="Create (authorise)">
    <Tabs>
      <Tab title="SDK">
        Initialise the JS SDK on your frontend, create the payment, and handle the callback. See the SDK Integration guide for setup and initialisation.
      </Tab>

      <Tab title="S2S">
        `POST` the raw `card_info` from your PCI-compliant backend to **Create Payment via Card Information**.
      </Tab>

      <Tab title="Tokenised">
        Use **Create Payment via Tokenisation** with a stored `token_id` (great for returning customers and one-click checkout) or a new card you then tokenise for reuse.
      </Tab>
    </Tabs>

    This step **authorises** the payment. Depending on your flow it may auto-capture or leave funds authorised pending capture.
  </Step>

  <Step title="Capture or void">
    * If the payment was authorised but not captured, call **Capture Payment** to settle the full amount (e.g. when you ship the order).
    * If you need to cancel before capture, call **Void Payment**.

    <Info>
      Capture and void are mutually exclusive; void only works pre-capture.
    </Info>
  </Step>

  <Step title="Refund">
    After capture, use **Refund Payment** for a full or partial refund (e.g. returns, price adjustments).
  </Step>

  <Step title="Post-purchase / upsell">
    The Card APIs support post-purchase flows: charge an upsell after the initial purchase, reusing a stored token so the customer doesn’t re-enter card details.
  </Step>
</Steps>

## Tokenisation and stored cards

Tokenise a card once, then charge it later with **Create Payment via Tokenisation** using the `token_id`. When a customer removes a card or you no longer need it, call **Delete Token** to deactivate it.

<Warning>
  Store only the `token_id` on your side, never raw card data unless you are PCI DSS-compliant and using S2S.
</Warning>

## Reconciliation

* **List Payment**: pull transactions by date range and status for reporting; paginate at 20/page by default.
* **Detail Payment**: drill into a single transaction for support and dispute handling.

## Webhooks

<Warning>
  Configure webhook notifications so your system is told when a payment’s status changes (authorised, captured, voided, refunded, etc.). Return `200 OK` to every delivery and handle duplicates idempotently; failed deliveries are retried. See the Card Webhook guide for the payload and signature details.
</Warning>

## Notes

* **Surcharging** and **digital wallets** (Apple Pay / Google Pay) are supported for the card payin service.
* Match currency support to your integration method: SDK supports USD and AUD; S2S supports AUD.


## Related topics

- [Get Started with Hello Clever](/getting-started/overview.md)
- [How Card Payments Work](/platform-overview/payment-concepts/how-cards-work.md)
- [Card Payin Service: Accept Card Payments](/services/card-payin.md)