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
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:
automaticcreates the refund, and Quidkey moves the money as soon as it can, with no further call.manualcreates 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.
transaction of type: refund whose parent_transaction is the payment transaction. Its Location header is /transactions/{refund_id}.
3. Execute a Held 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 inrequired_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
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
refund_status reads partially_refunded or fully_refunded, and can_refund reads true again while more can be refunded.