Skip to content
iSmartPayDevelopers
Esc
↑↓navigate↵open⌘Jpreview

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.

POSThold.status_changedWebhook
Header parameters
Webhook-Idstringrequired

The event id. The same event can arrive more than once; use this to ignore repeats.

Webhook-Timestampstringrequired

Unix seconds when this attempt was signed. Reject a delivery older than 5 minutes.

Webhook-Signaturestringrequired

v1, 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.

Request body
requiredapplication/json
idstringrequired

The event id, the same as the Webhook-Id header.

typestringrequired
createdAtstring<date-time>required

When the change happened.

dataHoldrequired

The 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 properties
idstring<uuid>

The hold's id. A beneficiary business reads and returns the hold with it.

referencestringrequired

The placing business's reference.

statusstringrequired

held 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.

Allowed:heldpaying_outpaid_outreturned
amountstringrequired

A decimal string in major units.

currencystringrequired
feestring

On an external hold, the payout fee in major units, priced when the hold is placed. The beneficiary still receives the full amount.

totalHeldstring

On an external hold, amount plus fee: what left your wallet, and what a return gives back.

reasonstring
walletIdstring<uuid>

For the placing business, the wallet the money is held from. For the beneficiary, the wallet it would land in.

beneficiaryHoldParty

Shown to the placing business. A business beneficiary carries businessName, never an id.

Show properties
typestring
Allowed:sub_accountbusinessexternal
walletIdstring<uuid>
businessNamestring

The business's display name, when known.

providerstring

On an external beneficiary.

destinationobject

On an external beneficiary.

Show properties
typestringrequired
Allowed:msisdnaccount
valuestringrequired

The mobile money number or bank account number.

accountNamestring

On 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.

payoutobject

On an external hold once a pay-out has been asked for: the latest payout attempt.

Show properties
attemptinteger
min 1
statusstring
failureReasonstring
placedByHoldParty

Shown to the beneficiary business instead of beneficiary.

Show properties
typestring
Allowed:sub_accountbusinessexternal
walletIdstring<uuid>
businessNamestring

The business's display name, when known.

providerstring

On an external beneficiary.

destinationobject

On an external beneficiary.

Show properties
typestringrequired
Allowed:msisdnaccount
valuestringrequired

The mobile money number or bank account number.

accountNamestring

On 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>
onExpirystring
Allowed:returnpay_out
decidedBystring

Who decided a final hold. ismartpay is a decision by iSmartPay support.

Allowed:payerbeneficiaryexpiryismartpay
decidedAtstring<date-time>
createdAtstring<date-time>
Responses
2XX

Received. Any 2xx stops retries.

Payload
{
  "id": "string",
  "type": "hold.status_changed",
  "createdAt": "2019-08-24T14:15:22Z",
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "reference": "string",
    "status": "held",
    "amount": "100.00",
    "currency": "GHS",
    "fee": "string",
    "totalHeld": "string",
    "reason": "string",
    "walletId": "0ecad4a2-3549-43fb-807e-9ff033247480",
    "beneficiary": {
      "type": "sub_account",
      "walletId": "0ecad4a2-3549-43fb-807e-9ff033247480",
      "businessName": "string",
      "provider": "string",
      "destination": {
        "type": "msisdn",
        "value": "string"
      },
      "accountName": "string"
    },
    "payout": {
      "attempt": 1,
      "status": "string",
      "failureReason": "string"
    },
    "placedBy": {
      "type": "sub_account",
      "walletId": "0ecad4a2-3549-43fb-807e-9ff033247480",
      "businessName": "string",
      "provider": "string",
      "destination": {
        "type": "msisdn",
        "value": "string"
      },
      "accountName": "string"
    },
    "expiresAt": "2019-08-24T14:15:22Z",
    "onExpiry": "return",
    "decidedBy": "payer",
    "decidedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z"
  }
}
Response
Received. Any 2xx stops retries.