PayFacto API - v2.0 - POST /refunds/{refundId}/voids
PayFacto API - v2.0 - POST /refunds/{refundId}/voids
Voids an unbatched refund before it is included in settlement. The refund must not yet be part of a closed batch.
π
Authentication β HTTP Basic Auth
All v2.0 endpoints use HTTP Basic Authentication. Set Authorization: Basic base64(username:password). Contact PayFacto for credentials.
π
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.
POST https://uat.ca.api.payfacto.cloud/payments/v1/refunds/{refundId}/voids
β οΈ
If the batch is already closed, the refund cannot be voided.
Path parameter
| Parameter | Type | Description |
|---|
| refundId | string (UUID) Β· required | ID of the refund 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 flows. Must include terminalId. |
3
Request β Code Example
JSON β Void refund
{
"reason": "REQUESTED_BY_CUSTOMER"
}JSON β Terminal void refund
{
"reason": "REQUESTED_BY_CUSTOMER",
"terminal": { "terminalId": "3a2049fb-6c9f-433d-9cef-701b6843f0cd" }
}Response fields (refund object)
| Field | Type | Description |
|---|
| id | string (UUID) | Unique refund identifier. |
| amount | integer | Refund amount in cents. |
| chargeId | string (UUID) | The charge that was refunded. |
| failureReason | string | If failed: LOST_OR_STOLEN_CARD, EXPIRED_OR_CANCELLED_CARD, UNKNOWN. |
| metadata | object | Key-value pairs. |
| originalTransactionTime | string (ISO 8601) | UTC timestamp of original charge. |
| paymentMethod | object | Payment method used for the refund. |
| reason | string | Refund reason from request. |
| result | object | Auth result including authCode. |
| status | string | SUCCEEDED, FAILED, or VOIDED. |
| transactionTime | string (ISO 8601) | UTC timestamp when this refund was created. |
| voidDetail | object | Void details if voided. |
| error | object | Error object on failure. |
5
Response β Code Examples
JSON β 200 Voided
{
"id": "3a2049fb-6c9f-433d-9cef-701b6843f0cd",
"amount": 1299,
"status": "VOIDED",
"originalTransactionTime": "2024-05-15T17:00:01Z",
"transactionTime": "2024-05-15T18:00:01Z"
}JSON β 422 Cannot Void
{
"error": { "code": "INVALID_STATE", "type": "INVALID_REQUEST_ERROR", "message": "The refund is in a state that can not be voided." }
}6
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 |