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.
Required end-user disclosure. When you build wire entry screens in your own UI, you must show your end users the following: "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."
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 403. Ask your Jiko point of contact for the ones you need.
| Flag | Needed for | Without it |
|---|---|---|
international_wire_counterparty | Creating any counterparty with type: "international_wire". There is no other way to address a non-US account | 403 at counterparty creation. Nothing else about the product is reachable |
enable_counterparty_ownership | Sending ownership_type on the counterparty | 403. Omitting the field is accepted |
unverified_wire_counterparty gates the domestic wire type only. On the international type, unverified is covered by international_wire_counterparty.
Neither flag gates the wire itself — POST /api/v1/jiko-accounts/{account_id}/wires/ carries no feature flag.
- Outbound wires enabled on your partnership, as for domestic. Commercial rather than a flag.
- An approved customer and a pocket in
OPENstatus. - An
international_wirecounterparty inLINKEDstatus.FAILED,UNLINKEDandCLOSEDare terminal — none returns toLINKED, so recovering means registering a new counterparty. - A verification method that fits. Only
supporting_documentsandunverifiedexist here, andunverifiedis for third-party destinations.supporting_documentsneeds at least one already-uploaded document ID and is reviewed by Jiko over days, so it is not a same-day path. - 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.
- Balance that can actually move. Read
liquidation_value_t0andliquidation_value_t1, nottotal_value. created_byon every wire, and awire_idyou generate yourself — the create call returns201with an empty body.- The end-user disclosure above, shown in your own UI. A contractual condition of the product.
- A wire-enabled portal and the
INTERNATIONAL_WIREfunding instruction, to receive. The portal must beOPENand carryWIRE, and the payer must reproduce the reference string exactly — an inbound international wire is attributed by that string, not by the beneficiary account. - A webhook subscription for
transfers.wire.out.*and, for inbound,transfers.wire.in.successandtransfers.wire.in.rejected.
POST /api/v2/customers/{customer_id}/counterparties/with type: "international_wire":
| Field | Notes |
|---|---|
counterparty_name | Discriminated on type: individual (first_name, last_name) or business (business_name) |
address | Beneficiary address |
swift_bic | 8 or 11 characters, AAAAAA + 2 + optional 3 |
identifier | The beneficiary account — an IBAN or a local account identifier |
identifier_type | iban or local (default local) |
bank_name | Beneficiary bank |
wire_instructions | Up to 140 characters, carried on the message |
ownership_type | FIRST_PARTY or THIRD_PARTY |
display_name | Up to 200 characters, your own label, no effect on routing |
| Method | Allowed on | Notes |
|---|---|---|
supporting_documents | First or third party | Documents submitted and reviewed by Jiko. Takes days |
unverified | Third party only | For payments to someone other than your customer, where ownership verification is not the right check. Enabled per partner |
incoming_wire and pre_verified are domestic-wire methods and are not available here.
Wait for counterparty.status.linked before originating. FAILED, UNLINKED and CLOSED are all terminal — none of them returns to LINKED, so recovering means registering a new counterparty.
Partner systems:
- Collect the beneficiary's details, including a SWIFT/BIC and either an IBAN or a local account identifier.
- Register the counterparty with
type: "international_wire". Onlysupporting_documentsandunverifiedare available, andunverifiedis for third-party destinations. - Wait for
counterparty.status.linked. - Create the wire with your own
wire_idand acreated_by— the same endpoint as a domestic wire. - Track it by
wire_id, and surfaceuetrto anyone chasing the payment.
| Step | Purpose | Endpoint |
|---|---|---|
| 1 | Register the beneficiary as a counterparty | POST /api/v2/customers/{customer_id}/counterparties/ |
| 2 | Check its status without waiting on the webhook | GET /api/v2/customers/{customer_id}/counterparties/{counterparty_id}/ |
| 3 | Send the wire | POST /api/v1/jiko-accounts/{account_id}/wires/ |
| 4 | Read it back, including wire_tracking_info | GET /api/v1/wires/{wire_id}/ |
| 5 | List inbound wires | GET /api/v1/wires/?direction=INCOMING |
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.
Identical to a domestic wire:
POST /api/v1/jiko-accounts/{account_id}/wires/| Field | Notes |
|---|---|
counterparty_id | The linked international_wire counterparty |
amount_usdc | Amount in USD cents |
created_by | Identifier of the person or system instructing the wire. Required |
description | Up to 100 characters, carried to the beneficiary |
wire_id | Client-generated UUID. Optional, but always supply one |
The endpoint returns 201 with an empty body. Without your own wire_id you have no handle on the wire and would have to find it by listing and matching on amount and time.
Statuses, webhooks, tracing and the transaction view are the same as for domestic wires — see Domestic wires. In short: PENDING → SUCCESS or REJECTED; transfers.wire.out.processing (repeatable) then .success or .rejected, carrying jiko_account_id and wire_id; uetr is the identifier to exchange with a beneficiary's bank, and it is absent until the wire is exported.
This is where the international path genuinely differs, and it is the part most integrations get wrong.
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:
<portal account number> - <customer legal name>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.
Get the details to hand to a payer from:
GET /api/v2/pockets/{pocket_id}/portals/{portal_id}/funding-instructions/The INTERNATIONAL_WIRE instruction returns the receiver bank (routing number, SWIFT, name, address), the beneficiary (account number, legal name, address) and a remittance_info.purpose — already populated and correct. Pass these verbatim.
A wire-enabled portal returns both a DOMESTIC_WIRE and an 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.
| Outcome | What you see |
|---|---|
| Wire posted | transfers.wire.in.success, and a WIRE transaction on the pocket |
| Wire returned to sender | transfers.wire.in.rejected |
| Beneficiary cannot be resolved to a pocket | Nothing. Jiko cannot identify the recipient, so no event is emitted and no transaction exists |
Until one of the first two occurs, the wire has no partner-visible representation at all.
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.
GET /api/v1/wires/?direction=INCOMING
GET /api/v1/wires/{wire_id}/The incoming webhook carries wire_id, so fetch the wire directly rather than scanning the transaction feed.
On the transaction side, type: "WIRE" with direction: "CREDIT" carries wire_id, portal_id, counterparty_name, reference_number and remittance_information.unstructured. On the international path that last field is where the <portal account number> - <legal name> reference appears, so it is worth reading even when attribution has already succeeded.
filter[wire] resolves a wire ID directly to its transaction.
| Field | What it tells you |
|---|---|
counterparty_name | The originator as named on the incoming message |
reference_number | The wire's reference as recorded on the transaction |
remittance_information.unstructured | Free text carried on the wire |
wire_tracking_info.end_to_end_identification | A reference set by the sending party, up to 35 characters |
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 GET /api/v1/wires/{wire_id}/ returns them. You see who sent the money by name, not by account.
If you need a payer-supplied reference you can rely on, ask them to populate 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.