PayFacto API - v2.0 - POST /charges/{chargeId}/voids

PayFacto API - v2.0 - POST /charges/{chargeId}/voids

Voids an unbatched captured charge. The charge must be captured but not yet included in a settled batch.

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

POST https://uat.ca.api.payfacto.cloud/payments/v1/charges/{chargeId}/voids

⚠️

If the batch has already closed, use POST /refunds instead.

Path parameter

Parameter	Type	Description
chargeId	string (UUID) · required	ID of the captured charge to void.

Request body fields

Field	Constraint	Description
reason	string · required	REQUESTED_BY_CUSTOMER, REQUESTED_BY_MERCHANT, DUPLICATE, FRAUDULENT, or ERROR_CORRECTION.
terminal	object · optional	Required for terminal voids. Must include `terminalId`.

reason values

reason	Description
REQUESTED_BY_CUSTOMER	Customer requested
REQUESTED_BY_MERCHANT	Merchant initiated
DUPLICATE	Duplicate transaction
FRAUDULENT	Suspected fraud
ERROR_CORRECTION	Error correction

Request — Code Example

JSON — Card void

{
  "reason": "REQUESTED_BY_CUSTOMER"
}

JSON — Terminal void

{
  "reason": "REQUESTED_BY_CUSTOMER",
  "terminal": { "terminalId": "3a2049fb-6c9f-433d-9cef-701b6843f0cd" }
}

Response

Response fields (charge object)

Field	Type	Description
id	string (UUID)	Unique charge identifier. Store for all subsequent operations.
amount	integer	Amount in cents (e.g. 1299 = $12.99).
amountCaptured	integer	Total captured amount in cents.
amountRefunded	integer	Total refunded amount in cents.
billingDetail	object	Customer billing info (address, email, name, phone).
capture	boolean	Whether the charge was captured immediately.
captured	boolean	Whether an uncaptured charge has since been captured.
invoiceNumber	string	Merchant invoice reference (max 25 chars).
metadata	object	Key-value pairs for custom data.
originalTransactionTime	string (ISO 8601)	UTC timestamp of original transaction. Only on post-charge operations.
paymentMethod	object	Payment method details (type, card/terminal/token data).
refunded	boolean	Whether the charge has been fully refunded.
releaseDetail	object	Release details if the charge was released.
result	object	Auth result: `authCode`, `batch`, `declineCode`, `isoResponseCode`, `issuerMessage`.
shippingDetail	object	Shipping recipient information.
statementDescriptor	string	Merchant descriptor on customer statement (max 23 chars).
status	string	Transaction status: AUTHORIZED, CAPTURED, DECLINED, FAILED, RELEASED, SUCCEEDED, VOIDED.
transactionTime	string (ISO 8601)	UTC timestamp when this object was created.
voidDetail	object	Void details if voided.
error	object	Error object on failure. Contains `code`, `type`, `details`, `message`.

Response — Code Examples

JSON — 200 Voided

{
  "id": "a1822999-099d-4fb1-a354-77be553a5b22",
  "amount": 1299,
  "status": "VOIDED",
  "voidDetail": { "reason": "REQUESTED_BY_CUSTOMER" },
  "transactionTime": "2024-05-15T16:00:01Z"
}

JSON — 422 Invalid State

{
  "error": { "code": "INVALID_STATE", "type": "INVALID_REQUEST_ERROR", "message": "The charge cannot be voided in its current state." }
}

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