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.

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

v5 (JSON)

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

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
}

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.

error · string | null

Processor result description.

error_code · string | null

Processor error code. See Errors.

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

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.

Next

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