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

# Your first charge

> From credentials to an approved test transaction, with a webhook registered to tell you the outcome.

**1. Get sandbox credentials**

PayChoice sends your sandbox API username, password, merchant GUID and (for the Widget) public key through a one-time secure link. Store them in a secrets manager.

**2. Decide how you'll take payments**

* **[PayChoice Widget](https://developers.paychoice.com.au/taking-payments/widget.md)** — hosted payment page in an iframe. No card data on your side.
* **[Banking API](https://developers.paychoice.com.au/taking-payments/charging-via-the-api.md)** — you collect the details and call the charge endpoint.

For this walkthrough we'll use the API, because it's the quickest way to see a complete request and response.

**3. Create a test charge**

Send a card charge to the sandbox using one of the [test cards](https://developers.paychoice.com.au/reference/testing.md). Any future expiry and a CVV of `123` will do.

```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": "TEST-0001",
    "card": {
      "name": "John Citizen",
      "number": "4761739001010010",
      "expiry_month": "12",
      "expiry_year": "28",
      "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=TEST-0001 \
  -d "card[name]=John Citizen" \
  -d "card[number]=4761739001010010" \
  -d "card[expiry_month]=12" \
  -d "card[expiry_year]=28" \
  -d "card[cvv]=123"
```

The response wraps a `charge` object:

```json theme={null}
{
  "charge": {
    "id": "f33a990c-237c-4e88-9bd1-eb2d655bb88c",
    "reference": "TEST-0001",
    "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",
    "link": { "href": "/api/v5/charge/f33a990c-237c-4e88-9bd1-eb2d655bb88c", "rel": "self" }
  },
  "object_type": "charge",
  "from_item": 0,
  "to_item": 0,
  "total_count": 0
}
```

`status_code` `"0"` is approved. The full list is under [Charge status](https://developers.paychoice.com.au/reference/charge-status.md).

**4. Try a decline**

On the sandbox, the decimal part of the amount selects the outcome. Send `10.51` and the charge comes back declined, with HTTP `402` and `error_code` `"51"` (Insufficient Funds) in the `charge` object. See [Testing](https://developers.paychoice.com.au/reference/testing.md) for the mechanics.

**5. Register a webhook**

Card charges are approved or declined immediately, but bank charges settle over several days, and every charge can change status later. Register an HTTPS endpoint so PayChoice can tell you:

```bash theme={null}
curl https://api-sandbox.paychoice.com.au/api/v4/merchantwebhooks \
  -u "$PAYCHOICE_USERNAME:$PAYCHOICE_PASSWORD" \
  -d merchant_guid=$PAYCHOICE_MERCHANT_GUID \
  -d webhook_url=https://your-app.example.com/paychoice/webhook
```

The response includes a `webhook_secret`. Store it: it signs every notification and is only returned once. The [Webhooks](https://developers.paychoice.com.au/getting-the-result/webhooks.md) guide covers verification, retries and the bank-settlement flow.

**6. Keep a payment method on file (optional)**

If you'll charge the same customer again, [tokenise](https://developers.paychoice.com.au/storing-payment-methods/tokens.md) their card or bank account and charge the token instead. For subscriptions and invoicing, continue to [Recurring billing](https://developers.paychoice.com.au/billing/overview.md).

> [!TIP]
>
> You've made a charge, seen a decline, and have a webhook registered. That's the complete loop; everything else in these docs is a variation on it.


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