Skip to main content

How ACH Pulls Work

An ACH pull funds an account's USD bank account by debiting the holder's own account at another bank. The holder adds that account once — a pull account — accepting the ACH debit authorization, and then asks for pulls from it whenever they need money in.

New in v3: v2 has no equivalent.

The path​

  1. Read the authorization text with Get the ACH Debit Authorization and show it to the holder exactly as answered.
  2. Add the account with Create a Pull Account, sending authorization.accepted: true and the version the holder was shown.
  3. Ask for a pull with Request an ACH Pull. The amount shows at once as pending on the account's balance.
  4. Within five minutes (grace_ends_at) the pull can still be cancelled. After that it is submitted to the bank.
  5. Follow it with Get an ACH Pull or List ACH Pulls. There is no webhook for ACH pulls yet.

The life of a pull​

statusWhat happenedThe account's balance
pendingRequested; waiting out the five-minute grace period. Can be cancelled.total in pending_credits
processingSubmitted to the bank. held: true while the bank reviews it.pending
postedThe debit settled (posted_at). It completes right after: available_at is posted_at, as no hold applies.pending
completedThe debit settled with no return (completed_at).available, less the pull's reserved share, which moves to the account's reserve and stays there until it is released
returnedThe holder's bank sent the debit back (return_code, for example R01 insufficient funds).dropped — or, if the pull had completed, covered by the whole reserve first and the rest taken back out of the available balance
failedThe bank refused the debit or never made it.dropped
cancelledCancelled within the grace period.dropped

A pull from a person's account can be disputed as unauthorized for sixty days, so a completed pull can still become returned.

The reserve​

When a pull completes, a share of it — 10% unless BlockWyre agreed another percent with your workspace — is set aside instead of made available: the pull's reserved. It is held in the account's reserve bank account, opened for the account the first time one of its pulls completes.

  • List Bank Accounts shows it as kind: reserve, active, with what it holds as its balance. It takes no deposit, transfer or withdrawal, is never the default, and has no account number or reference to share.
  • List Balances answers what it holds as reserved on its row (bank_account_is_reserve: true), and in the coin's totals. It is not part of available.
  • When a completed pull is returned, everything in the reserve — from that pull and every earlier one — goes towards the return first; only what it does not cover is taken from the available balance.

A $250.00 pull at 10%: $225.00 becomes available, $25.00 is reserved.

Returns that stop a pull account​

A return R02, R03 or R04 (closed, no such account, invalid number), R05, R07, R10, R11 or R29 (the holder says the debit was not authorized, or revoked the authorization), or a bank's notification of change, sets the pull account to disabled. No pull is accepted from it until its details are corrected, or the holder accepts the authorization again, with Update a Pull Account.

Limits​

One pull and the account's open pulls (pending, processing or posted) are capped. Today's caps are $5,000 per pull and $10,000 open per account; a request past them is refused with 422. Get ACH Pull Limits answers the caps and the most the account's next pull may be — show it when the holder asks for a pull.

Who can call it​

Every API key can call these endpoints. An account-scoped key acts for its own account; naming another account in account_id answers 403 forbidden, and another account's pull accounts and pulls read as 404. A workspace-scoped key names the account with account_id on the two creates and on Get ACH Pull Limits, and may leave it out on the lists to see the whole workspace.

ACH pulls are enabled per workspace or per account; while they are off, the two creates answer 404 feature_not_enabled.

Both creates require the Idempotency-Key header from every caller, API keys included, with no grace period: without it they answer 400 idempotency_key_required. See API v3 overview.

Support and Resources​

If you need assistance or have any questions, our support team is here to help. You can contact our support team at support@blockwyre.com.

Stay Updated​

Stay up-to-date with the latest news, updates, and features from BlockWyre by following us on social media:

We are excited to have you on board and look forward to seeing how you leverage BlockWyre's powerful tools to enhance your financial operations. Happy integrating!