ACH Originating

An ACH origination is an entry Jiko sends on your customer's behalf to a counterparty they have registered and verified. It is the only Jiko rail that moves money in both directions from a single endpoint:

• Credit — funds leave the pocket and are pushed to the counterparty. A withdrawal or disbursement.
• Debit — funds are pulled from the counterparty into the pocket. A funding pull.

Both are originated by the same call against the same counterparty. What makes a debit "outbound" is that Jiko originates it, not the direction the money travels.

POST /api/v2/customers/{customer_id}/counterparties/

type: "ach" accepts one verification type, pre_verified. You assert that you have already verified the account on your side, and say how:

{
  "type": "ach",
  "routing_number": "021000021",
  "account_number": "1234567890",
  "account_type": "CHECKING",
  "counterparty_name": "Jane Roe",
  "verification": { "type": "pre_verified", "verification_method": "PLAID" }
}

There is no verification Jiko drives on your behalf here — no Plaid flow Jiko hosts, no micro-deposits Jiko sends. Both values describe work you did. That makes pre_verified_ach_counterparty a hard prerequisite rather than an optimization; see Prerequisites.

A debit in particular cannot be made against an unverified account, because verification is what establishes your customer's right to pull from it.

Partner systems:

1. Verify the external account on your own side, by Plaid or by micro-deposits.
2. Create the counterparty with type: "ach" and a pre_verified verification block naming which method you used.
3. Wait for the counterparty.status.linked webhook. PENDING is not enough to originate against.
4. Originate against counterparty_id.

POST /api/v1/jiko-accounts/{account_id}/ach-originating/

X-Jiko-Idempotency is a required header on this endpoint.

Send a transfer_id you generate yourself. Retrying with the same transfer_id returns the original transfer instead of creating a second one, so a request that times out mid-flight can be repeated without risking a duplicate debit.

• Generate transfer_id once per transfer, not once per attempt. Generating a new one inside a retry loop creates a new transfer on every attempt.
• A retry returns 200 with the transfer's current status, which is indistinguishable from a fresh create. A transfer created two days ago comes back with the status it has now, not PENDING.
• transfer_id must be unique across all of your transfers, not just ACH originations. Reusing a value spent on another transfer type is rejected.
• You cannot reuse a transfer_id to retry a REJECTED transfer — the rejected transfer is what comes back. Make a fresh attempt with a new transfer_id.
• The nil UUID (00000000-0000-0000-0000-000000000000) is rejected. It is what an uninitialized client variable serializes to, and it would succeed once and then conflict with itself forever.

Reusing a transfer_id with a different body returns 409 jiko.errors.transfers.ACHTransferIdConflictError. A retry must repeat both the same transfer_id and the same body.

If you omit transfer_id, X-Jiko-Idempotency behaves as it does everywhere else: a repeated value within the hour is rejected with 409 jiko.errors.DuplicateRequestError. That header only rejects duplicates — it cannot hand you back the original — so transfer_id is the better choice for anything that needs to be retried.

Settlement on this rail is covered in full by ACH Transfer Settlement Timing, which explains the processing windows, the delay before an entry reaches the network, and the delay after it before Jiko marks a transfer settled. Read it before you quote a payout time to an end customer.

One point belongs here, because it is about the call you are making rather than about the network.

A pocket's balance is held in T-Bills, not idle cash. Before an outbound credit can be released, the amount has to be liquidated and that sale has to settle. Read liquidation_value_t0 and liquidation_value_t1 on the pocket's portfolio before instructing: total_value is what the customer owns, and the liquidation values are what can actually be moved, and when. An instruction whose liquidation has not settled cannot reach the network that day, whatever the amount and whatever the hour.

A debit origination has no such leg. Funds are arriving, not leaving.

Completion is not finality. The receiving bank can return an entry days after it settles — insufficient funds, a closed account, an unauthorized debit. A return reverses the money movement and appears as a separate transaction, not as a status change on the original origination. Do not treat PROCESSED as the end of the story, particularly for debits.

Payload: jiko_account_id and ach_origination_id. The origination is directly retrievable, so there is no need to scan the transaction feed. Intermediate statuses such as PENDING and APPROVED raise no event.

Both list endpoints are cursor-paginated and accept filter[status] and direction.

An origination appears in the transaction feed as type: "ACH" with ach_direction: "ORIGINATION":

• ach_id — the origination ID, matching ach_origination_id from the webhook
• company_name, company_entry_description — as submitted
• direction — DEBIT where funds left the pocket, CREDIT where they were pulled in
• trace_number — not populated on originations. It is only present on entries Jiko received

ach_direction distinguishes ORIGINATION from RECEIVING. It is not the credit/debit direction — use the base direction field for that.

Returns appear separately. A returned origination produces a further transaction, also type: "ACH" but with ach_direction: "RECEIVING", carrying the return's own trace_number and ach_id. The return does not carry the original origination's ID, so reconciling end to end means matching the original transaction with any later return against the same counterparty and amount.

Feeds:

/api/v1/customers/{customer_id}/ach-originating/ lists outgoing entries only. Money arriving over ACH is received against a portal, not a counterparty, and surfaces only in the transaction feed as type: "ACH" with ach_direction: "RECEIVING". Events are transfers.ach.in.success and transfers.ach.in.rejected, whose payload carries jiko_account_id and nothing else — treat them as a signal to go read the pocket's transactions, not as a description of what happened.

One consequence worth stating plainly to anyone designing an inbound flow: a portal's routing and account number are the customer's bank account details, reachable in both directions. Anyone holding them can originate a debit against the pocket, exactly as they could against any bank account. Jiko returns the entry if the portal is closed, is not ACH-enabled, or cannot fund it, but a valid debit against an open, funded portal will settle.

• ACH Transfer Settlement Timing — when an entry reaches the network, and when it settles
• Create ACH origination — full request and response schema
• Counterparties — registering and verifying the destination
• Webhooks