{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/partner-api/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"International wires","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":"international-wires","__idx":0},"children":["International wires"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An international wire sends funds from a pocket to an account outside the US. It uses the same create endpoint as a domestic wire; what differs is the counterparty type you register and, on the inbound side, how the money is addressed to you at all."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Required end-user disclosure."]}," When you build wire entry screens in your own UI, you must show your end users the following: ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["\"By using this service, you hereby acknowledge that sending wires to third parties presents an increased risk of fraud, and that as per the terms of your Commercial Bank Account Agreement (the \"Agreement\"), you agree that our security measures are commercially reasonable methods of providing security against unauthorized Funds Transfers, and that you shall be bound by any request for a Funds Transfer received by the Bank, whether or not authorized, issued in your name and accepted by the Bank in compliance with the security measures.\""]}]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"api-note"},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"feature-flags","__idx":2},"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":["international_wire_counterparty"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Creating any counterparty with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: \"international_wire\""]},". There is no other way to address a non-US account"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}," at counterparty creation. Nothing else about the product is reachable"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enable_counterparty_ownership"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sending ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ownership_type"]}," on the counterparty"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},". Omitting the field is accepted"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unverified_wire_counterparty"]}," gates the domestic ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wire"]}," type only. On the international type, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unverified"]}," is covered by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["international_wire_counterparty"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Neither flag gates the wire itself — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /api/v1/jiko-accounts/{account_id}/wires/"]}," carries no feature flag."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"everything-else","__idx":3},"children":["Everything else"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Outbound wires enabled on your partnership"]},", as for domestic. Commercial rather than a flag."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["An approved customer and a pocket in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OPEN"]}," status."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["An ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["international_wire"]}," counterparty in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LINKED"]}," status."]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNLINKED"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLOSED"]}," are terminal — none returns to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LINKED"]},", so recovering means registering a new counterparty."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["A verification method that fits."]}," Only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["supporting_documents"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unverified"]}," exist here, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unverified"]}," is for third-party destinations. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["supporting_documents"]}," needs at least one already-uploaded document ID and is reviewed by Jiko over days, so it is not a same-day path."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["A SWIFT/BIC that Jiko's screening resolves."]}," A BIC that does not resolve passes counterparty creation and fails later, at wire creation, as a pre-condition failure."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Balance that can actually move."]}," Read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["liquidation_value_t0"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["liquidation_value_t1"]},", not ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total_value"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_by"]}," on every wire"]},", and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wire_id"]}," you generate yourself — the create call returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]}," with an empty body."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The end-user disclosure above, shown in your own UI."]}," A contractual condition of the product."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["A wire-enabled portal and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INTERNATIONAL_WIRE"]}," funding instruction, to receive."]}," The portal must be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OPEN"]}," and carry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WIRE"]},", and the payer must reproduce the reference string exactly — an inbound international wire is attributed by that string, not by the beneficiary account."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["A webhook subscription"]}," for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfers.wire.out.*"]}," and, for inbound, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfers.wire.in.success"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfers.wire.in.rejected"]},"."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"register-the-counterparty","__idx":4},"children":["Register the counterparty"]},{"$$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: \"international_wire\""]},":"]},{"$$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":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["counterparty_name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Discriminated on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["individual"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["first_name"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["last_name"]},") or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["business"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["business_name"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Beneficiary address"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["swift_bic"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["8 or 11 characters, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AAAAAA"]}," + 2 + optional 3"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identifier"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The beneficiary account — an IBAN or a local account identifier"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identifier_type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["iban"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["local"]}," (default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["local"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bank_name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Beneficiary bank"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wire_instructions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Up to 140 characters, carried on the message"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ownership_type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FIRST_PARTY"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["THIRD_PARTY"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["display_name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Up to 200 characters, your own label, no effect on routing"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"verification","__idx":5},"children":["Verification"]},{"$$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":"Method"},"children":["Method"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Allowed on"},"children":["Allowed on"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["supporting_documents"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["First or third party"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Documents submitted and reviewed by Jiko. Takes days"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unverified"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Third party only"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["For payments to someone other than your customer, where ownership verification is not the right check. Enabled per partner"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["incoming_wire"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pre_verified"]}," are domestic-wire methods and are not available here."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Wait for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["counterparty.status.linked"]}," before originating. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNLINKED"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLOSED"]}," are all terminal — none of them returns to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["LINKED"]},", so recovering means registering a new counterparty."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"workflow","__idx":6},"children":["Workflow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Partner systems:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Collect the beneficiary's details, including a SWIFT/BIC and either an IBAN or a local account identifier."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Register the counterparty with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: \"international_wire\""]},". Only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["supporting_documents"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unverified"]}," are available, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unverified"]}," is for third-party destinations."]},{"$$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 wire with your own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wire_id"]}," and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_by"]}," — the same endpoint as a domestic wire."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Track it by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wire_id"]},", and surface ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["uetr"]}," to anyone chasing the payment."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"relevant-api-endpoints","__idx":7},"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":["Register the beneficiary as a 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":["2"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check its status without waiting on the webhook"]},{"$$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":["3"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send the wire"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["POST ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v1/jiko-accounts/{account_id}/wires/"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["4"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read it back, including ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wire_tracking_info"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["GET ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v1/wires/{wire_id}/"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["5"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List inbound wires"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["GET ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/v1/wires/?direction=INCOMING"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"a-note-on-swift_bic","__idx":8},"children":["A note on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["swift_bic"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A SWIFT/BIC that Jiko's screening cannot resolve fails at wire creation rather than at counterparty creation, and surfaces as a pre-condition failure. If an international wire is rejected with one, check the BIC before looking anywhere else."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-the-wire","__idx":9},"children":["Create the wire"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Identical to a domestic wire:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST /api/v1/jiko-accounts/{account_id}/wires/\n"},"children":[]},{"$$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":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["counterparty_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The linked ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["international_wire"]}," counterparty"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount_usdc"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Amount in USD cents"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_by"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identifier of the person or system instructing the wire. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Required"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Up to 100 characters, carried to the beneficiary"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wire_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Client-generated UUID. Optional, but always supply one"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The endpoint returns ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]}," with an empty body"]},". Without your own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wire_id"]}," you have no handle on the wire and would have to find it by listing and matching on amount and time."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Statuses, webhooks, tracing and the transaction view are the same as for domestic wires — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/partner-api/guides/building/domestic-wires"},"children":["Domestic wires"]},". In short: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SUCCESS"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REJECTED"]},"; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfers.wire.out.processing"]}," (repeatable) then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".success"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".rejected"]},", carrying ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["jiko_account_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wire_id"]},"; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["uetr"]}," is the identifier to exchange with a beneficiary's bank, and it is absent until the wire is exported."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"receiving-an-international-wire","__idx":10},"children":["Receiving an international wire"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is where the international path genuinely differs, and it is the part most integrations get wrong."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["An inbound international wire does not address the portal."]}," The wire is sent to Jiko's account at a correspondent bank, with your customer named as beneficiary. The portal appears only as a reference string in the remittance information, formatted:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"<portal account number> - <customer legal name>\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Jiko uses that string to attribute the funds to a pocket. If the payer omits it or mangles it, there is nothing to attribute against."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Get the details to hand to a payer from:"]},{"$$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":["INTERNATIONAL_WIRE"]}," instruction returns the receiver bank (routing number, SWIFT, name, address), the beneficiary (account number, legal name, address) and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["remittance_info.purpose"]}," — already populated and correct. Pass these verbatim."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["A wire-enabled portal returns both a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DOMESTIC_WIRE"]}," and an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INTERNATIONAL_WIRE"]}," instruction, and they are not interchangeable."]}," The beneficiary account differs between them. Handing an overseas payer the domestic instruction is a wire that does not arrive."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"outcomes","__idx":11},"children":["Outcomes"]},{"$$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":"Outcome"},"children":["Outcome"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What you see"},"children":["What you see"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Wire posted"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfers.wire.in.success"]},", and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WIRE"]}," transaction on the pocket"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Wire returned to sender"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfers.wire.in.rejected"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Beneficiary cannot be resolved to a pocket"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Nothing."]}," Jiko cannot identify the recipient, so no event is emitted and no transaction exists"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Until one of the first two occurs, the wire has no partner-visible representation at all."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Inbound wires post within a bank business day of arriving. One received outside banking hours, at a weekend, or on a bank holiday posts on the next business day."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"reading-it","__idx":12},"children":["Reading it"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /api/v1/wires/?direction=INCOMING\nGET /api/v1/wires/{wire_id}/\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The incoming webhook carries ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wire_id"]},", so fetch the wire directly rather than scanning the transaction feed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On the transaction side, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type: \"WIRE\""]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["direction: \"CREDIT\""]}," carries ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wire_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["portal_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["counterparty_name"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference_number"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["remittance_information.unstructured"]},". On the international path that last field is where the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<portal account number> - <legal name>"]}," reference appears, so it is worth reading even when attribution has already succeeded."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filter[wire]"]}," resolves a wire ID directly to its transaction."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-you-learn-about-the-sender","__idx":13},"children":["What you learn about the sender"]},{"$$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":"What it tells you"},"children":["What it tells you"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["counterparty_name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The originator as named on the incoming message"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference_number"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The wire's reference as recorded on the transaction"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["remittance_information.unstructured"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Free text carried on the wire"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["wire_tracking_info.end_to_end_identification"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A reference set by the sending party, up to 35 characters"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The sender's account number is not exposed."]}," The ISO 20022 message does carry the debtor's account and their bank's details, and Jiko stores them, but neither the transaction nor ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /api/v1/wires/{wire_id}/"]}," returns them. You see who sent the money by name, not by account."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you need a payer-supplied reference you can rely on, ask them to populate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end_to_end_identification"]}," at origination. It is set by the originating party, travels the chain, and is usually the most reliable way to tie an inbound wire to an expected payment."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"see-also","__idx":14},"children":["See also"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/partner-api/guides/building/domestic-wires"},"children":["Domestic wires"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/partner-api/reference/wires/create-wire"},"children":["Create wire"]}]},{"$$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"]}]}]}]},"headings":[{"value":"International wires","id":"international-wires","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Feature flags","id":"feature-flags","depth":3},{"value":"Everything else","id":"everything-else","depth":3},{"value":"Register the counterparty","id":"register-the-counterparty","depth":2},{"value":"Verification","id":"verification","depth":3},{"value":"Workflow","id":"workflow","depth":3},{"value":"Relevant API endpoints","id":"relevant-api-endpoints","depth":3},{"value":"A note on swift_bic","id":"a-note-on-swift_bic","depth":3},{"value":"Create the wire","id":"create-the-wire","depth":2},{"value":"Receiving an international wire","id":"receiving-an-international-wire","depth":2},{"value":"Outcomes","id":"outcomes","depth":3},{"value":"Reading it","id":"reading-it","depth":3},{"value":"What you learn about the sender","id":"what-you-learn-about-the-sender","depth":3},{"value":"See also","id":"see-also","depth":2}],"frontmatter":{"seo":{"title":"International wires"}},"lastModified":"2026-09-22T15:21:07.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/partner-api/guides/building/international-wires","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}