docs: add Global Accounts tab #403
+1,814
−217
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| --- | ||
| title: "Authentication" | ||
| description: "Authenticate customers before signed Global Account actions." | ||
| icon: "/images/icons/shield.svg" | ||
| "og:image": "/images/og/og-global-accounts.webp" | ||
| --- | ||
|
|
||
| import Authentication from '/snippets/embedded-wallets/authentication.mdx'; | ||
|
|
||
| Global Accounts require customer authentication before outbound actions, credential changes, session revocation, and wallet export. | ||
|
|
||
| Use this guide to register customer credentials, issue sessions, and authorize signed account actions. The endpoint group is named `Embedded Wallet Auth` in the API reference. | ||
|
|
||
| <Authentication /> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| --- | ||
| title: "Client keys" | ||
| description: "Understand the client keys used to sign Global Account actions." | ||
| icon: "/images/icons/key2.svg" | ||
| "og:image": "/images/og/og-global-accounts.webp" | ||
| --- | ||
|
|
||
| import ClientKeys from '/snippets/embedded-wallets/client-keys.mdx'; | ||
|
|
||
| Client keys bind a signed Global Account action to the customer's current device. | ||
|
|
||
| When a customer authorizes an outbound action, the client generates a key pair and sends the public key to Grid during credential verification. Grid encrypts the short-lived session signing key to that public key. Only the device with the matching private key can decrypt it and sign the action. | ||
|
|
||
| ## What client keys protect | ||
|
|
||
| Client keys help ensure that: | ||
|
|
||
| - The session signing key is delivered only to the device that requested it | ||
| - A stolen encrypted session key cannot be used by another device | ||
| - A signed withdrawal or account action is tied to an authenticated customer session | ||
|
|
||
| ## Signing responsibilities | ||
|
|
||
| Your frontend or mobile app handles device-local key generation, decryption, and signing. Your backend holds Grid API credentials and brokers requests to Grid. | ||
|
|
||
| The client should never receive your Grid client secret. | ||
|
|
||
| ## Full signing flow | ||
|
|
||
| Use the reference below to generate client keys, decrypt session material, and authorize `payloadToSign` values. | ||
|
|
||
| <ClientKeys /> | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| --- | ||
| title: "Core concepts" | ||
| description: "Learn the key Global Accounts concepts and API object names." | ||
| icon: "/images/icons/file-text.svg" | ||
| "og:image": "/images/og/og-global-accounts.webp" | ||
| --- | ||
|
|
||
| This page focuses on the concepts specific to Global Accounts. For the full Grid entity model, see [Entities](/platform-overview/core-concepts/entities) and [Account model](/platform-overview/core-concepts/account-model). | ||
|
|
||
| ## How Global Accounts fit into Grid | ||
|
|
||
| A platform creates customers. Each eligible customer gets a Global Account. In the API, that account is an internal account with `type: "EMBEDDED_WALLET"`. Funding and withdrawals use quotes, while outbound movement requires customer authorization. | ||
|
|
||
| For a step-by-step implementation path, see [Implementation overview](/global-accounts/implementation-overview). | ||
|
|
||
| ## Key objects | ||
|
|
||
| | Object | Meaning | | ||
| | --- | --- | | ||
| | Global Account | A branded account experience that lets a customer hold a stable dollar balance and move funds through supported Grid rails. | | ||
| | Customer | The person or business that owns the Global Account. Customers are represented by `Customer:...` IDs. | | ||
| | Internal account | The Grid account object that holds the balance. A Global Account is an internal account with `type: "EMBEDDED_WALLET"`. | | ||
| | External account | A bank account, wallet, or other destination outside Grid used for withdrawals and payouts. External accounts use `ExternalAccount:...` IDs. | | ||
| | Quote | A priced payment plan that locks amounts, currencies, fees, and payment instructions before execution. Quotes use `Quote:...` IDs. | | ||
| | Session | A short-lived signing context issued after the customer verifies a credential. Sessions use `Session:...` IDs. | | ||
| | Auth method | A registered customer credential such as passkey, OAuth, or email OTP. Auth methods use `AuthMethod:...` IDs. | | ||
|
|
||
| ## API naming | ||
|
|
||
| In these docs, **Global Account** refers to the customer-facing account product. In the API, that account is represented as an internal account with `type: "EMBEDDED_WALLET"`. | ||
|
|
||
| You may also see endpoint groups such as `Embedded Wallet Auth`; those are the authentication and signing APIs used by Global Accounts. The most important mapping is: | ||
|
|
||
| ```json | ||
| { | ||
| "id": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002", | ||
| "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001", | ||
| "type": "EMBEDDED_WALLET" | ||
| } | ||
| ``` | ||
|
|
||
| ## Global Accounts vs Payouts | ||
|
|
||
| Choose **Global Accounts** when you are building a customer-owned account experience: issuing an account, showing a balance, funding it, requiring customer authorization, and moving money out of that account. | ||
|
|
||
| Choose **Payouts & B2B** when you are building a payouts-only flow: sending money from platform-managed or customer-managed balances to bank accounts and other payout destinations, without a customer-owned account experience. | ||
|
|
||
| The APIs overlap because both products use customers, accounts, quotes, transactions, and webhooks. The difference is the account model and authorization requirement: outbound movement from a Global Account requires a customer signature with `Grid-Wallet-Signature`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,126 @@ | ||
| --- | ||
|
Contributor
There was a problem hiding this comment. a lot of these sections don't contain enough information for an actual implementation, ask claude to review the other business lines |
||
| title: "Customers" | ||
| description: "Configure customers before issuing and using Global Accounts." | ||
| icon: "/images/icons/people.svg" | ||
| "og:image": "/images/og/og-global-accounts.webp" | ||
| --- | ||
|
|
||
| A Global Account belongs to a Grid customer. Before the account can move funds to or from fiat rails, the customer must satisfy the required KYC or KYB checks for your platform and use case. | ||
|
|
||
| ## Customer types | ||
|
|
||
| Global Accounts can be used with individual or business customers, depending on your platform configuration. | ||
|
|
||
| - Use an **individual customer** when the account belongs to a person. | ||
| - Use a **business customer** when the account belongs to a company or organization. | ||
|
|
||
| Your compliance model determines whether Grid hosts the KYC/KYB flow or your platform provides verified customer information. | ||
|
|
||
| ## Create a customer | ||
|
|
||
| Create a customer with `POST /customers`. Use `platformCustomerId` to connect the Grid customer to the user or business in your system. | ||
|
|
||
| ```bash | ||
| curl -X POST "$GRID_BASE_URL/customers" \ | ||
| -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{ | ||
| "customerType": "INDIVIDUAL", | ||
| "platformCustomerId": "customer-123", | ||
| "region": "US", | ||
| "email": "jane@example.com", | ||
| "fullName": "Jane Doe", | ||
| "birthDate": "1990-01-15", | ||
| "nationality": "US", | ||
| "address": { | ||
| "line1": "123 Main Street", | ||
| "city": "San Francisco", | ||
| "state": "CA", | ||
| "postalCode": "94105", | ||
| "country": "US" | ||
| } | ||
| }' | ||
| ``` | ||
|
|
||
| The response includes the Grid-assigned `Customer:...` ID. Store both IDs: | ||
|
|
||
| - `Customer:...` for Grid API calls | ||
| - `platformCustomerId` for your internal records and hosted KYC links | ||
|
|
||
| ## KYC/KYB options | ||
|
|
||
| Global Accounts can only move funds to or from fiat rails after the required compliance checks are complete. | ||
|
|
||
| | Platform model | Typical flow | | ||
| | --- | --- | | ||
| | Regulated platform | Your platform performs KYC/KYB and creates or updates customers through the API. | | ||
| | Non-regulated platform | Grid can host the KYC/KYB flow and notify you when verification state changes. | | ||
|
|
||
| For hosted verification, generate a KYC link for the customer: | ||
|
|
||
| ```bash | ||
| curl -X GET "$GRID_BASE_URL/customers/kyc-link?platformCustomerId=customer-123&redirectUri=https://yourapp.com/onboarding-complete" \ | ||
| -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" | ||
| ``` | ||
|
|
||
| After the customer completes hosted verification, use customer or verification webhooks to update your product state. | ||
|
|
||
| ## Account provisioning | ||
|
|
||
| When a customer is created on a platform enabled for Global Accounts, Grid provisions a Global Account as an internal account with `type: "EMBEDDED_WALLET"`. | ||
|
|
||
| Use the customer's `Customer:...` ID to list internal accounts: | ||
|
|
||
| ```bash | ||
| curl -X GET "$GRID_BASE_URL/customers/internal-accounts?customerId=Customer:019542f5-b3e7-1d02-0000-000000000001&type=EMBEDDED_WALLET" \ | ||
| -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" | ||
| ``` | ||
|
|
||
| If no `EMBEDDED_WALLET` account appears, confirm that: | ||
|
|
||
| - The platform is enabled for Global Accounts. | ||
| - The customer is eligible for the configured Global Accounts currencies. | ||
| - The customer has completed the required KYC/KYB checks before attempting fiat movement. | ||
|
|
||
| ## Compliance before movement | ||
|
|
||
| <Warning> | ||
| Do not let customers move funds to or from fiat rails until the required KYC or KYB checks are complete. Sandbox can approve customers automatically for testing, but production behavior depends on your platform setup. | ||
| </Warning> | ||
|
|
||
| ## Updating and finding customers | ||
|
|
||
| Retrieve a customer by ID: | ||
|
|
||
| ```bash | ||
| curl -X GET "$GRID_BASE_URL/customers/Customer:019542f5-b3e7-1d02-0000-000000000001" \ | ||
| -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" | ||
| ``` | ||
|
|
||
| Or find customers by your own platform ID: | ||
|
|
||
| ```bash | ||
| curl -X GET "$GRID_BASE_URL/customers?platformCustomerId=customer-123" \ | ||
| -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" | ||
| ``` | ||
|
|
||
| If customer information changes, update it before starting payment flows that rely on that information: | ||
|
|
||
| ```bash | ||
| curl -X PATCH "$GRID_BASE_URL/customers/Customer:019542f5-b3e7-1d02-0000-000000000001" \ | ||
| -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{ | ||
| "customerType": "INDIVIDUAL", | ||
| "fullName": "Jane Doe", | ||
| "birthDate": "1990-01-15", | ||
| "nationality": "US" | ||
| }' | ||
| ``` | ||
|
|
||
| ## Related docs | ||
|
|
||
| - [Internal accounts](/global-accounts/internal-accounts) | ||
| - [Account model](/platform-overview/core-concepts/account-model) | ||
| - [Implementation overview](/global-accounts/implementation-overview) | ||
| - [Webhooks](/global-accounts/webhooks) | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
pull more from the current keys docs