hold.status_changed
Sent to the business that placed an escrow hold when it is placed, paid out or returned, and to the beneficiary business too when the beneficiary is another business. Needs holds.read to appear in the events list. Answer with any 2xx within 10 seconds. Anything else, a timeout or a redirect is retried up to 6 times over about a day. Events can arrive out of order, so compare statuses rather than trusting arrival order.
hold.status_changedWebhookWebhook-IdstringrequiredThe event id. The same event can arrive more than once; use this to ignore repeats.
Webhook-TimestampstringrequiredUnix seconds when this attempt was signed. Reject a delivery older than 5 minutes.
Webhook-Signaturestringrequiredv1, then a comma, then the base64 HMAC-SHA256 of "{Webhook-Id}.{Webhook-Timestamp}.{raw body}" keyed with your endpoint's signing secret. Compare in constant time.
application/jsonidstringrequiredThe event id, the same as the Webhook-Id header.
typestringrequiredcreatedAtstring<date-time>requiredWhen the change happened.
dataHoldrequiredThe hold as it stood when the event was sent, as the receiving business sees it. The placing business's copy has no id, decidedAt or createdAt, and the beneficiary's has no createdAt; read the hold for them.
Show propertiesHide properties
idstring<uuid>The hold's id. A beneficiary business reads and returns the hold with it.
referencestringrequiredThe placing business's reference.
statusstringrequiredheld until someone decides. paying_out while a payout to an external beneficiary is on the rail; if it fails, the hold is held again. paid_out and returned are final.
heldpaying_outpaid_outreturnedamountstringrequiredA decimal string in major units.
currencystringrequiredfeestringOn an external hold, the payout fee in major units, priced when the hold is placed. The beneficiary still receives the full amount.
totalHeldstringOn an external hold, amount plus fee: what left your wallet, and what a return gives back.
reasonstringwalletIdstring<uuid>For the placing business, the wallet the money is held from. For the beneficiary, the wallet it would land in.
beneficiaryHoldPartyShown to the placing business. A business beneficiary carries businessName, never an id.
Show propertiesHide properties
typestringsub_accountbusinessexternalwalletIdstring<uuid>businessNamestringThe business's display name, when known.
providerstringOn an external beneficiary.
destinationobjectOn an external beneficiary.
Show propertiesHide properties
typestringrequiredmsisdnaccountvaluestringrequiredThe mobile money number or bank account number.
accountNamestringOn an external beneficiary, the account name the provider returned when the hold was placed. Absent where the rail cannot look names up, as with banks.
payoutobjectOn an external hold once a pay-out has been asked for: the latest payout attempt.
Show propertiesHide properties
attemptintegerstatusstringfailureReasonstringplacedByHoldPartyShown to the beneficiary business instead of beneficiary.
Show propertiesHide properties
typestringsub_accountbusinessexternalwalletIdstring<uuid>businessNamestringThe business's display name, when known.
providerstringOn an external beneficiary.
destinationobjectOn an external beneficiary.
Show propertiesHide properties
typestringrequiredmsisdnaccountvaluestringrequiredThe mobile money number or bank account number.
accountNamestringOn an external beneficiary, the account name the provider returned when the hold was placed. Absent where the rail cannot look names up, as with banks.
expiresAtstring<date-time>onExpirystringreturnpay_outdecidedBystringWho decided a final hold. ismartpay is a decision by iSmartPay support.
payerbeneficiaryexpiryismartpaydecidedAtstring<date-time>createdAtstring<date-time>Received. Any 2xx stops retries.