Charging via the API

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.

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, and as a filter on Listing Charges.

If you’d rather not handle card or account details at all, the Widget and the Create Token page capture them on a PayChoice-hosted form.

Card charge

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"
  }'

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"

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"
  }'

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

Response

{
  "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
}

uuid

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

string

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

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.

string | null

Processor result description.

string | null

Processor error code. See Errors.

string

Decimal with two places.

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

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

Webhooks — learn the final outcome of every charge.
Tokens — keep a payment method on file for next time.
Refunds and pre-authorisations.

Getting started

Taking payments

Getting the result

Storing payment methods

After the payment

Recurring billing

Coming soon

Charging via the API

Card charge

Response

Declines

Bank account charge

Surcharges

Next

​Card charge

​Response

​Declines

​Bank account charge

​Surcharges

​Next

Card charge

Response

Declines

Bank account charge

Surcharges

Next