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

Pay out a hold

Pays the full held amount to the beneficiary. For an external beneficiary this starts a payout and answers with the hold paying_out; it becomes paid_out when the payout is delivered. If the payout fails, the money comes back, the hold is held again with the failed payout, and you can pay out again (a new attempt) or return it. A payout refused at once is 422 payout_failed. While a payout is on the rail, a return is 409 already_decided. Only the business that placed the hold can do this; there are no partial payouts. A hold already paid out or returned is 409 already_decided, and the message says how it ended; nothing moves. A hold no longer held for another reason is 409 hold_not_held. A beneficiary that cannot receive money right now is 422 beneficiary_unavailable and the hold stays held. Only holds with a beneficiary can be decided; any other hold is 404. Requires the holds.write and holds.read permissions. Escrow holds are available in the sandbox only for now; on the live API every holds route answers 403 holds_not_available.

POST/v1/holds/{reference}/pay-out
Authorization
AuthorizationBearer token (JWT) · headerrequired

A token from POST /v1/oauth/token on the iSmartPay identity service, obtained with an API credential's client id and secret.

Path parameters
referencestringrequired

The placing business uses its reference. The beneficiary business uses the hold's id.

matches ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$
Header parameters
Idempotency-Keystringrequired

A unique value you generate for this attempt, at most 255 characters. Send the same value when you retry the same request: it is answered once, however many times you send it. Reusing a value with a different body is refused with 409 idempotency_key_reused.

min length 1 · max length 255
Responses
200

The hold, paid_out, or paying_out for an external beneficiary.

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>
400

The request is not valid. message says which field.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

401

The token is missing, expired or not valid. Get a new one from the token endpoint.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

403

The request was understood and refused. Common causes: the token is not an API credential's (forbidden); the credential is for the other environment (environment_mismatch); it does not have the permission this operation needs (forbidden); a limit was reached (limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit); or iSmartPay has suspended or deactivated the business (business_suspended, business_deactivated). A suspended business's API credentials stop exchanging for tokens, so a request made with a token issued just before the suspension is refused with business_suspended.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

404

Nothing was found with that reference or number. For utilities, product_not_found means no product has that productId.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

409

idempotency_key_reused: the key was used before with a different body. request_in_flight: a request with this key is still being processed, so retry shortly. duplicate_reference: the reference is already used by a different request, so choose a new one; sending the same body again under a new key replays the first answer.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

422

The purchase cannot be made as asked: product_not_sellable (the product is not on sale now), amount_out_of_range (outside the product's price, min or max), currency_not_supported (only GHS is sold), beneficiary_invalid (the product cannot be sold to this number) or fee_unpriceable (the fee cannot be worked out right now; retry later).

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

429

Too many requests for this credential. Wait the number of seconds in the Retry-After header, then try again.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

500

Something failed on our side. The message is fixed. If the request was a POST, retry with the same Idempotency-Key and body.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

502

A service behind the API did not answer usably. If the request was a POST, retry with the same Idempotency-Key and body. A party lookup the provider rejects is provider_error.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

503

The API is temporarily unable to tell which environment it serves (environment_unknown), utility purchases are not available right now (utilities_unavailable), a settlement destination could not be name-checked just now (destination_verification_unavailable; retry the same request), or hosted checkout is not set up on this deployment (checkout_unavailable). Retry shortly, except for checkout_unavailable, which lasts until the deployment is configured.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

504

The request took too long. If it was a POST, its outcome is unknown: retry with the same Idempotency-Key and body, or read it back by reference. A party lookup the provider does not answer is provider_timeout: check again before relying on it.

errorobjectrequired
Show properties
codestringrequired

A stable, machine-readable code. Branch on this, not on the message. Codes include invalid_input, unauthenticated, forbidden, environment_mismatch, not_found, rate_limited, idempotency_key_reused, request_in_flight, limits_missing, limits_unusable, tier_ineligible, transaction_limit_exceeded, daily_limit_exceeded, monthly_limit_exceeded, new_destination_limit, business_suspended, business_deactivated, environment_unknown, duplicate_reference, provider_error, provider_timeout, destination_not_verified, destination_verification_unavailable, upstream_timeout and internal.

messagestringrequired

Readable detail for a person. For any 5xx it is always the fixed text internal server error.

Request
curl -X POST 'https://stgdeveloper-api.ismartghana.com/v1/holds/string/pay-out' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Idempotency-Key: string'
Response
{
  "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"
}