diff --git a/mintlify/global-p2p/quickstart.mdx b/mintlify/global-p2p/quickstart.mdx
index 19ac450c..8d438a94 100644
--- a/mintlify/global-p2p/quickstart.mdx
+++ b/mintlify/global-p2p/quickstart.mdx
@@ -161,8 +161,22 @@ In this guide, the entities map as follows:
```json
{
"id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
+ "status": "PENDING",
+ "source": {
+ "sourceType": "REALTIME_FUNDING",
+ "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
+ "currency": "USDC"
+ },
+ "destination": {
+ "destinationType": "ACCOUNT",
+ "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
+ },
+ "sendingCurrency": { "code": "USDC", "name": "USD Coin", "symbol": "USDC", "decimals": 2 },
+ "receivingCurrency": { "code": "MXN", "name": "Mexican Peso", "symbol": "$", "decimals": 2 },
+ "totalSendingAmount": 10000,
+ "totalReceivingAmount": 168500,
"exchangeRate": 16.85,
- "fees": { "amount": 50, "currency": { "code": "USD", "decimals": 2 } },
+ "feesIncluded": 50,
"paymentInstructions": [
{
"accountOrWalletInfo": {
@@ -178,8 +192,7 @@ In this guide, the entities map as follows:
"assetType": "USDC"
}
}
- ],
- "status": "PENDING"
+ ]
}
```
## Fund the quote (Sandbox simulation)
@@ -201,6 +214,19 @@ In this guide, the entities map as follows:
"id": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
"status": "PROCESSING",
"type": "OUTGOING",
+ "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
+ "platformCustomerId": "alice_user_id",
+ "source": {
+ "sourceType": "REALTIME_FUNDING",
+ "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
+ "currency": "USDC"
+ },
+ "destination": {
+ "destinationType": "ACCOUNT",
+ "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
+ },
+ "sentAmount": { "amount": 10000, "currency": { "code": "USDC", "decimals": 2 } },
+ "receivedAmount": { "amount": 168500, "currency": { "code": "MXN", "decimals": 2 } },
"quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006"
}
```
@@ -210,18 +236,18 @@ In this guide, the entities map as follows:
Webhook event:
```json
{
- "transaction": {
+ "id": "Webhook:019542f5-b3e7-1d02-0000-000000000007",
+ "type": "OUTGOING_PAYMENT.COMPLETED",
+ "timestamp": "2025-01-15T14:32:00Z",
+ "data": {
"id": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
"status": "COMPLETED",
"type": "OUTGOING",
- "senderUmaAddress": "$alice@yourapp.example",
- "receivedAmount": { "amount": 9706, "currency": { "code": "MXN", "decimals": 2 } },
+ "sentAmount": { "amount": 10000, "currency": { "code": "USDC", "decimals": 2 } },
+ "receivedAmount": { "amount": 168500, "currency": { "code": "MXN", "decimals": 2 } },
"customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
- "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
- },
- "timestamp": "2025-01-15T14:32:00Z",
- "webhookId": "Webhook:019542f5-b3e7-1d02-0000-000000000007",
- "type": "OUTGOING_PAYMENT"
+ "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006"
+ }
}
```
diff --git a/mintlify/global-p2p/sending-receiving-payments/receiving-payments.mdx b/mintlify/global-p2p/sending-receiving-payments/receiving-payments.mdx
index 4c1c6211..f62ea9e1 100644
--- a/mintlify/global-p2p/sending-receiving-payments/receiving-payments.mdx
+++ b/mintlify/global-p2p/sending-receiving-payments/receiving-payments.mdx
@@ -23,12 +23,17 @@ When someone initiates a payment to one of your users' UMA addresses, you'll rec
```json
{
- "transaction": {
- "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
+ "id": "Webhook:019542f5-b3e7-1d02-0000-000000000007",
+ "type": "INCOMING_PAYMENT.PENDING",
+ "timestamp": "2023-08-15T14:32:00Z",
+ "data": {
+ "id": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
"status": "PENDING",
"type": "INCOMING",
- "senderUmaAddress": "$mary.sender@thelessgoodbank.com",
- "receiverUmaAddress": "$john.receiver@thegoodbank.com",
+ "source": {
+ "sourceType": "UMA_ADDRESS",
+ "umaAddress": "$mary.sender@thelessgoodbank.com"
+ },
"receivedAmount": {
"amount": 50000,
"currency": {
@@ -38,8 +43,8 @@ When someone initiates a payment to one of your users' UMA addresses, you'll rec
"decimals": 2
}
},
- "userId": "User:019542f5-b3e7-1d02-0000-000000000001",
- "platformUserId": "9f84e0c2a72c4fa",
+ "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
+ "platformCustomerId": "9f84e0c2a72c4fa",
"description": "Payment for services",
"counterpartyInformation": {
"FULL_NAME": "Mary Sender",
@@ -47,20 +52,17 @@ When someone initiates a payment to one of your users' UMA addresses, you'll rec
},
"reconciliationInstructions": {
"reference": "REF-123456789"
- }
- },
- "requestedReceiverUserInfoFields": [
- { "name": "COUNTRY_OF_RESIDENCE", "mandatory": true },
- { "name": "FULL_NAME", "mandatory": true },
- { "name": "NATIONALITY", "mandatory": false }
- ],
- "timestamp": "2023-08-15T14:32:00Z",
- "webhookId": "Webhook:019542f5-b3e7-1d02-0000-000000000007",
- "type": "INCOMING_PAYMENT"
+ },
+ "requestedReceiverCustomerInfoFields": [
+ { "name": "COUNTRY_OF_RESIDENCE", "mandatory": true },
+ { "name": "FULL_NAME", "mandatory": true },
+ { "name": "NATIONALITY", "mandatory": false }
+ ]
+ }
}
```
-The `counterpartyInformation` object contains PII about the sender, provided by their FI, based on your configured `requiredCounterpartyFields`. If present, `requestedReceiverUserInfoFields` lists information needed about your user to proceed. Provide those fields when approving.
+The `counterpartyInformation` object contains PII about the sender, provided by their FI, based on your configured `requiredCounterpartyFields`. If present, `requestedReceiverCustomerInfoFields` lists information needed about your customer to proceed. Provide those fields when approving.
You can approve or reject the payment synchronously (recommended) or asynchronously:
@@ -68,14 +70,14 @@ You can approve or reject the payment synchronously (recommended) or asynchronou
To approve the payment synchronously, respond with a `200 OK` status:
-- If the `requestedReceiverUserInfoFields` array was present in the webhook request and contained mandatory fields, your `200 OK` response **must** include a JSON body containing a `receiverUserInfo` object. This object should contain the key-value pairs for the information fields that were requested.
-- If `requestedReceiverUserInfoFields` was not present, was empty, or contained only non-mandatory fields for which you have no information, your `200 OK` response can have an empty body.
+- If the `requestedReceiverCustomerInfoFields` array was present in the webhook request and contained mandatory fields, your `200 OK` response **must** include a JSON body containing a `receiverCustomerInfo` object. This object should contain the key-value pairs for the information fields that were requested.
+- If `requestedReceiverCustomerInfoFields` was not present, was empty, or contained only non-mandatory fields for which you have no information, your `200 OK` response can have an empty body.
Example `200 OK` response body when information was requested and provided:
```json
{
- "receiverUserInfo": {
+ "receiverCustomerInfo": {
"COUNTRY_OF_RESIDENCE": "US",
"FULL_NAME": "John Receiver"
}
@@ -110,7 +112,7 @@ curl -X POST "https://api.lightspark.com/grid/2025-10-13/transactions/Transactio
-H "Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
-H "Content-Type: application/json" \
-d '{
- "receiverUserInfo": {
+ "receiverCustomerInfo": {
"COUNTRY_OF_RESIDENCE": "US",
"FULL_NAME": "John Receiver"
}
@@ -134,16 +136,21 @@ If you choose the asynchronous path, you must call the approve/reject endpoint w
## Receive completion notification and credit
-When the payment completes, you'll receive another webhook notifying you of the completion:
+When the payment completes, you'll receive another webhook notifying you of the completion. The envelope `id` is distinct from the `INCOMING_PAYMENT.PENDING` delivery above — use it for idempotent deduplication.
```json
{
- "transaction": {
- "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
+ "id": "Webhook:019542f5-b3e7-1d02-0000-000000000008",
+ "type": "INCOMING_PAYMENT.COMPLETED",
+ "timestamp": "2023-08-15T14:32:00Z",
+ "data": {
+ "id": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
"status": "COMPLETED",
"type": "INCOMING",
- "senderUmaAddress": "$mary.sender@thelessgoodbank.com",
- "receiverUmaAddress": "$john.receiver@thegoodbank.com",
+ "source": {
+ "sourceType": "UMA_ADDRESS",
+ "umaAddress": "$mary.sender@thelessgoodbank.com"
+ },
"receivedAmount": {
"amount": 50000,
"currency": {
@@ -153,9 +160,9 @@ When the payment completes, you'll receive another webhook notifying you of the
"decimals": 2
}
},
- "userId": "User:019542f5-b3e7-1d02-0000-000000000001",
- "platformUserId": "9f84e0c2a72c4fa",
- "settlementTime": "2023-08-15T14:30:00Z",
+ "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
+ "platformCustomerId": "9f84e0c2a72c4fa",
+ "settledAt": "2023-08-15T14:30:00Z",
"createdAt": "2023-08-15T14:25:18Z",
"description": "Payment for services",
"counterpartyInformation": {
@@ -165,10 +172,7 @@ When the payment completes, you'll receive another webhook notifying you of the
"reconciliationInstructions": {
"reference": "REF-123456789"
}
- },
- "timestamp": "2023-08-15T14:32:00Z",
- "webhookId": "Webhook:019542f5-b3e7-1d02-0000-000000000007",
- "type": "INCOMING_PAYMENT"
+ }
}
```
diff --git a/mintlify/payouts-and-b2b/payment-flow/send-payment.mdx b/mintlify/payouts-and-b2b/payment-flow/send-payment.mdx
index 9b95d25f..d75dc913 100644
--- a/mintlify/payouts-and-b2b/payment-flow/send-payment.mdx
+++ b/mintlify/payouts-and-b2b/payment-flow/send-payment.mdx
@@ -205,43 +205,33 @@ curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes' \
{
"id": "Quote:019542f5-b3e7-1d02-0000-000000000025",
"status": "PENDING",
+ "createdAt": "2025-10-03T15:00:00Z",
+ "expiresAt": "2025-10-03T15:15:00Z",
"source": {
- "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
- "currency": "USD"
+ "sourceType": "ACCOUNT",
+ "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
},
"destination": {
- "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
- "currency": "EUR"
+ "destinationType": "ACCOUNT",
+ "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
},
- "sendingAmount": {
- "amount": 10000,
- "currency": {
- "code": "USD",
- "name": "United States Dollar",
- "symbol": "$",
- "decimals": 2
- }
+ "sendingCurrency": {
+ "code": "USD",
+ "name": "United States Dollar",
+ "symbol": "$",
+ "decimals": 2
},
- "receivingAmount": {
- "amount": 9200,
- "currency": {
- "code": "EUR",
- "name": "Euro",
- "symbol": "€",
- "decimals": 2
- }
+ "receivingCurrency": {
+ "code": "EUR",
+ "name": "Euro",
+ "symbol": "€",
+ "decimals": 2
},
+ "totalSendingAmount": 10000,
+ "totalReceivingAmount": 9200,
"exchangeRate": 0.92,
- "fee": {
- "amount": 50,
- "currency": {
- "code": "USD",
- "symbol": "$",
- "decimals": 2
- }
- },
- "expiresAt": "2025-10-03T15:15:00Z",
- "createdAt": "2025-10-03T15:00:00Z",
+ "feesIncluded": 50,
+ "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000030",
"description": "Payment for services - Invoice #1234"
}
```
@@ -279,33 +269,33 @@ curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes/Quote:019542f5-b
{
"id": "Quote:019542f5-b3e7-1d02-0000-000000000025",
"status": "PROCESSING",
- "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000030",
+ "createdAt": "2025-10-03T15:00:00Z",
+ "expiresAt": "2025-10-03T15:15:00Z",
"source": {
- "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
- "currency": "USD"
+ "sourceType": "ACCOUNT",
+ "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
},
"destination": {
- "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
- "currency": "EUR"
+ "destinationType": "ACCOUNT",
+ "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
},
- "sendingAmount": {
- "amount": 10000,
- "currency": {
- "code": "USD",
- "symbol": "$",
- "decimals": 2
- }
+ "sendingCurrency": {
+ "code": "USD",
+ "name": "United States Dollar",
+ "symbol": "$",
+ "decimals": 2
},
- "receivingAmount": {
- "amount": 9200,
- "currency": {
- "code": "EUR",
- "symbol": "€",
- "decimals": 2
- }
+ "receivingCurrency": {
+ "code": "EUR",
+ "name": "Euro",
+ "symbol": "€",
+ "decimals": 2
},
+ "totalSendingAmount": 10000,
+ "totalReceivingAmount": 9200,
"exchangeRate": 0.92,
- "executedAt": "2025-10-03T15:05:00Z"
+ "feesIncluded": 50,
+ "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000030"
}
```
@@ -464,8 +454,8 @@ const quote = await createQuote(quoteData);
await db.payments.create({
quoteId: quote.id,
customerId: customer.id,
- amount: quote.sendingAmount.amount,
- currency: quote.sendingAmount.currency.code,
+ amount: quote.totalSendingAmount,
+ currency: quote.sendingCurrency.code,
status: "pending",
createdAt: new Date(),
});
diff --git a/mintlify/payouts-and-b2b/quickstart.mdx b/mintlify/payouts-and-b2b/quickstart.mdx
index b928ced4..e0f1bb88 100644
--- a/mintlify/payouts-and-b2b/quickstart.mdx
+++ b/mintlify/payouts-and-b2b/quickstart.mdx
@@ -194,7 +194,10 @@ During the funding process, you'll receive transaction status update webhooks.
**Webhook Notification:**
```json
{
- "transaction": {
+ "id": "Webhook:019542f5-b3e7-1d02-0000-000000000020",
+ "type": "INCOMING_PAYMENT.COMPLETED",
+ "timestamp": "2025-10-03T14:32:00Z",
+ "data": {
"id": "Transaction:019542f5-b3e7-1d02-0000-000000000010",
"status": "COMPLETED",
"type": "INCOMING",
@@ -211,10 +214,7 @@ During the funding process, you'll receive transaction status update webhooks.
"settledAt": "2025-10-03T14:30:00Z",
"createdAt": "2025-10-03T14:25:00Z",
"description": "Internal account funding"
- },
- "timestamp": "2025-10-03T14:32:00Z",
- "webhookId": "Webhook:019542f5-b3e7-1d02-0000-000000000020",
- "type": "INCOMING_PAYMENT"
+ }
}
```
@@ -313,17 +313,17 @@ curl -X POST "https://api.lightspark.com/grid/2025-10-13/quotes" \
**Response:**
```json
{
- "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
+ "id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
"status": "PENDING",
"createdAt": "2025-10-03T15:00:00Z",
"expiresAt": "2025-10-03T15:05:00Z",
"source": {
- "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
- "currency": "USD"
+ "sourceType": "ACCOUNT",
+ "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
},
"destination": {
- "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
- "currency": "MXN"
+ "destinationType": "ACCOUNT",
+ "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
},
"sendingCurrency": {
"code": "USD",
@@ -366,17 +366,17 @@ curl -X POST "https://api.lightspark.com/grid/2025-10-13/quotes/Quote:019542f5-b
**Response:**
```json
{
- "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
+ "id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
"status": "PROCESSING",
"createdAt": "2025-10-03T15:00:00Z",
"expiresAt": "2025-10-03T15:05:00Z",
"source": {
- "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
- "currency": "USD"
+ "sourceType": "ACCOUNT",
+ "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
},
"destination": {
- "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
- "currency": "MXN"
+ "destinationType": "ACCOUNT",
+ "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
},
"sendingCurrency": {
"code": "USD",
@@ -403,7 +403,10 @@ The quote status changes to `PROCESSING` and the transfer is initiated. You'll r
**Completion Webhook:**
```json
{
- "transaction": {
+ "id": "Webhook:019542f5-b3e7-1d02-0000-000000000025",
+ "type": "OUTGOING_PAYMENT.COMPLETED",
+ "timestamp": "2025-10-03T15:03:00Z",
+ "data": {
"id": "Transaction:019542f5-b3e7-1d02-0000-000000000015",
"status": "COMPLETED",
"type": "OUTGOING",
@@ -431,10 +434,7 @@ The quote status changes to `PROCESSING` and the transfer is initiated. You'll r
"description": "Payment to Maria Garcia for services",
"exchangeRate": 17.25,
"quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006"
- },
- "timestamp": "2025-10-03T15:03:00Z",
- "webhookId": "Webhook:019542f5-b3e7-1d02-0000-000000000025",
- "type": "OUTGOING_PAYMENT"
+ }
}
```
diff --git a/mintlify/platform-overview/core-concepts/currencies-and-rails.mdx b/mintlify/platform-overview/core-concepts/currencies-and-rails.mdx
index 3d47f84c..7a086ce2 100644
--- a/mintlify/platform-overview/core-concepts/currencies-and-rails.mdx
+++ b/mintlify/platform-overview/core-concepts/currencies-and-rails.mdx
@@ -46,17 +46,17 @@ POST /quotes
```json
{
- "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000020",
+ "id": "Quote:019542f5-b3e7-1d02-0000-000000000020",
"status": "PROCESSING",
"createdAt": "2025-10-03T15:00:00Z",
"expiresAt": "2025-10-03T15:05:00Z",
"source": {
- "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
- "currency": "USD"
+ "sourceType": "ACCOUNT",
+ "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
},
"destination": {
- "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
- "currency": "MXN"
+ "destinationType": "ACCOUNT",
+ "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
},
"sendingCurrency": {
"code": "USD",
@@ -68,15 +68,15 @@ POST /quotes
"code": "MXN",
"name": "Mexican Peso",
"symbol": "$",
- "decimals": 8
+ "decimals": 2
},
- "totalSendingAmount": 100,
- "totalReceivingAmount": 17250,
+ "totalSendingAmount": 100000,
+ "totalReceivingAmount": 1725000,
"exchangeRate": 17.25,
- "feesIncluded": 5,
+ "feesIncluded": 500,
"transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000025"
}
```
-This shows: Send $1,000 → Receive $17,250 (at rate 17.25), $250 fee.
+This shows: Send $1,000 → Receive $17,250 (at rate 17.25), $5 fee.
diff --git a/mintlify/platform-overview/core-concepts/quote-system.mdx b/mintlify/platform-overview/core-concepts/quote-system.mdx
index 3a1ee6ef..a0b0e8d7 100644
--- a/mintlify/platform-overview/core-concepts/quote-system.mdx
+++ b/mintlify/platform-overview/core-concepts/quote-system.mdx
@@ -70,17 +70,17 @@ curl -X POST https://api.lightspark.com/grid/2025-10-13/quotes \
```json
{
- "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000020",
+ "id": "Quote:019542f5-b3e7-1d02-0000-000000000020",
"status": "PROCESSING",
"createdAt": "2025-10-03T15:00:00Z",
"expiresAt": "2025-10-03T15:05:00Z",
"source": {
- "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
- "currency": "USD"
+ "sourceType": "ACCOUNT",
+ "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
},
"destination": {
- "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
- "currency": "BTC"
+ "destinationType": "ACCOUNT",
+ "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
},
"sendingCurrency": {
"code": "USD",
@@ -175,7 +175,7 @@ Source is the customer ID or the platform itself — Grid provides payment instr
```json
{
- "quoteId": "Quote:...",
+ "id": "Quote:...",
"paymentInstructions": [
{
"instructionsNotes": "Please ensure the reference code is included in the payment memo/description field",
@@ -217,11 +217,12 @@ curl -X POST https://api.lightspark.com/grid/2025-10-13/quotes/Quote:abc123/exec
```json
{
- "id": "Transaction:019542f5-b3e7-1d02-0000-000000000060",
- "status": "PENDING",
- "type": "OUTGOING",
- "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000050"
- ...
+ "id": "Quote:019542f5-b3e7-1d02-0000-000000000050",
+ "status": "PROCESSING",
+ "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000060",
+ "totalSendingAmount": 100000,
+ "totalReceivingAmount": 91540,
+ "feesIncluded": 500
}
```
@@ -262,17 +263,17 @@ curl -X POST https://api.lightspark.com/grid/2025-10-13/quotes \
```json
{
- "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000020",
+ "id": "Quote:019542f5-b3e7-1d02-0000-000000000020",
"status": "COMPLETED",
"createdAt": "2025-10-03T15:00:00Z",
"expiresAt": "2025-10-03T15:05:00Z",
"source": {
- "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
- "currency": "USD"
+ "sourceType": "ACCOUNT",
+ "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
},
"destination": {
- "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
- "currency": "EUR"
+ "destinationType": "ACCOUNT",
+ "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
},
"sendingCurrency": {
"code": "USD",
@@ -312,7 +313,7 @@ All fees are transparently displayed in the quote response:
```json
{
- "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000020",
+ "id": "Quote:019542f5-b3e7-1d02-0000-000000000020",
"feesIncluded": 500,
... quote response ...
"rateDetails": {
@@ -398,9 +399,9 @@ Fees are deducted from the sending amount, so:
```javascript
app.post('/webhooks/grid', (req, res) => {
- const {transaction, type} = req.body;
+ const {data: transaction, type} = req.body;
- if (type === 'OUTGOING_PAYMENT' && transaction.quoteId) {
+ if (type.startsWith('OUTGOING_PAYMENT.') && transaction.quoteId) {
// Quote was executed, transaction created
updateCustomerUI(transaction);
}
diff --git a/mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx b/mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx
index 9f802c26..c9ed40fa 100644
--- a/mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx
+++ b/mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx
@@ -83,7 +83,7 @@ POST /transfer-out
{
"source": {"accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"},
- "destination": {"accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123", "currency": "USD"},
+ "destination": {"accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"},
"amount": 100000
}
```
@@ -106,7 +106,7 @@ Follows same lifecycle as quote-based outgoing transactions.
POST /transfer-in
{
- "source": {"accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123", "currency": "USD"},
+ "source": {"accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"},
"destination": {"accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"},
"amount": 100000
}
@@ -419,11 +419,19 @@ When a transaction fails, a refund is initiated automatically. Track the refund
- Use idempotency keys for safe retries:
+ Use the `Idempotency-Key` HTTP header for safe retries:
```javascript
const idempotencyKey = `payment-${userId}-${Date.now()}`;
- await createQuote({...params, idempotencyKey});
+ await fetch('https://api.lightspark.com/grid/2025-10-13/quotes', {
+ method: 'POST',
+ headers: {
+ 'Idempotency-Key': idempotencyKey,
+ 'Content-Type': 'application/json',
+ 'Authorization': `Basic ${credentials}`,
+ },
+ body: JSON.stringify(params),
+ });
```
diff --git a/mintlify/ramps/accounts/internal-accounts.mdx b/mintlify/ramps/accounts/internal-accounts.mdx
index a874da8b..55565aba 100644
--- a/mintlify/ramps/accounts/internal-accounts.mdx
+++ b/mintlify/ramps/accounts/internal-accounts.mdx
@@ -181,8 +181,8 @@ const btcAccount = accounts.data.find(
if (btcAccount.balance.amount >= requiredSats) {
// Create quote to convert BTC to fiat
const quote = await createQuote({
- source: { accountId: btcAccount.id },
- destination: { accountId: bankAccountId, currency: "USD" },
+ source: { sourceType: "ACCOUNT", accountId: btcAccount.id },
+ destination: { destinationType: "ACCOUNT", accountId: bankAccountId },
lockedCurrencySide: "SENDING",
lockedCurrencyAmount: requiredSats,
});
diff --git a/mintlify/ramps/conversion-flows/fiat-crypto-conversion.mdx b/mintlify/ramps/conversion-flows/fiat-crypto-conversion.mdx
index bc389986..d4a4c56b 100644
--- a/mintlify/ramps/conversion-flows/fiat-crypto-conversion.mdx
+++ b/mintlify/ramps/conversion-flows/fiat-crypto-conversion.mdx
@@ -49,6 +49,7 @@ curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes' \
-H 'Content-Type: application/json' \
-d '{
"source": {
+ "sourceType": "REALTIME_FUNDING",
"customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
"currency": "USD"
},
@@ -67,25 +68,41 @@ curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes' \
```json
{
"id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
- "totalSendingAmount": 6500,
- "receivingAmount": 100000,
+ "status": "PENDING",
+ "createdAt": "2025-10-03T12:00:00Z",
"expiresAt": "2025-10-03T12:05:00Z",
+ "source": {
+ "sourceType": "REALTIME_FUNDING",
+ "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
+ "currency": "USD"
+ },
+ "destination": {
+ "destinationType": "ACCOUNT",
+ "accountId": "ExternalAccount:b23dcbd6-dced-4ec4-b756-3c3a9ea3d456"
+ },
+ "sendingCurrency": { "code": "USD", "name": "United States Dollar", "symbol": "$", "decimals": 2 },
+ "receivingCurrency": { "code": "BTC", "name": "Bitcoin", "symbol": "₿", "decimals": 8 },
+ "totalSendingAmount": 6500,
+ "totalReceivingAmount": 100000,
+ "exchangeRate": 15.38,
+ "feesIncluded": 200,
+ "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000007",
"paymentInstructions": [
{
"accountOrWalletInfo": {
"accountType": "US_ACCOUNT",
"reference": "UMA-Q12345-REF",
- "accountNumber": "1234567890",
- "routingNumber": "021000021",
- "bankName": "Grid Settlement Bank"
- }
- },
- {
- "accountOrWalletInfo": {
- "accountType": "SOLANA_WALLET",
- "assetType": "USDC",
- "address": "4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8Wg"
- }
+ "accountNumber": "1234567890",
+ "routingNumber": "021000021",
+ "bankName": "Grid Settlement Bank"
+ }
+ },
+ {
+ "accountOrWalletInfo": {
+ "accountType": "SOLANA_WALLET",
+ "assetType": "USDC",
+ "address": "4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8Wg"
+ }
}
]
}
@@ -102,9 +119,9 @@ function displayPaymentInstructions(quote) {
bankName: instructions.accountOrWalletInfo.bankName,
accountNumber: instructions.accountOrWalletInfo.accountNumber,
routingNumber: instructions.accountOrWalletInfo.routingNumber,
- referenceCode: instructions.reference, // User must include this
+ referenceCode: instructions.accountOrWalletInfo.reference, // User must include this
expiresAt: quote.expiresAt,
- willReceive: `${quote.receivingAmount / 100000000} BTC`,
+ willReceive: `${quote.totalReceivingAmount / 100000000} BTC`,
};
}
```
@@ -145,11 +162,12 @@ const quote = await fetch("https://api.lightspark.com/grid/2025-10-13/quotes", {
method: "POST",
body: JSON.stringify({
source: {
+ sourceType: "ACCOUNT",
accountId: "InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
},
destination: {
+ destinationType: "ACCOUNT",
accountId: "ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
- currency: "USD",
},
lockedCurrencySide: "SENDING",
lockedCurrencyAmount: 100000, // 0.001 BTC
diff --git a/mintlify/ramps/conversion-flows/self-custody-wallets.mdx b/mintlify/ramps/conversion-flows/self-custody-wallets.mdx
index 0f2cecf7..98ae0a92 100644
--- a/mintlify/ramps/conversion-flows/self-custody-wallets.mdx
+++ b/mintlify/ramps/conversion-flows/self-custody-wallets.mdx
@@ -164,12 +164,13 @@ const quote = await fetch("https://api.lightspark.com/grid/2025-10-13/quotes", {
method: "POST",
body: JSON.stringify({
source: {
+ sourceType: "REALTIME_FUNDING",
customerId: "Customer:019542f5-b3e7-1d02-0000-000000000001",
currency: "USD",
},
destination: {
+ destinationType: "ACCOUNT",
accountId: externalAccount.id,
- currency: "BTC",
},
lockedCurrencySide: "SENDING",
lockedCurrencyAmount: 10000, // $100.00
@@ -179,7 +180,7 @@ const quote = await fetch("https://api.lightspark.com/grid/2025-10-13/quotes", {
// Display payment instructions to user
console.log("Send fiat to:", quote.paymentInstructions);
-console.log("Will receive:", `${quote.receivingAmount / 100000000} BTC`);
+console.log("Will receive:", `${quote.totalReceivingAmount / 100000000} BTC`);
```
#### Option B: From internal account to self-custody wallet
@@ -220,7 +221,6 @@ app.post("/webhooks/grid", async (req, res) => {
await notifyUser(data.customerId, {
message: "Bitcoin sent to your wallet!",
amount: `${data.receivedAmount.amount / 100000000} BTC`,
- walletAddress: data.destination.accountInfo.address,
});
break;
@@ -395,6 +395,7 @@ curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes' \
-H 'Content-Type: application/json' \
-d '{
"source": {
+ "sourceType": "ACCOUNT",
"accountId": "InternalAccount:..."
},
"destination": {
diff --git a/mintlify/ramps/platform-tools/sandbox-testing.mdx b/mintlify/ramps/platform-tools/sandbox-testing.mdx
index b535710d..2b5047a2 100644
--- a/mintlify/ramps/platform-tools/sandbox-testing.mdx
+++ b/mintlify/ramps/platform-tools/sandbox-testing.mdx
@@ -344,11 +344,12 @@ curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes' \
-H 'Content-Type: application/json' \
-d '{
"source": {
+ "sourceType": "ACCOUNT",
"accountId": "InternalAccount:empty_btc"
},
"destination": {
- "accountId": "ExternalAccount:bank001",
- "currency": "USD"
+ "destinationType": "ACCOUNT",
+ "accountId": "ExternalAccount:bank001"
},
"lockedCurrencySide": "SENDING",
"lockedCurrencyAmount": 10000000
diff --git a/mintlify/ramps/platform-tools/webhooks.mdx b/mintlify/ramps/platform-tools/webhooks.mdx
index fcf0dd58..1deb86a7 100644
--- a/mintlify/ramps/platform-tools/webhooks.mdx
+++ b/mintlify/ramps/platform-tools/webhooks.mdx
@@ -19,6 +19,9 @@ Grid sends webhooks for key events in the ramp lifecycle:
```json
{
+ "id": "Webhook:019542f5-b3e7-1d02-0000-000000000030",
+ "type": "OUTGOING_PAYMENT.COMPLETED",
+ "timestamp": "2025-10-03T15:03:00Z",
"data": {
"id": "Transaction:019542f5-b3e7-1d02-0000-000000000025",
"status": "COMPLETED",
@@ -35,10 +38,7 @@ Grid sends webhooks for key events in the ramp lifecycle:
"settledAt": "2025-10-03T15:02:30Z",
"exchangeRate": 9.5,
"quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006"
- },
- "timestamp": "2025-10-03T15:03:00Z",
- "webhookId": "Webhook:019542f5-b3e7-1d02-0000-000000000030",
- "type": "OUTGOING_PAYMENT.COMPLETED"
+ }
}
```
@@ -306,20 +306,20 @@ if (type === "INTERNAL_ACCOUNT.BALANCE_UPDATED") {
- Handle duplicate webhooks gracefully using webhook IDs:
-
+ Handle duplicate webhooks gracefully using the envelope `id`:
+
```javascript
- const { webhookId } = req.body;
-
+ const { id: webhookId } = req.body;
+
// Check if already processed
const existing = await db.webhooks.findUnique({ where: { webhookId } });
if (existing) {
return res.status(200).json({ received: true });
}
-
+
// Process webhook
await processRampWebhook(req.body);
-
+
// Record webhook ID
await db.webhooks.create({
data: { webhookId, processedAt: new Date() }
@@ -328,11 +328,11 @@ if (type === "INTERNAL_ACCOUNT.BALANCE_UPDATED") {
- Transaction IDs are unique identifiers for conversions:
-
+ The transaction lives on `data` and its `id` uniquely identifies the conversion:
+
```javascript
- const { transaction } = req.body;
-
+ const { data: transaction } = req.body;
+
// Upsert transaction (handles duplicates)
await db.transactions.upsert({
where: { gridTransactionId: transaction.id },
@@ -407,7 +407,7 @@ This sends a test webhook to your configured endpoint:
{
"test": true,
"timestamp": "2025-10-03T14:32:00Z",
- "webhookId": "Webhook:test001",
+ "id": "Webhook:test001",
"type": "TEST"
}
```
diff --git a/mintlify/ramps/quickstart.mdx b/mintlify/ramps/quickstart.mdx
index a2f6ed46..ccc9bb47 100644
--- a/mintlify/ramps/quickstart.mdx
+++ b/mintlify/ramps/quickstart.mdx
@@ -129,12 +129,13 @@ curl -X POST "https://api.lightspark.com/grid/2025-10-13/quotes" \
"createdAt": "2025-10-03T15:00:00Z",
"expiresAt": "2025-10-03T15:05:00Z",
"source": {
+ "sourceType": "REALTIME_FUNDING",
"customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
"currency": "USD"
},
"destination": {
- "accountId": "ExternalAccount:b23dcbd6-dced-4ec4-b756-3c3a9ea3d456",
- "currency": "BTC"
+ "destinationType": "ACCOUNT",
+ "accountId": "ExternalAccount:b23dcbd6-dced-4ec4-b756-3c3a9ea3d456"
},
"sendingCurrency": {
"code": "USD",
@@ -217,6 +218,18 @@ curl -X POST "https://api.lightspark.com/grid/2025-10-13/sandbox/send" \
"id": "Transaction:019542f5-b3e7-1d02-0000-000000000025",
"status": "PROCESSING",
"type": "OUTGOING",
+ "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
+ "platformCustomerId": "customer_12345",
+ "source": {
+ "sourceType": "REALTIME_FUNDING",
+ "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
+ },
+ "destination": {
+ "destinationType": "ACCOUNT",
+ "accountId": "ExternalAccount:b23dcbd6-dced-4ec4-b756-3c3a9ea3d456"
+ },
+ "sentAmount": { "amount": 10000, "currency": { "code": "USD", "decimals": 2 } },
+ "receivedAmount": { "amount": 83333, "currency": { "code": "BTC", "decimals": 8 } },
"quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006"
}
```
@@ -241,7 +254,10 @@ Once Grid receives your payment and completes the USD-to-BTC conversion and deli
```json
{
- "transaction": {
+ "id": "Webhook:019542f5-b3e7-1d02-0000-000000000030",
+ "type": "OUTGOING_PAYMENT.COMPLETED",
+ "timestamp": "2025-10-03T15:03:00Z",
+ "data": {
"id": "Transaction:019542f5-b3e7-1d02-0000-000000000025",
"status": "COMPLETED",
"type": "OUTGOING",
@@ -277,14 +293,11 @@ Once Grid receives your payment and completes the USD-to-BTC conversion and deli
"accountNumber": "1234567890",
"routingNumber": "021000021",
"bankName": "Chase Bank",
- "referenceCode": "REF123456"
+ "reference": "REF123456"
}
}
]
- },
- "timestamp": "2025-10-03T15:03:00Z",
- "webhookId": "Webhook:019542f5-b3e7-1d02-0000-000000000030",
- "type": "OUTGOING_PAYMENT"
+ }
}
```
diff --git a/mintlify/rewards/developer-guides/distributing-rewards.mdx b/mintlify/rewards/developer-guides/distributing-rewards.mdx
index 87f1a89e..2f4a8caf 100644
--- a/mintlify/rewards/developer-guides/distributing-rewards.mdx
+++ b/mintlify/rewards/developer-guides/distributing-rewards.mdx
@@ -79,6 +79,7 @@ curl -X POST "https://api.lightspark.com/grid/2025-10-13/quotes" \
-H "Content-Type: application/json" \
-d '{
"source": {
+ "sourceType": "ACCOUNT",
"accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
},
"destination": {
@@ -96,17 +97,17 @@ Response:
```json
{
- "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000020",
+ "id": "Quote:019542f5-b3e7-1d02-0000-000000000020",
"status": "PROCESSING",
"createdAt": "2025-10-03T15:00:00Z",
"expiresAt": "2025-10-03T15:05:00Z",
"source": {
- "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
- "currency": "USD"
+ "sourceType": "ACCOUNT",
+ "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
},
"destination": {
- "accountId": "ExternalAccount:b23dcbd6-dced-4ec4-b756-3c3a9ea3d456",
- "currency": "BTC"
+ "destinationType": "ACCOUNT",
+ "accountId": "ExternalAccount:b23dcbd6-dced-4ec4-b756-3c3a9ea3d456"
},
"sendingCurrency": {
"code": "USD",
@@ -242,7 +243,10 @@ When the Bitcoin transfer completes, you'll receive a webhook:
```json
{
- "transaction": {
+ "id": "Webhook:019542f5-b3e7-1d02-0000-000000000030",
+ "type": "OUTGOING_PAYMENT.COMPLETED",
+ "timestamp": "2025-10-03T15:02:00Z",
+ "data": {
"id": "Transaction:019542f5-b3e7-1d02-0000-000000000025",
"status": "COMPLETED",
"type": "OUTGOING",
@@ -256,8 +260,7 @@ When the Bitcoin transfer completes, you'll receive a webhook:
},
"customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
"settledAt": "2025-10-03T15:01:45Z"
- },
- "type": "OUTGOING_PAYMENT"
+ }
}
```
diff --git a/mintlify/rewards/quickstart.mdx b/mintlify/rewards/quickstart.mdx
index 0d944896..7ba6e74a 100644
--- a/mintlify/rewards/quickstart.mdx
+++ b/mintlify/rewards/quickstart.mdx
@@ -219,6 +219,7 @@ curl -X POST "https://api.lightspark.com/grid/2025-10-13/quotes" \
-H "Content-Type: application/json" \
-d '{
"source": {
+ "sourceType": "ACCOUNT",
"accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
},
"destination": {
@@ -243,17 +244,17 @@ and exchange rate details before executing the quote, set `immediatelyExecute` t
```json
{
- "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000020",
+ "id": "Quote:019542f5-b3e7-1d02-0000-000000000020",
"status": "PROCESSING",
"createdAt": "2025-10-03T15:00:00Z",
"expiresAt": "2025-10-03T15:05:00Z",
"source": {
- "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
- "currency": "USD"
+ "sourceType": "ACCOUNT",
+ "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
},
"destination": {
- "accountId": "ExternalAccount:b23dcbd6-dced-4ec4-b756-3c3a9ea3d456",
- "currency": "BTC"
+ "destinationType": "ACCOUNT",
+ "accountId": "ExternalAccount:b23dcbd6-dced-4ec4-b756-3c3a9ea3d456"
},
"sendingCurrency": {
"code": "USD",
@@ -288,7 +289,10 @@ When the Bitcoin transfer completes, you'll receive a webhook notification:
```json
{
- "transaction": {
+ "id": "Webhook:019542f5-b3e7-1d02-0000-000000000030",
+ "type": "OUTGOING_PAYMENT.COMPLETED",
+ "timestamp": "2025-10-03T15:02:00Z",
+ "data": {
"id": "Transaction:019542f5-b3e7-1d02-0000-000000000025",
"status": "COMPLETED",
"type": "OUTGOING",
@@ -315,10 +319,7 @@ When the Bitcoin transfer completes, you'll receive a webhook notification:
"description": "Bitcoin purchase for self-custody",
"exchangeRate": 8.1,
"quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000020"
- },
- "timestamp": "2025-10-03T15:02:00Z",
- "webhookId": "Webhook:019542f5-b3e7-1d02-0000-000000000030",
- "type": "OUTGOING_PAYMENT"
+ }
}
```
diff --git a/mintlify/snippets/global-accounts/walkthrough.mdx b/mintlify/snippets/global-accounts/walkthrough.mdx
index 7e21cd8c..2d1893d2 100644
--- a/mintlify/snippets/global-accounts/walkthrough.mdx
+++ b/mintlify/snippets/global-accounts/walkthrough.mdx
@@ -208,12 +208,12 @@ curl -X POST "$GRID_BASE_URL/quotes" \
"createdAt": "2026-04-19T12:05:00Z",
"expiresAt": "2026-04-19T12:10:00Z",
"source": {
- "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
- "currency": "USDB"
+ "sourceType": "ACCOUNT",
+ "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
},
"destination": {
- "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
- "currency": "USD"
+ "destinationType": "ACCOUNT",
+ "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
},
"sendingCurrency": { "code": "USDB", "name": "USDB", "decimals": 6 },
"receivingCurrency": { "code": "USD", "name": "United States Dollar", "symbol": "$", "decimals": 2 },
diff --git a/mintlify/snippets/reconciliation/reconciliation.mdx b/mintlify/snippets/reconciliation/reconciliation.mdx
index 123f50a1..28be2192 100644
--- a/mintlify/snippets/reconciliation/reconciliation.mdx
+++ b/mintlify/snippets/reconciliation/reconciliation.mdx
@@ -27,17 +27,20 @@ Sample webhook payload:
```json
{
- "transaction": {
- "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000030",
+ "id": "Webhook:019542f5-b3e7-1d02-0000-0000000000ab",
+ "type": "OUTGOING_PAYMENT.COMPLETED",
+ "timestamp": "2025-10-03T15:30:01Z",
+ "data": {
+ "id": "Transaction:019542f5-b3e7-1d02-0000-000000000030",
"status": "COMPLETED",
"type": "OUTGOING",
"source": {
- "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
- "currency": "USD"
+ "sourceType": "ACCOUNT",
+ "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
},
"destination": {
- "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
- "currency": "EUR"
+ "destinationType": "ACCOUNT",
+ "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
},
"sentAmount": {
"amount": 10000,
@@ -52,16 +55,13 @@ Sample webhook payload:
"createdAt": "2025-10-03T15:00:00Z",
"settledAt": "2025-10-03T15:30:00Z",
"description": "Payment for services - Invoice #1234"
- },
- "timestamp": "2025-10-03T15:30:01Z",
- "webhookId": "Webhook:019542f5-b3e7-1d02-0000-0000000000ab",
- "type": "OUTGOING_PAYMENT"
+ }
}
```
-Use the `webhookId`, `transaction.id`, and `timestamp` to ensure idempotent handling, updating your internal ledger on each status transition.
+Use the envelope `id`, `data.id`, and `timestamp` to ensure idempotent handling, updating your internal ledger on each status transition.
@@ -91,12 +91,12 @@ Response
"status": "COMPLETED",
"type": "OUTGOING",
"source": {
- "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
- "currency": "USD"
+ "sourceType": "ACCOUNT",
+ "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
},
"destination": {
- "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
- "currency": "EUR"
+ "destinationType": "ACCOUNT",
+ "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
},
"sentAmount": {
"amount": 10000,
diff --git a/mintlify/snippets/sending/cross-currency.mdx b/mintlify/snippets/sending/cross-currency.mdx
index 9c5bf0d5..29fc0cf4 100644
--- a/mintlify/snippets/sending/cross-currency.mdx
+++ b/mintlify/snippets/sending/cross-currency.mdx
@@ -31,14 +31,17 @@ curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes' \
{
"id": "Quote:019542f5-b3e7-1d02-0000-000000000025",
"status": "PENDING",
- "source": { "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965", "currency": "USD" },
- "destination": { "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123", "currency": "EUR" },
- "sendingAmount": { "amount": 10000, "currency": { "code": "USD", "decimals": 2 } },
- "receivingAmount": { "amount": 9200, "currency": { "code": "EUR", "decimals": 2 } },
- "exchangeRate": 0.92,
- "fee": { "amount": 50, "currency": { "code": "USD", "decimals": 2 } },
- "expiresAt": "2025-10-03T15:15:00Z",
"createdAt": "2025-10-03T15:00:00Z",
+ "expiresAt": "2025-10-03T15:15:00Z",
+ "source": { "sourceType": "ACCOUNT", "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965" },
+ "destination": { "destinationType": "ACCOUNT", "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123" },
+ "sendingCurrency": { "code": "USD", "name": "United States Dollar", "symbol": "$", "decimals": 2 },
+ "receivingCurrency": { "code": "EUR", "name": "Euro", "symbol": "€", "decimals": 2 },
+ "totalSendingAmount": 10000,
+ "totalReceivingAmount": 9200,
+ "exchangeRate": 0.92,
+ "feesIncluded": 50,
+ "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000030",
"description": "Payment for services - Invoice #1234"
}
```
@@ -111,13 +114,17 @@ curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes/Quote:019542f5-b
{
"id": "Quote:019542f5-b3e7-1d02-0000-000000000025",
"status": "PROCESSING",
- "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000030",
- "source": { "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965", "currency": "USD" },
- "destination": { "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123", "currency": "EUR" },
- "sendingAmount": { "amount": 10000, "currency": { "code": "USD", "decimals": 2 } },
- "receivingAmount": { "amount": 9200, "currency": { "code": "EUR", "decimals": 2 } },
+ "createdAt": "2025-10-03T15:00:00Z",
+ "expiresAt": "2025-10-03T15:15:00Z",
+ "source": { "sourceType": "ACCOUNT", "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965" },
+ "destination": { "destinationType": "ACCOUNT", "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123" },
+ "sendingCurrency": { "code": "USD", "name": "United States Dollar", "symbol": "$", "decimals": 2 },
+ "receivingCurrency": { "code": "EUR", "name": "Euro", "symbol": "€", "decimals": 2 },
+ "totalSendingAmount": 10000,
+ "totalReceivingAmount": 9200,
"exchangeRate": 0.92,
- "executedAt": "2025-10-03T15:05:00Z"
+ "feesIncluded": 50,
+ "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000030"
}
```
@@ -200,14 +207,17 @@ The response includes an array of payment instructions, including blockchain wal
{
"id": "Quote:019542f5-b3e7-1d02-0000-000000000025",
"status": "PENDING",
- "source": { "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001", "currency": "USDC" },
- "destination": { "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123", "currency": "EUR" },
- "sendingAmount": { "amount": 10000, "currency": { "code": "USDC", "decimals": 2 } },
- "receivingAmount": { "amount": 9200, "currency": { "code": "EUR", "decimals": 2 } },
- "exchangeRate": 0.92,
- "fee": { "amount": 50, "currency": { "code": "USD", "decimals": 2 } },
- "expiresAt": "2025-10-03T15:15:00Z",
"createdAt": "2025-10-03T15:00:00Z",
+ "expiresAt": "2025-10-03T15:15:00Z",
+ "source": { "sourceType": "REALTIME_FUNDING", "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001", "currency": "USDC" },
+ "destination": { "destinationType": "ACCOUNT", "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123" },
+ "sendingCurrency": { "code": "USDC", "name": "USD Coin", "symbol": "USDC", "decimals": 2 },
+ "receivingCurrency": { "code": "EUR", "name": "Euro", "symbol": "€", "decimals": 2 },
+ "totalSendingAmount": 10000,
+ "totalReceivingAmount": 9200,
+ "exchangeRate": 0.92,
+ "feesIncluded": 50,
+ "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000030",
"paymentInstructions": [
{
"accountOrWalletInfo": {
@@ -233,7 +243,7 @@ Grid automatically detects blockchain deposits and processes the transfer once f
- Transfer the exact amount of USDC specified in `sendingAmount` to your chosen blockchain wallet address.
+ Transfer the exact amount of USDC specified in `totalSendingAmount` to your chosen blockchain wallet address.
@@ -241,11 +251,13 @@ Grid automatically detects blockchain deposits and processes the transfer once f
```json
{
+ "id": "Webhook:019542f5-b3e7-1d02-0000-000000000040",
"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 } },
- "timestamp": "2025-10-03T15:05:00Z"
+ "timestamp": "2025-10-03T15:05:00Z",
+ "data": {
+ "id": "InternalAccount:019542f5-b3e7-1d02-0000-000000000025",
+ "balance": { "amount": 10000, "currency": { "code": "USDC", "decimals": 2 } }
+ }
}
```
@@ -255,18 +267,19 @@ Grid automatically detects blockchain deposits and processes the transfer once f
```json
{
+ "id": "Webhook:019542f5-b3e7-1d02-0000-000000000041",
"type": "OUTGOING_PAYMENT.COMPLETED",
+ "timestamp": "2025-10-03T15:31:00Z",
"data": {
"id": "Transaction:019542f5-b3e7-1d02-0000-000000000030",
"status": "COMPLETED",
"type": "OUTGOING",
- "sentAmount": { "amount": 10000, "currency": { "code": "USD", "decimals": 2 } },
+ "sentAmount": { "amount": 10000, "currency": { "code": "USDC", "decimals": 2 } },
"receivedAmount": { "amount": 9200, "currency": { "code": "EUR", "decimals": 2 } },
"exchangeRate": 0.92,
"settledAt": "2025-10-03T15:30:00Z",
"quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000025"
- },
- "timestamp": "2025-10-03T15:31:00Z"
+ }
}
```
diff --git a/mintlify/snippets/sending/same-currency.mdx b/mintlify/snippets/sending/same-currency.mdx
index 65da7f4c..f5e7da37 100644
--- a/mintlify/snippets/sending/same-currency.mdx
+++ b/mintlify/snippets/sending/same-currency.mdx
@@ -43,12 +43,12 @@ curl -X POST 'https://api.lightspark.com/grid/2025-10-13/transfer-out' \
"status": "PENDING",
"type": "OUTGOING",
"source": {
- "accountId": "InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
- "currency": "USD"
+ "sourceType": "ACCOUNT",
+ "accountId": "InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
},
"destination": {
- "accountId": "ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
- "currency": "USD"
+ "destinationType": "ACCOUNT",
+ "accountId": "ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"
},
"sentAmount": { "amount": 12550, "currency": { "code": "USD", "decimals": 2 } },
"receivedAmount": { "amount": 12550, "currency": { "code": "USD", "decimals": 2 } },
diff --git a/mintlify/snippets/sending/uma.mdx b/mintlify/snippets/sending/uma.mdx
index 6907d226..0bd43495 100644
--- a/mintlify/snippets/sending/uma.mdx
+++ b/mintlify/snippets/sending/uma.mdx
@@ -4,32 +4,33 @@ Send to an UMA address when the receiver is identified by their UMA handle, e.g.
### Look up the recipient
```bash
-curl -X GET "https://api.lightspark.com/grid/2025-10-13/receiver/\$recipient@example.com?platformUserId=9f84e0c2a72c4fa" \
+curl -X GET "https://api.lightspark.com/grid/2025-10-13/receiver/uma/\$recipient@example.com?customerId=Customer:019542f5-b3e7-1d02-0000-000000000001" \
-u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"
```
#### Response
```json Success (200 OK)
{
- "id": "Lookup:019542f5-b3e7-1d02-0000-000000000009",
- "receiver": {
- "handle": "$recipient@example.com",
- "vaspName": "ExampleBank",
- "network": "UMA"
- },
+ "receiverUmaAddress": "$recipient@example.com",
+ "lookupId": "Lookup:019542f5-b3e7-1d02-0000-000000000009",
"supportedCurrencies": [
- { "code": "EUR", "decimals": 2 },
- { "code": "BRL", "decimals": 2 }
- ],
- "requiredPayerFields": [
- "FULL_NAME",
- "BIRTH_DATE"
+ {
+ "currency": { "code": "EUR", "name": "Euro", "symbol": "€", "decimals": 2 },
+ "estimatedExchangeRate": 0.92,
+ "min": 100,
+ "max": 10000000
+ },
+ {
+ "currency": { "code": "BRL", "name": "Brazilian Real", "symbol": "R$", "decimals": 2 },
+ "estimatedExchangeRate": 5.15,
+ "min": 100,
+ "max": 10000000
+ }
],
- "constraints": {
- "minAmount": { "amount": 100, "currency": { "code": "USD", "decimals": 2 } },
- "maxAmount": { "amount": 10000000, "currency": { "code": "USD", "decimals": 2 } }
- },
- "createdAt": "2025-10-03T15:00:00Z"
+ "requiredPayerDataFields": [
+ { "name": "FULL_NAME", "mandatory": true },
+ { "name": "BIRTH_DATE", "mandatory": true }
+ ]
}
```
The response includes supported currencies and any required payer information fields.