From 24a5ef532690d676f827ce85ee406f407d9198ef Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Tue, 21 Jul 2026 09:00:28 +0000 Subject: [PATCH] docs: sync with recent OpenAPI changes Update documentation to reflect recent schema changes: - Business customers now require businessInfo field (#717) - Document 7 new sandbox card simulate endpoints (#715): authorization_advice, balance_inquiry, credit_authorization, credit_authorization_advice, financial_authorization, financial_credit_authorization, return_reversal Co-Authored-By: Claude Opus 4.5 --- .../onboarding/configuring-customers.mdx | 4 +- mintlify/snippets/cards/sandbox-testing.mdx | 139 ++++++++++++++++++ .../snippets/creating-customers/customers.mdx | 2 +- 3 files changed, 142 insertions(+), 3 deletions(-) diff --git a/mintlify/global-p2p/onboarding/configuring-customers.mdx b/mintlify/global-p2p/onboarding/configuring-customers.mdx index 521e92f90..6fdcf790c 100644 --- a/mintlify/global-p2p/onboarding/configuring-customers.mdx +++ b/mintlify/global-p2p/onboarding/configuring-customers.mdx @@ -16,7 +16,7 @@ This guide provides comprehensive information about creating customers in the Gr -The only required field for all customers is `customerType` (`INDIVIDUAL` or `BUSINESS`). It's recommended to also pass a `platformCustomerId` to tie the customer to your internal identifier, but if you don't, one will be generated automatically. +The required field for all customers is `customerType` (`INDIVIDUAL` or `BUSINESS`). For business customers, `businessInfo` is also required. It's recommended to also pass a `platformCustomerId` to tie the customer to your internal identifier, but if you don't, one will be generated automatically. If using sending and receiving to just-in-time UMA addresses, you'll also need to specify the bank account information @@ -147,7 +147,7 @@ curl -sS -X POST "https://api.lightspark.com/grid/2025-10-13/customers" \ Unregulated institutions should initiate a hosted KYC/KYB flow in two steps: create the customer, then generate a hosted KYC link for that customer. While KYC is pending, allow account setup but block funding and money movement. -1. Create the customer with `POST /customers`, supplying any information you already have. Only `customerType` is required. +1. Create the customer with `POST /customers`, supplying any information you already have. For individual customers, only `customerType` is required. For business customers, `businessInfo` is also required. ```bash curl -sS -X POST "https://api.lightspark.com/grid/2025-10-13/customers" \ diff --git a/mintlify/snippets/cards/sandbox-testing.mdx b/mintlify/snippets/cards/sandbox-testing.mdx index d9c175c15..bc3d68fdc 100644 --- a/mintlify/snippets/cards/sandbox-testing.mdx +++ b/mintlify/snippets/cards/sandbox-testing.mdx @@ -5,8 +5,15 @@ Production returns `404` on these paths. ```text POST /sandbox/cards/{id}/simulate/authorization +POST /sandbox/cards/{id}/simulate/authorization_advice +POST /sandbox/cards/{id}/simulate/balance_inquiry POST /sandbox/cards/{id}/simulate/clearing +POST /sandbox/cards/{id}/simulate/credit_authorization +POST /sandbox/cards/{id}/simulate/credit_authorization_advice +POST /sandbox/cards/{id}/simulate/financial_authorization +POST /sandbox/cards/{id}/simulate/financial_credit_authorization POST /sandbox/cards/{id}/simulate/return +POST /sandbox/cards/{id}/simulate/return_reversal ``` Outcomes are deterministic — driven by magic-value suffixes on the @@ -103,6 +110,138 @@ curl -X POST "$GRID_BASE_URL/sandbox/cards/Card:019542f5-b3e7-1d02-0000-00000000 A full refund flips the parent to `REFUNDED`; a partial refund keeps it `SETTLED` with a non-zero `refundedAmount`. +## Authorization advice simulate + +Re-sizes an existing open authorization to a new total amount: + +```bash +curl -X POST "$GRID_BASE_URL/sandbox/cards/Card:019542f5-b3e7-1d02-0000-000000000010/simulate/authorization_advice" \ + -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \ + -H "Content-Type: application/json" \ + -d '{ + "cardTransactionId": "CardTransaction:019542f5-b3e7-1d02-0000-000000000100", + "amount": 2000 + }' +``` + +The `amount` is the new *total* authorized amount. The parent +transaction must be in `AUTHORIZED` or `PARTIALLY_SETTLED` state. + +## Balance inquiry simulate + +Simulates a balance-inquiry authorization (always a zero-amount auth): + +```bash +curl -X POST "$GRID_BASE_URL/sandbox/cards/Card:019542f5-b3e7-1d02-0000-000000000010/simulate/balance_inquiry" \ + -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \ + -H "Content-Type: application/json" \ + -d '{ + "merchant": { + "descriptor": "SHELL OIL 12345678", + "mcc": "5541", + "country": "US" + } + }' +``` + +## Credit authorization simulate + +Simulates an inbound credit authorization (a merchant-initiated credit +to the card, e.g. a refund pushed as an authorization): + +```bash +curl -X POST "$GRID_BASE_URL/sandbox/cards/Card:019542f5-b3e7-1d02-0000-000000000010/simulate/credit_authorization" \ + -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \ + -H "Content-Type: application/json" \ + -d '{ + "amount": 2500, + "currency": { "code": "USD" }, + "merchant": { + "descriptor": "ACME MARKETPLACE", + "mcc": "5942", + "country": "US" + } + }' +``` + +Uses the same [merchant descriptor suffixes](#authorization-simulate) +for outcome control. + +## Credit authorization advice simulate + +Re-sizes an existing credit authorization: + +```bash +curl -X POST "$GRID_BASE_URL/sandbox/cards/Card:019542f5-b3e7-1d02-0000-000000000010/simulate/credit_authorization_advice" \ + -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \ + -H "Content-Type: application/json" \ + -d '{ + "cardTransactionId": "CardTransaction:019542f5-b3e7-1d02-0000-000000000100", + "amount": 3000 + }' +``` + +## Financial authorization simulate + +Simulates a single-message financial authorization (an authorization +that clears in the same message, e.g. an ATM withdrawal): + +```bash +curl -X POST "$GRID_BASE_URL/sandbox/cards/Card:019542f5-b3e7-1d02-0000-000000000010/simulate/financial_authorization" \ + -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \ + -H "Content-Type: application/json" \ + -d '{ + "amount": 8000, + "currency": { "code": "USD" }, + "merchant": { + "descriptor": "ATM WITHDRAWAL 24TH ST", + "mcc": "6011", + "country": "US" + } + }' +``` + +Uses the same [merchant descriptor suffixes](#authorization-simulate) +for outcome control. + +## Financial credit authorization simulate + +Simulates a single-message financial credit (a credit that clears in +the same message, e.g. an ATM deposit or push credit): + +```bash +curl -X POST "$GRID_BASE_URL/sandbox/cards/Card:019542f5-b3e7-1d02-0000-000000000010/simulate/financial_credit_authorization" \ + -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \ + -H "Content-Type: application/json" \ + -d '{ + "amount": 4000, + "currency": { "code": "USD" }, + "merchant": { + "descriptor": "ACME PAYOUTS", + "mcc": "6012", + "country": "US" + } + }' +``` + +Uses the same [merchant descriptor suffixes](#authorization-simulate) +for outcome control. + +## Return reversal simulate + +Reverses a previously settled return: + +```bash +curl -X POST "$GRID_BASE_URL/sandbox/cards/Card:019542f5-b3e7-1d02-0000-000000000010/simulate/return_reversal" \ + -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \ + -H "Content-Type: application/json" \ + -d '{ + "cardTransactionId": "CardTransaction:019542f5-b3e7-1d02-0000-000000000100" + }' +``` + +The parent transaction must be in `REFUNDED` state. + ## End-to-end happy path A simple Sandbox loop that exercises issue → activate → auth → clear diff --git a/mintlify/snippets/creating-customers/customers.mdx b/mintlify/snippets/creating-customers/customers.mdx index 0d6c4deb3..544d6f232 100644 --- a/mintlify/snippets/creating-customers/customers.mdx +++ b/mintlify/snippets/creating-customers/customers.mdx @@ -16,7 +16,7 @@ export const Customers = ({ individualEnabled = true, businessEnabled = true, um Your platform's configuration (retrieved via `GET /config`) includes a `supportedCurrencies` array. Each currency object within this array has a `providerRequiredCustomerFields` list. If a customer is intended to use a specific currency, any fields listed for that currency **must** be provided when creating or updating the customer. - The only required field for all customers is `customerType` (`INDIVIDUAL` or `BUSINESS`). It's recommended to also pass a `platformCustomerId` to tie the customer to your internal identifier, but if you don't, one will be generated automatically. + The required field for all customers is `customerType` (`INDIVIDUAL` or `BUSINESS`). For business customers, `businessInfo` is also required. It's recommended to also pass a `platformCustomerId` to tie the customer to your internal identifier, but if you don't, one will be generated automatically. If using sending and receiving to just-in-time UMA addresses, you'll also need to specify the bank account information