Skip to content

feat: adding more docs about minimum required data for external accounts #312

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
+111 −0
Open

feat: adding more docs about minimum required data for external accounts #312

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
111 changes: 111 additions & 0 deletions mintlify/snippets/external-accounts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,79 @@ curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers/external-acco

</Tab>

<Tab title="Philippines">
**PHP Bank Transfer**

```bash cURL
curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers/external-accounts' \
-H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET' \
-H 'Content-Type: application/json' \
-d '{
"currency": "PHP",
"platformAccountId": "ph_bank_001",
"accountInfo": {
"accountType": "PHP_ACCOUNT",
"bankName": "BDO Unibank",
"accountNumber": "001234567890",
"paymentRails": ["BANK_TRANSFER"],
"beneficiary": {
"beneficiaryType": "INDIVIDUAL",
"fullName": "Maria Santos",
"birthDate": "1995-04-10",
"nationality": "PH",
"address": {
"line1": "123 Rizal Avenue",
"city": "Manila",
"state": "Metro Manila",
"postalCode": "1000",
"country": "PH"
}
}
}
}'
```

<Note>
Account number must be 8-16 digits.
</Note>
</Tab>

<Tab title="United Kingdom">
**GBP Faster Payments**

```bash cURL
curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers/external-accounts' \
-H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET' \
-H 'Content-Type: application/json' \
-d '{
"currency": "GBP",
"platformAccountId": "gb_bank_001",
"accountInfo": {
"accountType": "GBP_ACCOUNT",
"sortCode": "123456",
"accountNumber": "12345678",
"paymentRails": ["FASTER_PAYMENTS"],
"beneficiary": {
"beneficiaryType": "INDIVIDUAL",
"fullName": "James Smith",
"birthDate": "1985-09-03",
"nationality": "GB",
"address": {
"line1": "10 Downing Street",
"city": "London",
"postalCode": "SW1A 2AA",
"country": "GB"
}
}
}
}'
```

<Note>
Sort code must be 6 digits. Account number must be 8 digits. Address is required for GBP individual beneficiaries.
</Note>
</Tab>

<Tab title="India">
**UPI**

Expand Down Expand Up @@ -521,6 +594,31 @@ 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.

### Individual beneficiaries

| Country | Required Fields | Required Address Fields | Notes |
| --- | --- | --- | --- |
| US (USD) | `beneficiaryType`, `fullName` | None (address optional) | |
| Mexico (MXN) | `beneficiaryType`, `fullName` | None (address optional) | |
| Brazil (BRL) | `beneficiaryType`, `fullName` | None (address optional) | `taxId` required at account level |
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps bot Apr 1, 2026

Choose a reason for hiding this comment

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

P2 Brazil taxId note conflicts with the PIX code example

The table notes "taxId required at account level" for Brazil, but the existing PIX code example (around line 88) does not include a taxId field anywhere in the accountInfo payload. A developer reading this table note will look at the code example for guidance on where to place taxId and find nothing there.

Either update the PIX code example to include the taxId field in accountInfo, or clarify in the note precisely what the field name and location are (e.g. accountInfo.taxId).

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

Comment:
**Brazil `taxId` note conflicts with the PIX code example**

The table notes "`taxId` required at account level" for Brazil, but the existing PIX code example (around line 88) does not include a `taxId` field anywhere in the `accountInfo` payload. A developer reading this table note will look at the code example for guidance on where to place `taxId` and find nothing there.

Either update the PIX code example to include the `taxId` field in `accountInfo`, or clarify in the note precisely what the field name and location are (e.g. `accountInfo.taxId`).

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

| Philippines (PHP) | `beneficiaryType`, `fullName` | None (address optional) | |
| United Kingdom (GBP) | `beneficiaryType`, `fullName`, `address` | `line1`, `postalCode`, `country` | Address is required |
| Europe (EUR) | `beneficiaryType`, `fullName`, `address` | `line1`, `postalCode`, `country` | Address is required |
Comment on lines +603 to +610
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps bot Apr 1, 2026

Choose a reason for hiding this comment

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

P2 Minimum required fields table is missing many supported countries

The new table covers US, Mexico, Brazil, Philippines, and United Kingdom/Europe, but the tabs section documents many additional countries — India (INR), Nigeria (NGN), South Africa (ZAR), Kenya (KES), Tanzania (TZS), Zambia (ZMW), Rwanda (RWF), and Canada (CAD) — none of which appear here. Developers targeting those markets will search this table and find nothing, undercutting the table's value as a comprehensive reference.

Consider adding rows for the remaining countries, or adding a clarifying note (e.g. "Countries not listed above follow the same rules as US (USD)") so readers know what applies to omitted regions.

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

Comment:
**Minimum required fields table is missing many supported countries**

The new table covers US, Mexico, Brazil, Philippines, and United Kingdom/Europe, but the tabs section documents many additional countries — India (INR), Nigeria (NGN), South Africa (ZAR), Kenya (KES), Tanzania (TZS), Zambia (ZMW), Rwanda (RWF), and Canada (CAD) — none of which appear here. Developers targeting those markets will search this table and find nothing, undercutting the table's value as a comprehensive reference.

Consider adding rows for the remaining countries, or adding a clarifying note (e.g. "Countries not listed above follow the same rules as US (USD)") so readers know what applies to omitted regions.

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


### Business beneficiaries

| Country | Required Fields | Required Address Fields | Notes |
| --- | --- | --- | --- |
| All countries | `beneficiaryType`, `legalName` | None (address optional) | Same requirements across all regions |
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps bot Apr 1, 2026

Choose a reason for hiding this comment

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

P1 legalName field path is incorrect for business beneficiaries

The table lists legalName as a required field directly on the beneficiary object, but the actual API structure (shown in the "Business beneficiaries" code example above at line ~580) nests it under businessInfo.legalName. A developer relying on this table would likely send:

"beneficiary": {
  "beneficiaryType": "BUSINESS",
  "legalName": "Acme Corp"
}

…instead of the correct structure:

"beneficiary": {
  "beneficiaryType": "BUSINESS",
  "businessInfo": {
    "legalName": "Acme Corp"
  }
}

This will likely result in an API error or silent field-drop for developers using this table as a reference.

Suggested change
| All countries | `beneficiaryType`, `legalName` | None (address optional) | Same requirements across all regions |
| All countries | `beneficiaryType`, `businessInfo.legalName` | None (address optional) | Same requirements across all regions |
Prompt To Fix With AI 
This is a comment left during a code review.
Path: mintlify/snippets/external-accounts.mdx
Line: 616

Comment:
**`legalName` field path is incorrect for business beneficiaries**

The table lists `legalName` as a required field directly on the beneficiary object, but the actual API structure (shown in the "Business beneficiaries" code example above at line ~580) nests it under `businessInfo.legalName`. A developer relying on this table would likely send:

```json
"beneficiary": {
  "beneficiaryType": "BUSINESS",
  "legalName": "Acme Corp"
}
```

…instead of the correct structure:

```json
"beneficiary": {
  "beneficiaryType": "BUSINESS",
  "businessInfo": {
    "legalName": "Acme Corp"
  }
}
```

This will likely result in an API error or silent field-drop for developers using this table as a reference.

```suggestion
| All countries | `beneficiaryType`, `businessInfo.legalName` | None (address optional) | Same requirements across all regions |
```

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


<Info>
While only the fields listed above are strictly required, providing additional information like `birthDate`, `nationality`, and `address` can speed up compliance review and reduce the chance of your account being held in `UNDER_REVIEW` status.
</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 Expand Up @@ -587,6 +685,19 @@ if (!/^\d{7,12}$/.test(cadAccountNumber)) {
throw new Error("Invalid Canadian account number");
}

// PHP: 8-16 digit account number
if (!/^\d{8,16}$/.test(phpAccountNumber)) {
throw new Error("Invalid Philippine account number");
}

// GBP: 6-digit sort code, 8-digit account number
if (!/^\d{6}$/.test(sortCode)) {
throw new Error("Invalid sort code");
}
if (!/^\d{8}$/.test(gbpAccountNumber)) {
throw new Error("Invalid UK account number");
}

// ZAR: 9-13 digit account number
if (!/^\d{9,13}$/.test(zarAccountNumber)) {
throw new Error("Invalid South African account number");
Expand Down
Loading