Skip to content

docs(payments): sync quote/transfer/webhook examples with schema #503

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jklein24 merged 6 commits into from
May 26, 2026
Merged

docs(payments): sync quote/transfer/webhook examples with schema #503

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
e77ac8e
docs(payments): sync quote/transfer/webhook examples with schema
jklein24 May 25, 2026
a4ca636
fix USDC decimal mismatch and duplicate webhook ID (Greptile review)
jklein24 May 25, 2026
ca8d4c7
fix remaining best-practices snippets and stale paths (Greptile review)
jklein24 May 25, 2026
1cfd347
complete quote schema migration in global-p2p quickstart (Greptile re…
jklein24 May 25, 2026
6ad21e2
add currency to REALTIME_FUNDING source per schema (Greptile review)
jklein24 May 25, 2026
c6ecb47
complete envelope migration on USDC webhook block (Greptile review)
jklein24 May 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 37 additions & 11 deletions mintlify/global-p2p/quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand All @@ -178,8 +192,7 @@ In this guide, the entities map as follows:
"assetType": "USDC"
}
}
],
"status": "PENDING"
]
}
```
## Fund the quote (Sandbox simulation)
Expand All @@ -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"
}
```
Expand All @@ -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"
}
}
```

70 changes: 37 additions & 33 deletions mintlify/global-p2p/sending-receiving-payments/receiving-payments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand All @@ -38,44 +43,41 @@ 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",
"BIRTH_DATE": "1985-06-15"
},
"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:

### Option 1: Synchronous (recommended)

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"
}
Expand Down Expand Up @@ -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"
}
Expand All @@ -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": {
Expand All @@ -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": {
Expand All @@ -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"
}
}
```

Expand Down
94 changes: 42 additions & 52 deletions mintlify/payouts-and-b2b/payment-flow/send-payment.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
```
Expand Down Expand Up @@ -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"
}
```

Expand Down Expand Up @@ -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(),
});
Expand Down
Loading
Loading