PayFacto API - v2.0 - GET /charges

Returns a paginated list of charges sorted from most recent to oldest.

Prerequisites

🔑

Authentication — HTTP Basic Auth

All v2.0 endpoints use HTTP Basic Authentication. Set Authorization: Basic base64(username:password). Contact PayFacto for credentials.

🌐

Environment Base URLs

UAT: https://uat.ca.api.payfacto.cloud/payments/v1 | Production: https://ca.api.payfacto.cloud/payments/v1

📋

Content-Type

All request bodies require Content-Type: application/json.

🔄

Idempotency

Include Idempotency-Key header (max 64 chars) on POST requests. 200 = duplicate; 201 = newly created.

💵

Amounts

All monetary amounts are positive integers in cents. $12.99 = 1299.

Request

GET https://uat.ca.api.payfacto.cloud/payments/v1/charges

ℹ️

All parameters are query string parameters. No request body is required.

Query parameters

Parameter	Type / Constraint	Description
terminalId	string (UUID) · optional	Restrict to a specific terminal.
authCode	string max 6 · optional	Filter by authorization code.
idempotencyKey	string max 64 · optional	Filter by idempotency key. Overrides all other filters.
invoiceNumber	string max 25 · optional	Filter by invoice number.
lastFour	string 4 digits · optional	Filter by last 4 card digits.
startDate	string YYYY-MM-DD · optional	Start of date range in UTC. Default: 30 days before endDate.
endDate	string YYYY-MM-DD · optional	End of date range in UTC. Default: today.
offset	integer · optional	Pagination offset. Default: 0.
limit	integer · optional	Max results per page. Default: 10.

Request — Code Example

cURL

curl -X GET "https://uat.ca.api.payfacto.cloud/payments/v1/charges?startDate=2024-05-01&limit=10" \
  -H "Authorization: Basic YOUR_BASE64_CREDENTIALS"

Response

ℹ️

Returns a charges object with itemsTotal and data array of charge objects.

Response fields

Field	Type	Description
itemsTotal	integer	Total matching charges across all pages.
data	array	Charge objects for the current page.
error	object	Present only on failure.

Response — Code Example

JSON — 200 Success

{
  "itemsTotal": 1,
  "data": [{
    "id": "a1822999-099d-4fb1-a354-77be553a5b22",
    "amount": 1299,
    "status": "SUCCEEDED",
    "transactionTime": "2024-05-15T14:30:01Z"
  }]
}

Error / HTTP Status Codes

HTTP Status	Meaning	Recommended Action
200	OK — Previously created (same idempotency key)	Check `status` field in response body
201	Created — New resource created	Store the `id` for future operations
400	Bad Request — Invalid payload	Check `error.details` and `error.invalidFields`
402	Payment Required — Issuer declined	Check `result.declineCode` — do not retry automatically
404	Not Found	Verify the ID in the request path
422	Unprocessable — Invalid state	Check `error.message`
500	Internal Server Error	Retry with backoff; contact PayFacto Support if persistent