{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/partner-api/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"JikoNet transfers","description":"Jiko Technologies' external APIs for integrators.","lang":"en-US","siteUrl":"https://docs.jiko.io","projectTitle":"Jiko Technologies API Documentation","jsonLd":{"@context":"https://schema.org","@type":"Organization","name":"Jiko Technologies","url":"https://docs.jiko.io","logo":"https://docs.jiko.io/static/jiko-logo-blue.svg"},"llmstxt":{"hide":false,"title":"Jiko Technologies API Documentation","description":"External APIs for integrators","sections":[{"title":"Customer API","includeFiles":["products/customer-api/**/*.md"]},{"title":"Partner API","includeFiles":["products/partner-api/**/*.md"]}]},"meta":[{"name":"robots","content":"index,follow,max-image-preview:large"}]},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"jikonet-transfers","__idx":0},"children":["JikoNet transfers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A JikoNet transfer — also known as an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["On-Us"]}," transfer in the API — is the easiest way to send cash directly between two Jiko pockets. Nothing touches an external network, so there is no cut-off, no return window and no clearing delay."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"jikonet-use-cases","__idx":1},"children":["JikoNet Use Cases"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Build a peer to peer payment network like venmo"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Debit and Credit your users Jiko pockets"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"api-note"},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":2},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"feature-flags","__idx":3},"children":["Feature flags"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Feature flags are set by Jiko per partner and evaluated against the API user making the request. A call that needs a flag you do not have fails with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},". Ask your Jiko point of contact for the ones you need."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Flag"},"children":["Flag"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Needed for"},"children":["Needed for"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Without it"},"children":["Without it"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowed_pocket_types"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Passing an explicit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," when creating a pocket. A comma-separated list, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["JIKO_PAY,JIKO_STORE"]},". A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," outside the list is refused"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}," on pocket creation. Omitting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," is accepted and you get your partnership's default type"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Nothing gates ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v1/transfers/on-us/"]}," itself, and an On-Us counterparty — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: \"on_us\""]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name_match"]}," verification — needs no flag either. The flag above matters only because the rail needs a particular kind of pocket, and that is what decides whether you can ask for one."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"everything-else","__idx":4},"children":["Everything else"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JikoPay pockets at both ends."]}," A portal on a JikoStore pocket does not carry the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ON_US"]}," rail. Read the portal's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_rails"]}," rather than assuming, and confirm with your Jiko point of contact which pocket types your partnership can open."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Approved customers and pockets in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OPEN"]}," status"]}," on both sides of the transfer."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["A partner-owned facilitation account, for funding and defunding."]}," Jiko provisions it; you address it by pocket ID in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["from_account"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to_account"]},". Without one, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PARTNER_CUSTOMER_FUNDING"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PARTNER_CUSTOMER_DEFUNDING"]}," have no near end."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["An ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["on_us"]}," counterparty in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LINKED"]}," status, for peer-to-peer."]}," Registered from the recipient portal's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account_number"]}," and the account holder's exact ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["legal_name"]},". The recipient portal must be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OPEN"]},", must carry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ON_US"]},", and must not belong to the registering customer — a customer moving money between their own pockets uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INTERNAL_REALLOCATION"]},", not a counterparty. A name mismatch stops the counterparty being created, and the error is about the name rather than the account."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Two pockets of the same customer, for internal reallocation."]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SECURITY_TRANSFER"]}," is currently limited to JikoPay pockets."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Balance that can actually move."]}," Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FULL_WITHDRAWAL"]}," where you mean \"everything\", rather than reading a balance and sending it back as a requested amount."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["A webhook subscription"]},", since the recommended ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["async_mode: true"]}," reports progress only through events: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfers.on-us.processing"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfers.on-us.success"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfers.on-us.rejected"]}," on the originating side, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfers.on-us.received"]}," on the receiving side. Subscriptions are recorded against the API user that creates them."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-four-types","__idx":5},"children":["The four types"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"type"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Moves money"},"children":["Moves money"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Typical use"},"children":["Typical use"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PARTNER_CUSTOMER_FUNDING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["From a partner-owned facilitation account to a customer's pocket"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Disbursing funds to a customer"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PARTNER_CUSTOMER_DEFUNDING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["From a customer's pocket to a partner-owned facilitation account"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Collecting funds from a customer"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PEER_TO_PEER"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Between two of your customers"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customer-to-customer payment"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INTERNAL_REALLOCATION"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Between two pockets of the same customer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Moving a customer's own money"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Funding and defunding carry an extra descriptive field — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source"]}," on funding, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["target"]}," on defunding — recording where the money came from or went to on your own side. Free text up to 200 characters. It is your reference; Jiko does not interpret it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"reallocation-has-two-flavors","__idx":6},"children":["Reallocation has two flavors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INTERNAL_REALLOCATION"]}," takes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer_type"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BANK_TRANSFER"]}]}," (default) — sells holdings in the origin pocket and buys new holdings for the destination."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SECURITY_TRANSFER"]}]}," — moves the securities directly between pockets with no bank transaction. Instant, and currently limited to JikoPay pockets."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"addressing-the-far-end","__idx":7},"children":["Addressing the far end"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["How you identify the destination depends on the type."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Funding, defunding and internal reallocation"]}," address a pocket directly:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"\"to_account\": { \"id\": \"<pocket_id>\", \"type\": \"JIKO_ACCOUNT\" }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Peer-to-peer"]}," addresses an On-Us counterparty:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"\"to_account\": { \"id\": \"<counterparty_id>\", \"type\": \"COUNTERPARTY\" }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The sending customer registers the recipient by their Jiko network address — the account number of a virtual bank account portal that carries the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ON_US"]}," rail — and Jiko verifies it by ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["name match"]}," against the account holder:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST /api/v2/customers/{customer_id}/counterparties/\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: \"on_us\""]},", the recipient's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account_number"]},", and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name_match"]}," verification carrying the recipient's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["legal_name"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Get both values from the recipient portal's funding instructions:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /api/v2/pockets/{pocket_id}/portals/{portal_id}/funding-instructions/\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ON_US"]}," instruction returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account_number"]}," (the Jiko network address) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["legal_name"]},". Pass both to the sender — ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["a name mismatch prevents the counterparty being created"]},", and the error at that point is about the name, not the account."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A portal only carries ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ON_US"]}," if the pocket is JikoPay. Read the portal's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_rails"]}," rather than assuming."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two things are rejected at registration: a portal that is not ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OPEN"]}," or does not allow ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ON_US"]},", and a portal belonging to the registering customer themselves. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INTERNAL_REALLOCATION"]}," to move a customer's money between their own pockets."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"workflow-for-a-peer-to-peer-transfer","__idx":8},"children":["Workflow, for a peer-to-peer transfer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Partner systems:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ask the recipient for their Jiko network address. It comes from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ON_US"]}," funding instruction on their portal: an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["account_number"]}," and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["legal_name"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Register it against the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sending"]}," customer with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: \"on_us\""]}," and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name_match"]}," verification carrying that exact legal name."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Wait for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["counterparty.status.linked"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create the transfer with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: \"PEER_TO_PEER\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["async_mode: true"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to_account"]}," addressing the counterparty."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Track it by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["on_us_transfer_id"]},", which both ends share."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Funding, defunding and internal reallocation skip steps 1–3 — they address a pocket by ID and need no counterparty."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"relevant-api-endpoints","__idx":9},"children":["Relevant API endpoints"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Step"},"children":["Step"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["1"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read the recipient's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ON_US"]}," address and legal name"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["GET ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v2/pockets/{pocket_id}/portals/{portal_id}/funding-instructions/"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Register the recipient as an On-Us counterparty"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["POST ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v2/customers/{customer_id}/counterparties/"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check its status"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["GET ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v2/customers/{customer_id}/counterparties/{counterparty_id}/"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["4"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Dry-run a security-transfer reallocation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["POST ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v1/transfers/on-us/quotes/"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["5"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create the transfer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["POST ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v1/transfers/on-us/"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["6"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read it back from either side, where both ends are yours"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["GET ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v1/transfers/on-us/{transfer_id}/"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"specifying-the-amount","__idx":10},"children":["Specifying the amount"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two forms are accepted, discriminated on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount.type"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REQUESTED_AMOUNT"]}]}," — a specific amount in USD cents (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount_usdc"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FULL_WITHDRAWAL"]}]}," — liquidates all holdings in the source pocket and moves the proceeds."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FULL_WITHDRAWAL"]}," is available on defunding, peer-to-peer and internal reallocation. It is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," valid for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PARTNER_CUSTOMER_FUNDING"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FULL_WITHDRAWAL"]}," rather than reading a balance and sending it as a requested amount — it avoids the race between the two calls, and the source pocket's balance is invested, not idle cash."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount_usdc"]}," field on the request body is deprecated in favor of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," object. New integrations should send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"synchronous-and-asynchronous","__idx":11},"children":["Synchronous and asynchronous"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The request takes an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["async_mode"]}," flag, defaulting to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["async_mode: true"]},"."]}," Jiko accepts the instruction, returns immediately with the transfer in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING"]},", and reports progress through webhooks. With ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["async_mode: false"]}," the call blocks until the transfer resolves, which ties your request to Jiko's processing time and makes timeouts your problem to reconcile."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"quotes","__idx":12},"children":["Quotes"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST /api/v1/transfers/on-us/quotes/\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A quote is a dry run of a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["security-transfer internal reallocation"]},": the same validation and the same ruleset evaluation as the real thing, but nothing is booked and nothing is persisted. It returns:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_allowed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Whether the transfer would be permitted at evaluation time"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rejection_reason"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Partner-facing reason when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_allowed"]}," is false, otherwise null"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rejection_detail"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Human-readable explanation, otherwise null"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["settlement_type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The settlement the transfer would receive, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["T+0"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["T+1"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eligible_transfer_amount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Maximum the customer is eligible to move given their short-maturity holdings. Zero when the request was rejected before holdings could be evaluated"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: \"INTERNAL_REALLOCATION\""]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer_type: \"SECURITY_TRANSFER\""]}," is quotable. Funding, defunding, peer-to-peer and bank-transfer reallocation are rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful quote is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["indicative"]},". It is not a guarantee that the transfer will book."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"lifecycle","__idx":13},"children":["Lifecycle"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Accepted, in progress"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Both legs posted"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REJECTED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not processed"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A rejection carries a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INSUFFICIENT_FUNDS"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCOUNT_UNAVAILABLE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_TRANSFER"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_CURRENCY"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SANCTION_SCREEN_FAILED"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELED"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The transfer resource also returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fees"]}," list. Fees are a distinct posting against the pocket and are never netted against the transfer amount."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhooks","__idx":14},"children":["Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["originating"]}," side:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfers.on-us.processing"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Instruction accepted and in progress"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfers.on-us.success"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transfer completed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfers.on-us.rejected"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transfer rejected"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payload: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["on_us_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["origin_account_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["destination_account_id"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["receiving"]}," side:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfers.on-us.received"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Funds credited to the receiving pocket"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payload: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["on_us_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receiving_pocket_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_activity_id"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["That is the most complete payload of any rail — the resulting transaction is addressable directly, with no search of the feed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You receive both sets of events for a peer-to-peer transfer only when both ends are your own customers. Where the recipient belongs to another partner, you get the originating events and their partner gets ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["received"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"endpoints","__idx":15},"children":["Endpoints"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Operation"},"children":["Operation"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create a transfer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v1/transfers/on-us/"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Quote a security transfer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v1/transfers/on-us/quotes/"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Get a transfer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/transfers/on-us/{transfer_id}/"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The create request is discriminated on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," and accepts:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer_id"]}," — client-generated UUID for idempotency"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end_to_end_identification"]}," — up to 35 characters"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}," — up to 100 characters"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/transfers/on-us/{transfer_id}/"]}," resolves from either side of a transfer where both ends are yours. It returns the transfer's type, amount, status, rejection reason where applicable, and any fees."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reading-the-money","__idx":16},"children":["Reading the money"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both legs appear in the transaction feed as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: \"ON_US\""]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["on_us_transfer_id"]}," — the transfer, shared by both sides"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["on_us_transfer_type"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PEER_TO_PEER_TRANSFER"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INTERNAL_REALLOCATION"]}," and so on"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["counterparty_name"]}," — the party at the other end"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["associated_pocket_id"]}," — the pocket at the other end"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end_to_end_identification"]}," — the sender's reference, visible to the recipient"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["direction"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DEBIT"]}," on the sending pocket, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREDIT"]}," on the receiving one"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Filter with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filter[on_us_transfer]"]}," to resolve a transfer ID to its transactions, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filter[type]=ON_US"]}," for the rail."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tracing","__idx":17},"children":["Tracing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["JikoNet is the simplest rail to trace. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["on_us_transfer_id"]}," is a single identifier shared by both ends and present on the transfer resource, on both transactions, and on every webhook. Where both ends are your own customers you can see the complete transfer from either side, which no other rail offers. Where the recipient belongs to another partner you see your own leg only, as on any external rail."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Where the sender populates ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end_to_end_identification"]},", that reference travels with the transfer and is visible to the recipient — the closest thing Jiko offers to a payer-supplied reference both parties agree on in advance."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"see-also","__idx":18},"children":["See also"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/partner-api/reference/on-us-transfers/create-on-us-transfer"},"children":["Create On-Us transfer"]}," — full request schema"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/partner-api/reference/counterparties-v2/create_counterparty_api_v2_customers__customer_id__counterparties__post"},"children":["Counterparties"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/partner-api/reference/portals-v2/portal-list-funding-instructions"},"children":["Portals and funding instructions"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/partner-api/guides/building/webhooks"},"children":["Webhooks"]}]}]}]},"headings":[{"value":"JikoNet transfers","id":"jikonet-transfers","depth":1},{"value":"JikoNet Use Cases","id":"jikonet-use-cases","depth":3},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Feature flags","id":"feature-flags","depth":3},{"value":"Everything else","id":"everything-else","depth":3},{"value":"The four types","id":"the-four-types","depth":2},{"value":"Reallocation has two flavors","id":"reallocation-has-two-flavors","depth":3},{"value":"Addressing the far end","id":"addressing-the-far-end","depth":2},{"value":"Workflow, for a peer-to-peer transfer","id":"workflow-for-a-peer-to-peer-transfer","depth":3},{"value":"Relevant API endpoints","id":"relevant-api-endpoints","depth":3},{"value":"Specifying the amount","id":"specifying-the-amount","depth":2},{"value":"Synchronous and asynchronous","id":"synchronous-and-asynchronous","depth":2},{"value":"Quotes","id":"quotes","depth":2},{"value":"Lifecycle","id":"lifecycle","depth":2},{"value":"Webhooks","id":"webhooks","depth":2},{"value":"Endpoints","id":"endpoints","depth":2},{"value":"Reading the money","id":"reading-the-money","depth":2},{"value":"Tracing","id":"tracing","depth":2},{"value":"See also","id":"see-also","depth":2}],"frontmatter":{"seo":{"title":"JikoNet transfers"}},"lastModified":"2026-09-28T14:11:34.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/partner-api/guides/building/jikonet-v2","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}