Create a refund

POST 
/refunds

Issues a full or partial refund for a payment.

Request

Responses

200

Refund created successfully.

400

Missing or invalid required parameters.

Cause: See error in the response body:

• missing_param: payment_id wasn't provided.
• invalid_param: amount exceeds the original payment's amount, or reason isn't one of the supported values.

Fix: Check message for which field failed, correct the request body, and resend.

Retry: Safe once the request body is corrected. Retrying the same unmodified request will fail again.

401

Missing or invalid API key.

Cause: One of three things; see error in the response body:

• no_api_key: the Authorization header was omitted entirely.
• invalid_api_key: a header was sent but the token isn't a recognized PayFlow key (wrong scheme, malformed, or a test-mode key used against production, or vice versa).
• api_key_expired: the key was valid but has since been rotated or revoked.

Fix: Send Authorization: Bearer <your API key>. For api_key_expired, generate a new key in the Dashboard and update the integration.

Retry: Safe, but will keep failing until a valid, current key for the right environment is supplied.

404

Payment not found.

Cause: No payment exists with the given payment_id (error: resource_not_found).

Fix: Double-check payment_id and that you're using the correct API key/environment.

Retry: Safe, but will keep failing until payment_id is corrected.

409

Duplicate request (idempotency conflict).

Cause: The Idempotency-Key header was reused, but the request body doesn't match the first request that used that key.

Fix: Use a new, unique Idempotency-Key for a genuinely different request. Re-send the original body if you meant to retry the same operation.

Retry: Not safe to retry unchanged; the same conflict will recur. Retrying with the original body succeeds (idempotent replay) instead of erroring.

429

Rate limit exceeded.

Cause: Too many requests were sent from this API key within the current window.

Fix: Slow down request rate and honor the Retry-After header if present. Consider batching or caching reads where possible.

Retry: Safe after waiting out the window; retrying immediately will fail again.

Response Headers

X-RateLimit-Limit

The maximum number of requests allowed per window.

X-RateLimit-Remaining

Requests remaining in the current window.

X-RateLimit-Reset

Unix timestamp (seconds) when the current window resets.

Retry-After

Seconds to wait before retrying.

500

PayFlow server error.

Cause: An unexpected failure on PayFlow's side, not caused by the request.

Fix: Nothing to change in the request. If it persists, contact PayFlow Developer Support with the request ID.

Retry: Safe. Use an idempotency key on write requests so a retry can't create a duplicate if the original actually succeeded.