This page lists every data requirement for JPY payments to Japan: the beneficiary and originator identities, the beneficiary financial instrument, and the transaction itself.
The identity and financial instrument tables on this page list only the fields JP_ZENGIN requires, taken from the PII v3 schema. Identities and financial instruments accept further optional fields. For the complete set, see Payment identities and Financial instruments, or use the Payload Schema Utility.
Create the beneficiary identity before the financial instrument, then reference it when you create the payment. See Create and manage identities for the API workflow.
The required fields depend on whether the beneficiary is a business or an individual.
Applies to the B2B, B2B2B, C2B2B use cases. Submit a business identity.
| Field | Required | Type | Constraints |
|---|---|---|---|
businessName | Required | STRING | Business Legal Name. 1–140 characters. Must match ^(?![ .,'&\/()-])(?!.*([ .,'&\/()-])\1)[\p{L}\p{N} .,'&\/()-]+(?<![ .,'&\/-])?$. |
address.streetAddress | Required | ARRAY of STRING | Allows the street address of the business to be held. |
address.country | Required | STRING | Exactly 2 characters. Must match ^[A-Z]+$. |
address.city | Required | STRING | City. 1–140 characters. Must match ^(?![ .'-])(?!.*[ .'-]{2})[\p{L} .'-]+(?<![ .'-])$. |
address.stateOrProvince | Required | STRING | State, province, or county of the business address, as defined by postal services. 1–140 characters. Must match ^(?![ .'-])(?!.*[ .'-]{2})[\p{L}\p{N} .'-]+(?<![ .'-])$. |
address.postalCode | Required | STRING | Postal code for the business. 3–15 characters. Must match ^[\p{L}\p{N}][\p{L}\p{N} -]{1,15}[\p{L}\p{N}]$. |
Applies to the B2B2C, B2C, C2B2C use cases. Submit an individual identity.
| Field | Required | Type | Constraints |
|---|---|---|---|
firstName | Required | STRING | First name of the individual. 1–140 characters. Must match ^(?![ .'-])(?!.*([ .'-])\1)[\p{L} .'-]+(?<![ .'-])$. |
lastName | Required | STRING | Last name of the individual. 1–140 characters. Must match ^(?![ .'-])(?!.*([ .'-])\1)[\p{L} .'-]+(?<![ .'-])$. |
address.streetAddress | Required | ARRAY of STRING | Allows the street address of the individual to be held. |
address.country | Required | STRING | Exactly 2 characters. Must match ^[A-Z]+$. |
address.city | Required | STRING | City. 1–140 characters. Must match ^(?![ .'-])(?!.*[ .'-]{2})[\p{L} .'-]+(?<![ .'-])$. |
address.stateOrProvince | Required | STRING | State, province, or county of the individual's address, as defined by postal services. 1–140 characters. Must match ^(?![ .'-])(?!.*[ .'-]{2})[\p{L}\p{N} .'-]+(?<![ .'-])$. |
address.postalCode | Required | STRING | Postal code for the individual's address. 3–15 characters. Must match ^[\p{L}\p{N}][\p{L}\p{N} -]{1,15}[\p{L}\p{N}]$. |
Set financialInstrumentType: JP_ZENGIN and currency: JPY. Provide the following fields in the jpZengin payment rail object. See Create and manage financial instruments for the API workflow.
| Field | Required | Type | Constraints |
|---|---|---|---|
bankName | Required | STRING | The name of the identity's bank. 2–140 characters. Must match ^(?![ .,'&\/()-])(?!.*([ .,'&\/()-])\1)[\p{L}\p{N} .,'&\/()-]+(?<![ .,'&\/-])?$. |
accountHolderName | Required | STRING | Name of the account holder in Japanese Katakana characters. 1–100 characters. Must match ^[\p{L}\p{N} .,'&\/()-]+$. |
bankCode | Required | STRING | 1–16 characters. Must match ^[A-Za-z0-9]+$. Use the Bank Codes lookup and select Japan to find the bank code. |
branchCode | Required | STRING | Bank-assigned branch code identifying the specific branch. 1–50 characters. Must match ^[A-Za-z0-9]+$. |
accountNumber | Required | STRING | The identity's bank account number. 1–45 characters. Must match ^[A-Za-z0-9]+$. |
accountType | Required | STRING | The identity's account type. One of CHECKING, ORDINARY, SAVINGS. |
Create the originator identity once and reuse it across payments.
The required fields depend on whether the originator is a business or an individual.
Applies to the B2B, B2B2B, B2B2C, B2C use cases. Submit a business identity.
| Field | Required | Type | Constraints |
|---|---|---|---|
businessName | Required | STRING | Business Legal Name. 1–140 characters. Must match ^(?![ .,'&\/()-])(?!.*([ .,'&\/()-])\1)[\p{L}\p{N} .,'&\/()-]+(?<![ .,'&\/-])?$. |
address.streetAddress | Required | ARRAY of STRING | Allows the street address of the business to be held. |
address.country | Required | STRING | Exactly 2 characters. Must match ^[A-Z]+$. |
address.city | Required | STRING | City. 1–140 characters. Must match ^(?![ .'-])(?!.*[ .'-]{2})[\p{L} .'-]+(?<![ .'-])$. |
address.stateOrProvince | Required | STRING | State, province, or county of the business address, as defined by postal services. 1–140 characters. Must match ^(?![ .'-])(?!.*[ .'-]{2})[\p{L}\p{N} .'-]+(?<![ .'-])$. |
address.postalCode | Required | STRING | Postal code for the business. 3–15 characters. Must match ^[\p{L}\p{N}][\p{L}\p{N} -]{1,15}[\p{L}\p{N}]$. |
Applies to the C2B2B, C2B2C use cases. Submit an individual identity.
| Field | Required | Type | Constraints |
|---|---|---|---|
firstName | Required | STRING | First name of the individual. 1–140 characters. Must match ^(?![ .'-])(?!.*([ .'-])\1)[\p{L} .'-]+(?<![ .'-])$. |
lastName | Required | STRING | Last name of the individual. 1–140 characters. Must match ^(?![ .'-])(?!.*([ .'-])\1)[\p{L} .'-]+(?<![ .'-])$. |
address.streetAddress | Required | ARRAY of STRING | Allows the street address of the individual to be held. |
address.country | Required | STRING | Exactly 2 characters. Must match ^[A-Z]+$. |
address.city | Required | STRING | City. 1–140 characters. Must match ^(?![ .'-])(?!.*[ .'-]{2})[\p{L} .'-]+(?<![ .'-])$. |
address.stateOrProvince | Required | STRING | State, province, or county of the individual's address, as defined by postal services. 1–140 characters. Must match ^(?![ .'-])(?!.*[ .'-]{2})[\p{L}\p{N} .'-]+(?<![ .'-])$. |
address.postalCode | Required | STRING | Postal code for the individual's address. 3–15 characters. Must match ^[\p{L}\p{N}][\p{L}\p{N} -]{1,15}[\p{L}\p{N}]$. |
The following transaction-level fields apply to all JPY payments to Japan via Zengin.
| Field | Description | Required | Type | Constraints |
|---|---|---|---|---|
purposeCode | Purpose of payment | Required | ENUM | See valid values below |
paymentMemo | Payment purpose remarks | Required | STRING | Max 100 characters. Required for compliance; not forwarded to the beneficiary. |
sourceOfCash | Source of funds | Required | ENUM | See valid values below |
receiverRelationship | Relationship to the debtor | Required | ENUM | See valid values below |
Valid purposeCode values depend on whether the originator is a business or an individual.
| Code | Description |
|---|---|
ACCT | Account management |
BEXP | Business expenses |
CASH | Cash management transfer |
CISC | Construction |
CMDT | Commodity transfer |
COMM | Commission |
GDDS | Purchase or sale of goods |
HLTC | Health care |
INSU | Insurance |
INVS | Investment and securities |
IPDO | Donation |
LOAN | Loan |
OTHR | Other |
PSFR | Travel |
REAB | Real estate |
RENT | Rent |
SALA | Salary payment |
SCTS | Purchase or sale of services, translation |
STDY | Research expenses |
TAXS | Tax payment |
TRAD | Trade services |
| Code | Description |
|---|---|
ACCT | Account management |
CHAR | Charity payment |
CMDT | Commodity transfer |
COMM | Commission |
COST | Living expense |
EDUC | Education |
FAMI | Family support |
GDDS | Purchase or sale of goods |
GIFT | Gift |
HLTC | Health care |
INSU | Insurance |
INVS | Investment and securities |
IPDO | Donation |
LOAN | Loan |
OTHR | Other |
PENS | Pension |
PSFR | Travel |
REAB | Real estate |
RENT | Rent |
SALA | Salary payment |
SCTS | Purchase or sale of translation service |
STDY | Research expenses |
TAXS | Tax payment |
Valid sourceOfCash values depend on whether the originator is a business or an individual.
| Code | Description |
|---|---|
CASH | Loan drawdown |
COMP | Rental income |
REST | Property sale |
RETA | Company profit |
SEAQ | Company sale |
SVGS | Investment |
| Code | Description |
|---|---|
CASH | Loan drawdown |
COMP | Rental income |
EMIN | Employment income |
GIFT | Gift |
REST | Property sale |
SEAQ | Company sale |
SELF | Self-employment income |
SVGS | Investment |
Valid receiverRelationship values depend on whether the originator is a business or an individual. They do not depend on the beneficiary type.
| Code | Description |
|---|---|
CUST | Customer |
EMPL | Employee |
FRAN | Investment company |
HOLD | Holding company |
LEND | Loan provider |
OTHR | Consultant |
PART | Contractor |
SUPP | Supplier of goods |
VEND | Service provider |
| Code | Description |
|---|---|
CHIL | Child |
FREN | Friend |
OTHR | Other |
PARE | Parent |
PART | Business partner |
SELF | Self |
SIBL | Sibling |
SPOU | Spouse or partner |
SUPP | Supplier |
VEND | Service provider |