> ## Documentation Index
> Fetch the complete documentation index at: https://developers.paychoice.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# Charging via the API

> Create a charge against a card, a bank account or a stored token from your own systems.

`POST /charge` creates a charge. The same endpoint handles three cases, selected by which fields you send:

| You send | What happens |
| - | - |
| `card[...]` fields or `card_token` | Card charge. Approved or declined immediately. |
| `bank[...]` fields or `bank_token` | Bank account charge. Returns `Processing`; settles over up to three business days. |
| `pre_authid` | Captures a [pre-authorisation](https://developers.paychoice.com.au/after-the-payment/pre-authorisations.md). |

Every charge needs `currency`, `amount` and a `reference`. The reference is yours — an invoice or order number — and it comes back on the charge, in every [webhook](https://developers.paychoice.com.au/getting-the-result/webhooks.md), and as a filter on [Listing Charges](https://developers.paychoice.com.au/getting-the-result/reconciliation.md).

> [!NOTE]
>
> If you'd rather not handle card or account details at all, the [Widget](https://developers.paychoice.com.au/taking-payments/widget.md) and the [Create Token page](https://developers.paychoice.com.au/storing-payment-methods/create-token-page.md) capture them on a PayChoice-hosted form.

## Card charge

```bash v5 (JSON) theme={null}
curl https://api-sandbox.paychoice.com.au/api/v5/charge \
  -u "$PAYCHOICE_USERNAME:$PAYCHOICE_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "AUD",
    "amount": "10.00",
    "reference": "INV-4325454",
    "card[name]": "John Citizen",
    "card[number]": "4761739001010010",
    "card[expiry_month]": "12",
    "card[expiry_year]": "28",
    "card[cvv]": "123"
  }'
```

```bash v4 (form-data) theme={null}
curl https://api-sandbox.paychoice.com.au/api/v4/charge/ \
  -u "$PAYCHOICE_USERNAME:$PAYCHOICE_PASSWORD" \
  -d currency=AUD -d amount=10.00 -d reference=INV-4325454 \
  -d "card[name]=John Citizen" -d "card[number]=4761739001010010" \
  -d "card[expiry_month]=12" -d "card[expiry_year]=28" -d "card[cvv]=123"
```

```bash Stored token theme={null}
curl https://api-sandbox.paychoice.com.au/api/v5/charge \
  -u "$PAYCHOICE_USERNAME:$PAYCHOICE_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "AUD",
    "amount": "10.00",
    "reference": "INV-4325455",
    "card_token": "c629ac3b-682b-41e4-9a81-9445960843cf"
  }'
```

> [!NOTE]
>
> The v5 JSON body uses the same bracketed key names as v4 form-data (`card[name]`, `bank[bsb]`). Send them as literal keys.

### Response

```json theme={null}
{
  "charge": {
    "id": "f33a990c-237c-4e88-9bd1-eb2d655bb88c",
    "reference": "INV-4325454",
    "amount": "10.00",
    "currency": "AUD",
    "status": "Approved",
    "status_code": "0",
    "error": "Transaction Approved",
    "error_code": "00",
    "created": "2026-11-04T02:15:31.118Z",
    "merchantguid": "315564b9-b863-4016-8c53-02c9d8cc80b7",
    "aggregator_reference": "123456789012",
    "meta_data_reference": null,
    "link": { "href": "/api/v5/charge/f33a990c-237c-4e88-9bd1-eb2d655bb88c", "rel": "self" }
  },
  "object_type": "charge",
  "from_item": 0,
  "to_item": 0,
  "total_count": 0
}
```

**id** `uuid`

The charge ID. Use it to retrieve or refund the charge, and to match webhook notifications.

**status** `string`

Outcome as returned by the processor: `Approved`, `Dishonoured`, `Blocked`, `Errored` or `Processing`.

**status\_code** `string`

`"0"` Approved, `"4"` Blocked, `"5"` Dishonoured, `"6"` Errored, `"9"` Processing. A string on this endpoint; an integer when you retrieve the charge later. See [Charge status](https://developers.paychoice.com.au/reference/charge-status.md).

**error** `string | null`

Processor result description.

**error\_code** `string | null`

Processor error code. See [Errors](https://developers.paychoice.com.au/reference/errors.md).

**amount** `string`

Decimal with two places.

**feeapplied / feeamount / orginal\_amount**

Present only when a surcharge was applied. `orginal_amount` is spelt that way in the response.

### Declines

A declined card charge returns HTTP `402 Payment Required` with the same `charge` object; read `status`, `error` and `error_code` for the reason. Don't treat `402` as a transport error.

## Bank account charge

```bash theme={null}
curl https://api-sandbox.paychoice.com.au/api/v5/charge \
  -u "$PAYCHOICE_USERNAME:$PAYCHOICE_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "AUD",
    "amount": "5.00",
    "reference": "INV-4325456",
    "bank[name]": "John Smith",
    "bank[bsb]": "123-456",
    "bank[number]": "123456"
  }'
```

The response is the same shape, with `status` `Processing` and `status_code` `"9"`. The charge is not approved yet. The final outcome arrives through the [webhook](https://developers.paychoice.com.au/getting-the-result/webhooks.md) once the bank responds — typically within three business days. `bank[bsb]` is not required for New Zealand accounts.

## Surcharges

When a surcharge applies to a charge, the response includes `feeapplied`, `feeamount` and `orginal_amount` so you can show the customer the breakdown. Whether surcharging is enabled, and at what rate, is configured on your merchant account.

## Next

* [Webhooks](https://developers.paychoice.com.au/getting-the-result/webhooks.md) — learn the final outcome of every charge.
* [Tokens](https://developers.paychoice.com.au/storing-payment-methods/tokens.md) — keep a payment method on file for next time.
* [Refunds](https://developers.paychoice.com.au/after-the-payment/refunds.md) and [pre-authorisations](https://developers.paychoice.com.au/after-the-payment/pre-authorisations.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.