GET /v1/contract-withdrawals #
Withdrawal requests, newest first (at most 200)
Parameters
| Name | In | Type | Description |
|---|
customer_external_id | query | string | |
status | query | received | accepted | rejected | refunded | |
Responses
Example response
{
"withdrawals": [
{
"id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
"customer_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
"customer_external_id": "string",
"subscription_id": "string",
"invoice_id": "string",
"statement": "string",
"source": "api",
"status": "received",
"receive_time": "2026-11-03T10:15:00Z",
"decide_time": "2026-11-03T10:15:00Z",
"decided_by": "string",
"decision_note": "string",
"credit_note_id": "string",
"refund_state": "none",
"refund_note": "string",
"refund_time": "2026-11-03T10:15:00Z"
}
]
}
curl
curl -X GET https://YOUR-API-ADDRESS/v1/contract-withdrawals \
-H "Authorization: Bearer $PAYRUDDER_API_KEY"
PUT /v1/contract-withdrawals/{id}/status #
Decide a withdrawal request, or mark an accepted one refunded
received becomes accepted or rejected, once; accepted becomes refunded (plans.contract.withdrawal_decided otherwise). Sends the webhook event contract.withdrawal_decided. Accepting a withdrawal that names an invoice also asks billing for the refund when the settings say withdrawal_refund: full (the default): a credit note that returns the amount to the card, for refund_amount_minor or whatever is left of the invoice. The decision is recorded first; what happened to the refund is on the returned withdrawal (refund_state, credit_note_id, refund_note) and never makes this call fail. An invoice paid by bank transfer or cash cannot go back through Payrudder: refund_state is outside and the seller refunds it by hand, then marks the withdrawal refunded. Needs customers:write. A key that does not also hold invoices:write cannot accept a withdrawal while the settings say withdrawal_refund: full (403 gateway.auth.permission_denied, nothing is decided): the refund is a credit note, and creating one needs invoices:write everywhere. Rejecting, or accepting while the setting is none, needs customers:write only.
Parameters
| Name | In | Type | Description |
|---|
id required | path | string · uuid | |
Request body
| Field | Type | Description |
|---|
status required | accepted | rejected | refunded | |
note | string | |
refund_amount_minor | string · int64 | Accepting only: the amount to refund when the settings ask for a refund, in minor units; 0 or absent is whatever is left of the invoice. |
Example
{
"status": "accepted"
}
Responses
Example response
{
"id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
"customer_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
"customer_external_id": "string",
"subscription_id": "string",
"invoice_id": "string",
"statement": "string",
"source": "api",
"status": "received",
"receive_time": "2026-11-03T10:15:00Z",
"decide_time": "2026-11-03T10:15:00Z",
"decided_by": "string",
"decision_note": "string",
"credit_note_id": "string",
"refund_state": "none",
"refund_note": "string",
"refund_time": "2026-11-03T10:15:00Z"
}
curl
curl -X PUT https://YOUR-API-ADDRESS/v1/contract-withdrawals/<id>/status \
-H "Authorization: Bearer $PAYRUDDER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"accepted"}'
POST /v1/contract-withdrawals/{id}/refund #
Ask for the refund of an accepted withdrawal
For a withdrawal whose settings say withdrawal_refund: none, or whose first request failed. Only an accepted withdrawal that names an invoice, once: a request under way or made already answers plans.contract.refund_not_possible. The refund is a credit note with refund_to_card for amount_minor (0 is whatever is left of the invoice), made by billing under its own rules (a paid invoice, never more than what is left of it, only a payment a provider can return). The answer is the withdrawal with its refund_state. Needs invoices:write, not only customers:write: it returns money to a card.
Parameters
| Name | In | Type | Description |
|---|
id required | path | string · uuid | |
Request body
| Field | Type | Description |
|---|
amount_minor | string · int64 | In minor units; 0 or absent is whatever is left of the invoice. |
Example
{}
Responses
Example response
{
"id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
"customer_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
"customer_external_id": "string",
"subscription_id": "string",
"invoice_id": "string",
"statement": "string",
"source": "api",
"status": "received",
"receive_time": "2026-11-03T10:15:00Z",
"decide_time": "2026-11-03T10:15:00Z",
"decided_by": "string",
"decision_note": "string",
"credit_note_id": "string",
"refund_state": "none",
"refund_note": "string",
"refund_time": "2026-11-03T10:15:00Z"
}
curl
curl -X POST https://YOUR-API-ADDRESS/v1/contract-withdrawals/<id>/refund \
-H "Authorization: Bearer $PAYRUDDER_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'