Skip to navigation
API ReferenceMerchant

Get Withdraws

Get All Withdraws associated with the merchant

Authentication

OR
Authorizationstring
API Key authentication via header

Query parameters

sincestringOptional
untilstringOptional
pagedoubleOptional
statusstringOptional
searchstringOptional
sortByenumOptional
Allowed values:
sortDirectiondoubleOptional
speedstringOptional
merchantIdstringOptional
limitdoubleOptional
bankSettlementsOnlybooleanOptional
typeenumOptional
Allowed values:

Response

Ok
transactionstring
createdAtdatetime
_idstring
withdrawerstring or object
transferIdstring
walletstring
blockchainenum
accountIdstring
amountobject
usdToForeignExchangeRatedouble

This is the conversion rate from USD to the foreign currency. For example 0.90 = 0.90 USD/GBP

So if you want to convert GBP to USD you would multiply 15 GBP * 0.90 USD/GBP = 13.5 USD If you want to convert USD to GBP you would multiply 13.5 USD * 1/0.90 GBP/USD = 15 GBP

userPaidFeesobject
merchantPaidFeesobject
invoiceIdstring

Set on completion when merchantPaidFees were not settled inline: the Accruing invoice the fees were attached to. Mirrors the refund/chargeback/payment invoicing pattern — presence of invoiceId marks the fees as billed.

outstandingobject
statusenum
expectedDeliveryDatedatetime
merchantstring or object
updatedAtdatetime
speedenum
achTraceIdstring

The provider's ACH trace ID for this withdraw, when available. Used by support to give customers a reference the receiving bank can look up. Currently populated for Braid ACH payouts (transaction.ach.traceNumber), AptPay ACH payouts (the settled webhook's os-trace), and AptPay push-to-card payouts (the transaction's RRN / Retrieval Reference Number).

returnStatusenumOptional
Allowed values:
unclaimedAtdatetimeOptional

When the provider reported the payout as unclaimed: sent to an email or phone with no account behind it, so the recipient has to claim it before the provider cancels it (30 days for PayPal).

awaitingProviderReturnAtdatetimeOptional

When the provider reported that it is holding the payout and will not let us cancel it, so the withdraw stays pending until the provider returns the funds (30 days for PayPal).

cryptoPayoutInfoobjectOptional

Delivery details for crypto (speed=crypto) payouts. Chain, token and destination are stamped when the withdrawal is created; the delivery transaction hash is stored by the provider's completion webhook.

returnTransactionstringOptional
returnedAtdatetimeOptional
returnAddressstringOptional

Optional end-user address to send a failed-withdraw refund to instead of the originating wallet. Copied from the CryptoWithdrawSession at creation.

returnCurrencystringOptional
returnGlideSessionIdstringOptional
userIdstringOptional
detailMessagestringOptional
errorDatastringOptional
pinstringOptional
Only used for Interac payments if the user must provide their bank a PIN to claim the transfer.
isFirstPartybooleanOptional

True when this withdraw was a first-party payout (the merchant withdrawing from their own settlement wallet).

payoutInitiatedbooleanOptional
payoutInitiatedAtdatetimeOptional
idempotencyKeystringOptional
manuallyFailedByobjectOptional
manuallySucceededByobjectOptional
userLocationobjectOptional

Browser-captured geolocation at the time of the withdraw request, when the caller supplied one. Stored independently of payout method so the merchant dashboard can render a map for any withdraw. resolved* fields are populated when the GEOLOCATION enforcement step happened to reverse- geocode the coordinates — they're a free piggyback on the lock cache, not a guarantee.

orchestrationTraceIdstringOptional
entityTagobjectOptional