Payment Methods API
11 PracBill API endpoints for payment methods. Base URL https://billing.pracbill.com.au/api.
Get payment method
GET /{api_key}/customer/paymentMethods/{id}
Retrieve details for a specific payment method. Bank account numbers are returned unmasked. Failure description: `Payment method not found`.
Responses
200— Payment method retrieved successfullydefault— Failure envelope. The legacy API answers failures with HTTP 200 and `success: false` plus a `description` (e.g. `invalid key`, `Customer not found`).
Set payment method nickname
POST /{api_key}/customer/paymentMethods/{id}/nickname
Update the nickname/display name of a payment method. The body is parsed with the shared request extractor: raw JSON, url-encoded JSON, or the legacy `name={json}` form. Failure descriptions: `Nickname is required`, `Payment method not found`.
Request body
| Field | Type | Description |
|---|---|---|
nickname required | string | New nickname for the payment method (empty string clears it) |
Responses
200— Nickname updated successfully (description: `Payment method nickname updated`)default— Failure envelope. The legacy API answers failures with HTTP 200 and `success: false` plus a `description` (e.g. `invalid key`, `Customer not found`).
Set payment method status
POST /{api_key}/customer/paymentMethods/{id}/status
Update the status of a payment method. Valid statuses: primary, backup, inactive. Setting a method to primary or backup will also set it as active. Setting to inactive deactivates the method. The body is parsed with the shared request extractor: raw JSON, url-encoded JSON, or the legacy `name={json}` form. Failure descriptions: `Status is required. Valid values: primary, backup, inactive`, `Invalid status. Valid values: primary, backup, inactive`, `Payment method not found`; when the gateway refuses the change the description may be an empty string.
Request body
| Field | Type | Description |
|---|---|---|
status required | string (primary | backup | inactive) | New status for the payment method. 'primary' sets as primary and activates, 'backup' sets as backup and activates, 'inactive' deactivates the method. |
Responses
200— Status updated successfully (description: `Payment method status updated to {status}`)default— Failure envelope. The legacy API answers failures with HTTP 200 and `success: false` plus a `description` (e.g. `invalid key`, `Customer not found`).
List payment methods
GET /{api_key}/customer/{cid}/paymentMethods
Retrieve all payment methods for a customer (both active and inactive), active first, then primary, backup, newest.
Responses
200— Payment methods retrieved successfullydefault— Failure envelope. The legacy API answers failures with HTTP 200 and `success: false` plus a `description` (e.g. `invalid key`, `Customer not found`).
Filter payment methods
POST /{api_key}/customer/{cid}/paymentMethods
Retrieve payment methods with optional filters for active status, type (bank/card), primary/backup method, and payment gateway. Same response shape as the GET. The body is parsed with the shared request extractor: raw JSON, url-encoded JSON, or the legacy `name={json}` form.
Request body
| Field | Type | Description |
|---|---|---|
active | boolean | Filter by active status (true/false; when omitted both are returned) |
primary_method | boolean | When truthy, only primary payment methods (false is ignored) |
backup_method | boolean | When truthy, only backup payment methods (false is ignored) |
type | string (bank | card) | Filter by type; any other value is ignored |
payment_gateway | string | Filter by payment gateway name (exact match) |
Responses
200— Payment methods retrieved successfullydefault— Failure envelope. The legacy API answers failures with HTTP 200 and `success: false` plus a `description` (e.g. `invalid key`, `Customer not found`).
Add payment method
POST /{api_key}/customer/{cid}/paymentMethods/add
Add a new payment method to a customer. Can be a credit card (via token or full card details) or bank account. Supply `gateway` to nominate a gateway configured for the department, otherwise the gateway is automatically selected based on the data provided. The body is parsed with the shared request extractor: raw JSON, url-encoded JSON, or the legacy `name={json}` form. Failure descriptions include `No data provided`, `No Bank/Direct Debit Gateway configured for this department`, `No Credit Card Gateway configured for this department`, `Payment gateway '{name}' is not configured for this department`, `Payment gateway '{name}' is not available`, or the gateway's own message.
Request body
| Field | Type | Description |
|---|---|---|
gateway | string | Optional payment gateway name (payment_gateways.gateway_name) to create and tokenise the payment method against, e.g. "ezidebit". Must be a gateway configured for the authenticated department; an unknown, deleted or other-department gateway is rejected. When omitted the department default direct debit gateway is used if `bank_account_name` or `bank_name` is supplied, otherwise the default credit card gateway. |
payment_token | string | Payment gateway token (for tokenized card storage) |
card_token | string | Alias of payment_token |
token | string | Alias of payment_token |
cc_name | string | Name on the credit card |
cc_number | string | Credit card number |
cc_expmonth | string | Card expiry month |
cc_expyear | string | Card expiry year |
cc_ccv | string | Card CVV/security code |
bank_account_name | string | Account holder name |
bank_account_number | string | Bank account number |
bank_name | string | Alias for bank_account_name (account holder name; takes precedence when both are supplied) |
bank_number | string | Account number, used together with `bank_name` |
bank_bsb | string | BSB number (Australian banks) |
Responses
200— Request processed. Check `success`.default— Failure envelope. The legacy API answers failures with HTTP 200 and `success: false` plus a `description` (e.g. `invalid key`, `Customer not found`).
List payment methods
GET /{api_key}/customer/{cid}/paymentMethods/list
Alias of `/{api_key}/customer/{cid}/paymentMethods`. Retrieve all payment methods for a customer (both active and inactive), active first, then primary, backup, newest.
Responses
200— Payment methods retrieved successfullydefault— Failure envelope. The legacy API answers failures with HTTP 200 and `success: false` plus a `description` (e.g. `invalid key`, `Customer not found`).
Filter payment methods
POST /{api_key}/customer/{cid}/paymentMethods/list
Alias of `/{api_key}/customer/{cid}/paymentMethods`. Retrieve payment methods with optional filters for active status, type (bank/card), primary/backup method, and payment gateway. Same response shape as the GET. The body is parsed with the shared request extractor: raw JSON, url-encoded JSON, or the legacy `name={json}` form.
Request body
| Field | Type | Description |
|---|---|---|
active | boolean | Filter by active status (true/false; when omitted both are returned) |
primary_method | boolean | When truthy, only primary payment methods (false is ignored) |
backup_method | boolean | When truthy, only backup payment methods (false is ignored) |
type | string (bank | card) | Filter by type; any other value is ignored |
payment_gateway | string | Filter by payment gateway name (exact match) |
Responses
200— Payment methods retrieved successfullydefault— Failure envelope. The legacy API answers failures with HTTP 200 and `success: false` plus a `description` (e.g. `invalid key`, `Customer not found`).
Get payment method
GET /{api_key}/paymentMethods/{id}
Alias of `/{api_key}/customer/paymentMethods/{id}`. Retrieve details for a specific payment method. Bank account numbers are returned unmasked. Failure description: `Payment method not found`.
Responses
200— Payment method retrieved successfullydefault— Failure envelope. The legacy API answers failures with HTTP 200 and `success: false` plus a `description` (e.g. `invalid key`, `Customer not found`).
Set payment method nickname
POST /{api_key}/paymentMethods/{id}/nickname
Alias of `/{api_key}/customer/paymentMethods/{id}/nickname`. Update the nickname/display name of a payment method. The body is parsed with the shared request extractor: raw JSON, url-encoded JSON, or the legacy `name={json}` form. Failure descriptions: `Nickname is required`, `Payment method not found`.
Request body
| Field | Type | Description |
|---|---|---|
nickname required | string | New nickname for the payment method (empty string clears it) |
Responses
200— Nickname updated successfully (description: `Payment method nickname updated`)default— Failure envelope. The legacy API answers failures with HTTP 200 and `success: false` plus a `description` (e.g. `invalid key`, `Customer not found`).
Set payment method status
POST /{api_key}/paymentMethods/{id}/status
Alias of `/{api_key}/customer/paymentMethods/{id}/status`. Update the status of a payment method. Valid statuses: primary, backup, inactive. Setting a method to primary or backup will also set it as active. Setting to inactive deactivates the method. The body is parsed with the shared request extractor: raw JSON, url-encoded JSON, or the legacy `name={json}` form. Failure descriptions: `Status is required. Valid values: primary, backup, inactive`, `Invalid status. Valid values: primary, backup, inactive`, `Payment method not found`; when the gateway refuses the change the description may be an empty string.
Request body
| Field | Type | Description |
|---|---|---|
status required | string (primary | backup | inactive) | New status for the payment method. 'primary' sets as primary and activates, 'backup' sets as backup and activates, 'inactive' deactivates the method. |
Responses
200— Status updated successfully (description: `Payment method status updated to {status}`)default— Failure envelope. The legacy API answers failures with HTTP 200 and `success: false` plus a `description` (e.g. `invalid key`, `Customer not found`).