PayFacto API - v2.0 - GET /refunds

Returns a paginated list of refunds 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/refunds

ℹ️

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

Query parameters

Parameter	Type / Constraint	Description
terminalId	string (UUID) · optional	Restrict to a terminal.
authCode	string max 6 · optional	Filter by auth code.
idempotencyKey	string max 64 · optional	Filter by idempotency key. Overrides 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 date UTC. Default: 30 days before endDate.
endDate	string YYYY-MM-DD · optional	End date UTC. Default: today.
offset	integer · optional	Pagination offset. Default: 0.
limit	integer · optional	Max per page. Default: 10.

Request — Code Example

cURL

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

Response

Response fields

Field	Type	Description
itemsTotal	integer	Total matching refunds.
data	array	Refund objects for current page.
error	object	Present only on failure.

Response — Code Example

JSON — 200 Success

{
  "itemsTotal": 1,
  "data": [{ "id": "3a2049fb-6c9f-433d-9cef-701b6843f0cd", "amount": 1299, "chargeId": "a1822999-099d-4fb1-a354-77be553a5b22", "status": "SUCCEEDED", "transactionTime": "2024-05-15T17:00: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