Skip to content

docs: document business beneficiary requirements #535

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pengying wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document business beneficiary requirements #535

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 21 additions & 1 deletion mintlify/snippets/external-accounts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -879,7 +879,7 @@ For business accounts, include business information:

## Minimum required beneficiary fields

The following table shows the minimum required fields for individual and business beneficiaries by country. All other fields are optional but recommended for faster compliance review.
The following tables show the minimum required fields for individual and business beneficiaries. All other fields are optional but recommended for faster compliance review.

### Individual beneficiaries

Expand All @@ -896,6 +896,26 @@ The following table shows the minimum required fields for individual and busines
While only the fields listed above are strictly required, providing additional information like `birthDate`, `nationality`, and `address` can reduce the likelihood of false positive compliance checks and increase transaction success rates.
</Info>

### Business beneficiaries

For business beneficiaries, the required fields vary by destination currency:

| Currency | Required fields |
| --- | --- |
| USD | `legalName`, `address` |
| MXN | `legalName`, `address` |
| EUR | `legalName`, `address`, `registrationNumber` |
| GBP, INR, BRL, DKK, PHP, HKD, IDR, MYR, SGD, THB, VND, AED | `legalName`, `address` |
| NGN, ZAR, KES, TZS, RWF, ZMW, UGX, BWP, MWK, XOF, XAF | `legalName`, `address`, `registrationNumber`, `taxId` |

<Note>
When sending to GBP, INR, BRL, DKK, PHP, HKD, IDR, MYR, SGD, THB, VND, or AED, business senders (originators) must also provide `registrationNumber`.
</Note>
Comment on lines +911 to +913
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps Bot Jun 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Originator requirement buried in beneficiary section

This <Note> describes an originator/sender requirement (registrationNumber on the sending business), but it appears inside the "Business beneficiaries" section, which developers read to understand what fields the receiving business needs. A developer building the payer side of a Tazapay corridor may not look here — and if they miss the requirement, their transactions will fail. Consider moving this callout to wherever originator/sender fields are documented, or at minimum using a <Warning> (per the style guide, <Warning> is for "critical information about potential issues") to make sure it isn't skimmed.

Prompt To Fix With AI 
This is a comment left during a code review.
Path: mintlify/snippets/external-accounts.mdx
Line: 911-913

Comment:
**Originator requirement buried in beneficiary section**

This `<Note>` describes an originator/sender requirement (`registrationNumber` on the sending business), but it appears inside the "Business beneficiaries" section, which developers read to understand what fields the **receiving** business needs. A developer building the payer side of a Tazapay corridor may not look here — and if they miss the requirement, their transactions will fail. Consider moving this callout to wherever originator/sender fields are documented, or at minimum using a `<Warning>` (per the style guide, `<Warning>` is for "critical information about potential issues") to make sure it isn't skimmed.

How can I resolve this? If you propose a fix, please make it concise.

Fix in Claude Code


<Info>
`registrationNumber` is the business's official registration or incorporation number (e.g., EIN in the US, CNPJ in Brazil, company registration number in the UK). `taxId` is the business's tax identification number where it differs from the registration number.
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps Bot Jun 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 The EIN (Employer Identification Number) is a federal tax identification number issued by the IRS — it is not a company registration or incorporation number. US businesses register at the state level with no single federal registration identifier. Listing EIN as the canonical example for registrationNumber could cause developers to pass their EIN into the wrong field, potentially triggering validation failures in corridors that distinguish between the two. A more accurate example might be a state entity number, or the example could simply be omitted for the US and clarified that registrationNumber and taxId may overlap per jurisdiction.

Suggested change
`registrationNumber` is the business's official registration or incorporation number (e.g., EIN in the US, CNPJ in Brazil, company registration number in the UK). `taxId` is the business's tax identification number where it differs from the registration number.
`registrationNumber` is the business's official registration or incorporation number (e.g., CNPJ in Brazil, company registration number in the UK). `taxId` is the business's tax identification number (e.g., EIN in the US) where it differs from the registration number.
Prompt To Fix With AI 
This is a comment left during a code review.
Path: mintlify/snippets/external-accounts.mdx
Line: 916

Comment:
The EIN (Employer Identification Number) is a federal **tax** identification number issued by the IRS — it is not a company registration or incorporation number. US businesses register at the state level with no single federal registration identifier. Listing EIN as the canonical example for `registrationNumber` could cause developers to pass their EIN into the wrong field, potentially triggering validation failures in corridors that distinguish between the two. A more accurate example might be a state entity number, or the example could simply be omitted for the US and clarified that `registrationNumber` and `taxId` may overlap per jurisdiction.

```suggestion
  `registrationNumber` is the business's official registration or incorporation number (e.g., CNPJ in Brazil, company registration number in the UK). `taxId` is the business's tax identification number (e.g., EIN in the US) where it differs from the registration number.
```

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Fix in Claude Code

</Info>

## Account status
Beneficiary data may be reviewed for risk and compliance. Only `ACTIVE` accounts can receive payments. Updates to account data may trigger account re-review.

Expand Down
Loading