Skip to main content
A hold is a compliance check that has not finished. The movement is neither done nor failed. It is paused, and it will resume or stop depending on the result. It is worth handling as its own case, because the two things a flow usually does with an unfinished movement are both wrong here: retrying creates a second one, and treating it as failed tells your customer something that is not true yet.

On a deposit

A held deposit sits in KYT_PENDING. From there it moves on when the check passes (a bank deposit to a fiat account completes, any other goes back to PENDING), or moves to KYT_REJECTED. A crypto inbound can also end FAILED during the review. KYT_REJECTED is not FAILED. A failure is technical, and this is a decision. Keeping them apart is what makes the record readable afterwards. Only a return moves it, to REFUNDED. A rejection is never withdrawn, so a rejected deposit is never credited.
A held deposit’s amount cannot be paid out while it lasts. The account’s available_balance leaves it out, and a payout larger than what remains is refused for insufficient balance; the rest of the balance can still be sent. When a payout is refused on an account that looks funded, check for a held deposit before you assume your integration is at fault.A crypto inbound holds back nothing. Its money reaches the balance only once it is credited.

On a payout

A held payout sits in KYT_PENDING, or in IN_REVIEW when the hold is a manual check rather than an automatic one. Both reach you only on payout.status_changed. See Payouts.

The hold that waits on you

A compliance check can also ask for something instead of deciding. The movement is then held on a request for information, not on a running check. The payout or deposit reports status of NEEDS_ACTION, and a payout also carries an rfi object with the request and its deadline. The stage underneath does not change. The movement continues from there when the request closes. A request holds only what it names. One anchored to a payout holds that payout, and the sub-client’s other movements continue. One about the sub-client holds their verification, not a movement.

Who releases it

A check or a reviewer. The exception is a request for information: you end that hold by answering it. No endpoint releases a hold, and retrying the movement does not change one. What you can do:
  • Show it as pending, not as failed and not as done.
  • Answer the request when status reads NEEDS_ACTION. It is the only hold your integration can lift.
  • Do not retry. Retrying with the same idempotency key returns the same held movement; retrying with a fresh one creates a second one that will be held for the same reason.

Testing a hold

Both endings are reachable in sandbox and resolve on their own, without anyone at Kira. Forcing outcomes has the values. One pair of cents holds and then approves, another holds and then rejects. Test them together. The failure to look for is not in either ending. It is in the code that runs while the movement is paused and assumes it will resume.