From 554444cb5393d30384a8d4a5dca5f4a89f510d23 Mon Sep 17 00:00:00 2001 From: Shreya Vissamsetti Date: Mon, 6 Jul 2026 23:24:10 +0000 Subject: [PATCH 1/2] Docs: add SWIFT payout documentation (searchable guide + external-account tab) --- mintlify/docs.json | 1 + .../payment-flow/swift-payouts.mdx | 134 ++++++++++++++++++ .../core-concepts/currencies-and-rails.mdx | 2 +- mintlify/snippets/external-accounts.mdx | 42 ++++++ 4 files changed, 178 insertions(+), 1 deletion(-) create mode 100644 mintlify/payouts-and-b2b/payment-flow/swift-payouts.mdx diff --git a/mintlify/docs.json b/mintlify/docs.json index f74c8476f..19a83b930 100644 --- a/mintlify/docs.json +++ b/mintlify/docs.json @@ -142,6 +142,7 @@ "pages": [ "payouts-and-b2b/depositing-funds/depositing-funds", "payouts-and-b2b/payment-flow/send-payment", + "payouts-and-b2b/payment-flow/swift-payouts", "payouts-and-b2b/payment-flow/list-transactions", "payouts-and-b2b/payment-flow/receipts", "payouts-and-b2b/payment-flow/reconciliation", diff --git a/mintlify/payouts-and-b2b/payment-flow/swift-payouts.mdx b/mintlify/payouts-and-b2b/payment-flow/swift-payouts.mdx new file mode 100644 index 000000000..d40768489 --- /dev/null +++ b/mintlify/payouts-and-b2b/payment-flow/swift-payouts.mdx @@ -0,0 +1,134 @@ +--- +title: "SWIFT Payouts" +description: "Send international wire payouts over the SWIFT network by creating a SWIFT external account and paying out with the standard quote flow" +icon: "/images/icons/globe.svg" +"og:image": "/images/og/og-payouts-b2b.png" +--- + +import { FeatureCard, FeatureCardGrid } from '/snippets/feature-card.mdx'; + +Send payouts to bank accounts anywhere in the world over the SWIFT network. Use SWIFT when the destination country or currency isn't covered by one of Grid's local payment rails (like ACH, SEPA, PIX, or SPEI), or when the recipient specifically needs an international wire. + +## How SWIFT payouts work + +You don't select SWIFT with a request parameter — the rail follows from the destination account type. Create an external account with `accountType: "SWIFT_ACCOUNT"`, then send to it with the same quote flow you use for any other payout. Grid routes the payment over SWIFT, and the resulting transaction reports `SWIFT` as its payment rail. + +## Prerequisites + +Before sending SWIFT payouts, ensure you have: + +- An active internal account with sufficient balance +- The recipient's bank details: SWIFT/BIC code, bank name, bank country, and account number (or IBAN) +- Valid API credentials with appropriate permissions + +## Send a SWIFT payout + + + + Register the destination bank account as a SWIFT external account: + +```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": "USD", + "platformAccountId": "swift_usd_001", + "accountInfo": { + "accountType": "SWIFT_ACCOUNT", + "country": "NG", + "swiftCode": "GTBINGLA", + "bankName": "Guaranty Trust Bank", + "accountNumber": "1234567890", + "beneficiary": { + "beneficiaryType": "INDIVIDUAL", + "fullName": "Adaeze Okafor", + "birthDate": "1991-03-22", + "nationality": "NG", + "address": { + "line1": "15 Broad Street", + "city": "Lagos", + "state": "Lagos", + "postalCode": "101233", + "country": "NG" + } + } + } + }' +``` + +Field notes: + +- `currency` is the currency the destination account holds, and `country` is where the bank account is located — they can differ. +- `swiftCode` is the bank's SWIFT/BIC code (8 or 11 characters). +- Provide `accountNumber` for most corridors; use `iban` instead for IBAN-only corridors (e.g. GB, BR). +- `beneficiary` accepts an individual or a business, the same shape as other bank account types. + +Note the `id` from the response (e.g. `ExternalAccount:a12dcbd6-...`) — it's the payout destination. + +See the [SWIFT Account schema](/api-reference/external-accounts/add-a-new-external-account) in the API reference for the complete field list. + + + + Request a quote from your internal account to the SWIFT external account: + +```bash cURL +curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes' \ + -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET' \ + -H 'Content-Type: application/json' \ + -d '{ + "source": { + "sourceType": "ACCOUNT", + "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965" + }, + "destination": { + "destinationType": "ACCOUNT", + "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123" + }, + "lockedCurrencySide": "SENDING", + "lockedCurrencyAmount": 100000, + "description": "Payment for services - Invoice #1234" + }' +``` + +The quote response includes the exchange rate (for cross-currency payouts), fees, and the receiving amount, so you can review the full cost before committing. See [Sending Payments](/payouts-and-b2b/payment-flow/send-payment) for the complete quote flow and response shape. + + + + Execute the quote before it expires to initiate the wire: + +```bash cURL +curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes/Quote:019542f5-b3e7-1d02-0000-000000000025/execute' \ + -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET' +``` + + + Once executed, the quote creates a transaction and the payout begins processing over SWIFT. Use the `transactionId` to track it. + + + + + The transaction progresses through `PENDING` → `PROCESSING` → `COMPLETED` or `FAILED`, and you'll receive `OUTGOING_PAYMENT.` webhooks along the way — same as any other payout. If the payout fails, Grid initiates a refund automatically. + + + For the full state diagram and webhook scenarios, see the [Transaction Lifecycle](/platform-overview/core-concepts/transaction-lifecycle) guide. + + + + +## Next steps + + + + Add and manage payout destinations, including SWIFT accounts + + + The complete quote and transfer flow + + + Handle payout failures and error scenarios + + + See which currencies and rails Grid supports + + diff --git a/mintlify/platform-overview/core-concepts/currencies-and-rails.mdx b/mintlify/platform-overview/core-concepts/currencies-and-rails.mdx index 7a086ce2e..d36fa2c29 100644 --- a/mintlify/platform-overview/core-concepts/currencies-and-rails.mdx +++ b/mintlify/platform-overview/core-concepts/currencies-and-rails.mdx @@ -14,7 +14,7 @@ Grid supports a wide range of fiat currencies and cryptocurrencies, with automat -Grid automatically selects the optimal rail based on currency, country, and amount. You don't need to specify the rail in your API requests. +Grid automatically selects the optimal rail based on currency, country, and amount. You don't need to specify the rail in your API requests. For destinations without a local rail, create a SWIFT external account to pay out over international wire — see [SWIFT Payouts](/payouts-and-b2b/payment-flow/swift-payouts). ## Currency Conversion diff --git a/mintlify/snippets/external-accounts.mdx b/mintlify/snippets/external-accounts.mdx index 16fb671ec..461760d5e 100644 --- a/mintlify/snippets/external-accounts.mdx +++ b/mintlify/snippets/external-accounts.mdx @@ -789,6 +789,48 @@ curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers/external-acco + +**SWIFT / International Wire** + +Use a SWIFT account to send payouts to bank accounts in countries or currencies where Grid doesn't offer a local payment rail. Provide the bank's SWIFT/BIC code and the beneficiary's account number (or IBAN for IBAN-based corridors). + +```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": "USD", + "platformAccountId": "swift_usd_001", + "accountInfo": { + "accountType": "SWIFT_ACCOUNT", + "country": "NG", + "swiftCode": "GTBINGLA", + "bankName": "Guaranty Trust Bank", + "accountNumber": "1234567890", + "beneficiary": { + "beneficiaryType": "INDIVIDUAL", + "fullName": "Adaeze Okafor", + "birthDate": "1991-03-22", + "nationality": "NG", + "address": { + "line1": "15 Broad Street", + "city": "Lagos", + "state": "Lagos", + "postalCode": "101233", + "country": "NG" + } + } + } + }' +``` + + + `currency` is the currency the destination account holds, and `country` is where the bank + account is located — they can differ. Provide `accountNumber` for most corridors; use `iban` + instead for IBAN-only corridors (e.g. GB, BR). + + + **Bitcoin Lightning (Spark Wallet)** From a1f9d1fc17012b91f77b929799138630acab66d4 Mon Sep 17 00:00:00 2001 From: Shreya Vissamsetti Date: Tue, 7 Jul 2026 15:28:20 +0000 Subject: [PATCH 2/2] Remove dedicated SWIFT Payouts page; keep the external-accounts SWIFT tab Per shreya's feedback the separate guide page was excessive. Search discoverability is preserved: snippet tab titles are indexed per importing page, so the SWIFT (International) tab surfaces on all four External Accounts pages. Co-Authored-By: shreyav --- mintlify/docs.json | 1 - .../payment-flow/swift-payouts.mdx | 134 ------------------ .../core-concepts/currencies-and-rails.mdx | 2 +- 3 files changed, 1 insertion(+), 136 deletions(-) delete mode 100644 mintlify/payouts-and-b2b/payment-flow/swift-payouts.mdx diff --git a/mintlify/docs.json b/mintlify/docs.json index 19a83b930..f74c8476f 100644 --- a/mintlify/docs.json +++ b/mintlify/docs.json @@ -142,7 +142,6 @@ "pages": [ "payouts-and-b2b/depositing-funds/depositing-funds", "payouts-and-b2b/payment-flow/send-payment", - "payouts-and-b2b/payment-flow/swift-payouts", "payouts-and-b2b/payment-flow/list-transactions", "payouts-and-b2b/payment-flow/receipts", "payouts-and-b2b/payment-flow/reconciliation", diff --git a/mintlify/payouts-and-b2b/payment-flow/swift-payouts.mdx b/mintlify/payouts-and-b2b/payment-flow/swift-payouts.mdx deleted file mode 100644 index d40768489..000000000 --- a/mintlify/payouts-and-b2b/payment-flow/swift-payouts.mdx +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: "SWIFT Payouts" -description: "Send international wire payouts over the SWIFT network by creating a SWIFT external account and paying out with the standard quote flow" -icon: "/images/icons/globe.svg" -"og:image": "/images/og/og-payouts-b2b.png" ---- - -import { FeatureCard, FeatureCardGrid } from '/snippets/feature-card.mdx'; - -Send payouts to bank accounts anywhere in the world over the SWIFT network. Use SWIFT when the destination country or currency isn't covered by one of Grid's local payment rails (like ACH, SEPA, PIX, or SPEI), or when the recipient specifically needs an international wire. - -## How SWIFT payouts work - -You don't select SWIFT with a request parameter — the rail follows from the destination account type. Create an external account with `accountType: "SWIFT_ACCOUNT"`, then send to it with the same quote flow you use for any other payout. Grid routes the payment over SWIFT, and the resulting transaction reports `SWIFT` as its payment rail. - -## Prerequisites - -Before sending SWIFT payouts, ensure you have: - -- An active internal account with sufficient balance -- The recipient's bank details: SWIFT/BIC code, bank name, bank country, and account number (or IBAN) -- Valid API credentials with appropriate permissions - -## Send a SWIFT payout - - - - Register the destination bank account as a SWIFT external account: - -```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": "USD", - "platformAccountId": "swift_usd_001", - "accountInfo": { - "accountType": "SWIFT_ACCOUNT", - "country": "NG", - "swiftCode": "GTBINGLA", - "bankName": "Guaranty Trust Bank", - "accountNumber": "1234567890", - "beneficiary": { - "beneficiaryType": "INDIVIDUAL", - "fullName": "Adaeze Okafor", - "birthDate": "1991-03-22", - "nationality": "NG", - "address": { - "line1": "15 Broad Street", - "city": "Lagos", - "state": "Lagos", - "postalCode": "101233", - "country": "NG" - } - } - } - }' -``` - -Field notes: - -- `currency` is the currency the destination account holds, and `country` is where the bank account is located — they can differ. -- `swiftCode` is the bank's SWIFT/BIC code (8 or 11 characters). -- Provide `accountNumber` for most corridors; use `iban` instead for IBAN-only corridors (e.g. GB, BR). -- `beneficiary` accepts an individual or a business, the same shape as other bank account types. - -Note the `id` from the response (e.g. `ExternalAccount:a12dcbd6-...`) — it's the payout destination. - -See the [SWIFT Account schema](/api-reference/external-accounts/add-a-new-external-account) in the API reference for the complete field list. - - - - Request a quote from your internal account to the SWIFT external account: - -```bash cURL -curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes' \ - -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET' \ - -H 'Content-Type: application/json' \ - -d '{ - "source": { - "sourceType": "ACCOUNT", - "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965" - }, - "destination": { - "destinationType": "ACCOUNT", - "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123" - }, - "lockedCurrencySide": "SENDING", - "lockedCurrencyAmount": 100000, - "description": "Payment for services - Invoice #1234" - }' -``` - -The quote response includes the exchange rate (for cross-currency payouts), fees, and the receiving amount, so you can review the full cost before committing. See [Sending Payments](/payouts-and-b2b/payment-flow/send-payment) for the complete quote flow and response shape. - - - - Execute the quote before it expires to initiate the wire: - -```bash cURL -curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes/Quote:019542f5-b3e7-1d02-0000-000000000025/execute' \ - -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET' -``` - - - Once executed, the quote creates a transaction and the payout begins processing over SWIFT. Use the `transactionId` to track it. - - - - - The transaction progresses through `PENDING` → `PROCESSING` → `COMPLETED` or `FAILED`, and you'll receive `OUTGOING_PAYMENT.` webhooks along the way — same as any other payout. If the payout fails, Grid initiates a refund automatically. - - - For the full state diagram and webhook scenarios, see the [Transaction Lifecycle](/platform-overview/core-concepts/transaction-lifecycle) guide. - - - - -## Next steps - - - - Add and manage payout destinations, including SWIFT accounts - - - The complete quote and transfer flow - - - Handle payout failures and error scenarios - - - See which currencies and rails Grid supports - - diff --git a/mintlify/platform-overview/core-concepts/currencies-and-rails.mdx b/mintlify/platform-overview/core-concepts/currencies-and-rails.mdx index d36fa2c29..694a807e0 100644 --- a/mintlify/platform-overview/core-concepts/currencies-and-rails.mdx +++ b/mintlify/platform-overview/core-concepts/currencies-and-rails.mdx @@ -14,7 +14,7 @@ Grid supports a wide range of fiat currencies and cryptocurrencies, with automat -Grid automatically selects the optimal rail based on currency, country, and amount. You don't need to specify the rail in your API requests. For destinations without a local rail, create a SWIFT external account to pay out over international wire — see [SWIFT Payouts](/payouts-and-b2b/payment-flow/swift-payouts). +Grid automatically selects the optimal rail based on currency, country, and amount. You don't need to specify the rail in your API requests. For destinations without a local rail, create a SWIFT external account to pay out over international wire — see [External Accounts](/payouts-and-b2b/depositing-funds/external-accounts). ## Currency Conversion