Skip to main content
You choose whether a refund moves money straight away or is held until you execute it. Refunds send no webhook events, so follow them by polling.

1. Read the Refundable Amount

Response
amount is the most a new refund may ask for now, in the customer’s currency. A payment transaction whose customer hasn’t paid yet reads zero. The payment transaction’s can_refund says whether a refund that moves money can be created now. A payment transaction that’s still processing reads can_refund: false beside a refundable amount: you can prepare a refund held with execution: manual, and executing it waits, with PAYMENT_IN_TRANSIT, until the payment transaction converts.

2. Create the Refund

Make one Idempotency-Key for each refund you mean to make, and store it with your record of the refund before you send the request. A retry with the same key answers the refund the first attempt made. A retry with a new key is a second refund. See Idempotency. execution is required, with no default:
  • automatic creates the refund, and Quidkey moves the money as soon as it can, with no further call.
  • manual creates it and holds it until you call :executeRefund. A held refund blocks further refunds of the payment transaction until it’s executed, or cancelled by Quidkey support.
The answer is 201, with the refund itself, a transaction of type: refund whose parent_transaction is the payment transaction. Its Location header is /transactions/{refund_id}.

3. Execute a Held Refund

Call it on the refund’s ID. It answers 200 with the refund, processing, or pending with the required_actions that hold it. It’s safe to repeat: a refund already processing or completed answers 200. A failed or cancelled refund answers 409 REFUND_NOT_PENDING. While another request is working on the refund, it answers 409 REFUND_BUSY, which is retryable: send the same request again. A refund of a payment transaction still in transit waits with PAYMENT_IN_TRANSIT, and goes on by itself once the payment transaction converts. If :executeRefund answers 503 OUTCOME_UNKNOWN, the refund still goes on. Read it, or call :executeRefund again, to see where it stands.

4. Resolve What Blocks It

Each entry in required_actions says who resolves it, in actor: A held or blocked refund that shouldn’t go ahead is cancelled by Quidkey support, and then reads cancelled. The API doesn’t cancel refunds.

5. Follow the Refund

Poll until the refund reads completed, which means the payment to the customer’s account went out. GET /transactions/{id}/refunds lists all of a payment transaction’s refunds.

6. Read the Payment Transaction

The payment transaction’s refund_status reads partially_refunded or fully_refunded, and can_refund reads true again while more can be refunded.