Skip to main content
POST
Refund a waiting transfer

What this endpoint does

Returns the full AUD amount of an on-ramp transfer waiting at awaiting_client_action to the account that paid it. Nothing is converted.

When to use it

Call it when you do not want to accept a payment that arrived on a route with clientGate enabled. Send an empty body.

Before you call

Use a secret API key with transfer write access and pass a transfer owned by this tenant account. A request made from a console session also needs a recent second-factor confirmation.

Money and balance effect

Returns the full landed AUD to the payer; the Wayex transfer fee applies to the refunded amount and appears on your monthly invoice. Partial refunds are not supported.

States and completion

The transfer moves to refunding, then returned, reversing, and reversed once the refund executes. A payment can only be refunded five minutes after it arrived, so refunding can take several minutes. If the refund cannot be completed, the transfer returns to awaiting_client_action with references.lastCaseReason set to refund_rejected; you can then progress it or request the refund again. 409 refund_not_available means the payment can no longer be refunded — progress it instead.

Safe retries

Send a unique Idempotency-Key. A repeat call after the refund was requested returns 200 with the current state and never sends a second refund. 409 client_gate_busy means another action on the transfer is in progress — retry shortly. Read Activity and history for the complete workflow.

Authorizations

Authorization
string
header
required

Send the same Wayex API key as Authorization: Bearer <key>.

Headers

Idempotency-Key
string
required

A unique key for this logical action. Reuse the same key and identical payload when retrying after an unknown response.

Required string length: 8 - 255

Path Parameters

id
string
required

Body

application/json

The body is of type object.

Response

The transfer after the decision (usually refunding).

id
string
required

Unique identifier for this transfer.

Minimum string length: 1
counterpartyId
string
required

The client account (counterparty) this transfer belongs to. For API callers this is always your own account id.

Minimum string length: 1
customerId
string
required

The customer this transfer is for.

Minimum string length: 1
status
enum<string>
required

Current lifecycle status. State advances asynchronously, so treat this as the source of truth.

Available options:
created,
validated,
screening,
fx_executed,
completed,
awaiting_deposit,
deposit_detected,
deposit_confirming,
deposit_cleared,
sweeping,
onforwarding,
payout_instructed,
payout_held,
payout_settled,
awaiting_payin,
payin_cleared,
disbursing,
sending,
send_confirming,
pooled,
awaiting_client_action,
refunding,
on_hold,
frozen,
failed,
cancelled,
returned,
expired,
reversing,
reversed
sourceDepositInstructions
object
required
references
object
required
timeline
object[]
required

Ordered history of the states this transfer passed through, with timestamps.

createdAt
string<date-time>
required

When the transfer was created (ISO 8601).

updatedAt
string<date-time>
required

When the transfer was last updated (ISO 8601).

type
enum<string>
required
Available options:
offramp
source
object
required
destination
object
required
destinationAmount
string
required

Net AUD the customer receives as a decimal string; set once the conversion executes ("0" before).

Pattern: ^\d+(\.\d+)?$
destinationCurrency
enum<string>
required
Available options:
AUD
routeId
string

The payment route whose funding spawned this transfer.

Minimum string length: 1
quoteId
string

Reference to the live price struck at funding; absent until the conversion executes.

Minimum string length: 1
metadata
object
developerFee
object

Your developer fee withheld from this conversion (AUD). Present once the conversion executes; omitted on a returned, reversing or reversed transfer.

exchangeRate
string

Destination units per one source unit the conversion executed at, excluding your developer fee. Present once the conversion executes.

Pattern: ^\d+(\.\d+)?$