From 25d2f667268046d91716f63fb3c9dc192e0d39d1 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Thu, 14 May 2026 09:05:02 +0000 Subject: [PATCH] Sync docs with recent OpenAPI schema changes Updates documentation to reflect recent schema changes: 1. **Internal Account Status** (cff4d23): Added `status` and `type` fields to internal account examples. Added `INTERNAL_ACCOUNT.STATUS_UPDATED` webhook documentation. 2. **Webhook Type Correction**: Fixed all references from legacy `ACCOUNT_STATUS` type to the correct `INTERNAL_ACCOUNT.BALANCE_UPDATED` enum value across all documentation files. 3. **Colombia (COP) Support** (2033ecc): Added Colombia tab to external-accounts.mdx showing both bank transfer and mobile money (Nequi/Daviplata) flows with new fields (bankName, bankAccountType, documentType, documentNumber). Files updated: - mintlify/platform-overview/core-concepts/account-model.mdx - mintlify/ramps/accounts/internal-accounts.mdx - mintlify/ramps/platform-tools/sandbox-testing.mdx - mintlify/ramps/platform-tools/webhooks.mdx - mintlify/rewards/platform-tools/sandbox-testing.mdx - mintlify/rewards/quickstart.mdx - mintlify/snippets/depositing-funds.mdx - mintlify/snippets/external-accounts.mdx - mintlify/snippets/internal-accounts.mdx - mintlify/snippets/sending/cross-currency.mdx Co-Authored-By: Claude Opus 4.5 --- .../core-concepts/account-model.mdx | 2 +- mintlify/ramps/accounts/internal-accounts.mdx | 28 ++++--- .../ramps/platform-tools/sandbox-testing.mdx | 2 +- mintlify/ramps/platform-tools/webhooks.mdx | 62 +++++++++++---- .../platform-tools/sandbox-testing.mdx | 2 +- mintlify/rewards/quickstart.mdx | 40 +++++----- mintlify/snippets/depositing-funds.mdx | 2 +- mintlify/snippets/external-accounts.mdx | 75 +++++++++++++++++++ mintlify/snippets/internal-accounts.mdx | 6 +- mintlify/snippets/sending/cross-currency.mdx | 4 +- 10 files changed, 169 insertions(+), 54 deletions(-) diff --git a/mintlify/platform-overview/core-concepts/account-model.mdx b/mintlify/platform-overview/core-concepts/account-model.mdx index 5d40d698..35df3735 100644 --- a/mintlify/platform-overview/core-concepts/account-model.mdx +++ b/mintlify/platform-overview/core-concepts/account-model.mdx @@ -212,7 +212,7 @@ PENDING → ACTIVE - **INACTIVE**: Disabled (can be reactivated) - **REJECTED**: Failed verification -You'll receive `ACCOUNT_STATUS` webhooks as status changes. +You'll receive `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhooks as balance changes, and `INTERNAL_ACCOUNT.STATUS_UPDATED` webhooks when account status changes (e.g., ACTIVE to FROZEN). ### Using External Accounts diff --git a/mintlify/ramps/accounts/internal-accounts.mdx b/mintlify/ramps/accounts/internal-accounts.mdx index 2f091360..a874da8b 100644 --- a/mintlify/ramps/accounts/internal-accounts.mdx +++ b/mintlify/ramps/accounts/internal-accounts.mdx @@ -136,22 +136,26 @@ Internal accounts support both fiat and crypto balances: ## Monitoring account balance changes -Subscribe to `ACCOUNT_STATUS` webhooks to receive real-time balance updates: +Subscribe to `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhooks to receive real-time balance updates: ```json { - "accountId": "InternalAccount:btc456", - "oldBalance": { - "amount": 5000000, - "currency": { "code": "BTC", "decimals": 8 } - }, - "newBalance": { - "amount": 10000000, - "currency": { "code": "BTC", "decimals": 8 } - }, + "id": "Webhook:019542f5-b3e7-1d02-0000-000000000007", + "type": "INTERNAL_ACCOUNT.BALANCE_UPDATED", "timestamp": "2025-10-03T14:32:00Z", - "webhookId": "Webhook:webhook001", - "type": "ACCOUNT_STATUS" + "data": { + "id": "InternalAccount:btc456", + "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001", + "type": "INTERNAL_CRYPTO", + "status": "ACTIVE", + "balance": { + "amount": 10000000, + "currency": { "code": "BTC", "name": "Bitcoin", "symbol": "₿", "decimals": 8 } + }, + "fundingPaymentInstructions": [], + "createdAt": "2025-08-01T10:00:00Z", + "updatedAt": "2025-10-03T14:32:00Z" + } } ``` diff --git a/mintlify/ramps/platform-tools/sandbox-testing.mdx b/mintlify/ramps/platform-tools/sandbox-testing.mdx index 1a878952..25c6c288 100644 --- a/mintlify/ramps/platform-tools/sandbox-testing.mdx +++ b/mintlify/ramps/platform-tools/sandbox-testing.mdx @@ -190,7 +190,7 @@ curl -X POST 'https://api.lightspark.com/grid/2025-10-13/sandbox/internal-accoun Replace `InternalAccount:btc001` with your actual BTC internal account ID. - You'll receive an `ACCOUNT_STATUS` webhook showing the updated balance. + You'll receive an `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook showing the updated balance. ### Step 2: Create external bank account diff --git a/mintlify/ramps/platform-tools/webhooks.mdx b/mintlify/ramps/platform-tools/webhooks.mdx index 568f583f..fcf0dd58 100644 --- a/mintlify/ramps/platform-tools/webhooks.mdx +++ b/mintlify/ramps/platform-tools/webhooks.mdx @@ -47,23 +47,27 @@ Grid sends webhooks for key events in the ramp lifecycle: - + Sent when internal account balances change (deposits, conversions, withdrawals). ```json { - "accountId": "InternalAccount:btc456", - "oldBalance": { - "amount": 10000000, - "currency": { "code": "BTC", "decimals": 8 } - }, - "newBalance": { - "amount": 5000000, - "currency": { "code": "BTC", "decimals": 8 } - }, + "id": "Webhook:019542f5-b3e7-1d02-0000-000000000007", + "type": "INTERNAL_ACCOUNT.BALANCE_UPDATED", "timestamp": "2025-10-03T15:03:00Z", - "webhookId": "Webhook:webhook001", - "type": "ACCOUNT_STATUS" + "data": { + "id": "InternalAccount:btc456", + "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001", + "type": "INTERNAL_CRYPTO", + "status": "ACTIVE", + "balance": { + "amount": 5000000, + "currency": { "code": "BTC", "name": "Bitcoin", "symbol": "₿", "decimals": 8 } + }, + "fundingPaymentInstructions": [], + "createdAt": "2025-08-01T10:00:00Z", + "updatedAt": "2025-10-03T15:03:00Z" + } } ``` @@ -72,6 +76,35 @@ Grid sends webhooks for key events in the ramp lifecycle: + + Sent when the status of an internal account changes (e.g., PENDING → ACTIVE, ACTIVE → FROZEN). + + ```json + { + "id": "Webhook:019542f5-b3e7-1d02-0000-000000000008", + "type": "INTERNAL_ACCOUNT.STATUS_UPDATED", + "timestamp": "2025-10-03T15:03:00Z", + "data": { + "id": "InternalAccount:btc456", + "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001", + "type": "INTERNAL_CRYPTO", + "status": "FROZEN", + "balance": { + "amount": 5000000, + "currency": { "code": "BTC", "name": "Bitcoin", "symbol": "₿", "decimals": 8 } + }, + "fundingPaymentInstructions": [], + "createdAt": "2025-08-01T10:00:00Z", + "updatedAt": "2025-10-03T15:03:00Z" + } + } + ``` + + + Account status values: `PENDING` (provisioning), `ACTIVE` (ready for payments), `CLOSED` (customer-initiated), `FROZEN` (compliance/fraud hold). Frozen accounts cannot send or receive payments. + + + Sent when customer KYC verification completes (required before conversions). @@ -240,8 +273,9 @@ if (type === "OUTGOING_PAYMENT.COMPLETED") { Track crypto deposits for off-ramp liquidity: ```javascript -if (type === "ACCOUNT_STATUS") { - const { accountId, newBalance, oldBalance } = req.body; +if (type === "INTERNAL_ACCOUNT.BALANCE_UPDATED") { + const { data } = req.body; + const { id: accountId, balance: newBalance } = data; // Crypto deposit detected if ( diff --git a/mintlify/rewards/platform-tools/sandbox-testing.mdx b/mintlify/rewards/platform-tools/sandbox-testing.mdx index b83f588d..7d3a76cc 100644 --- a/mintlify/rewards/platform-tools/sandbox-testing.mdx +++ b/mintlify/rewards/platform-tools/sandbox-testing.mdx @@ -47,7 +47,7 @@ curl -X POST https://api.lightspark.com/grid/2025-10-13/sandbox/internal-account }' ``` -This endpoint returns the updated `InternalAccount` object with the new balance. You'll also receive an `ACCOUNT_STATUS` webhook showing the balance change. +This endpoint returns the updated `InternalAccount` object with the new balance. You'll also receive an `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook showing the balance change. In production, ACH transfers typically take 1-3 business days to settle. In sandbox, funding is instant. diff --git a/mintlify/rewards/quickstart.mdx b/mintlify/rewards/quickstart.mdx index b8e66629..0d944896 100644 --- a/mintlify/rewards/quickstart.mdx +++ b/mintlify/rewards/quickstart.mdx @@ -140,28 +140,26 @@ When the funds are received and the internal account balance is updated, you'll ```json { - "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965", - "oldBalance": { - "amount": 0, - "currency": { - "code": "USD", - "name": "United States Dollar", - "symbol": "$", - "decimals": 2 - } - }, - "newBalance": { - "amount": 200000, - "currency": { - "code": "USD", - "name": "United States Dollar", - "symbol": "$", - "decimals": 2 - } - }, + "id": "Webhook:019542f5-b3e7-1d02-0000-000000000020", + "type": "INTERNAL_ACCOUNT.BALANCE_UPDATED", "timestamp": "2025-10-03T14:32:00Z", - "webhookId": "Webhook:019542f5-b3e7-1d02-0000-000000000020", - "type": "ACCOUNT_STATUS" + "data": { + "id": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965", + "type": "INTERNAL_FIAT", + "status": "ACTIVE", + "balance": { + "amount": 200000, + "currency": { + "code": "USD", + "name": "United States Dollar", + "symbol": "$", + "decimals": 2 + } + }, + "fundingPaymentInstructions": [], + "createdAt": "2025-10-03T12:00:00Z", + "updatedAt": "2025-10-03T14:32:00Z" + } } ``` diff --git a/mintlify/snippets/depositing-funds.mdx b/mintlify/snippets/depositing-funds.mdx index 9c76035b..adaba3f5 100644 --- a/mintlify/snippets/depositing-funds.mdx +++ b/mintlify/snippets/depositing-funds.mdx @@ -75,7 +75,7 @@ Customer initiates a push payment from their bank or wallet to the account/addre Set up webhook listeners to receive updates for the deposit transaction and account balance updates. The account balance will update automatically. -You'll receive `ACCOUNT_STATUS` webhook events when the internal account balance changes. +You'll receive `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook events when the internal account balance changes. diff --git a/mintlify/snippets/external-accounts.mdx b/mintlify/snippets/external-accounts.mdx index baea75db..4e9fb957 100644 --- a/mintlify/snippets/external-accounts.mdx +++ b/mintlify/snippets/external-accounts.mdx @@ -149,6 +149,81 @@ curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers/external-acco Key types: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, or `RANDOM` + +**Bank Transfer or Mobile Money (Nequi, Daviplata)** + +Colombia supports two payment rails: bank transfer and mobile money. + +**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": "COP", + "platformAccountId": "co_bank_001", + "accountInfo": { + "accountType": "COP_ACCOUNT", + "bankName": "Bancolombia", + "accountNumber": "1234567890", + "bankAccountType": "CHECKING", + "beneficiary": { + "beneficiaryType": "INDIVIDUAL", + "fullName": "Juan Carlos García", + "birthDate": "1988-03-15", + "nationality": "CO", + "documentType": "CC", + "documentNumber": "1234567890", + "address": { + "line1": "Carrera 7 #45-23", + "city": "Bogotá", + "postalCode": "110111", + "country": "CO" + } + } + } + }' +``` + +**Mobile Money (Nequi, Daviplata):** + +```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": "COP", + "platformAccountId": "co_mobile_001", + "accountInfo": { + "accountType": "COP_ACCOUNT", + "phoneNumber": "+573001234567", + "beneficiary": { + "beneficiaryType": "INDIVIDUAL", + "fullName": "María López", + "birthDate": "1992-07-20", + "nationality": "CO", + "documentType": "CC", + "documentNumber": "9876543210", + "address": { + "line1": "Calle 100 #15-30", + "city": "Medellín", + "postalCode": "050021", + "country": "CO" + } + } + } + }' +``` + + + Bank transfer requires `bankName`, `accountNumber`, and `bankAccountType` (CHECKING or SAVINGS). + Mobile money requires `phoneNumber` in international format (e.g., +573001234567). + Most Colombian banks require `documentType` and `documentNumber` for KYC matching. + Document types: `CC` (Cédula de Ciudadanía), `CE` (Cédula de Extranjería), `TI` (Tarjeta de Identidad), `NIT` (Número de Identificación Tributaria), `PP` (Passport). + + + **Bank Transfer or Mobile Money (Tigo Money)** diff --git a/mintlify/snippets/internal-accounts.mdx b/mintlify/snippets/internal-accounts.mdx index 496d7ef2..48cfe9e5 100644 --- a/mintlify/snippets/internal-accounts.mdx +++ b/mintlify/snippets/internal-accounts.mdx @@ -47,6 +47,8 @@ curl -X GET 'https://api.lightspark.com/grid/2025-10-13/customers/internal-accou { "id": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965", "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001", + "type": "INTERNAL_FIAT", + "status": "ACTIVE", "balance": { "amount": 50000, "currency": { @@ -249,6 +251,8 @@ curl -X GET 'https://api.lightspark.com/grid/2025-10-13/customers/internal-accou "data": { "id": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965", "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001", + "type": "INTERNAL_FIAT", + "status": "ACTIVE", "balance": { "amount": 50000, "currency": { @@ -307,7 +311,7 @@ Show the payment details prominently in your UI: Set up webhook listeners to receive notifications when deposits are credited to the internal account. The account balance will update automatically. -You'll receive `ACCOUNT_STATUS` webhook events when the internal account balance changes. +You'll receive `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook events when the internal account balance changes. diff --git a/mintlify/snippets/sending/cross-currency.mdx b/mintlify/snippets/sending/cross-currency.mdx index 42450202..f256f68e 100644 --- a/mintlify/snippets/sending/cross-currency.mdx +++ b/mintlify/snippets/sending/cross-currency.mdx @@ -229,11 +229,11 @@ Grid automatically detects blockchain deposits and processes the transfer once f - Grid monitors the blockchain for incoming deposits. You'll receive an `ACCOUNT_STATUS` webhook when the deposit is confirmed: + Grid monitors the blockchain for incoming deposits. You'll receive an `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook when the deposit is confirmed: ```json { - "type": "ACCOUNT_STATUS", + "type": "INTERNAL_ACCOUNT.BALANCE_UPDATED", "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000025", "oldBalance": { "amount": 0, "currency": { "code": "USDC", "decimals": 2 } }, "newBalance": { "amount": 10000, "currency": { "code": "USDC", "decimals": 2 } },