openapi: 3.2.0 info: title: Lightspark Webhooks API version: '2025-10-13' contact: name: Lightspark Support email: support@lightspark.com license: name: Proprietary url: https://lightspark.com/terms description: 'Operations tagged Webhooks across 2 of this provider''s published API definitions: lightspark-openapi.yml, lightspark-webhooks-api-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server security: - BasicAuth: [] - AgentAuth: [] tags: - name: Webhooks description: Webhook endpoints and configuration for receiving notifications paths: {} webhooks: agent-action: post: summary: Agent action pending approval webhook description: 'Fired when an agent submits an action that requires platform approval before Grid will execute it. Use this to send a push notification to the customer so they can review and approve or reject the action in your app. This endpoint should be implemented by clients of the Grid API. ### Authentication The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid. To verify the signature: 1. Get the Grid public key provided to you during integration 2. Decode the base64 signature from the header 3. Create a SHA-256 hash of the request body 4. Verify the signature using the public key and the hash If the signature verification succeeds, the webhook is authentic. If not, it should be rejected. The payload contains the full `AgentAction` — including the embedded quote or transfer details — so you can render the approval UI without a second API call. Approve or reject via `POST /agents/{agentId}/actions/{actionId}/approve` or `POST /agents/{agentId}/actions/{actionId}/reject`.' operationId: agentActionWebhook tags: - Webhooks security: - WebhookSignature: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentActionWebhook' examples: pendingApproval: summary: Agent action pending approval value: id: Webhook:019542f5-b3e7-1d02-0000-000000000020 type: AGENT_ACTION.PENDING_APPROVAL timestamp: '2025-10-03T15:00:00Z' data: id: AgentAction:019542f5-b3e7-1d02-0000-000000000099 agentId: Agent:019542f5-b3e7-1d02-0000-000000000042 customerId: Customer:019542f5-b3e7-1d02-0000-000000000010 platformCustomerId: user-a1b2c3 status: PENDING_APPROVAL type: EXECUTE_QUOTE quote: id: Quote:019542f5-b3e7-1d02-0000-000000000006 status: PENDING expiresAt: '2025-10-03T15:00:30Z' createdAt: '2025-10-03T15:00:00Z' source: sourceType: ACCOUNT accountId: InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123 destination: destinationType: ACCOUNT accountId: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 sendingCurrency: code: USD name: United States Dollar symbol: $ decimals: 2 receivingCurrency: code: INR name: Indian Rupee symbol: ₹ decimals: 2 totalSendingAmount: 50000 totalReceivingAmount: 4625000 exchangeRate: 92.5 feesIncluded: 250 platformFeesIncluded: 0 transactionId: Transaction:019542f5-b3e7-1d02-0000-000000000099 expiresAt: '2025-10-03T15:00:30Z' createdAt: '2025-10-03T15:00:00Z' updatedAt: '2025-10-03T15:00:00Z' responses: '200': description: Webhook received and acknowledged. '401': description: Unauthorized - Signature validation failed content: application/json: schema: $ref: '#/components/schemas/Error401' '409': description: Conflict - Webhook has already been processed (duplicate id) content: application/json: schema: $ref: '#/components/schemas/Error409' servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server incoming-payment: post: summary: Incoming payment webhook and approval mechanism description: 'Webhook that is called when an incoming payment is received by a customer — over UMA to the customer''s UMA address, or over a bank rail (e.g. a SWIFT wire to the customer''s funding coordinates from `fundingPaymentInstructions`). This endpoint should be implemented by clients of the Grid API. ### Authentication The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid. To verify the signature: 1. Get the Grid public key provided to you during integration 2. Decode the base64 signature from the header 3. Create a SHA-256 hash of the request body 4. Verify the signature using the public key and the hash If the signature verification succeeds, the webhook is authentic. If not, it should be rejected. ### Payment Approval Flow When a transaction has `status: "PENDING"`, this webhook serves as an approval mechanism: 1. The client should check the `counterpartyInformation` against their requirements 2. To APPROVE the payment synchronously, return a 200 OK response 3. To REJECT the payment, return a 403 Forbidden response with an Error object 4. To request more information, return a 422 Unprocessable Entity with specific missing fields 5. To process the payment asynchronously, return a 202 Accepted response and then call the `/transactions/{transactionId}/approve` or `/transactions/{transactionId}/reject` endpoint within 5 seconds. Note that synchronous approval/rejection is preferred where possible. The Grid system will proceed or cancel the payment based on your response. For transactions with other statuses (COMPLETED, FAILED, REFUNDED), this webhook is purely informational. An ACH deposit can be returned after `COMPLETED`, days after it settled. The return takes the funds back, so the payment moves to `FAILED` and `INCOMING_PAYMENT.FAILED` is sent with `source.railDetails.status` set to `RETURNED` and `returnedAt` set. If the return is dishonored and the funds come back, the payment moves to `COMPLETED` again and `INCOMING_PAYMENT.COMPLETED` is sent with `railDetails.status` set to `RETURN_DISHONORED` and `dishonoredAt` set. A contested dishonor sends `INCOMING_PAYMENT.FAILED` once more with `RETURN_CONTESTED`. Bank-rail incoming payments (e.g. SWIFT) are informational at every status, including PENDING: the funds have already moved interbank, so the approval mechanism and the 5-second response window do not apply.' operationId: incomingPaymentWebhook tags: - Webhooks security: - WebhookSignature: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IncomingPaymentWebhook' examples: pendingPayment: summary: Pending payment example requiring approval value: id: Webhook:019542f5-b3e7-1d02-0000-000000000007 type: INCOMING_PAYMENT.PENDING timestamp: '2025-08-15T14:32:00Z' data: id: Transaction:019542f5-b3e7-1d02-0000-000000000005 status: PENDING type: INCOMING direction: CREDIT destination: destinationType: UMA_ADDRESS umaAddress: $recipient@uma.domain customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 senderUmaAddress: $sender@external.domain receiverUmaAddress: $recipient@uma.domain receivedAmount: amount: 50000 currency: code: USD name: United States Dollar symbol: $ decimals: 2 counterpartyInformation: FULL_NAME: John Sender BIRTH_DATE: '1985-06-15' NATIONALITY: US reconciliationInstructions: reference: REF-123456789 requestedReceiverCustomerInfoFields: - name: NATIONALITY mandatory: true - name: POSTAL_ADDRESS mandatory: false incomingCompletedPayment: summary: Completed payment notification value: id: Webhook:019542f5-b3e7-1d02-0000-000000000007 type: INCOMING_PAYMENT.COMPLETED timestamp: '2025-08-15T14:32:00Z' data: id: Transaction:019542f5-b3e7-1d02-0000-000000000005 status: COMPLETED type: INCOMING direction: CREDIT destination: destinationType: UMA_ADDRESS umaAddress: $recipient@uma.domain customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 senderUmaAddress: $sender@external.domain receiverUmaAddress: $recipient@uma.domain receivedAmount: amount: 50000 currency: code: USD name: United States Dollar symbol: $ decimals: 2 settledAt: '2025-08-15T14:30:00Z' createdAt: '2025-08-15T14:25:18Z' description: Payment for services reconciliationInstructions: reference: REF-123456789 incomingCompletedCryptoPayment: summary: Completed payment funded from an external crypto wallet value: id: Webhook:019542f5-b3e7-1d02-0000-000000000009 type: INCOMING_PAYMENT.COMPLETED timestamp: '2025-08-15T14:32:00Z' data: id: Transaction:019542f5-b3e7-1d02-0000-000000000006 status: COMPLETED type: INCOMING direction: CREDIT source: sourceType: REALTIME_FUNDING currency: USDC railDetails: paymentRail: ONCHAIN transactionHash: 7RJWhvQBQPEjJmki5fhBboGBWRJhmcFkMvrr4Fu3tMSJ5EdynMEiYSyiWAH9GpcbHpeUzeSQF9ZY6q4x8AhBskUf network: SOLANA onChainTransaction: transactionHash: 7RJWhvQBQPEjJmki5fhBboGBWRJhmcFkMvrr4Fu3tMSJ5EdynMEiYSyiWAH9GpcbHpeUzeSQF9ZY6q4x8AhBskUf network: SOLANA destination: destinationType: ACCOUNT accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 receivedAmount: amount: 100000 currency: code: USDC name: USD Coin symbol: '' decimals: 6 settledAt: '2025-08-15T14:30:00Z' createdAt: '2025-08-15T14:25:18Z' description: USDC deposit from self-custody wallet incomingCompletedWirePayment: summary: Completed payment funded by a wire value: id: Webhook:019542f5-b3e7-1d02-0000-000000000011 type: INCOMING_PAYMENT.COMPLETED timestamp: '2025-08-15T14:32:00Z' data: id: Transaction:019542f5-b3e7-1d02-0000-000000000012 status: COMPLETED type: INCOMING direction: CREDIT source: sourceType: REALTIME_FUNDING currency: USD railDetails: paymentRail: WIRE status: SETTLED settledAt: '2025-08-15T14:30:00Z' imad: 20250815MMQFMP9C000123 originatorToBeneficiaryInformation: INV-12345 bankAccount: accountHolderName: John Sender routingNumber: '021000021' accountNumber: '****6789' bankName: Chase Bank paymentRail: WIRE accountHolderName: John Sender accountIdentifier: '****6789' bankName: Chase Bank bankIdentifier: '021000021' remittanceInformation: INV-12345 traceNumber: 20250815MMQFMP9C000123 destination: destinationType: ACCOUNT accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 receivedAmount: amount: 2500000 currency: code: USD name: United States Dollar symbol: $ decimals: 2 settledAt: '2025-08-15T14:30:00Z' createdAt: '2025-08-15T14:25:18Z' description: Wire deposit incomingAchDepositReturned: summary: ACH deposit returned after completion description: The deposit settled, and the originating bank later returned the ACH entry. The return takes the funds back, so the payment moves to `FAILED` and the source's `railDetails` shows `RETURNED`. value: id: Webhook:019542f5-b3e7-1d02-0000-000000000013 type: INCOMING_PAYMENT.FAILED timestamp: '2025-08-18T15:02:00Z' data: id: Transaction:019542f5-b3e7-1d02-0000-000000000014 status: FAILED type: INCOMING direction: CREDIT source: sourceType: ACCOUNT accountId: ExternalAccount:b23dcbd6-dced-4ec4-b756-3c3a9ea3d456 currency: USD railDetails: paymentRail: ACH status: RETURNED bankAccount: accountHolderName: Jane Sender routingNumber: '021000021' accountNumber: '****4321' traceNumber: '021000020123456' returnedAt: '2025-08-18T15:00:00Z' destination: destinationType: ACCOUNT accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 receivedAmount: amount: 100000 currency: code: USD name: United States Dollar symbol: $ decimals: 2 settledAt: '2025-08-15T14:30:00Z' createdAt: '2025-08-15T14:25:18Z' description: ACH deposit incomingRefundedPayment: summary: Refunded incoming payment notification value: id: Webhook:019542f5-b3e7-1d02-0000-000000000011 type: INCOMING_PAYMENT.REFUND_COMPLETED timestamp: '2025-08-15T14:40:00Z' data: id: Transaction:019542f5-b3e7-1d02-0000-000000000005 status: FAILED type: INCOMING direction: CREDIT destination: destinationType: UMA_ADDRESS umaAddress: $recipient@uma.domain customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 senderUmaAddress: $sender@external.domain receiverUmaAddress: $recipient@uma.domain receivedAmount: amount: 50000 currency: code: USD name: United States Dollar symbol: $ decimals: 2 createdAt: '2025-08-15T14:25:18Z' description: Payment for services reconciliationInstructions: reference: REF-123456789 failureReason: OFFRAMP_FAILED refund: reference: REF-123456789-REFUND initiatedAt: '2025-08-15T14:35:00Z' settledAt: '2025-08-15T14:40:00Z' status: COMPLETED reason: TRANSACTION_FAILED responses: '200': description: 'Webhook received successfully. For PENDING transactions on approval-mechanism rails, this indicates approval to proceed with the payment. For bank-rail incoming payments (e.g. SWIFT) a 200 only acknowledges receipt: there is nothing to approve. If `requestedReceiverCustomerInfoFields` were present in the webhook request, the corresponding fields for the recipient must be included in this response in the `receiverCustomerInfo` object. ' content: application/json: schema: $ref: '#/components/schemas/IncomingPaymentWebhookResponse' '202': description: 'Webhook received and will be processed asynchronously. The synchronous 200 response should be preferred where possible. This asycnhronous path should only be used in cases where the platform''s architecture requires async (but still very quick) processing before approving or rejecting the payment. The platform must call the `/transactions/{transactionId}/approve` or `/transactions/{transactionId}/reject` endpoint to approve or reject the payment within 5 seconds or the payment will be automatically rejected. Bank-rail incoming payments (e.g. SWIFT) need no approve/reject call: a 202 is treated the same as a 200 acknowledgment. ' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized - Signature validation failed content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: 'Forbidden - Payment rejected by the client. Only applicable for PENDING transactions on approval-mechanism rails; a bank-rail incoming payment (e.g. SWIFT) cannot be rejected through this response because the funds have already moved interbank. ' content: application/json: schema: $ref: '#/components/schemas/IncomingPaymentWebhookForbiddenResponse' '409': description: Conflict - Webhook has already been processed (duplicate id) content: application/json: schema: $ref: '#/components/schemas/Error409' '422': description: 'Unprocessable Entity - Additional counterparty information required. Only applicable for PENDING transactions on approval-mechanism rails; for bank-rail incoming payments (e.g. SWIFT) this response has no effect on the already-received funds. ' content: application/json: schema: $ref: '#/components/schemas/IncomingPaymentWebhookUnprocessableResponse' servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server outgoing-payment: post: summary: Outgoing payment status webhook description: 'Webhook that is called when an outgoing payment''s status changes. A side''s `railDetails` carries the rail-level status of that leg; for example, a payout the receiving bank returns arrives as `OUTGOING_PAYMENT.FAILED` with `destination.railDetails.status` set to `RETURNED`, and the payout is refunded to its source. A returned payout stays `FAILED` even if the originating bank later dishonors the return: the refund has already been posted, so the funds are reconciled manually. The dishonor is still reported: `OUTGOING_PAYMENT.FAILED` is sent again with `railDetails.status` set to `RETURN_DISHONORED` and `dishonoredAt` set. This endpoint should be implemented by clients of the Grid API. ### Authentication The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid. To verify the signature: 1. Get the Grid public key provided to you during integration 2. Decode the base64 signature from the header 3. Create a SHA-256 hash of the request body 4. Verify the signature using the public key and the hash If the signature verification succeeds, the webhook is authentic. If not, it should be rejected. This webhook is informational only and is sent when an outgoing payment completes successfully, fails, or is refunded.' operationId: outgoingPaymentWebhook tags: - Webhooks security: - WebhookSignature: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OutgoingPaymentWebhook' examples: outgoingCompletedPayment: summary: Completed outgoing payment value: id: Webhook:019542f5-b3e7-1d02-0000-000000000007 type: OUTGOING_PAYMENT.COMPLETED timestamp: '2025-08-15T14:32:00Z' data: id: Transaction:019542f5-b3e7-1d02-0000-000000000005 status: COMPLETED type: OUTGOING direction: DEBIT source: sourceType: ACCOUNT accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 destination: destinationType: ACCOUNT accountId: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 senderUmaAddress: $sender@uma.domain receiverUmaAddress: $recipient@external.domain sentAmount: amount: 10550 currency: code: USD name: United States Dollar symbol: $ decimals: 2 receivedAmount: amount: 9706 currency: code: EUR name: Euro symbol: € decimals: 2 exchangeRate: 0.92 quoteId: Quote:019542f5-b3e7-1d02-0000-000000000006 settledAt: '2025-08-15T14:30:00Z' createdAt: '2025-08-15T14:25:18Z' description: 'Payment for invoice #1234' paymentInstructions: [] rateDetails: counterpartyMultiplier: 1.08 counterpartyFixedFee: 10 gridApiMultiplier: 0.925 gridApiFixedFee: 10 gridApiVariableFeeRate: 0.003 gridApiVariableFeeAmount: 30 outgoingCompletedCryptoPayment: summary: Completed crypto payout to an external wallet value: id: Webhook:019542f5-b3e7-1d02-0000-000000000008 type: OUTGOING_PAYMENT.COMPLETED timestamp: '2025-08-15T14:32:00Z' data: id: Transaction:019542f5-b3e7-1d02-0000-000000000009 status: COMPLETED type: OUTGOING direction: DEBIT source: sourceType: ACCOUNT accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 destination: destinationType: ACCOUNT accountId: ExternalAccount:c34dcbd6-dced-4ec4-b756-3c3a9ea3d789 railDetails: paymentRail: ONCHAIN transactionHash: h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx network: SOLANA onChainTransaction: transactionHash: h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx network: SOLANA customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 sentAmount: amount: 100000 currency: code: USDC name: USD Coin symbol: '' decimals: 6 receivedAmount: amount: 100000 currency: code: USDC name: USD Coin symbol: '' decimals: 6 quoteId: Quote:019542f5-b3e7-1d02-0000-000000000010 settledAt: '2025-08-15T14:30:00Z' createdAt: '2025-08-15T14:25:18Z' description: USDC withdrawal to self-custody wallet paymentInstructions: [] outgoingAchPaymentReturned: summary: ACH payout returned by the receiving bank description: The payout settled, and the receiving bank later returned the ACH entry. The transaction moves to `FAILED` with `PAYOUT_RETURNED`, and the destination's `railDetails` moves to `RETURNED`. The refund back to the source follows as `OUTGOING_PAYMENT.REFUND_PENDING` and `OUTGOING_PAYMENT.REFUND_COMPLETED`. value: id: Webhook:019542f5-b3e7-1d02-0000-000000000011 type: OUTGOING_PAYMENT.FAILED timestamp: '2025-08-18T15:02:00Z' data: id: Transaction:019542f5-b3e7-1d02-0000-000000000012 status: FAILED type: OUTGOING direction: DEBIT source: sourceType: ACCOUNT accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 destination: destinationType: ACCOUNT accountId: ExternalAccount:b23dcbd6-dced-4ec4-b756-3c3a9ea3d456 railDetails: paymentRail: ACH status: RETURNED bankAccount: accountHolderName: Jane Receiver routingNumber: '021000021' accountNumber: '****4321' traceNumber: '021000020123456' statementDescriptor: INVOICE addenda: INV-2025-0815 settledAt: '2025-08-15T14:30:00Z' returnedAt: '2025-08-18T15:00:00Z' customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 sentAmount: amount: 50000 currency: code: USD name: United States Dollar symbol: $ decimals: 2 receivedAmount: amount: 50000 currency: code: USD name: United States Dollar symbol: $ decimals: 2 quoteId: Quote:019542f5-b3e7-1d02-0000-000000000013 settledAt: '2025-08-15T14:30:00Z' createdAt: '2025-08-15T14:25:18Z' description: Vendor payout paymentInstructions: [] failureReason: PAYOUT_RETURNED failedPayment: summary: Failed outgoing payment value: id: Webhook:019542f5-b3e7-1d02-0000-000000000007 type: OUTGOING_PAYMENT.FAILED timestamp: '2025-08-15T14:32:00Z' data: id: Transaction:019542f5-b3e7-1d02-0000-000000000005 status: FAILED type: OUTGOING direction: DEBIT source: sourceType: ACCOUNT accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 destination: destinationType: ACCOUNT accountId: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 senderUmaAddress: $sender@uma.domain receiverUmaAddress: $recipient@external.domain sentAmount: amount: 10550 currency: code: USD name: United States Dollar symbol: $ decimals: 2 createdAt: '2025-08-15T14:25:18Z' quoteId: Quote:019542f5-b3e7-1d02-0000-000000000006 failureReason: QUOTE_EXECUTION_FAILED responses: '200': description: Webhook received successfully '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized - Signature validation failed content: application/json: schema: $ref: '#/components/schemas/Error401' '409': description: Conflict - Webhook has already been processed (duplicate id) content: application/json: schema: $ref: '#/components/schemas/Error409' servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server test-webhook: post: summary: Test webhook for integration verification description: 'Webhook that is sent once to verify your webhook endpoint is correctly set up. This is sent when you configure or update your platform settings with a webhook URL. ### Authentication The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by the Grid API. To verify the signature: 1. Get the Grid public key provided to you during integration 2. Decode the base64 signature from the header 3. Create a SHA-256 hash of the request body 4. Verify the signature using the public key and the hash If the signature verification succeeds, the webhook is authentic. If not, it should be rejected. This webhook is purely for testing your endpoint integration and signature verification.' operationId: testWebhook tags: - Webhooks security: - WebhookSignature: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TestWebhookRequest' examples: testWebhook: summary: Test webhook example value: id: Webhook:019542f5-b3e7-1d02-0000-000000000001 type: TEST timestamp: '2025-08-15T14:32:00Z' data: {} responses: '200': description: Webhook received successfully. This confirms your webhook endpoint is properly configured. '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized - Signature validation failed content: application/json: schema: $ref: '#/components/schemas/Error401' '409': description: Conflict - Webhook has already been processed (duplicate id) content: application/json: schema: $ref: '#/components/schemas/Error409' servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server bulk-upload: post: summary: Bulk upload status webhook description: 'Webhook that is called when a bulk customer upload job completes or fails. This endpoint should be implemented by clients of the Grid API. ### Authentication The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid. To verify the signature: 1. Get the Grid public key provided to you during integration 2. Decode the base64 signature from the header 3. Create a SHA-256 hash of the request body 4. Verify the signature using the public key and the hash If the signature verification succeeds, the webhook is authentic. If not, it should be rejected. This webhook is sent when a bulk upload job completes or fails, providing detailed information about the results.' operationId: bulkUploadWebhook tags: - Webhooks security: - WebhookSignature: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BulkUploadWebhook' examples: completedUpload: summary: Successful bulk upload completion value: id: Webhook:019542f5-b3e7-1d02-0000-000000000008 type: BULK_UPLOAD.COMPLETED timestamp: '2025-08-15T14:32:00Z' data: id: Job:019542f5-b3e7-1d02-0000-000000000006 status: COMPLETED progress: total: 5000 processed: 5000 successful: 5000 failed: 0 errors: [] failedUpload: summary: Failed bulk upload value: id: Webhook:019542f5-b3e7-1d02-0000-000000000008 type: BULK_UPLOAD.FAILED timestamp: '2025-08-15T14:32:00Z' data: id: Job:019542f5-b3e7-1d02-0000-000000000006 status: FAILED progress: total: 5000 processed: 5000 successful: 0 failed: 5000 errors: - correlationId: row_1 error: code: invalid_csv_format message: Invalid CSV format details: reason: missing_required_column column: umaAddress responses: '200': description: Webhook received successfully '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized - Signature validation failed content: application/json: schema: $ref: '#/components/schemas/Error401' '409': description: Conflict - Webhook has already been processed (duplicate id) content: application/json: schema: $ref: '#/components/schemas/Error409' servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server invitation-claimed: post: summary: Invitation claimed webhook description: 'Webhook that is called when an invitation is claimed by a customer. This endpoint should be implemented by platform clients of the Grid API. When a customer claims an invitation, this webhook is triggered to notify the platform that: 1. The invitation has been successfully claimed 2. The invitee UMA address is now associated with the invitation 3. The invitation status has changed from PENDING to CLAIMED This allows platforms to: - Track invitation usage and conversion rates - Trigger onboarding flows for new customers who joined via invitation - Apply referral bonuses or rewards to the inviter - Update their UI to reflect the claimed status ### Authentication The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid. To verify the signature: 1. Get the Grid public key provided to you during integration 2. Decode the base64 signature from the header 3. Create a SHA-256 hash of the request body 4. Verify the signature using the public key and the hash If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.' operationId: invitationClaimedWebhook tags: - Webhooks security: - WebhookSignature: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InvitationClaimedWebhook' examples: claimedInvitation: summary: Invitation claimed notification value: id: Webhook:019542f5-b3e7-1d02-0000-000000000008 type: INVITATION.CLAIMED timestamp: '2025-09-01T15:45:00Z' data: code: 019542f5 createdAt: '2025-09-01T14:30:00Z' claimedAt: '2025-09-01T15:45:00Z' inviterUma: $inviter@uma.domain inviteeUma: $invitee@uma.domain status: CLAIMED url: https://uma.me/i/019542f5 responses: '200': description: Webhook received successfully '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized - Signature validation failed content: application/json: schema: $ref: '#/components/schemas/Error401' '409': description: Conflict - Webhook has already been processed (duplicate id) content: application/json: schema: $ref: '#/components/schemas/Error409' servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server customer-update: post: summary: Customer status change description: 'Webhook that is called when the status of a customer is updated, including KYC and KYB status changes. This endpoint should be implemented by clients of the Grid API. ### Authentication The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid. To verify the signature: 1. Get the Grid API public key provided to you during integration 2. Decode the base64 signature from the header 3. Create a SHA-256 hash of the request body 4. Verify the signature using the public key and the hash If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.' operationId: customerStatusWebhook tags: - Webhooks security: - WebhookSignature: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomerWebhook' examples: kycApprovedWebhook: summary: When an individual customer KYC has been approved value: id: Webhook:019542f5-b3e7-1d02-0000-000000000007 type: CUSTOMER.KYC_APPROVED timestamp: '2025-08-15T14:32:00Z' data: id: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 9f84e0c2a72c4fa customerType: INDIVIDUAL agreementConsents: - type: LIGHTSPARK_END_USER_TERMS acceptedAt: '2025-07-21T17:30:00Z' ipAddress: 203.0.113.42 termsVersion: '2025-10-13' acceptanceMethod: CHECKBOX region: US currencies: - USD - USDC umaAddress: $john.doe@uma.domain.com kycStatus: APPROVED fullName: John Michael Doe birthDate: '1990-01-15' nationality: US address: line1: 123 Main Street line2: Apt 4B city: Seattle state: WA postalCode: '98101' country: US createdAt: '2025-07-21T17:32:28Z' updatedAt: '2025-07-21T17:32:28Z' isDeleted: false kycRejectedWebhook: summary: When an individual customer KYC has been rejected value: id: Webhook:019542f5-b3e7-1d02-0000-000000000008 type: CUSTOMER.KYC_REJECTED timestamp: '2025-08-15T14:32:00Z' data: id: Customer:019542f5-b3e7-1d02-0000-000000000002 platformCustomerId: 4b7c1e9d3f5a8e2 customerType: INDIVIDUAL agreementConsents: - type: LIGHTSPARK_END_USER_TERMS acceptedAt: '2025-07-21T17:30:00Z' ipAddress: 203.0.113.42 termsVersion: '2025-10-13' acceptanceMethod: CHECKBOX region: US currencies: - USD - USDC umaAddress: $jane.smith@uma.domain.com kycStatus: REJECTED fullName: Jane Smith birthDate: '1988-03-22' nationality: US createdAt: '2025-07-21T17:32:28Z' updatedAt: '2025-08-15T14:32:00Z' isDeleted: false kybApprovedWebhook: summary: When a business customer KYB has been approved value: id: Webhook:019542f5-b3e7-1d02-0000-000000000009 type: CUSTOMER.KYB_APPROVED timestamp: '2025-08-15T14:32:00Z' data: id: Customer:019542f5-b3e7-1d02-0000-000000000003 platformCustomerId: 7a2f9d4e1b8c3f5 customerType: BUSINESS agreementConsents: - type: LIGHTSPARK_END_USER_TERMS acceptedAt: '2025-07-21T17:30:00Z' ipAddress: 203.0.113.42 termsVersion: '2025-10-13' acceptanceMethod: CHECKBOX region: US currencies: - USD - USDC umaAddress: $acme.corp@uma.domain.com kybStatus: APPROVED address: line1: 456 Business Ave city: Seattle state: WA postalCode: '98101' country: US businessInfo: legalName: Acme Corporation registrationNumber: '12345678' taxId: 98-7654321 incorporatedOn: '2018-03-14' createdAt: '2025-07-21T17:32:28Z' updatedAt: '2025-08-15T14:32:00Z' isDeleted: false kybRejectedWebhook: summary: When a business customer KYB has been rejected value: id: Webhook:019542f5-b3e7-1d02-0000-000000000010 type: CUSTOMER.KYB_REJECTED timestamp: '2025-08-15T14:32:00Z' data: id: Customer:019542f5-b3e7-1d02-0000-000000000004 platformCustomerId: 3c8e5f2a9d1b7e4 customerType: BUSINESS agreementConsents: - type: LIGHTSPARK_END_USER_TERMS acceptedAt: '2025-07-21T17:30:00Z' ipAddress: 203.0.113.42 termsVersion: '2025-10-13' acceptanceMethod: CHECKBOX region: US currencies: - USD umaAddress: $globex.inc@uma.domain.com kybStatus: REJECTED address: line1: 789 Corporate Blvd city: Chicago state: IL postalCode: '60601' country: US businessInfo: legalName: Globex Inc taxId: 47-1234567 incorporatedOn: '2015-09-01' createdAt: '2025-07-21T17:32:28Z' updatedAt: '2025-08-15T14:32:00Z' isDeleted: false responses: '200': description: 'Webhook received successfully ' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized - Signature validation failed content: application/json: schema: $ref: '#/components/schemas/Error401' '409': description: Conflict - Webhook has already been processed (duplicate id) content: application/json: schema: $ref: '#/components/schemas/Error409' servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server internal-account-status: post: summary: Internal account status webhook description: 'Webhook that is called when the status of an internal account changes. This includes balance updates and may include additional account events in the future. This endpoint should be implemented by clients of the Grid API. ### Authentication The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid. To verify the signature: 1. Get the Grid public key provided to you during integration 2. Decode the base64 signature from the header 3. Create a SHA-256 hash of the request body 4. Verify the signature using the public key and the hash If the signature verification succeeds, the webhook is authentic. If not, it should be rejected. ### Event types - `INTERNAL_ACCOUNT.BALANCE_UPDATED` — Fired when the balance of an internal account changes. The `data` payload contains the full internal account object. - `INTERNAL_ACCOUNT.STATUS_UPDATED` — Fired when the status of an internal account changes (e.g., `OPEN` → `FROZEN`). The `data` payload contains the full internal account object. - `INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED` — Fired when the account''s `fundingPaymentInstructions` change: new funding coordinates became available (e.g., a SWIFT collection account finished provisioning) or previously served coordinates were withdrawn. The `data` payload contains the full internal account object, including the current `fundingPaymentInstructions`.' operationId: internalAccountStatusWebhook tags: - Webhooks security: - WebhookSignature: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InternalAccountStatusWebhook' examples: balanceDecrease: summary: A transaction just cleared a customer account and the balance has decreased value: id: Webhook:019542f5-b3e7-1d02-0000-000000000007 type: INTERNAL_ACCOUNT.BALANCE_UPDATED timestamp: '2025-08-15T14:32:00Z' data: id: InternalAccount:019542f5-b3e7-1d02-0000-000000000005 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 type: INTERNAL_FIAT status: ACTIVE balance: amount: 10000 currency: code: USD name: United States Dollar symbol: $ decimals: 2 totalBalance: amount: 12500 currency: code: USD name: United States Dollar symbol: $ decimals: 2 fundingPaymentInstructions: [] createdAt: '2025-08-01T10:00:00Z' updatedAt: '2025-08-15T14:32:00Z' statusUpdated: summary: The status of an internal account changed (e.g., frozen by Grid) value: id: Webhook:019542f5-b3e7-1d02-0000-000000000008 type: INTERNAL_ACCOUNT.STATUS_UPDATED timestamp: '2025-08-15T14:32:00Z' data: id: InternalAccount:019542f5-b3e7-1d02-0000-000000000005 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 type: INTERNAL_FIAT status: FROZEN balance: amount: 10000 currency: code: USD name: United States Dollar symbol: $ decimals: 2 totalBalance: amount: 10000 currency: code: USD name: United States Dollar symbol: $ decimals: 2 fundingPaymentInstructions: [] createdAt: '2025-08-01T10:00:00Z' updatedAt: '2025-08-15T14:32:00Z' fundingInstructionsUpdated: summary: A SWIFT collection account finished provisioning and the account gained wire coordinates value: id: Webhook:019542f5-b3e7-1d02-0000-000000000009 type: INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED timestamp: '2025-08-15T14:32:00Z' data: id: InternalAccount:019542f5-b3e7-1d02-0000-000000000005 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 type: INTERNAL_FIAT status: ACTIVE balance: amount: 10000 currency: code: USD name: United States Dollar symbol: $ decimals: 2 totalBalance: amount: 10000 currency: code: USD name: United States Dollar symbol: $ decimals: 2 fundingPaymentInstructions: - accountOrWalletInfo: accountType: SWIFT_ACCOUNT country: SG swiftCode: DBSSSGSG bankName: DBS Bank accountNumber: '8850123456' accountHolderName: Acme Exports Pte Ltd paymentRails: - SWIFT instructionsNotes: Payments are attributed automatically by the destination account; no reference code is required. createdAt: '2025-08-01T10:00:00Z' updatedAt: '2025-08-15T14:32:00Z' responses: '200': description: 'Webhook received successfully ' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized - Signature validation failed content: application/json: schema: $ref: '#/components/schemas/Error401' '409': description: Conflict - Webhook has already been processed (duplicate id) content: application/json: schema: $ref: '#/components/schemas/Error409' servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server external-account-status: post: summary: External account webhook description: 'Webhook that is called whenever the status or the account details of an external account change. Status changes cover any transition between statuses (`PENDING`, `ACTIVE`, `UNDER_REVIEW`, `INACTIVE`, `PENDING_OWNERSHIP_VERIFICATION`, `UNVERIFIED`) — for example when an account under review becomes active, when ownership verification completes (`PENDING_OWNERSHIP_VERIFICATION` → `ACTIVE`), or when a verification attempt fails (`PENDING_OWNERSHIP_VERIFICATION` → `UNVERIFIED`). This endpoint should be implemented by clients of the Grid API. ### Authentication The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid. To verify the signature: 1. Get the Grid public key provided to you during integration 2. Decode the base64 signature from the header 3. Create a SHA-256 hash of the request body 4. Verify the signature using the public key and the hash If the signature verification succeeds, the webhook is authentic. If not, it should be rejected. ### Event types - `EXTERNAL_ACCOUNT.STATUS_UPDATED` — Fired when the status of an external account changes. The `data` payload contains the full external account object. - `EXTERNAL_ACCOUNT.ACCOUNT_INFO_UPDATED` — Fired when Grid corrects an external account''s `accountInfo`. Today this happens when the receiving bank sends an ACH notification of change (NOC) with corrected details, such as a new routing number, account number or bank account type. The account keeps its `id`, and later payments to it use the corrected details. The `data` payload contains the full external account object with the corrected `accountInfo`. Deliveries can arrive out of order, and the external account has no version field, so an older `STATUS_UPDATED` payload can carry the pre-correction details. Before you replace a stored copy of the account details, fetch the current account with `GET /customers/external-accounts/{externalAccountId}` (or the platform equivalent) and store that response.' operationId: externalAccountStatusWebhook tags: - Webhooks security: - WebhookSignature: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExternalAccountStatusWebhook' examples: verificationSucceeded: summary: A wallet account became active after ownership verification value: id: Webhook:019542f5-b3e7-1d02-0000-000000000042 type: EXTERNAL_ACCOUNT.STATUS_UPDATED timestamp: '2025-08-15T14:32:00Z' data: id: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 customerId: Customer:da459a29-1fb7-41ce-a4cb-eb3a3c9fd7a7 status: ACTIVE currency: USDC ownershipType: FIRST_PARTY accountInfo: accountType: ETHEREUM_WALLET address: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' arbitrumWalletActive: summary: An Arbitrum wallet account became active value: id: Webhook:019542f5-b3e7-1d02-0000-000000000044 type: EXTERNAL_ACCOUNT.STATUS_UPDATED timestamp: '2025-08-15T14:32:00Z' data: id: ExternalAccount:f95dcbd6-dced-4ec4-b756-3c3a9ea3d966 customerId: Customer:da459a29-1fb7-41ce-a4cb-eb3a3c9fd7a7 status: ACTIVE currency: USDC ownershipType: FIRST_PARTY accountInfo: accountType: ARBITRUM_WALLET address: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' accountInfoCorrected: summary: The receiving bank corrected a US account's routing number value: id: Webhook:019542f5-b3e7-1d02-0000-000000000045 type: EXTERNAL_ACCOUNT.ACCOUNT_INFO_UPDATED timestamp: '2025-08-15T14:32:00Z' data: id: ExternalAccount:a75dcbd6-dced-4ec4-b756-3c3a9ea3d967 customerId: Customer:da459a29-1fb7-41ce-a4cb-eb3a3c9fd7a7 status: ACTIVE currency: USD ownershipType: FIRST_PARTY accountInfo: accountType: USD_ACCOUNT accountNumber: '12345678901' routingNumber: '061000227' bankAccountType: CHECKING bankName: Chase Bank paymentRails: - ACH - WIRE beneficiary: beneficiaryType: INDIVIDUAL fullName: John Doe verificationFailed: summary: A liveness check failed; a new challenge is needed to retry value: id: Webhook:019542f5-b3e7-1d02-0000-000000000043 type: EXTERNAL_ACCOUNT.STATUS_UPDATED timestamp: '2025-08-15T14:45:00Z' data: id: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 customerId: Customer:da459a29-1fb7-41ce-a4cb-eb3a3c9fd7a7 status: UNVERIFIED currency: USDC ownershipType: FIRST_PARTY accountInfo: accountType: ETHEREUM_WALLET address: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' responses: '200': description: 'Webhook received successfully ' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized - Signature validation failed content: application/json: schema: $ref: '#/components/schemas/Error401' '409': description: Conflict - Webhook has already been processed (duplicate id) content: application/json: schema: $ref: '#/components/schemas/Error409' servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server verification-update: post: summary: Verification status change description: 'Webhook that is called when a customer''s KYC/KYB verification status changes. This endpoint should be implemented by clients of the Grid API. ### Authentication The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid. To verify the signature: 1. Get the Grid API public key provided to you during integration 2. Decode the base64 signature from the header 3. Create a SHA-256 hash of the request body 4. Verify the signature using the public key and the hash If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.' operationId: verificationStatusWebhook tags: - Webhooks security: - WebhookSignature: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VerificationWebhook' examples: approved: summary: Verification approved value: id: Webhook:019542f5-b3e7-1d02-0000-000000000030 type: VERIFICATION.APPROVED timestamp: '2025-08-15T14:32:00Z' data: id: Verification:019542f5-b3e7-1d02-0000-000000000010 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 verificationStatus: APPROVED errors: [] createdAt: '2025-08-15T14:00:00Z' resolveErrors: summary: Verification requires action value: id: Webhook:019542f5-b3e7-1d02-0000-000000000031 type: VERIFICATION.RESOLVE_ERRORS timestamp: '2025-08-15T14:32:00Z' data: id: Verification:019542f5-b3e7-1d02-0000-000000000011 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 verificationStatus: RESOLVE_ERRORS errors: - resourceId: Customer:019542f5-b3e7-1d02-0000-000000000001 type: MISSING_PROOF_OF_ADDRESS_DOCUMENT acceptedDocumentTypes: - PROOF_OF_ADDRESS reason: Proof of address document is required createdAt: '2025-08-15T14:00:00Z' responses: '200': description: 'Webhook received successfully ' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized - Signature validation failed content: application/json: schema: $ref: '#/components/schemas/Error401' '409': description: Conflict - Webhook has already been processed (duplicate id) content: application/json: schema: $ref: '#/components/schemas/Error409' servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server card-status-change: post: summary: Card status change description: 'Webhook that is called when a card''s lifecycle status changes. Fires on `PROCESSING → ACTIVE | PENDING_AUTH`, `ACTIVE ⇄ PENDING_AUTH` as funding sources or delegated signing authorization change, on `PROCESSING → CLOSED (ISSUER_REJECTED)` when issuer provisioning fails, and on every subsequent `ACTIVE ⇄ FROZEN`, `PENDING_AUTH → FROZEN`, and `→ CLOSED` transition. This endpoint should be implemented by clients of the Grid API. ### Authentication The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid. To verify the signature: 1. Get the Grid public key provided to you during integration 2. Decode the base64 signature from the header 3. Create a SHA-256 hash of the request body 4. Verify the signature using the public key and the hash If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.' operationId: cardStatusChangeWebhook tags: - Webhooks security: - WebhookSignature: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CardStatusChangeWebhook' examples: activated: summary: Card transitioned from PROCESSING to ACTIVE value: id: Webhook:019542f5-b3e7-1d02-0000-000000000020 type: CARD.STATUS_CHANGE timestamp: '2026-05-08T14:11:00Z' data: id: Card:019542f5-b3e7-1d02-0000-000000000010 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCardId: card-emp-001 status: ACTIVE brand: VISA form: VIRTUAL last4: '4242' expMonth: 12 expYear: 2029 fundingSource: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 maxSpendPerTransaction: 5000 maxSpendPerDay: 25000 maxTransactionsPerDay: 20 currency: USD processorRef: card_b81c2a4f issuerRef: lead_card_7a1b9c3d createdAt: '2026-05-08T14:10:00Z' updatedAt: '2026-05-08T14:11:00Z' delegationRequired: summary: Provisioned card requires funding authorization value: id: Webhook:019542f5-b3e7-1d02-0000-000000000020 type: CARD.STATUS_CHANGE timestamp: '2026-05-08T14:11:00Z' data: id: Card:019542f5-b3e7-1d02-0000-000000000010 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCardId: card-emp-001 status: PENDING_AUTH statusReason: DELEGATION_REQUIRED brand: VISA form: VIRTUAL last4: '4242' expMonth: 12 expYear: 2029 fundingSource: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 maxSpendPerTransaction: 5000 maxSpendPerDay: 25000 maxTransactionsPerDay: 20 currency: USD processorRef: card_b81c2a4f issuerRef: lead_card_7a1b9c3d createdAt: '2026-05-08T14:10:00Z' updatedAt: '2026-05-08T14:11:00Z' issuerRejected: summary: Card rejected by issuer during provisioning value: id: Webhook:019542f5-b3e7-1d02-0000-000000000021 type: CARD.STATUS_CHANGE timestamp: '2026-05-08T14:12:00Z' data: id: Card:019542f5-b3e7-1d02-0000-000000000011 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 status: CLOSED statusReason: ISSUER_REJECTED form: VIRTUAL fundingSource: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 maxSpendPerTransaction: null maxSpendPerDay: null maxTransactionsPerDay: null currency: USD createdAt: '2026-05-08T14:10:00Z' updatedAt: '2026-05-08T14:12:00Z' frozen: summary: Card frozen by the platform value: id: Webhook:019542f5-b3e7-1d02-0000-000000000022 type: CARD.STATUS_CHANGE timestamp: '2026-05-09T09:00:00Z' data: id: Card:019542f5-b3e7-1d02-0000-000000000010 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 status: FROZEN brand: VISA form: VIRTUAL last4: '4242' expMonth: 12 expYear: 2029 fundingSource: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 maxSpendPerTransaction: 5000 maxSpendPerDay: 25000 maxTransactionsPerDay: 20 currency: USD createdAt: '2026-05-08T14:10:00Z' updatedAt: '2026-05-09T09:00:00Z' responses: '200': description: 'Webhook received successfully ' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized - Signature validation failed content: application/json: schema: $ref: '#/components/schemas/Error401' '409': description: Conflict - Webhook has already been processed (duplicate id) content: application/json: schema: $ref: '#/components/schemas/Error409' servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server card-pin-status-change: post: summary: Card PIN status change description: 'Sent when Grid records a change to a card''s PIN status, including changes detected after a hosted PIN submission, an API request, or a PIN becoming blocked. The data contains the updated Card resource and its new pinStatus. Initial card creation does not trigger this event. Changing an existing PIN while its status remains OK does not trigger it either; use the submission result to confirm that the PIN changed. Changes made outside the Grid API are detected asynchronously. The event describes the status Grid observed, not every intermediate PIN status. Delivery can be repeated or arrive out of order. Deduplicate by id and use data.updatedAt to avoid replacing newer card data with an older snapshot. Read pinStatus from GET /cards/{id} to retrieve the card''s saved status. Verify the X-Grid-Signature header using your Grid webhook public key, as for other Grid webhooks. No PIN, encrypted PIN block, or PIN-entry session credential is included.' operationId: cardPinStatusChangeWebhook tags: - Webhooks security: - WebhookSignature: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CardPinStatusChangeWebhook' examples: blocked: summary: The card PIN became blocked value: id: Webhook:019542f5-b3e7-1d02-0000-000000000023 type: CARD.PIN_STATUS_CHANGE timestamp: '2026-05-09T10:00:00Z' data: id: Card:019542f5-b3e7-1d02-0000-000000000010 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 status: ACTIVE pinStatus: BLOCKED brand: VISA form: VIRTUAL last4: '4242' expMonth: 12 expYear: 2029 fundingSource: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 maxSpendPerTransaction: null maxSpendPerDay: null maxTransactionsPerDay: null currency: USD createdAt: '2026-05-08T14:10:00Z' updatedAt: '2026-05-09T10:00:00Z' responses: '200': description: Webhook received successfully '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized - Signature validation failed content: application/json: schema: $ref: '#/components/schemas/Error401' '409': description: Conflict - Webhook has already been processed (duplicate id) content: application/json: schema: $ref: '#/components/schemas/Error409' servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server card-transaction: post: summary: Card transaction description: 'Webhook that is called on every lifecycle update of a card `CardTransaction`. Fires when an authorization is approved (`CARD_TRANSACTION.AUTHORIZED`), as clearings settle against it (`CARD_TRANSACTION.PARTIALLY_SETTLED`, `CARD_TRANSACTION.SETTLED`), when the authorization is declined (`CARD_TRANSACTION.DECLINED`), when an authorization is fully reversed or expires (`CARD_TRANSACTION.VOIDED`), and when a transaction settles to the card network but the funding-source pull fails (`CARD_TRANSACTION.EXCEPTION`). The payload carries the full `CardTransaction` resource. A merchant return is its own `CardTransaction` row (`direction: CREDIT`) linked to the purchase via `originalTransactionId`, and fires its own `CARD_TRANSACTION.*` deliveries on that row — the purchase row is not re-fired for the return. This endpoint should be implemented by clients of the Grid API. ### Authentication The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid. To verify the signature: 1. Get the Grid public key provided to you during integration 2. Decode the base64 signature from the header 3. Create a SHA-256 hash of the request body 4. Verify the signature using the public key and the hash If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.' operationId: cardTransactionWebhook tags: - Webhooks security: - WebhookSignature: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CardTransactionWebhook' examples: authorized: summary: Authorization approved value: id: Webhook:019542f5-b3e7-1d02-0000-000000000040 type: CARD_TRANSACTION.AUTHORIZED timestamp: '2026-05-09T10:00:00Z' data: type: CARD id: Transaction:019542f5-b3e7-1d02-0000-000000000100 cardId: Card:019542f5-b3e7-1d02-0000-000000000010 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 issuerTransactionToken: lithic_txn_b81c2a4f status: AUTHORIZED direction: DEBIT description: BLUE BOTTLE COFFEE SF merchant: descriptor: BLUE BOTTLE COFFEE SF mcc: '5814' country: US authorizedAmount: amount: 12550 currency: code: USD name: United States Dollar symbol: $ decimals: 2 accountId: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 authorizedAt: '2026-05-09T10:00:00Z' createdAt: '2026-05-09T10:00:00Z' updatedAt: '2026-05-09T10:00:00Z' settled: summary: All clearings posted value: id: Webhook:019542f5-b3e7-1d02-0000-000000000041 type: CARD_TRANSACTION.SETTLED timestamp: '2026-05-09T15:42:11Z' data: type: CARD id: Transaction:019542f5-b3e7-1d02-0000-000000000100 cardId: Card:019542f5-b3e7-1d02-0000-000000000010 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 issuerTransactionToken: lithic_txn_b81c2a4f status: SETTLED direction: DEBIT description: BLUE BOTTLE COFFEE SF merchant: descriptor: BLUE BOTTLE COFFEE SF mcc: '5814' country: US authorizedAmount: amount: 12550 currency: code: USD name: United States Dollar symbol: $ decimals: 2 settledAmount: amount: 12550 currency: code: USD name: United States Dollar symbol: $ decimals: 2 accountId: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 authorizedAt: '2026-05-09T10:00:00Z' createdAt: '2026-05-09T10:00:00Z' updatedAt: '2026-05-09T15:42:11Z' returned: summary: Merchant return posted as its own CREDIT row value: id: Webhook:019542f5-b3e7-1d02-0000-000000000042 type: CARD_TRANSACTION.SETTLED timestamp: '2026-05-10T09:15:00Z' data: type: CARD id: Transaction:019542f5-b3e7-1d02-0000-000000000105 cardId: Card:019542f5-b3e7-1d02-0000-000000000010 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 issuerTransactionToken: lithic_txn_r55e8c1d status: SETTLED direction: CREDIT originalTransactionId: Transaction:019542f5-b3e7-1d02-0000-000000000100 description: BLUE BOTTLE COFFEE SF merchant: descriptor: BLUE BOTTLE COFFEE SF mcc: '5814' country: US authorizedAmount: amount: 12550 currency: code: USD name: United States Dollar symbol: $ decimals: 2 settledAmount: amount: 12550 currency: code: USD name: United States Dollar symbol: $ decimals: 2 accountId: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 authorizedAt: '2026-05-10T09:15:00Z' createdAt: '2026-05-10T09:15:00Z' updatedAt: '2026-05-10T09:15:00Z' declined: summary: Authorization declined for insufficient funds value: id: Webhook:019542f5-b3e7-1d02-0000-000000000044 type: CARD_TRANSACTION.DECLINED timestamp: '2026-05-09T16:10:00Z' data: type: CARD id: Transaction:019542f5-b3e7-1d02-0000-000000000102 cardId: Card:019542f5-b3e7-1d02-0000-000000000010 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 issuerTransactionToken: lithic_txn_d41a7f02 status: DECLINED cardDeclinedReason: INSUFFICIENT_FUNDS direction: DEBIT description: UBER EATS merchant: descriptor: UBER EATS mcc: '5812' country: US authorizedAmount: amount: 4200 currency: code: USD name: United States Dollar symbol: $ decimals: 2 accountId: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 authorizedAt: '2026-05-09T16:10:00Z' createdAt: '2026-05-09T16:10:00Z' updatedAt: '2026-05-09T16:10:00Z' voided: summary: Authorization fully reversed before clearing value: id: Webhook:019542f5-b3e7-1d02-0000-000000000045 type: CARD_TRANSACTION.VOIDED timestamp: '2026-05-09T16:20:00Z' data: type: CARD id: Transaction:019542f5-b3e7-1d02-0000-000000000103 cardId: Card:019542f5-b3e7-1d02-0000-000000000010 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 issuerTransactionToken: lithic_txn_e52b8c13 status: VOIDED direction: DEBIT description: HOTEL AUTHORIZATION merchant: descriptor: HOTEL AUTHORIZATION mcc: '7011' country: US authorizedAmount: amount: 0 currency: code: USD name: United States Dollar symbol: $ decimals: 2 accountId: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 authorizedAt: '2026-05-09T15:50:00Z' createdAt: '2026-05-09T15:50:00Z' updatedAt: '2026-05-09T16:20:00Z' exception: summary: Settled to the network but the funding-source pull failed value: id: Webhook:019542f5-b3e7-1d02-0000-000000000043 type: CARD_TRANSACTION.EXCEPTION timestamp: '2026-05-09T16:05:00Z' data: type: CARD id: Transaction:019542f5-b3e7-1d02-0000-000000000101 cardId: Card:019542f5-b3e7-1d02-0000-000000000010 customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 issuerTransactionToken: lithic_txn_c92d3b5a status: EXCEPTION direction: DEBIT description: UBER EATS merchant: descriptor: UBER EATS mcc: '5812' country: US authorizedAmount: amount: 4200 currency: code: USD name: United States Dollar symbol: $ decimals: 2 settledAmount: amount: 4200 currency: code: USD name: United States Dollar symbol: $ decimals: 2 accountId: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 authorizedAt: '2026-05-09T15:30:00Z' createdAt: '2026-05-09T15:30:00Z' updatedAt: '2026-05-09T16:05:00Z' responses: '200': description: 'Webhook received successfully ' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized - Signature validation failed content: application/json: schema: $ref: '#/components/schemas/Error401' '409': description: Conflict - Webhook has already been processed (duplicate id) content: application/json: schema: $ref: '#/components/schemas/Error409' servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server wallet-operation: post: summary: Wallet operation completed or failed description: 'Webhook that is called when an asynchronous embedded-wallet operation reaches a terminal state. Fires `WALLET_OPERATION.COMPLETED` on terminal success and `WALLET_OPERATION.FAILED` on terminal failure. The payload is self-contained — handle it from the fields below with no follow-up API call needed. The specific operation is carried in `data.operationType` (`auth_credential.create`, `auth_credential.delete`, `session.revoke`, `wallet.export`, or `customer.contact_update`), and the business resource it affected is carried in `data.resourceType` / `data.resourceId`: | `operationType` | `resourceType` | `resourceId` identifies | | --- | --- | --- | | `auth_credential.create` | `AUTH_METHOD` | the created credential — its id can''t be known before this webhook, since the create request has nothing to echo | | `auth_credential.delete` | `AUTH_METHOD` | the deleted credential | | `session.revoke` | `SESSION` | the revoked session | | `wallet.export` | `INTERNAL_ACCOUNT` | the account whose wallet was exported | | `customer.contact_update` | `CUSTOMER` | the customer whose email or phone number changed | The webhook carries no sensitive result material — for `wallet.export`, the export bundle itself is never delivered here; retrieve it by resubmitting the original signed export request until it returns the result. ### Correlating this webhook - **`data.requestId`** is the primary correlation key. It is the same `Request-Id` value you supplied on the signed retry that produced this terminal result — echo it against the `Request-Id` you sent (and, if you polled through one or more `200 { status: "PROCESSING" }` responses, against the value you kept resending). - **`data.resourceId`** is the primary correlator for the *business resource* itself, distinct from `requestId`''s role of matching the request. For `auth_credential.create` this is the only way to learn the created credential''s id — the request that created it had nothing to echo. - **`id`** (the top-level webhook envelope id) is for deduplication. Grid may redeliver a webhook after a transient failure; track `id` to avoid double-processing. - **`data.operationId`** is a Grid-internal identifier for the operation. It''s useful when contacting support about a specific operation, but isn''t intended as a correlation key. This endpoint should be implemented by clients of the Grid API. ### Authentication The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid. To verify the signature: 1. Get the Grid public key provided to you during integration 2. Decode the base64 signature from the header 3. Create a SHA-256 hash of the request body 4. Verify the signature using the public key and the hash If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.' operationId: walletOperationWebhook tags: - Webhooks security: - WebhookSignature: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WalletOperationWebhook' examples: completed: summary: Wallet export completed value: id: Webhook:019542f5-b3e7-1d02-0000-000000000040 type: WALLET_OPERATION.COMPLETED timestamp: '2026-06-08T14:31:00Z' data: operationId: Operation:019542f5-b3e7-1d02-0000-000000000099 requestId: Request:9f7a2c10-5e88-4fb1-bd0e-1c3a8e7b2d45 operationType: wallet.export resourceType: INTERNAL_ACCOUNT resourceId: InternalAccount:019542f5-b3e7-1d02-0000-000000000005 status: completed failed: summary: Session revoke failed terminally value: id: Webhook:019542f5-b3e7-1d02-0000-000000000041 type: WALLET_OPERATION.FAILED timestamp: '2026-06-08T14:32:00Z' data: operationId: Operation:019542f5-b3e7-1d02-0000-00000000009a requestId: Request:3c1e5a2f-8b44-4d7a-9e10-6f2b8c4d1a90 operationType: session.revoke resourceType: SESSION resourceId: Session:019542f5-b3e7-1d02-0000-00000000009a status: failed error: code: SIGNER_PROVIDER_REJECTED contactUpdateCompleted: summary: Customer contact change completed value: id: Webhook:019542f5-b3e7-1d02-0000-000000000042 type: WALLET_OPERATION.COMPLETED timestamp: '2026-06-08T14:33:00Z' data: operationId: Operation:019542f5-b3e7-1d02-0000-00000000009b requestId: Request:019542f5-b3e7-1d02-0000-000000000010 operationType: customer.contact_update resourceType: CUSTOMER resourceId: Customer:019542f5-b3e7-1d02-0000-000000000001 status: completed responses: '200': description: Webhook received successfully '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized - Signature validation failed content: application/json: schema: $ref: '#/components/schemas/Error401' '409': description: Conflict - Webhook has already been processed (duplicate id) content: application/json: schema: $ref: '#/components/schemas/Error409' servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server card-state-change: post: summary: Card state change description: 'Webhook that is called when a card''s lifecycle state changes. Fires on `PROCESSING → ACTIVE`, on `PROCESSING → CLOSED (ISSUER_REJECTED)` when issuer provisioning fails, and on every subsequent `ACTIVE ⇄ FROZEN` and `→ CLOSED` transition. This endpoint should be implemented by clients of the Grid API. ### Authentication The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid. To verify the signature: 1. Get the Grid public key provided to you during integration 2. Decode the base64 signature from the header 3. Create a SHA-256 hash of the request body 4. Verify the signature using the public key and the hash If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.' operationId: cardStateChangeWebhook tags: - Webhooks security: - WebhookSignature: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CardStateChangeWebhook' examples: activated: summary: Card transitioned from PROCESSING to ACTIVE value: id: Webhook:019542f5-b3e7-1d02-0000-000000000020 type: CARD.STATE_CHANGE timestamp: '2026-05-08T14:11:00Z' data: id: Card:019542f5-b3e7-1d02-0000-000000000010 cardholderId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCardId: card-emp-aary-001 state: ACTIVE stateReason: null brand: VISA form: VIRTUAL last4: '4242' expMonth: 12 expYear: 2029 fundingSources: - InternalAccount:019542f5-b3e7-1d02-0000-000000000002 currency: USD processorRef: card_b81c2a4f issuerRef: lead_card_7a1b9c3d createdAt: '2026-05-08T14:10:00Z' updatedAt: '2026-05-08T14:11:00Z' issuerRejected: summary: Card rejected by issuer during provisioning value: id: Webhook:019542f5-b3e7-1d02-0000-000000000021 type: CARD.STATE_CHANGE timestamp: '2026-05-08T14:12:00Z' data: id: Card:019542f5-b3e7-1d02-0000-000000000011 cardholderId: Customer:019542f5-b3e7-1d02-0000-000000000001 state: CLOSED stateReason: ISSUER_REJECTED form: VIRTUAL fundingSources: - InternalAccount:019542f5-b3e7-1d02-0000-000000000002 currency: USD createdAt: '2026-05-08T14:10:00Z' updatedAt: '2026-05-08T14:12:00Z' frozen: summary: Card frozen by the platform value: id: Webhook:019542f5-b3e7-1d02-0000-000000000022 type: CARD.STATE_CHANGE timestamp: '2026-05-09T09:00:00Z' data: id: Card:019542f5-b3e7-1d02-0000-000000000010 cardholderId: Customer:019542f5-b3e7-1d02-0000-000000000001 state: FROZEN stateReason: null brand: VISA form: VIRTUAL last4: '4242' expMonth: 12 expYear: 2029 fundingSources: - InternalAccount:019542f5-b3e7-1d02-0000-000000000002 currency: USD createdAt: '2026-05-08T14:10:00Z' updatedAt: '2026-05-09T09:00:00Z' responses: '200': description: 'Webhook received successfully ' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error400_2' '401': description: Unauthorized - Signature validation failed content: application/json: schema: $ref: '#/components/schemas/Error401_2' '409': description: Conflict - Webhook has already been processed (duplicate id) content: application/json: schema: $ref: '#/components/schemas/Error409_2' servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server card-funding-source-change: post: summary: Card funding source change description: 'Webhook that is called when the funding sources bound to a card change. Fires whenever `PATCH /cards/{id}` updates the `fundingSources` array. The payload carries the full `Card` resource with the post-change `fundingSources` array. This endpoint should be implemented by clients of the Grid API. ### Authentication The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid. To verify the signature: 1. Get the Grid public key provided to you during integration 2. Decode the base64 signature from the header 3. Create a SHA-256 hash of the request body 4. Verify the signature using the public key and the hash If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.' operationId: cardFundingSourceChangeWebhook tags: - Webhooks security: - WebhookSignature: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CardFundingSourceChangeWebhook' examples: fundingSourcesReplaced: summary: Funding sources replaced via PATCH /cards/{id} value: id: Webhook:019542f5-b3e7-1d02-0000-000000000030 type: CARD.FUNDING_SOURCE_CHANGE timestamp: '2026-05-08T14:30:00Z' data: id: Card:019542f5-b3e7-1d02-0000-000000000010 cardholderId: Customer:019542f5-b3e7-1d02-0000-000000000001 state: ACTIVE stateReason: null brand: VISA form: VIRTUAL last4: '4242' expMonth: 12 expYear: 2029 fundingSources: - InternalAccount:019542f5-b3e7-1d02-0000-000000000002 - InternalAccount:019542f5-b3e7-1d02-0000-000000000003 currency: USD createdAt: '2026-05-08T14:10:00Z' updatedAt: '2026-05-08T14:30:00Z' responses: '200': description: 'Webhook received successfully ' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error400_2' '401': description: Unauthorized - Signature validation failed content: application/json: schema: $ref: '#/components/schemas/Error401_2' '409': description: Conflict - Webhook has already been processed (duplicate id) content: application/json: schema: $ref: '#/components/schemas/Error409_2' servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server components: schemas: UmaInvitationStatus: type: string enum: - PENDING - CLAIMED - EXPIRED - CANCELLED description: The status of the invitation example: PENDING SwiftAccountInfoBase: type: object description: 'At least one of accountNumber or iban is always present: IBAN-only corridors (e.g. BR, GB) use iban, other corridors use accountNumber, and both appear when the bank exposes both identifiers for the same account.' required: - accountType - swiftCode - bankName - country properties: accountType: type: string enum: - SWIFT_ACCOUNT country: type: string description: The ISO 3166-1 alpha-2 country code of the bank account example: NG minLength: 2 maxLength: 2 pattern: ^[A-Z]{2}$ swiftCode: type: string description: The SWIFT/BIC code of the bank example: DEUTDEFF minLength: 8 maxLength: 11 pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$ bankName: type: string description: The name of the bank example: Deutsche Bank minLength: 1 maxLength: 255 accountNumber: type: string description: The bank account number. Required for most corridors. Use iban instead for IBAN-only corridors (e.g. BR, GB). example: '1234567890' minLength: 1 maxLength: 34 iban: type: string description: The IBAN of the bank account. Required for IBAN-only corridors (e.g. BR, GB). Use accountNumber for all other corridors. example: GB29NWBK60161331926819 minLength: 15 maxLength: 34 pattern: ^[A-Z]{2}[0-9]{2}[A-Za-z0-9]{11,30}$ example: accountType: SWIFT_ACCOUNT country: NG swiftCode: DEUTDEFF bankName: Deutsche Bank accountNumber: '1234567890' CounterpartyFieldDefinition: type: object properties: name: $ref: '#/components/schemas/CustomerInfoFieldName' mandatory: type: boolean description: Whether the field is mandatory example: true required: - name - mandatory PurposeOfPayment: type: string description: 'The purpose of the payment. This may be required when sending to certain geographies (e.g. India). Some destinations accept only certain purposes. A business payout to China must use one of the purposes listed in [Supporting Documents](https://docs.lightspark.com/payouts-and-b2b/payment-flow/send-payment#supporting-documents), and each needs its own supporting documents.' enum: - GIFT - SELF - GOODS_OR_SERVICES - EDUCATION - HEALTH_OR_MEDICAL - REAL_ESTATE_PURCHASE - TAX_PAYMENT - LOAN_PAYMENT - UTILITY_BILL - DONATION - TRAVEL - FAMILY_SUPPORT - SALARY_PAYMENT - EXPORTED_GOODS_PREPAYMENT - EXPORTED_GOODS_POSTPAYMENT - SERVICE_CHARGES - OFFICE_EXPENSES - DELIVERY_FEES - HOTEL_ACCOMMODATION - COMMISSION_ON_GOODS - COMMISSION_ON_SERVICES - ACCOUNTING_SERVICES - EXHIBITION_SERVICES - OTHER BdtExternalAccountInfo: title: BDT Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/BdtAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/BdtBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/BusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/BdtBeneficiary' BUSINESS: '#/components/schemas/BusinessBeneficiary' KesAccountInfoBase: type: object required: - accountType - phoneNumber - provider properties: accountType: type: string enum: - KES_ACCOUNT phoneNumber: type: string description: Kenyan mobile money phone number example: '+254712345678' minLength: 7 maxLength: 15 pattern: ^\+254[0-9]{9}$ provider: type: string description: The mobile money provider name minLength: 1 maxLength: 255 example: accountType: KES_ACCOUNT phoneNumber: '+254712345678' provider: Example Provider BusinessCustomer: title: Business Customer allOf: - $ref: '#/components/schemas/Customer' - $ref: '#/components/schemas/BusinessCustomerFields' - type: object properties: businessInfo: $ref: '#/components/schemas/BusinessInfoResponse' beneficialOwners: type: array items: $ref: '#/components/schemas/BeneficialOwner' IlsBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - address - legalName properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' GhsAccountInfoBase: type: object required: - accountType - bankName description: 'Required fields depend on the selected paymentRails: - BANK_TRANSFER: accountNumber, bankName - MOBILE_MONEY: bankName, phoneNumber' properties: accountType: type: string enum: - GHS_ACCOUNT accountNumber: type: string description: The account number of the bank minLength: 1 maxLength: 34 bankName: type: string description: The name of the bank. Must be one of the `bankName` values `GET /discoveries` returns for this country and currency. Send it exactly as returned; any other name is rejected. minLength: 1 maxLength: 255 example: Gcb Bank Ltd phoneNumber: type: string description: The phone number in international format example: '+1234567890' minLength: 7 maxLength: 15 pattern: ^\+[0-9]{6,14}$ example: accountType: GHS_ACCOUNT accountNumber: '1234567890' bankName: Gcb Bank Ltd phoneNumber: '+1234567890' XafAccountInfoBase: type: object required: - accountType - phoneNumber - provider - region properties: accountType: type: string enum: - XAF_ACCOUNT phoneNumber: type: string description: The phone number in international format example: '+1234567890' minLength: 7 maxLength: 15 pattern: ^\+[0-9]{6,14}$ provider: type: string description: The mobile money provider name minLength: 1 maxLength: 255 region: type: string description: Country code within the Central African CFA franc zone minLength: 2 maxLength: 2 pattern: ^[A-Z]{2}$ enum: - CM - CG example: accountType: XAF_ACCOUNT phoneNumber: '+1234567890' provider: Example Provider region: CM UsdBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' EurBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - countryOfResidence - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' GtqExternalAccountInfo: title: GTQ Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/GtqAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/GtqBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/BusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/GtqBeneficiary' BUSINESS: '#/components/schemas/BusinessBeneficiary' DkkExternalAccountInfo: title: DKK Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/DkkAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/DkkBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/DkkBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/DkkBeneficiary' BUSINESS: '#/components/schemas/DkkBusinessBeneficiary' PaymentBrlAccountInfo: title: BRL Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - type: object required: - qrCode properties: accountType: type: string enum: - BRL_ACCOUNT qrCode: type: string description: A PIX QR code payload that can be used to fund the transaction. This can be rendered as a QR code image or pasted into a PIX-compatible banking app. minLength: 1 DkkAccountInfo: allOf: - $ref: '#/components/schemas/DkkAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - SEPA - SEPA_INSTANT TransactionDirection: type: string enum: - CREDIT - DEBIT description: 'Whether the transaction credits (funds in) or debits (funds out) the customer''s account. Independent of `type`: an incoming transaction is normally a `CREDIT`, but an inbound ACH pull, for example, is an `INCOMING` transaction with a `DEBIT` direction.' RwfAccountInfoBase: type: object required: - accountType - phoneNumber - provider properties: accountType: type: string enum: - RWF_ACCOUNT phoneNumber: type: string description: Rwandan mobile money phone number example: '+250781234567' minLength: 7 maxLength: 15 pattern: ^\+250[0-9]{9}$ provider: type: string description: The mobile money provider name minLength: 1 maxLength: 255 example: accountType: RWF_ACCOUNT phoneNumber: '+250781234567' provider: Example Provider AgreementConsent: allOf: - $ref: '#/components/schemas/AgreementConsentRequest' ArbitrumWalletExternalAccountInfo: title: Arbitrum Wallet allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/ArbitrumWalletInfo' - $ref: '#/components/schemas/WalletBeneficiaryFields' - $ref: '#/components/schemas/WalletCustodyFields' SlvBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' BulkCustomerImportJobStatus: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED description: Current status of the job example: PROCESSING InvitationClaimedWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/UmaInvitation' type: type: string enum: - INVITATION.CLAIMED UsdAccountInfoBase: type: object required: - accountType - accountNumber - routingNumber properties: accountType: type: string enum: - USD_ACCOUNT accountNumber: type: string description: The account number of the bank minLength: 1 maxLength: 34 routingNumber: type: string description: The ABA routing number example: '021000021' minLength: 9 maxLength: 9 pattern: ^[0-9]{9}$ bankName: type: string description: The name of the financial institution holding the account. Optional on every rail, and recommended for wires, where it identifies the beneficiary's institution on the payment message. Not checked against `GET /discoveries`. minLength: 1 maxLength: 140 example: Chase Bank intermediaryBankName: type: string description: The name of the intermediary financial institution, for accounts reachable only through a correspondent bank. Used on the WIRE rail; ignored on ACH, RTP and FEDNOW. example: JPMorgan Chase Bank minLength: 1 maxLength: 140 intermediaryRoutingNumber: type: string description: The ABA routing number of the intermediary financial institution. Used on the WIRE rail; ignored on ACH, RTP and FEDNOW. example: '021000021' minLength: 9 maxLength: 9 pattern: ^[0-9]{9}$ fiToFiInformation: type: string description: Bank-to-bank instructions carried alongside the payment. Used on the WIRE rail; ignored on ACH, RTP and FEDNOW. example: /BNF/Invoice 4471 maxLength: 210 example: accountType: USD_ACCOUNT accountNumber: '1234567890' routingNumber: '021000021' bankName: Chase Bank intermediaryBankName: JPMorgan Chase Bank intermediaryRoutingNumber: '021000021' fiToFiInformation: /BNF/Invoice 4471 bankAccountType: CHECKING JmdAccountInfoBase: type: object required: - accountType - accountNumber - branchCode - bankAccountType - bankName properties: accountType: type: string enum: - JMD_ACCOUNT accountNumber: type: string description: The account number of the bank minLength: 1 maxLength: 34 branchCode: type: string description: The branch code minLength: 5 maxLength: 5 pattern: ^[0-9]{5}$ bankAccountType: type: string description: The bank account type enum: - CHECKING - SAVINGS bankName: type: string description: The name of the bank. Must be one of the `bankName` values `GET /discoveries` returns for this country and currency. Send it exactly as returned; any other name is rejected. minLength: 1 maxLength: 255 example: National Commercial Bank Ja Ltd example: accountType: JMD_ACCOUNT accountNumber: '1234567890' branchCode: '11111' bankAccountType: CHECKING bankName: National Commercial Bank Ja Ltd IndividualCustomer: title: Individual Customer allOf: - $ref: '#/components/schemas/Customer' - $ref: '#/components/schemas/IndividualCustomerFields' BusinessInfoUpdate: type: object description: Additional information for business entities properties: legalName: type: string maxLength: 250 description: Legal name of the business example: Acme Corporation, Inc. doingBusinessAs: type: string maxLength: 250 description: Trade name or DBA name of the business, if different from the legal name example: Acme country: type: string description: Country of incorporation or registration (ISO 3166-1 alpha-2) example: US registrationNumber: type: string maxLength: 100 description: Business registration number example: '5523041' incorporatedOn: type: string format: date description: Date of incorporation in ISO 8601 format (YYYY-MM-DD) example: '2018-03-14' entityType: $ref: '#/components/schemas/EntityType' taxId: type: string maxLength: 100 description: Tax identification number example: 47-1234567 countriesOfOperation: type: array items: type: string description: List of countries where the business operates (ISO 3166-1 alpha-2) example: - US businessType: $ref: '#/components/schemas/BusinessType' purposeOfAccount: $ref: '#/components/schemas/PurposeOfAccount' sourceOfFunds: type: string maxLength: 500 description: The primary source of funds for the business example: Funds derived from customer payments for software services expectedMonthlyTransactionCount: $ref: '#/components/schemas/ExpectedMonthlyTransactionCount' expectedMonthlyTransactionVolume: $ref: '#/components/schemas/ExpectedMonthlyTransactionVolume' expectedRecipientJurisdictions: type: array items: type: string description: List of countries where the business expects to send payments (ISO 3166-1 alpha-2) example: - US naicsCode: type: string pattern: ^\d{2,6}$ description: NAICS code describing the nature of the business (2-6 digits) example: '541511' sourceOfFundsCategories: type: array items: $ref: '#/components/schemas/SourceOfFundsCategory' description: Structured source-of-funds categories for the business example: - OPERATING_REVENUE sourceOfFundsOtherDescription: type: string minLength: 1 maxLength: 500 description: Description of the source of funds when OTHER is selected example: Proceeds from a legal settlement purposeOfAccountOtherDescription: type: string minLength: 1 maxLength: 500 description: Description of the account purpose when OTHER is selected example: Escrow for equipment leases expectedCounterpartyCountries: type: array items: type: string description: List of countries of the business's expected transaction counterparties (ISO 3166-1 alpha-2) example: - US primaryContactFirstName: type: string maxLength: 250 description: First name of the business's primary contact — a registered director or authorised representative of the business. Required in regions where a named individual is verified against the business during onboarding (e.g. the EU). The customer's `email` and `phoneNumber` are this person's contact details. example: Jane primaryContactLastName: type: string maxLength: 250 description: Last name of the business's primary contact. example: Smith CnyBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' IdrAccountInfoBase: type: object required: - accountType - bankName - accountNumber - swiftCode - phoneNumber properties: accountType: type: string enum: - IDR_ACCOUNT bankName: type: string description: The name of the bank. Must be one of the `bankName` values `GET /discoveries` returns for this country and currency. Send it exactly as returned; any other name is rejected. minLength: 1 maxLength: 255 example: Bank Central Asia (BCA) accountNumber: type: string description: Indonesian bank account number minLength: 1 maxLength: 34 example: '1234567890' swiftCode: type: string description: The SWIFT/BIC code of the bank example: CENAIDJA minLength: 8 maxLength: 11 pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$ phoneNumber: type: string description: Indonesian phone number for e-wallet payments example: '+6281234567890' minLength: 7 maxLength: 15 pattern: ^\+62[0-9]{9,12}$ example: accountType: IDR_ACCOUNT bankName: Bank Central Asia (BCA) accountNumber: '1234567890' swiftCode: CENAIDJA phoneNumber: '+6281234567890' IdrBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' GbpAccountInfo: allOf: - $ref: '#/components/schemas/GbpAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - FASTER_PAYMENTS IlsAccountInfo: allOf: - $ref: '#/components/schemas/IlsAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER ThbAccountInfo: allOf: - $ref: '#/components/schemas/ThbAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER CardTransaction: title: Card Transaction type: object required: - type - id - status - direction - merchant - authorizedAmount - accountId - customerId - platformCustomerId - authorizedAt - createdAt - updatedAt description: One row per cardholder-visible card transaction. A purchase row rolls its clearings up into `settledAmount`; a merchant return is its own dated `CREDIT` row linked back to the purchase via `originalTransactionId` rather than a rollup on the parent, so statements can list purchases and refunds as separate dated lines. Delivered whole as the `data` payload of every `CARD_TRANSACTION.*` webhook, and returned as the `CARD` variant of `Transaction` from `GET /transactions`. properties: type: type: string enum: - CARD description: Discriminator identifying this transaction as a card transaction in the `Transaction` list. id: type: string description: System-generated unique card transaction identifier example: Transaction:019542f5-b3e7-1d02-0000-000000000100 cardId: type: string description: The id of the `Card` this transaction was made on. example: Card:019542f5-b3e7-1d02-0000-000000000010 customerId: type: string description: System ID of the customer (cardholder) this transaction belongs to. example: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: type: string description: Platform-specific ID of the customer (cardholder) this transaction belongs to. example: 18d3e5f7b4a9c2 issuerTransactionToken: type: string description: Opaque identifier for the transaction on the underlying issuer. Used to cross-reference Grid records against issuer dashboards and webhooks. example: lithic_txn_b81c2a4f status: $ref: '#/components/schemas/CardTransactionStatus' cardDeclinedReason: $ref: '#/components/schemas/CardDeclinedReason' description: Present only when `status` is `DECLINED`. example: INSUFFICIENT_FUNDS direction: $ref: '#/components/schemas/TransactionDirection' description: A purchase is a `DEBIT`. A merchant refund is a `CREDIT` with the credited value in `settledAmount`; when the refund returns against a known purchase, `originalTransactionId` identifies it. example: DEBIT originalTransactionId: type: string description: 'On a refund row (`direction: CREDIT`), the id of the purchase this return credits back against. Absent on purchases and on standalone credits with no matching purchase.' example: Transaction:019542f5-b3e7-1d02-0000-000000000099 description: type: string description: The merchant descriptor, repeated from `merchant.descriptor` so a transaction list reads without expanding each card row. Unlike `description` on other transaction types, this is set by Grid from the card network's descriptor, not supplied by the platform. example: BLUE BOTTLE COFFEE SF merchant: $ref: '#/components/schemas/CardMerchant' authorizedAmount: $ref: '#/components/schemas/CurrencyAmount' settledAmount: $ref: '#/components/schemas/CurrencyAmount' refundedAmount: $ref: '#/components/schemas/CurrencyAmount' accountId: type: string description: Internal account id that funded this transaction (the funding source selected by Authorization Decisioning at auth time). example: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 authorizedAt: type: string format: date-time description: When the authorization was approved or declined. example: '2026-05-08T14:30:00Z' createdAt: type: string format: date-time description: Creation timestamp (same as `authorizedAt` for card transactions). example: '2026-05-08T14:30:00Z' updatedAt: type: string format: date-time description: Last update timestamp. example: '2026-05-08T15:42:11Z' ZarAccountInfoBase: type: object required: - accountType - accountNumber - bankName properties: accountType: type: string enum: - ZAR_ACCOUNT accountNumber: type: string description: South African bank account number minLength: 9 maxLength: 13 example: '1234567890' pattern: ^[0-9]{9,13}$ bankName: type: string description: The name of the bank. Must be one of the `bankName` values `GET /discoveries` returns for this country and currency. Send it exactly as returned; any other name is rejected. minLength: 1 maxLength: 255 example: Standard Bank (South Africa) example: accountType: ZAR_ACCOUNT accountNumber: '1234567890' bankName: Standard Bank (South Africa) PaymentSolanaWalletInfo: title: Solana Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/SolanaWalletInfo' - type: object properties: assetType: $ref: '#/components/schemas/StablecoinAssetType' EntityType: type: string enum: - SOLE_PROPRIETORSHIP - PARTNERSHIP - LLC - CORPORATION - S_CORPORATION - NON_PROFIT - PUBLICLY_LISTED_COMPANY - TRUST - PRIVATE_FOUNDATION - CHARITY - OTHER description: Legal entity type of the business example: LLC CardStatusChangeWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/Card' type: type: string enum: - CARD.STATUS_CHANGE PhpAccountInfo: allOf: - $ref: '#/components/schemas/PhpAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER AchRailStatus: type: string enum: - PENDING - SETTLED - RETURNED - RETURN_DISHONORED - RETURN_CONTESTED - REVERSED - FAILED description: 'Status of the entry on the ACH network. | Status | Description | |--------|-------------| | `PENDING` | Submitted to the ACH network and not yet settled. | | `SETTLED` | The entry settled. | | `RETURNED` | The receiving bank returned the entry, before or after it settled. | | `RETURN_DISHONORED` | The originating bank dishonored the return, so the returned funds came back. | | `RETURN_CONTESTED` | The receiving bank contested the dishonor, so the funds went back again. | | `REVERSED` | The originator reversed the entry after it settled. | | `FAILED` | The entry was rejected before submission and no funds moved. | A return, dishonor or contest can arrive days after the step before it. This status reports the ACH entry; the transaction''s top-level `status` reports where the funds are now. A return moves the transaction to `FAILED`. On an incoming payment, a dishonor brings the credit back and moves it to `COMPLETED`, and a contest moves it to `FAILED` again. A returned payout stays `FAILED` through a dishonor, since it has already been refunded; the rail status still records the dishonor.' example: SETTLED Quote: type: object required: - id - status - expiresAt - createdAt - source - destination - sendingCurrency - receivingCurrency - totalSendingAmount - totalReceivingAmount - exchangeRate - feesIncluded - transactionId properties: id: type: string description: Unique identifier for this quote example: Quote:019542f5-b3e7-1d02-0000-000000000006 status: $ref: '#/components/schemas/QuoteStatus' createdAt: type: string format: date-time description: When this quote was created example: '2025-10-03T12:00:00Z' expiresAt: type: string format: date-time description: 'Absolute UTC timestamp when the rate locked in this quote becomes invalid and the quote can no longer be executed. The window depends on the rail and corridor: instant rails (Lightning, Spark, USDC on Solana/Base/Polygon, RTP, SEPA Instant) typically expire in 1–5 minutes; corridors with longer settlement guarantees may have longer windows. Always rely on this timestamp rather than assuming a fixed window.' example: '2025-10-03T12:05:00Z' source: $ref: '#/components/schemas/QuoteSourceOneOf' destination: $ref: '#/components/schemas/QuoteDestinationOneOf' sendingCurrency: $ref: '#/components/schemas/Currency' description: Currency for the sending amount receivingCurrency: $ref: '#/components/schemas/Currency' description: Currency for the receiving amount totalSendingAmount: type: integer format: int64 description: The total amount that will be sent in the smallest unit of the sending currency (eg. cents). exclusiveMinimum: 0 example: 123010 totalReceivingAmount: type: integer format: int64 description: The total amount that will be received in the smallest unit of the receiving currency (eg. cents). exclusiveMinimum: 0 example: 1000 exchangeRate: type: number description: 'Number of sending currency units per receiving currency unit. The rate is fee-exclusive: Grid deducts `feesIncluded` from `totalSendingAmount` first, then converts the remainder at this rate to reach `totalReceivingAmount`.' exclusiveMinimum: 0 feesIncluded: type: integer format: int64 description: 'The fees associated with the quote in the smallest unit of the sending currency (eg. cents). Note: this value may fluctuate between quotes — some underlying fee components are defined in the receiving currency, so their equivalent in the sending currency moves with the FX rate. The fees shown here are locked only for the lifetime of this quote.' minimum: 0 example: 10 platformFeesIncluded: type: integer format: int64 description: The portion of `feesIncluded` collected by the platform (platform-configured transaction fees), in the smallest unit of the sending currency. 0 when the platform has no applicable fee configured. Already included in `feesIncluded`. May be omitted from payloads produced before platform fees existed. minimum: 0 example: 5 paymentInstructions: type: array description: Payment instructions for executing the payment. This is not required when using an internal account source. items: $ref: '#/components/schemas/PaymentInstructions' example: - accountOrWalletInfo: accountType: USD_ACCOUNT paymentRails: - ACH - WIRE accountNumber: '1234567890' routingNumber: '021000021' bankName: Chase Bank reference: UMA-Q12345-REF instructionsNotes: Include reference UMA-Q12345-REF in memo - accountOrWalletInfo: accountType: SPARK_WALLET assetType: BTC address: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu invoice: lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs transactionId: type: string description: The ID of the transaction created from this quote. example: Transaction:019542f5-b3e7-1d02-0000-000000000005 counterpartyInformation: $ref: '#/components/schemas/CounterpartyInformation' description: Additional information about the counterparty, if available and required by the platform in their configuration. rateDetails: $ref: '#/components/schemas/OutgoingRateDetails' description: Details about the rate and fees for the transaction. purposeOfPayment: $ref: '#/components/schemas/PurposeOfPayment' description: The purpose of payment the quote was created with. Present only when the quote request set `purposeOfPayment`. documentIds: type: array description: IDs of the supporting documents attached to the payment behind this quote, as passed in `documentIds` on `POST /quotes`. Present only when the quote was created with `documentIds`. Grid returns such a quote only after it has attached every document. Call `GET /payment-documents/{paymentDocumentId}` for each document's details, such as its `documentType` and its `ATTACHED` status. items: type: string example: - PaymentDocument:019542f5-b3e7-1d02-0000-000000000001 - PaymentDocument:019542f5-b3e7-1d02-0000-000000000002 - PaymentDocument:019542f5-b3e7-1d02-0000-000000000003 scaChallenge: $ref: '#/components/schemas/ScaChallenge' description: 'Present only while `status` is `PENDING_AUTHORIZATION`: the Strong Customer Authentication challenge to satisfy before this quote can be executed (or, for realtime-funding sources, before `paymentInstructions` are issued). Omitted for customers outside SCA-regulated regions (non-EU).' HkdExternalAccountInfo: title: HKD Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/HkdAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/HkdBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/HkdBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/HkdBeneficiary' BUSINESS: '#/components/schemas/HkdBusinessBeneficiary' CnyAccountInfoBase: type: object required: - accountType - bankName description: 'Required fields depend on the selected paymentRails: - BANK_TRANSFER: accountNumber, bankName. Business-to-business only, so the beneficiary must be a business. - MOBILE_MONEY: bankName, phoneNumber. Pays an AliPay or WeChat Pay wallet; bankName selects the wallet.' properties: accountType: type: string enum: - CNY_ACCOUNT accountNumber: type: string description: The account number of the bank minLength: 1 maxLength: 34 bankName: type: string description: The name of the bank. Must be one of the `bankName` values `GET /discoveries` returns for this country and currency. Send it exactly as returned; any other name is rejected. minLength: 1 maxLength: 255 example: China Construction Bank phoneNumber: type: string description: The phone number in international format example: '+1234567890' minLength: 7 maxLength: 15 pattern: ^\+[0-9]{6,14}$ example: accountType: CNY_ACCOUNT accountNumber: '1234567890' bankName: China Construction Bank phoneNumber: '+1234567890' WalletOperationWebhookEventType: type: string enum: - WALLET_OPERATION.COMPLETED - WALLET_OPERATION.FAILED SlvAccountInfo: allOf: - $ref: '#/components/schemas/SlvAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER - MOBILE_MONEY HkdAccountInfoBase: type: object required: - accountType - accountNumber - swiftCode properties: accountType: type: string enum: - HKD_ACCOUNT bankName: type: string description: Name of the beneficiary's bank. When omitted, resolved from swiftCode via the payout partner bank directory at account creation. Not checked against `GET /discoveries`. minLength: 1 maxLength: 255 example: HSBC Hong Kong accountNumber: type: string description: Hong Kong bank account number minLength: 1 maxLength: 34 example: '123456789012' swiftCode: type: string description: The SWIFT/BIC code of the bank example: HSBCHKHHHKH minLength: 8 maxLength: 11 pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$ example: accountType: HKD_ACCOUNT bankName: HSBC Hong Kong accountNumber: '123456789012' swiftCode: HSBCHKHHHKH Transaction: type: object required: - id - status - type - direction - destination - customerId - platformCustomerId properties: id: type: string description: Unique identifier for the transaction example: Transaction:019542f5-b3e7-1d02-0000-000000000004 status: $ref: '#/components/schemas/TransactionStatus' pendingReason: $ref: '#/components/schemas/TransactionPendingReason' description: Present when compliance review or required customer action is delaying settlement. type: $ref: '#/components/schemas/TransactionType' direction: $ref: '#/components/schemas/TransactionDirection' description: Whether this transaction credits or debits the customer's account. destination: $ref: '#/components/schemas/TransactionDestinationOneOf' ruleBasedAccountId: type: string description: The `RULE_BASED` internal account whose deposit this transaction sweeps. Present only on sweep transactions. For these, `source` describes the party that made the deposit when it is known, and is this account otherwise. example: InternalAccount:019542f5-b3e7-1d02-0000-000000000011 customerId: type: string description: System ID of the customer this transaction belongs to example: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: type: string description: Platform-specific ID of the customer this transaction belongs to example: 18d3e5f7b4a9c2 settledAt: type: string format: date-time description: When the payment was or will be settled example: '2025-08-15T14:30:00Z' createdAt: type: string format: date-time description: When the transaction was created example: '2025-08-15T14:25:18Z' updatedAt: type: string format: date-time description: When the transaction was last updated example: '2025-08-15T14:30:00Z' receiptDeliveryConfirmedAt: type: string format: date-time description: The time at which the platform confirmed delivery of the receipt to their customer. example: '2025-08-15T14:31:00Z' agentId: type: string description: If this transaction was initiated by an agent, the system-generated ID of that agent. Absent for platform-initiated transactions. example: Agent:019542f5-b3e7-1d02-0000-000000000042 description: type: string description: Optional memo or description for the payment example: 'Payment for invoice #1234' sentAmount: $ref: '#/components/schemas/CurrencyAmount' description: Amount sent in the sender's currency exchangeRate: type: number description: 'Number of sending currency units per receiving currency unit. The rate is fee-exclusive: Grid deducts fees from the sending amount before converting at this rate.' exclusiveMinimum: 0 example: 1.08 quoteId: type: string description: The ID of the quote that was used to trigger this payment example: Quote:019542f5-b3e7-1d02-0000-000000000006 refund: $ref: '#/components/schemas/Refund' description: The refund if transaction was refunded. counterpartyInformation: $ref: '#/components/schemas/CounterpartyInformation' WalletBeneficiaryFields: type: object properties: beneficiary: description: The wallet's owner. Optional for `FIRST_PARTY` accounts — the customer's verified identity is used. Required for `THIRD_PARTY` wallets on platforms with counterparty requirements (e.g. EU Travel Rule); if missing there, creation fails with `400 INVALID_INPUT`. $ref: '#/components/schemas/WalletBeneficiaryOneOf' BeneficiaryVerificationStatus: type: string enum: - MATCHED - PARTIAL_MATCH - NOT_MATCHED - UNSUPPORTED - CHECKED_BY_RECEIVING_FI - PENDING description: 'The result of verifying the beneficiary name against the account holder name. | Status | Description | |--------|-------------| | `MATCHED` | The beneficiary name is an exact match | | `PARTIAL_MATCH` | The beneficiary name is a fuzzy match | | `NOT_MATCHED` | The beneficiary name does not match | | `UNSUPPORTED` | The payment rail does not support name verification | | `CHECKED_BY_RECEIVING_FI` | Verification is deferred to the receiving financial institution (e.g. ACH) | | `PENDING` | Verification is still in progress | ' AgentChainAddressDestination: title: Chain Address type: object required: - destinationType - network - currency - address properties: destinationType: type: string enum: - CHAIN_ADDRESS description: Marks a destination on another chain. example: CHAIN_ADDRESS network: $ref: '#/components/schemas/AgentSendNetwork' description: Network the recipient receives on. example: BASE currency: $ref: '#/components/schemas/AgentSendCurrency' description: 'Asset the recipient receives: `USDC` or `USDT`. `TRON` supports `USDT` only, and `BASE` supports `USDC` only.' example: USDC address: type: string maxLength: 128 description: Recipient address on `network`. example: '0x1234567890abcdef1234567890abcdef12345678' description: An address on another chain, paid from an `EMBEDDED_WALLET` holding `USDB`. Grid records the address as an external account of the agent's customer, reusing the account when the customer already has one for the same network, currency and address, and screens it before quoting. The quote's `destination` names that account. IndividualSourceOfFundsCategory: type: string enum: - SALARY - SELF_EMPLOYMENT_INCOME - INVESTMENT_INCOME - PENSION - RENTAL_INCOME - GIFT - INHERITANCE - LOAN - SAVINGS - SALE_OF_ASSETS - OTHER description: A structured source-of-funds category for an individual customer (FLOW of funds into this account). Distinct from `SourceOfFundsCategory`, which covers business customers. example: SALARY SparkWalletExternalAccountInfo: title: Spark Wallet allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/SparkWalletInfo' - $ref: '#/components/schemas/WalletBeneficiaryFields' - $ref: '#/components/schemas/WalletCustodyFields' AgreementAcceptanceMethod: type: string description: Method the customer used to affirmatively accept an agreement. enum: - CHECKBOX - CLICK_TO_ACCEPT example: CHECKBOX PaymentBitcoinDepositAddressInfo: title: Bitcoin L1 Deposit Address allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - type: object required: - address properties: accountType: type: string enum: - BITCOIN_L1 address: type: string description: On-chain Bitcoin (L1) deposit address to send funds to example: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq network: type: string description: The blockchain network for the deposit address. enum: - BITCOIN example: BITCOIN XofBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName - registrationNumber - taxId properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' BaseQuoteSource: type: object required: - sourceType properties: sourceType: $ref: '#/components/schemas/QuoteSourceType' NgnBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName - registrationNumber - taxId properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' Verification: type: object required: - id - customerId - verificationStatus - errors - createdAt properties: id: type: string description: Unique identifier for this verification example: Verification:019542f5-b3e7-1d02-0000-000000000001 customerId: type: string description: The ID of the customer being verified example: Customer:019542f5-b3e7-1d02-0000-000000000001 verificationStatus: $ref: '#/components/schemas/VerificationStatus' errors: type: array description: List of issues preventing verification from proceeding. Empty when verificationStatus is APPROVED or IN_PROGRESS. items: $ref: '#/components/schemas/VerificationError' createdAt: type: string format: date-time description: When this verification was created example: '2025-10-03T12:00:00Z' updatedAt: type: string format: date-time description: When this verification was last updated example: '2025-10-03T12:00:00Z' AgentSendNetwork: type: string enum: - BASE - ETHEREUM - SOLANA - POLYGON - ARBITRUM - TRON description: Network an agent can send USDC or USDT to from an embedded wallet. `TRON` supports `USDT` only, and `BASE` supports `USDC` only. FixedFee: type: object description: Fixed fee charged per transaction. required: - amount - currency properties: amount: type: integer format: int64 minimum: 0 maximum: 9007199254740991 description: Fee amount in the smallest unit of the fixed fee's `currency` (e.g., cents for USD). example: 100 currency: type: string description: Three-letter currency code (ISO 4217) the fixed fee is denominated in. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) example: USD OutgoingRateDetails: description: 'Details about the rate and fees for an outgoing transaction or quote. Note: `counterpartyFixedFee` is denominated in the receiving currency, so its equivalent value in the sending currency fluctuates with the FX rate. As a result, the total fee on a subsequent quote for the same transfer may differ even if the underlying fee structure is unchanged.' type: object required: - counterpartyMultiplier - counterpartyFixedFee - gridApiMultiplier - gridApiFixedFee - gridApiVariableFeeRate - gridApiVariableFeeAmount properties: counterpartyMultiplier: type: number format: double description: The underlying multiplier from mSATs to the receiving currency as returned by the counterparty institution. exclusiveMinimum: 0 example: 1.08 counterpartyFixedFee: type: integer format: int64 description: The fixed fee charged by the counterparty institution to execute the quote in the smallest unit of the receiving currency (eg. cents). minimum: 0 example: 10 gridApiMultiplier: type: number format: double description: The underlying multiplier from the sending currency to mSATS, including variable fees. exclusiveMinimum: 0 example: 0.925 gridApiFixedFee: type: integer format: int64 description: The fixed fee charged by the Grid product to execute the quote in the smallest unit of the sending currency (eg. cents). minimum: 0 example: 10 gridApiVariableFeeRate: type: number format: double description: The variable fee rate charged by the Grid product to execute the quote as a percentage of the sending currency amount. minimum: 0 example: 0.003 gridApiVariableFeeAmount: type: number format: int64 description: The variable fee amount charged by the Grid product to execute the quote in the smallest unit of the sending currency (eg. cents). This is the sending amount times gridApiVariableFeeRate. minimum: 0 example: 30 QuoteStatus: type: string enum: - PENDING - PENDING_AUTHORIZATION - PROCESSING - COMPLETED - FAILED - EXPIRED description: 'Current status of the quote. `PENDING_AUTHORIZATION` occurs only for customers in a region where Strong Customer Authentication is required (e.g. EU): the quote carries an `scaChallenge` that must be authorized before execution, and for realtime-funding sources `paymentInstructions` are withheld until it is satisfied.' example: PENDING XofExternalAccountInfo: title: XOF Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/XofAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/XofBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/XofBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/XofBeneficiary' BUSINESS: '#/components/schemas/XofBusinessBeneficiary' BaseWebhook: type: object required: - timestamp - id - type properties: id: type: string description: Unique identifier for this webhook delivery (can be used for idempotency) example: Webhook:019542f5-b3e7-1d02-0000-000000000007 type: $ref: '#/components/schemas/WebhookType' description: Status-specific event type in OBJECT.EVENT dot-notation (e.g., OUTGOING_PAYMENT.COMPLETED) timestamp: type: string format: date-time description: ISO 8601 timestamp of when the webhook was sent example: '2025-08-15T14:32:00Z' TronWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - TRON_WALLET address: type: string description: Tron wallet address example: TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL PaymentUsdAccountInfo: title: USD Bank Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/UsdAccountInfo' - type: object required: - reference properties: reference: type: string description: Unique reference code that must be included with the payment to properly credit it example: UMA-Q12345-REF bankAddress: type: string description: The postal address of the financial institution holding the account, on a single line. Optional on every rail, and recommended for wires, where some originating banks require the beneficiary institution's address before they will send. example: 885 Teaneck Road, Teaneck, NJ 07666 minLength: 1 maxLength: 255 HkdBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' BrlExternalAccountInfo: title: BRL Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/BrlAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/BrlBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/BrlBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/BrlBeneficiary' BUSINESS: '#/components/schemas/BrlBusinessBeneficiary' NgnAccountInfo: allOf: - $ref: '#/components/schemas/NgnAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER ScaChallenge: type: object description: 'A Strong Customer Authentication challenge that must be satisfied before a money-movement operation can complete. This object is **only present when the customer is in a region where SCA is required** (the EU); for customers outside SCA-regulated regions it is omitted entirely and no action is needed. When present on a quote, authorize it by submitting an `ScaAuthorization` proof to `POST /quotes/{quoteId}/authorize`. **A single operation may require more than one authorization, in sequence.** Treat `scaChallenge` as *the challenge to satisfy now*, not "the only one". After each authorize, re-inspect the returned quote/transaction: if it is still `PENDING_AUTHORIZATION`, it carries the **next** `scaChallenge` (a new `id`) — authorize that too, and repeat until it leaves `PENDING_AUTHORIZATION`. Do not assume one authorization releases the transfer. The number of authorizations is flow-dependent and **may decrease in future**: for example, a cross-currency send today authorizes the currency conversion and the payout as two separate challenges; a future update may collapse them into one. A client written to loop on status handles any count unchanged.' required: - id - expiresAt - factor - availableFactors properties: id: type: string description: Unique identifier for this challenge. The server resolves the active challenge from the quote or transaction being authorized, so this field need not be supplied back; it is informational (e.g. for logging or correlation). example: ScaChallenge:019542f5-b3e7-1d02-0000-000000000007 expiresAt: type: string format: date-time description: Absolute UTC timestamp after which this challenge can no longer be authorized. example: '2025-10-03T12:05:00Z' factor: $ref: '#/components/schemas/ScaFactor' description: The factor this challenge was issued for. Defaults to `SMS_OTP`. availableFactors: type: array description: The factors the customer may use to satisfy this challenge. items: $ref: '#/components/schemas/ScaFactor' example: - SMS_OTP purpose: type: - string - 'null' description: Optional, informational label for what this particular challenge in the sequence authorizes — useful for step UX (e.g. "Authorize the currency conversion" vs "Authorize the payout"). Known values include `CURRENCY_CONVERSION`, `PAYOUT`, and `TRANSFER`, but the set is **non-exhaustive and may grow** — treat unrecognized values as a generic authorization step and do not branch program logic on it. Omitted when steps are not distinguished (e.g. a single-authorization flow). example: PAYOUT passkeyAssertionOptions: type: - object - 'null' additionalProperties: true description: Opaque WebAuthn assertion request options (including the relying-party id, challenge, and allowed credentials), present only when `factor` is `PASSKEY`. Pass to the device's WebAuthn API to produce the assertion submitted back in `ScaAuthorization.passkeyAssertion`. passkeyAllowedOrigins: type: - array - 'null' items: type: string description: The origins the WebAuthn ceremony may run against. Populated for enrollment and login passkey challenges; the origin the assertion is produced against must be one of these and echoed back as `ScaAuthorization.origin`. Per-transaction passkey challenges omit this (they carry `passkeyAssertionOptions` only) — see `ScaAuthorization.origin` for how to source the origin in that case. example: - https://app.example.com Refund: type: object required: - reference - initiatedAt - status properties: reference: type: string description: The unique reference ID of the refund example: UMA-Q12345-REFUND initiatedAt: type: string format: date-time description: When the refund was initiated example: '2025-08-15T14:30:00Z' settledAt: type: string format: date-time description: When the refund was settled example: '2025-08-15T14:35:00Z' status: $ref: '#/components/schemas/RefundStatus' reason: $ref: '#/components/schemas/RefundReason' CnyExternalAccountInfo: title: CNY Account description: A payout to a CNY bank account with a `BUSINESS` beneficiary needs supporting documents for its `purposeOfPayment`. Upload them with `POST /payment-documents` and pass their IDs in `documentIds` on `POST /quotes`. [Supporting documents](https://docs.lightspark.com/payouts-and-b2b/payment-flow/send-payment#supporting-documents) lists the documents each purpose needs. allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/CnyAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/CnyBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/CnyBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/CnyBeneficiary' BUSINESS: '#/components/schemas/CnyBusinessBeneficiary' AccountTransactionSource: title: Account Source allOf: - $ref: '#/components/schemas/BaseTransactionSource' - type: object required: - accountId - sourceType properties: sourceType: type: string enum: - ACCOUNT accountId: type: string description: Source account identifier example: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 railDetails: $ref: '#/components/schemas/RailDetailsOneOf' onChainTransaction: $ref: '#/components/schemas/OnChainTransaction' deprecated: true description: Deprecated. Use `railDetails`, which carries the same hash and network when `paymentRail` is `ONCHAIN`. description: Source account details AgentActionWebhookEventType: type: string enum: - AGENT_ACTION.PENDING_APPROVAL - AGENT_ACTION.APPROVED - AGENT_ACTION.REJECTED - AGENT_ACTION.FAILED PaymentTronWalletInfo: title: Tron Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/TronWalletInfo' - type: object properties: assetType: type: string description: Type of asset enum: - USDT FedNowRailStatus: type: string enum: - PENDING - SETTLED - FAILED description: 'Status of the payment on FedNow. | Status | Description | |--------|-------------| | `PENDING` | Submitted and awaiting the receiving bank''s response. | | `SETTLED` | The receiving bank accepted the payment and the funds settled. | | `FAILED` | The receiving bank or the network rejected the payment and no funds moved. |' example: SETTLED GhsExternalAccountInfo: title: GHS Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/GhsAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/GhsBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/BusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/GhsBeneficiary' BUSINESS: '#/components/schemas/BusinessBeneficiary' AgreementType: type: string description: 'Identifies which Grid agreement a consent record or document refers to. Values are stable identifiers: a document''s hosted URL or version may change, but its type does not. Accepting one agreement never implies acceptance of another, even when two agreements share a hosted page. The cardholder and accountholder agreements differ by customer kind: an `INDIVIDUAL` customer accepts the `_CONSUMER_` variant, and a `BUSINESS` customer accepts the `_COMMERCIAL_` one.' enum: - LIGHTSPARK_END_USER_TERMS - LIGHTSPARK_E_SIGN_CONSENT - LIGHTSPARK_PRIVACY_POLICY - LEAD_E_SIGN_CONSENT - LEAD_ACCOUNTHOLDER_CONSUMER_AGREEMENT - LEAD_ACCOUNTHOLDER_COMMERCIAL_AGREEMENT - LEAD_PRIVACY_POLICY - LEAD_CARDHOLDER_CONSUMER_AGREEMENT - LEAD_CARDHOLDER_COMMERCIAL_AGREEMENT example: LIGHTSPARK_END_USER_TERMS QuoteSourceType: type: string enum: - ACCOUNT - REALTIME_FUNDING description: Type of quote funding source example: ACCOUNT TzsExternalAccountInfo: title: TZS Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/TzsAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/TzsBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/TzsBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/TzsBeneficiary' BUSINESS: '#/components/schemas/TzsBusinessBeneficiary' PlatformFeeOverride: type: object description: Overrides the platform-collected fee for this transaction. When present, it replaces any configured platform-collected fees that would otherwise apply to the transaction. Currently only supported when the quote's source currency is USD; the fixed fee must be denominated in the source currency. required: - platformFixedFee - platformVariableFeeBps properties: platformFixedFee: $ref: '#/components/schemas/FixedFee' description: Fixed fee charged for this transaction. Must be denominated in the quote's source currency (USD today). platformVariableFeeBps: type: integer minimum: 0 maximum: 10000 description: Variable fee in basis points (1 bps = 0.01%) to apply to the transaction's source-currency amount. example: 30 example: platformFixedFee: amount: 50 currency: USD platformVariableFeeBps: 30 IncomingPaymentWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/IncomingPaymentWebhookData' type: $ref: '#/components/schemas/IncomingPaymentWebhookEventType' TransactionPendingReason: type: string enum: - COUNTERPARTY_DECLARATION_REQUIRED - WALLET_VERIFICATION_REQUIRED - COUNTERPARTY_INFORMATION_REQUIRED - COMPLIANCE_REVIEW description: 'Why a transaction is pending. | Reason | Description | |--------|-------------| | `COUNTERPARTY_DECLARATION_REQUIRED` | The customer must declare who controls the sending wallet. | | `WALLET_VERIFICATION_REQUIRED` | The customer must verify ownership of the sending wallet. | | `COUNTERPARTY_INFORMATION_REQUIRED` | Information about the sender is required. | | `COMPLIANCE_REVIEW` | The customer''s action is complete and the deposit remains under compliance review. | ' SourceOfFundsCategory: type: string enum: - OPERATING_REVENUE - INVESTMENT_INCOME - LOANS - VENTURE_CAPITAL - PERSONAL_SAVINGS - DONATIONS - OTHER description: A structured source-of-funds category for the business example: OPERATING_REVENUE WireRailDetails: title: Wire Transfer description: A domestic wire over Fedwire. allOf: - $ref: '#/components/schemas/BaseUsdBankRailDetails' - type: object required: - paymentRail - status properties: bankAccount: $ref: '#/components/schemas/WireBankAccountDetails' paymentRail: type: string enum: - WIRE status: $ref: '#/components/schemas/WireRailStatus' imad: type: string description: Fedwire Input Message Accountability Data assigned when the wire was sent. example: 20260929MMQFMP9C000123 originatorToBeneficiaryInformation: type: string description: Free-form originator-to-beneficiary information (OBI) sent with the wire. example: INV-12345 UsdBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' XofBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' OnChainTransaction: type: object required: - transactionHash - network properties: transactionHash: type: string description: On-chain transaction hash of the crypto transfer for this leg of the transaction. example: h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx network: $ref: '#/components/schemas/CryptoNetwork' description: Blockchain network the transaction settled on (mainnet vs test network is determined by your platform environment). RwfBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' MxnBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' PaymentCopAccountInfo: title: COP Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - type: object required: - paymentUrl properties: accountType: type: string enum: - COP_ACCOUNT paymentUrl: type: string format: uri description: A payment URL where the customer can complete their COP deposit. example: https://payments.example.com/t/abc123 PaymentLightningInvoiceInfo: title: Lightning Invoice allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - type: object required: - invoice properties: accountType: type: string enum: - LIGHTNING invoice: type: string description: Invoice for the payment example: lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs UsdExternalAccountInfo: title: USD Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/UsdAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/UsdBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/UsdBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/UsdBeneficiary' BUSINESS: '#/components/schemas/UsdBusinessBeneficiary' MxnExternalAccountInfo: title: MXN Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/MxnAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/MxnBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/MxnBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/MxnBeneficiary' BUSINESS: '#/components/schemas/MxnBusinessBeneficiary' Error400: type: object required: - reason - code properties: code: type: string description: '| Error Code | Description | |------------|-------------| | INVALID_INPUT | Invalid input provided | | END_USER_TERMS_VERSION_NOT_FOUND | The submitted version is not supported for the agreement it was sent for | | MISSING_MANDATORY_USER_INFO | Required customer information is missing | | INVITATION_ALREADY_CLAIMED | Invitation has already been claimed | | INVITATIONS_NOT_CONFIGURED | Invitations are not configured | | INVALID_UMA_ADDRESS | UMA address format is invalid | | INVITATION_CANCELLED | Invitation has been cancelled | | INVALID_RECEIVER | Receiver is invalid | | PARSE_PAYREQ_RESPONSE_ERROR | Error parsing receiver PayReq response | | CERT_CHAIN_INVALID | Counterparty certificate chain is invalid | | CERT_CHAIN_EXPIRED | Counterparty certificate chain has expired | | INVALID_PUBKEY_FORMAT | Counterparty Public key format is invalid | | MISSING_REQUIRED_UMA_PARAMETERS | Counterparty required UMA parameters are missing | | SENDER_NOT_ACCEPTED | The receiving institution declined this sender. Final; a retry returns the same answer | | AMOUNT_OUT_OF_RANGE | Amount is out of range | | INVALID_CURRENCY | Currency is invalid | | INVALID_TIMESTAMP | Timestamp is invalid | | INVALID_NONCE | Nonce is invalid | | INVALID_REQUEST_FORMAT | Request format is invalid | | INVALID_BANK_ACCOUNT | Bank account is invalid | | SELF_PAYMENT | Self payment not allowed | | PARSE_LNURLP_RESPONSE_ERROR | Error parsing LNURLP response | | INVALID_AMOUNT | Amount is invalid | | WEBHOOK_ENDPOINT_NOT_SET | Webhook endpoint is not set | | WEBHOOK_DELIVERY_ERROR | Webhook delivery error | | LOW_QUALITY | Document quality too low to process | | DATA_MISMATCH | Document details don''t match provided information | | EXPIRED | Document has expired | | SUSPECTED_FRAUD | Document suspected of being forged or edited | | UNSUITABLE_DOCUMENT | Document type is not accepted or not supported | | INCOMPLETE | Document is missing pages or sides | | EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS | An EMAIL_OTP credential is already registered on the target internal account; only one email OTP credential is supported per internal account at this time | | SMS_OTP_CREDENTIAL_ALREADY_EXISTS | An SMS_OTP credential is already registered on the target internal account; only one SMS OTP credential is supported per internal account at this time | | PASSKEY_CREDENTIAL_ALREADY_EXISTS | A PASSKEY credential with the same WebAuthn credentialId is already registered on the target internal account | | AUTH_CREDENTIAL_VERIFICATION_REQUIRED | The new email or phone number has no verified replacement credential | | AUTH_CREDENTIAL_VERIFICATION_EXPIRED | The replacement credential''s verification has expired | | STABLECOIN_PROVIDER_ACCOUNT_INVALID | The stablecoin provider account link is not usable | | STABLECOIN_PROVIDER_ACCOUNT_REVOKED | The stablecoin provider account link has been revoked | | STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED | Multiple active provider account links exist; pass `stablecoinProviderAccountId` to select one | | CARDHOLDER_KYC_NOT_APPROVED | The cardholder''s KYC status is not `APPROVED`, so a card cannot be issued | | ACCOUNTHOLDER_AGREEMENT_NOT_ACCEPTED | The customer create request omits an accountholder agreement its accounts require | | TRANSACTION_SIZE_LIMIT_EXCEEDED | The requested amount exceeds the configured maximum single-transaction amount for this trade corridor or withdrawal currency | | EXTERNAL_ACCOUNT_VERIFICATION_REQUIRED | The destination account''s ownership must be verified before this transfer can proceed | | INSUFFICIENT_FUNDS | Insufficient funds for this operation | | QUOTE_EXPIRED | The quote has expired; request a new quote | | QUOTE_RATE_UNAVAILABLE | No exchange rate is available for this corridor right now | | STABLECOIN_AMOUNT_NOT_REPRESENTABLE | The amount cannot be represented at the token''s precision | | STABLECOIN_BURN_SOURCE_NOT_SUPPORTED | The burn source account cannot be used for this operation | | STABLECOIN_EXTERNAL_ACCOUNT_LINK_FAILED | Linking the external account for stablecoin operations failed | | STABLECOIN_EXTERNAL_ACCOUNT_LINK_METHOD_REQUIRED | The external account needs a link method before it can be used | | STABLECOIN_EXTERNAL_ACCOUNT_NOT_LINKED | The external account is not linked for stablecoin operations | | STABLECOIN_EXTERNAL_ACCOUNT_NOT_SUPPORTED | This external account type is not supported for stablecoin operations | | STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_FAILED | The provider could not link the external account | | STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_REQUIRED | The external account must be linked with the provider first | | STABLECOIN_GRID_OPERATIONS_NOT_ENABLED | The stablecoin is not enabled for Grid operations | | STABLECOIN_NOT_PROVISIONED | The stablecoin is not provisioned for issuer operations | | STABLECOIN_OPERATION_NOT_SUPPORTED | The stablecoin does not support this operation | | STABLECOIN_PROVIDER_ERROR | The stablecoin provider rejected the operation | | STABLECOIN_PROVIDER_SOURCE_NOT_LINKED | The provider source account is not linked | | STABLECOIN_VERIFICATION_FAILED | The stablecoin could not be verified with the provider | | DOCUMENTS_REQUIRED | The destination requires supporting documents for the quote''s `purposeOfPayment` that the request did not supply. `details.missingRequirements` lists the requirement ID of each one | ' enum: - INVALID_INPUT - END_USER_TERMS_VERSION_NOT_FOUND - MISSING_MANDATORY_USER_INFO - INVITATION_ALREADY_CLAIMED - INVITATIONS_NOT_CONFIGURED - INVALID_UMA_ADDRESS - INVITATION_CANCELLED - INVALID_RECEIVER - PARSE_PAYREQ_RESPONSE_ERROR - CERT_CHAIN_INVALID - CERT_CHAIN_EXPIRED - INVALID_PUBKEY_FORMAT - MISSING_REQUIRED_UMA_PARAMETERS - SENDER_NOT_ACCEPTED - AMOUNT_OUT_OF_RANGE - INVALID_CURRENCY - INVALID_TIMESTAMP - INVALID_NONCE - INVALID_REQUEST_FORMAT - INVALID_BANK_ACCOUNT - SELF_PAYMENT - PARSE_LNURLP_RESPONSE_ERROR - INVALID_AMOUNT - WEBHOOK_ENDPOINT_NOT_SET - WEBHOOK_DELIVERY_ERROR - LOW_QUALITY - DATA_MISMATCH - EXPIRED - SUSPECTED_FRAUD - UNSUITABLE_DOCUMENT - INCOMPLETE - EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS - SMS_OTP_CREDENTIAL_ALREADY_EXISTS - PASSKEY_CREDENTIAL_ALREADY_EXISTS - AUTH_CREDENTIAL_VERIFICATION_REQUIRED - AUTH_CREDENTIAL_VERIFICATION_EXPIRED - STABLECOIN_PROVIDER_ACCOUNT_INVALID - STABLECOIN_PROVIDER_ACCOUNT_REVOKED - STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED - CARDHOLDER_KYC_NOT_APPROVED - ACCOUNTHOLDER_AGREEMENT_NOT_ACCEPTED - TRANSACTION_SIZE_LIMIT_EXCEEDED - EXTERNAL_ACCOUNT_VERIFICATION_REQUIRED - INSUFFICIENT_FUNDS - QUOTE_EXPIRED - QUOTE_RATE_UNAVAILABLE - STABLECOIN_AMOUNT_NOT_REPRESENTABLE - STABLECOIN_BURN_SOURCE_NOT_SUPPORTED - STABLECOIN_EXTERNAL_ACCOUNT_LINK_FAILED - STABLECOIN_EXTERNAL_ACCOUNT_LINK_METHOD_REQUIRED - STABLECOIN_EXTERNAL_ACCOUNT_NOT_LINKED - STABLECOIN_EXTERNAL_ACCOUNT_NOT_SUPPORTED - STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_FAILED - STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_REQUIRED - STABLECOIN_GRID_OPERATIONS_NOT_ENABLED - STABLECOIN_NOT_PROVISIONED - STABLECOIN_OPERATION_NOT_SUPPORTED - STABLECOIN_PROVIDER_ERROR - STABLECOIN_PROVIDER_SOURCE_NOT_LINKED - STABLECOIN_VERIFICATION_FAILED - DOCUMENTS_REQUIRED reason: type: string description: Error message details: type: object description: Additional error details. Shape varies by `code`. For field-validation errors on submit endpoints (e.g. `POST /customers`, `PATCH /customers/{id}`), `details.errors[]` enumerates every invalid field so platforms can render form-field-level UX for the entire request in a single round-trip. properties: errors: type: array description: One entry per invalid field. Present on field-validation errors from submit endpoints. items: $ref: '#/components/schemas/FieldError' missingRequirements: type: array description: The requirement ID of each required document that the quote request did not supply. Present on `DOCUMENTS_REQUIRED`. items: $ref: '#/components/schemas/PaymentDocumentRequirementId' additionalProperties: true BrlAccountInfoBase: type: object required: - accountType - pixKey - pixKeyType - taxId properties: accountType: type: string enum: - BRL_ACCOUNT pixKey: type: string description: The PIX key (email, phone, CPF, CNPJ, or random) minLength: 1 maxLength: 77 pixKeyType: type: string description: The type of PIX key enum: - CPF - CNPJ - EMAIL - PHONE - RANDOM taxId: type: string description: The tax ID (CPF or CNPJ) minLength: 11 maxLength: 14 pattern: ^[0-9]{11,14}$ example: accountType: BRL_ACCOUNT pixKey: user@example.com pixKeyType: CPF taxId: '11111111111' JmdBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - address - fullName - phoneNumber properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' GtqAccountInfoBase: type: object required: - accountType - accountNumber - bankAccountType - bankName properties: accountType: type: string enum: - GTQ_ACCOUNT accountNumber: type: string description: The account number of the bank minLength: 1 maxLength: 34 bankAccountType: type: string description: The bank account type enum: - CHECKING - SAVINGS bankName: type: string description: The name of the beneficiary's bank. Must be one of the `bankName` values `GET /discoveries` returns for this country and currency. Send it exactly as returned; any other name is rejected. minLength: 1 maxLength: 255 example: Banco Industrial example: accountType: GTQ_ACCOUNT accountNumber: '1234567890' bankAccountType: CHECKING bankName: Banco Industrial VndBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' AgentActionFailureReason: type: string enum: - QUOTE_EXPIRED - POLICY_DENIED - AGENT_INACTIVE - EXECUTION_FAILED - PRICE_MOVED - ADDRESS_REFUSED description: 'Why an agent action has status `FAILED`. | Reason | Description | |--------|-------------| | `QUOTE_EXPIRED` | The action''s quote expired before execution | | `POLICY_DENIED` | The agent policy no longer allowed the action | | `AGENT_INACTIVE` | The agent was paused or deleted before execution | | `EXECUTION_FAILED` | Grid could not execute the approved action | | `PRICE_MOVED` | A quote to a `CHAIN_ADDRESS` would no longer deliver its `minimumReceivingAmount` when it executed, so Grid did not send | | `ADDRESS_REFUSED` | Grid refused the send''s destination before it signed the send: the destination is no longer one the agent may send to (for example, a Spark address removed from the customer''s saved addresses), or one of the customer''s records of the address was refused or is held for review. A `CHAIN_ADDRESS` that screening refuses fails with `EXECUTION_FAILED` | ' BaseDestination: type: object required: - destinationType properties: destinationType: $ref: '#/components/schemas/DestinationType' AgentSendCurrency: type: string enum: - USDC - USDT description: Asset an agent can send to an address on another chain. `TRON` supports `USDT` only, and `BASE` supports `USDC` only. GridError: type: object title: GridError properties: code: type: string description: Error code message: type: string description: Error message details: type: object description: Additional error details additionalProperties: true TryAccountInfoBase: type: object required: - accountType - iban - bankName properties: accountType: type: string enum: - TRY_ACCOUNT iban: type: string description: Turkish IBAN (26 characters, starting with TR) example: TR330006100519786457841326 minLength: 26 maxLength: 26 pattern: ^TR[0-9]{2}[0-9A-Z]{22}$ bankName: type: string description: The name of the bank. Must be one of the `bankName` values `GET /discoveries` returns for this country and currency. Send it exactly as returned; any other name is rejected. minLength: 1 maxLength: 255 example: example: accountType: TRY_ACCOUNT iban: TR330006100519786457841326 bankName: CadExternalAccountInfo: title: CAD Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/CadAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/CadBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/BusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/CadBeneficiary' BUSINESS: '#/components/schemas/BusinessBeneficiary' SlvExternalAccountInfo: title: SLV Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/SlvAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/SlvBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/BusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/SlvBeneficiary' BUSINESS: '#/components/schemas/BusinessBeneficiary' StablecoinAssetType: type: string description: Type of asset enum: - USDC - USDT IncomingPaymentWebhookEventType: type: string enum: - INCOMING_PAYMENT.PENDING - INCOMING_PAYMENT.PROCESSING - INCOMING_PAYMENT.COMPLETED - INCOMING_PAYMENT.FAILED - INCOMING_PAYMENT.REFUND_PENDING - INCOMING_PAYMENT.REFUND_COMPLETED - INCOMING_PAYMENT.REFUND_FAILED AgentAction: type: object description: An action submitted by an agent that may require platform approval before execution. All agent-initiated operations (quote execution, transfers) are represented as AgentActions, giving the platform a consistent object to approve, reject, and audit regardless of the underlying operation type. required: - id - agentId - customerId - platformCustomerId - status - type - expiresAt - createdAt - updatedAt properties: id: type: string description: System-generated unique identifier for this action. example: AgentAction:019542f5-b3e7-1d02-0000-000000000099 agentId: type: string description: The agent that submitted this action. example: Agent:019542f5-b3e7-1d02-0000-000000000042 customerId: type: string description: The customer on whose behalf the action was submitted. example: Customer:019542f5-b3e7-1d02-0000-000000000010 platformCustomerId: type: string description: Platform-specific ID of the customer. example: user-a1b2c3 status: $ref: '#/components/schemas/AgentActionStatus' type: $ref: '#/components/schemas/AgentActionType' quote: allOf: - $ref: '#/components/schemas/AgentQuote' description: The quote being executed. Contains the full amount, currency, destination, and rate details needed to present an approval decision to the user. Present for `EXECUTE_QUOTE`. transaction: allOf: - $ref: '#/components/schemas/TransactionOneOf' description: The resulting transaction, populated once the action has been approved and execution has begun. Absent while the action is `PENDING_APPROVAL` or `REJECTED`. rejectionReason: type: string description: Human-readable reason provided by the platform when rejecting the action. Only present when status is `REJECTED`. example: Transaction amount exceeds customer's current risk limit. failureReason: $ref: '#/components/schemas/AgentActionFailureReason' description: Machine-readable reason the action failed. Only present when status is `FAILED`; `rejectionReason` is used only for `REJECTED` actions. expiresAt: type: string format: date-time description: When the action expires. For `EXECUTE_QUOTE`, this is the quote's own expiry. A `PENDING_APPROVAL` action that reaches this time transitions to `FAILED` with `failureReason` `QUOTE_EXPIRED`; approval never creates a replacement quote. example: '2025-10-03T15:05:00Z' createdAt: type: string format: date-time description: When the action was submitted by the agent. example: '2025-10-03T15:00:00Z' updatedAt: type: string format: date-time description: When the action was last updated. example: '2025-10-03T15:02:00Z' AgentActionType: type: string enum: - EXECUTE_QUOTE description: 'The type of action the agent is requesting. | Type | Description | |------|-------------| | `EXECUTE_QUOTE` | Execute a quote | ' OutgoingTransactionFailureReason: type: string enum: - QUOTE_EXPIRED - QUOTE_RATE_UNAVAILABLE - QUOTE_EXECUTION_FAILED - FUNDING_AMOUNT_MISMATCH - SCA_NOT_COMPLETED - PAYOUT_RETURNED - LIMIT_EXCEEDED - ACCOUNT_CANNOT_RECEIVE - ACCOUNT_INVALID - COMPLIANCE_REJECTED - LIGHTNING_PAYMENT_FAILED - COUNTERPARTY_POST_TX_FAILED - SWEEP_AMOUNT_OUT_OF_RANGE - SWEEP_QUOTE_FAILED description: 'Reason for failure of an outgoing transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted. When a payout partner rejects or fails a payment, one of the granular payout reasons (`PAYOUT_RETURNED`, `LIMIT_EXCEEDED`, `ACCOUNT_CANNOT_RECEIVE`, `ACCOUNT_INVALID`, `COMPLIANCE_REJECTED`) is returned when available. `COUNTERPARTY_POST_TX_FAILED` is a coarse fallback used only when no granular reason is available. `SCA_NOT_COMPLETED` means the customer did not satisfy the Strong Customer Authentication challenge before it expired, so the transaction was never authorized and no funds were moved. Only occurs for customers in a region where SCA is required (e.g. the EU). Create a new quote to try again, and have the customer authorize it while the challenge is live. | Reason | Description | |--------|-------------| | `QUOTE_EXPIRED` | The quote was not executed before its expiry window | | `QUOTE_RATE_UNAVAILABLE` | The quoted exchange rate was no longer available when the quote was executed, so nothing was exchanged. Create a new quote to get a current rate | | `QUOTE_EXECUTION_FAILED` | The quote could not be executed. Covers any internal failure on the way to settlement, whether or not funds were debited — a debited amount is refunded automatically | | `FUNDING_AMOUNT_MISMATCH` | The funds received did not match the expected amount | | `SCA_NOT_COMPLETED` | The customer did not complete the Strong Customer Authentication challenge before it expired | | `PAYOUT_RETURNED` | The receiving bank accepted the payout and then returned or reversed it | | `LIMIT_EXCEEDED` | The payout exceeds a recipient-, account-, or corridor-level limit at the partner | | `ACCOUNT_CANNOT_RECEIVE` | The account exists but can''t accept this payment — dormant, frozen, restricted, or the currency or payment rail isn''t supported for that account. A sweep whose rule names a rail the destination cannot accept reports this | | `ACCOUNT_INVALID` | The recipient account couldn''t be found or the details are wrong — bad IBAN/account number, beneficiary not found, or account closed | | `COMPLIANCE_REJECTED` | The payout partner rejected the recipient on compliance grounds — sanctions, watchlist, or KYC/AML screening | | `LIGHTNING_PAYMENT_FAILED` | Deprecated — superseded by `QUOTE_EXECUTION_FAILED`. The Lightning settlement leg failed | | `COUNTERPARTY_POST_TX_FAILED` | Deprecated — coarse fallback retained for historical transactions when no granular payout reason is available | | `SWEEP_AMOUNT_OUT_OF_RANGE` | The amount was outside the range the corridor to the rule''s destination can carry — below its minimum or above its maximum. The rule''s `minimumAmount` and `maximumAmount` give the current band | | `SWEEP_QUOTE_FAILED` | Grid could not price the sweep to the rule''s destination. A sweep that was priced and then failed on the way to settlement reports `QUOTE_EXECUTION_FAILED`, the same as any other payout | The `SWEEP_*` reasons apply to a payment that settled into a rule-based account and could not be swept onward. A rule-based account never holds a balance, so the funds are moved to the account holder''s own account in the same currency. ' ExpectedMonthlyTransactionVolume: type: string enum: - VOLUME_UNDER_10K - VOLUME_10K_TO_100K - VOLUME_100K_TO_1M - VOLUME_1M_TO_10M - VOLUME_OVER_10M description: Expected total transaction volume per month in USD equivalent example: VOLUME_100K_TO_1M BrlAccountInfo: allOf: - $ref: '#/components/schemas/BrlAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - PIX IlsBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' BwpAccountInfo: allOf: - $ref: '#/components/schemas/BwpAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - MOBILE_MONEY CustomerInfoFieldName: type: string enum: - FULL_NAME - BIRTH_DATE - NATIONALITY - PHONE_NUMBER - EMAIL - POSTAL_ADDRESS - TAX_ID - REGISTRATION_NUMBER - USER_TYPE - COUNTRY_OF_RESIDENCE - ACCOUNT_IDENTIFIER - FI_LEGAL_ENTITY_NAME - FI_ADDRESS - PURPOSE_OF_PAYMENT - ULTIMATE_INSTITUTION_COUNTRY - IDENTIFIER - BUSINESS_TYPE - COMPANY_LEGAL_NAME - ID_TYPE - ID_NUMBER description: Name of a type of field containing info about a platform's customer or counterparty customer. example: FULL_NAME GbpBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' AedAccountInfoBase: type: object required: - accountType - iban properties: accountType: type: string enum: - AED_ACCOUNT iban: type: string description: UAE IBAN (23 characters, starting with AE) example: AE070331234567890123456 minLength: 23 maxLength: 23 pattern: ^AE[0-9]{21}$ swiftCode: type: string description: The SWIFT/BIC code of the bank example: EBILAEAD minLength: 8 maxLength: 11 pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$ example: accountType: AED_ACCOUNT iban: AE070331234567890123456 swiftCode: EBILAEAD PaymentMxnAccountInfo: title: MXN Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/MxnAccountInfo' - type: object required: - reference properties: reference: type: string description: Unique reference code that must be included with the payment to properly credit it example: UMA-Q12345-REF UmaAddressDestination: title: UMA Address allOf: - $ref: '#/components/schemas/BaseDestination' - type: object required: - umaAddress - destinationType - currency properties: destinationType: type: string enum: - UMA_ADDRESS umaAddress: type: string maxLength: 200 description: UMA address of the recipient example: $receiver@uma.domain.com currency: type: string description: Currency code for the destination. See [Supported Currencies](https://docs.lightspark.com/platform-overview/core-concepts/currencies-and-rails) for the full list of supported fiat and crypto currencies. example: EUR description: UMA address destination details NgnAccountInfoBase: type: object required: - accountType - accountNumber - bankName properties: accountType: type: string enum: - NGN_ACCOUNT accountNumber: type: string description: Nigerian bank account number minLength: 10 maxLength: 10 example: 0123456789 pattern: ^[0-9]{10}$ bankName: type: string description: The name of the bank. Must be one of the `bankName` values `GET /discoveries` returns for this country and currency. Send it exactly as returned; any other name is rejected. minLength: 1 maxLength: 255 example: Access Bank example: accountType: NGN_ACCOUNT accountNumber: 0123456789 bankName: Access Bank RwfBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName - registrationNumber - taxId properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' BwpAccountInfoBase: type: object required: - accountType - phoneNumber - provider properties: accountType: type: string enum: - BWP_ACCOUNT phoneNumber: type: string description: The phone number in international format example: '+1234567890' minLength: 7 maxLength: 15 pattern: ^\+[0-9]{6,14}$ provider: type: string description: The mobile money provider name minLength: 1 maxLength: 255 example: accountType: BWP_ACCOUNT phoneNumber: '+1234567890' provider: Example Provider InrAccountInfoBase: type: object required: - accountType description: 'Required fields depend on the selected paymentRails: - NEFT: accountNumber, ifsc, rail - RTGS: accountNumber, ifsc, rail - UPI: vpa' properties: accountType: type: string enum: - INR_ACCOUNT vpa: type: string description: The UPI Virtual Payment Address example: user@upi minLength: 3 maxLength: 255 pattern: ^[a-zA-Z0-9.\-_]+@[a-zA-Z0-9]+$ accountNumber: type: string description: Indian bank account number (9–18 digits) minLength: 9 maxLength: 18 example: '000111222333' pattern: ^[0-9]{9,18}$ ifsc: type: string description: The Indian Financial System Code (IFSC) of the beneficiary's bank branch (NEFT/RTGS) example: HDFC0001234 minLength: 11 maxLength: 11 pattern: ^[A-Z]{4}0[A-Z0-9]{6}$ rail: type: string description: 'The payment rail to route the payout over: NEFT or RTGS. Omitted, the payout resolves it by amount.' minLength: 1 maxLength: 32 example: NEFT example: accountType: INR_ACCOUNT vpa: user@upi accountNumber: '000111222333' ifsc: HDFC0001234 rail: NEFT AedBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - address - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' RwfExternalAccountInfo: title: RWF Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/RwfAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/RwfBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/RwfBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/RwfBeneficiary' BUSINESS: '#/components/schemas/RwfBusinessBeneficiary' SparkWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - SPARK_WALLET address: type: string description: Spark wallet address example: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu PaymentEthereumWalletInfo: title: Ethereum Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/EthereumWalletInfo' - type: object properties: assetType: $ref: '#/components/schemas/StablecoinAssetType' PlasmaWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - PLASMA_WALLET address: type: string description: Plasma wallet address example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' CardTransactionStatus: type: string enum: - AUTHORIZED - PARTIALLY_SETTLED - SETTLED - DECLINED - VOIDED - EXCEPTION description: 'Lifecycle status of a card transaction. The status tracks the authorization outcome and settlement — a return against a purchase is its own dated `CREDIT` row linked to the purchase via `originalTransactionId`, not a status of its own. | Status | Description | |--------|-------------| | `AUTHORIZED` | The auth has been approved and a hold placed on the funding source; no clearing has arrived yet. | | `PARTIALLY_SETTLED` | At least one clearing has arrived and posted, but more clearings are still expected (split shipments, tips, multi-leg trips). | | `SETTLED` | All clearings for the auth have posted and the transaction is closed against the funding source. A `RETURN` received afterwards keeps the purchase `SETTLED`; the return appears as its own `CREDIT` transaction. | | `DECLINED` | The authorization was declined before any money moved. Declines carry no settlement and must be excluded from cardholder statements. | | `VOIDED` | The authorization was fully reversed or expired before any clearing posted, so the hold closed without moving money. `authorizedAmount` reports what is still held, normally 0, and `settledAmount` is absent. | | `EXCEPTION` | The transaction settled to the card network but the corresponding pull from the funding source failed (e.g. balance no longer covers the post-hoc clearing). Surfaces high-urgency alerts and is the dashboard query for stuck reconciliations. | ' EurAccountInfoBase: type: object required: - accountType - iban properties: accountType: type: string enum: - EUR_ACCOUNT iban: type: string description: The IBAN of the bank account example: DE89370400440532013000 minLength: 15 maxLength: 34 pattern: ^[A-Z]{2}[0-9]{2}[A-Za-z0-9]{11,30}$ swiftCode: type: string description: The SWIFT/BIC code of the bank. When omitted, Grid derives it from the IBAN when possible. Provide it when automatic derivation is unavailable. example: DEUTDEFF minLength: 8 maxLength: 11 pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$ example: accountType: EUR_ACCOUNT iban: DE89370400440532013000 swiftCode: DEUTDEFF EurBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - countryOfResidence - legalName - registrationNumber - taxId properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' Currency: type: object properties: code: type: string description: Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) example: USD name: type: string description: Full name of the currency example: United States Dollar symbol: type: string description: Symbol of the currency example: $ decimals: type: integer description: Number of decimal places for the currency minimum: 0 example: 2 PaymentEurAccountInfo: title: EUR Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/EurAccountInfo' - type: object required: - reference properties: reference: type: string description: Unique reference code that must be included with the payment to properly credit it example: UMA-Q12345-REF PaymentPlasmaWalletInfo: title: Plasma Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/PlasmaWalletInfo' - type: object properties: assetType: type: string description: Type of asset enum: - USDT InrAccountInfo: allOf: - $ref: '#/components/schemas/InrAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - UPI - NEFT - RTGS RailSelectionMode: type: string enum: - AUTO - MANUAL description: How the payment rail was chosen — MANUAL when the platform specified a paymentRail on the destination, AUTO when Lightspark selects it. example: AUTO ZmwAccountInfo: allOf: - $ref: '#/components/schemas/ZmwAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - MOBILE_MONEY PhpBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' FedNowRailDetails: title: FedNow Transfer description: An instant payment over the FedNow Service. allOf: - $ref: '#/components/schemas/BaseUsdBankRailDetails' - type: object required: - paymentRail - status properties: paymentRail: type: string enum: - FEDNOW status: $ref: '#/components/schemas/FedNowRailStatus' endToEndId: type: string description: The originator's end-to-end reference for the payment. example: E2E-9f2c6b6f remittanceInformation: type: string description: Unstructured remittance information sent with the payment. example: INV-12345 MxnAccountInfo: allOf: - $ref: '#/components/schemas/MxnAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - SPEI IncomingTransaction: title: Incoming Transaction allOf: - $ref: '#/components/schemas/Transaction' - type: object required: - type properties: type: type: string enum: - INCOMING source: $ref: '#/components/schemas/TransactionSourceOneOf' receivedAmount: $ref: '#/components/schemas/CurrencyAmount' description: Amount received in the recipient's currency. This is only absent for rule-based account sweeps if the sweep couldn't be quoted. It's always present otherwise. fees: type: integer format: int64 description: The total fees available from the receive quote in the smallest unit of the sending currency (eg. cents). minimum: 0 example: 10 reconciliationInstructions: $ref: '#/components/schemas/ReconciliationInstructions' description: Included for all transactions except those with "CREATED" status failureReason: $ref: '#/components/schemas/IncomingTransactionFailureReason' description: If the transaction failed, this field provides the reason for failure. EthereumWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - ETHEREUM_WALLET address: type: string description: Ethereum L1 wallet address example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' PaymentAccountType: type: string enum: - USD_ACCOUNT - BRL_ACCOUNT - MXN_ACCOUNT - DKK_ACCOUNT - ARS_ACCOUNT - COP_ACCOUNT - EUR_ACCOUNT - INR_ACCOUNT - NGN_ACCOUNT - CAD_ACCOUNT - GBP_ACCOUNT - HKD_ACCOUNT - IDR_ACCOUNT - MYR_ACCOUNT - PHP_ACCOUNT - SGD_ACCOUNT - THB_ACCOUNT - VND_ACCOUNT - SWIFT_ACCOUNT - SPARK_WALLET - LIGHTNING - SOLANA_WALLET - TRON_WALLET - PLASMA_WALLET - ARBITRUM_WALLET - POLYGON_WALLET - BASE_WALLET - ETHEREUM_WALLET - EMBEDDED_WALLET - BITCOIN_L1 description: Type of payment account or wallet example: USD_ACCOUNT FieldConstraint: type: object description: Machine-readable validator hint accompanying a 400 `INVALID_INPUT` error. Consumers use it to drive form UI (input types, dropdowns, masking, length limits) and to pre-validate the field client-side before re-submitting. Fields are additive. properties: format: type: string description: Named format the value must satisfy — HTML5 input type names (`email`, `tel`, `url`, `date`, ...) or semantic slugs (`iso3166-1-alpha-2`, `bcp47-language-tag`, `us-ssn`, `e.164`). example: email pattern: type: string description: Regular expression the value must match (JavaScript-flavor). example: ^\d{5}(-\d{4})?$ enum: type: array items: type: string description: Allowed values when the field is drawn from a fixed set. example: - SSN - ITIN - NON_US_TAX_ID minLength: type: integer description: Minimum length in characters. example: 1 maxLength: type: integer description: Maximum length in characters. example: 500 MwkAccountInfo: allOf: - $ref: '#/components/schemas/MwkAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - MOBILE_MONEY DkkBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' ExpectedMonthlyTransactionCount: type: string enum: - COUNT_UNDER_10 - COUNT_10_TO_100 - COUNT_100_TO_500 - COUNT_500_TO_1000 - COUNT_OVER_1000 description: Expected number of transactions per month example: COUNT_100_TO_500 WalletCustodyFields: type: object properties: vaspName: type: string description: Name of the VASP that custodies this account. Present when the wallet is held at an exchange or other custodial platform; omit it for self-custody wallets. Ownership verification applies only to self-custody wallets. example: Kraken TryBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - countryOfResidence - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' OutgoingTransactionStatus: type: string enum: - PENDING - PENDING_AUTHORIZATION - EXPIRED - PROCESSING - COMPLETED - FAILED description: 'Status of an outgoing payment transaction. | Status | Description | |--------|-------------| | `PENDING` | Quote is pending confirmation | | `PENDING_AUTHORIZATION` | Awaiting Strong Customer Authentication. Only occurs for customers in a region where SCA is required (e.g. EU). The challenge is carried by the quote, not the transaction — fetch `GET /quotes/{quoteId}` using the transaction''s `quoteId`, then authorize its `scaChallenge` via `POST /quotes/{quoteId}/authorize`. | | `EXPIRED` | Quote wasn''t executed before expiry window. Terminal | | `PROCESSING` | Executing the quote after receiving funds | | `COMPLETED` | The funds are at the destination. A bank return moves the payout to `FAILED` | | `FAILED` | The payout did not reach the destination, or was returned after it did — accompanied by a `failureReason`, and refunded to the source. A returned payout stays `FAILED` even if the return is later dishonored, since the refund has already been posted; the dishonor shows on `destination.railDetails` | ' KesBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName - registrationNumber - taxId properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' PaymentDocumentRequirementId: type: string description: 'A stable identifier for one required document within a purpose''s requirements. The same ID means the same requirement across quotes. It is separate from `PaymentDocumentType`. The requirement ID names the document to supply, and the document type names what a file is. The two differ where a requirement accepts alternatives. For example, a file declared as either `PURCHASE_ORDER` or `DELIVERY_SLIP` fills the `SUPPORTING_PROOF` requirement. [Supporting Documents](https://docs.lightspark.com/payouts-and-b2b/payment-flow/send-payment#supporting-documents) lists the IDs each purpose requires. Treat the ID as an opaque value, not a member of a fixed list. Grid may add new IDs as requirements change.' example: SUPPORTING_PROOF BaseUsdBankRailDetails: title: Base US Bank Rail Details type: object description: Fields shared by every US bank rail. properties: bankAccount: $ref: '#/components/schemas/UsdBankAccountDetails' settledAt: type: string format: date-time description: When the transfer settled. example: '2026-09-29T15:04:12Z' SgdAccountInfoBase: type: object required: - accountType - accountNumber - swiftCode properties: accountType: type: string enum: - SGD_ACCOUNT bankName: type: string description: Name of the beneficiary's bank. When omitted, resolved from swiftCode via the payout partner bank directory at account creation. Not checked against `GET /discoveries`. minLength: 1 maxLength: 255 example: DBS Bank Ltd accountNumber: type: string description: Bank account number minLength: 1 maxLength: 34 example: 0123456789 swiftCode: type: string description: The SWIFT/BIC code of the bank example: DBSSSGSG minLength: 8 maxLength: 11 pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$ example: accountType: SGD_ACCOUNT bankName: DBS Bank Ltd accountNumber: 0123456789 swiftCode: DBSSSGSG ExternalAccountStatus: type: string enum: - PENDING - ACTIVE - PENDING_OWNERSHIP_VERIFICATION - UNVERIFIED - UNDER_REVIEW - INACTIVE description: 'Status of an external account. `PENDING_OWNERSHIP_VERIFICATION`: the wallet''s ownership must be verified (e.g. under the EU Travel Rule) before unrestricted use; transfers below regulatory thresholds are still allowed. `UNVERIFIED`: the most recent verification attempt failed; start a new challenge to retry. Successful verification moves the account to `ACTIVE`. ' BwpExternalAccountInfo: title: BWP Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/BwpAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/BwpBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/BwpBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/BwpBeneficiary' BUSINESS: '#/components/schemas/BwpBusinessBeneficiary' PkrBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' CadAccountInfoBase: type: object required: - accountType - bankCode - branchCode - accountNumber properties: accountType: type: string enum: - CAD_ACCOUNT bankCode: type: string description: Canadian financial institution number (3 digits) example: '001' minLength: 3 maxLength: 3 pattern: ^[0-9]{3}$ branchCode: type: string description: Transit number identifying the branch (5 digits) example: '00012' minLength: 5 maxLength: 5 pattern: ^[0-9]{5}$ accountNumber: type: string description: Bank account number (7-12 digits) example: '1234567' minLength: 7 maxLength: 12 pattern: ^[0-9]{7,12}$ ZarBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' ZmwBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' PhpExternalAccountInfo: title: PHP Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/PhpAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/PhpBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/PhpBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/PhpBeneficiary' BUSINESS: '#/components/schemas/PhpBusinessBeneficiary' BrlBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' BdtAccountInfoBase: type: object required: - accountType - bankName description: 'Required fields depend on the selected paymentRails: - BANK_TRANSFER: accountNumber, bankName - MOBILE_MONEY: bankName, phoneNumber' properties: accountType: type: string enum: - BDT_ACCOUNT accountNumber: type: string description: The account number of the bank minLength: 1 maxLength: 34 bankName: type: string description: The name of the bank. Must be one of the `bankName` values `GET /discoveries` returns for this country and currency. Send it exactly as returned; any other name is rejected. minLength: 1 maxLength: 255 example: BRAC Bank branchCode: type: string description: The branch code minLength: 5 maxLength: 5 pattern: ^[0-9]{5}$ swiftCode: type: string description: The SWIFT/BIC code of the bank example: DEUTDEFF minLength: 8 maxLength: 11 pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$ phoneNumber: type: string description: The phone number in international format example: '+1234567890' minLength: 7 maxLength: 15 pattern: ^\+[0-9]{6,14}$ example: accountType: BDT_ACCOUNT accountNumber: '1234567890' bankName: BRAC Bank branchCode: '11111' swiftCode: DEUTDEFF phoneNumber: '+1234567890' IncomingPaymentWebhookResponse: type: object properties: receiverCustomerInfo: type: object additionalProperties: true description: Information about the recipient, provided by the platform if requested in the webhook via `requestedReceiverCustomerInfoFields` and the payment is approved. CardDeclinedReason: type: string enum: - CARD_NOT_ACTIVE - SPEND_LIMIT_EXCEEDED - INSUFFICIENT_FUNDS - NO_ELIGIBLE_FUNDING_SOURCE - BLOCKED - UNSUPPORTED_NETWORK - INCORRECT_CARD_DETAILS - TEMPORARILY_UNAVAILABLE - OTHER description: 'Why Grid declined a card authorization. Present only when a card transaction''s `status` is `DECLINED`. | Reason | Returned when | |--------|---------------| | `CARD_NOT_ACTIVE` | The card is not `ACTIVE`. A `FROZEN`, `PROCESSING`, `PENDING_KYC`, or `CLOSED` card declines every authorization. | | `SPEND_LIMIT_EXCEEDED` | The authorization exceeds `maxSpendPerTransaction`, `maxSpendPerDay`, `maxTransactionsPerDay`, or the matching platform cap. | | `INSUFFICIENT_FUNDS` | The funding source balance does not cover the authorization. Grid reserves the amount when it decides the authorization, so an underfunded card is declined. | | `NO_ELIGIBLE_FUNDING_SOURCE` | The card has no usable funding source, for example an Embedded Wallet source with no active delegated key. | | `BLOCKED` | Program rules block the merchant category or the transaction. | | `UNSUPPORTED_NETWORK` | Grid does not support the network or the transaction type. | | `INCORRECT_CARD_DETAILS` | The PIN, security code, expiry date, or billing address entered at the merchant did not match the card. | | `TEMPORARILY_UNAVAILABLE` | A temporary problem at Grid, the card processor, or the card network stopped the authorization. The cardholder can try again. | | `OTHER` | Any other reason, including a security or fraud decline the card processor made. | ' CurrencyAmount: type: object required: - amount - currency properties: amount: type: integer format: int64 description: Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC) example: 12550 currency: $ref: '#/components/schemas/Currency' CopAccountInfoBase: type: object required: - accountType - bankName description: 'Required fields depend on the selected paymentRails: - BANK_TRANSFER: accountNumber, bankAccountType, bankName - MOBILE_MONEY: bankName, phoneNumber' properties: accountType: type: string enum: - COP_ACCOUNT accountNumber: type: string description: The account number of the bank minLength: 1 maxLength: 34 bankAccountType: type: string description: The bank account type enum: - CHECKING - SAVINGS bankName: type: string description: The name of the bank. Must be one of the `bankName` values `GET /discoveries` returns for this country and currency. Send it exactly as returned; any other name is rejected. minLength: 1 maxLength: 255 example: Banco de Colombia (Bancolombia) phoneNumber: type: string description: The phone number in international format example: '+1234567890' minLength: 7 maxLength: 15 pattern: ^\+[0-9]{6,14}$ example: accountType: COP_ACCOUNT accountNumber: '1234567890' bankAccountType: CHECKING bankName: Banco de Colombia (Bancolombia) phoneNumber: '+1234567890' BwpBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName - registrationNumber - taxId properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' CardTransactionWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/CardTransaction' type: $ref: '#/components/schemas/CardTransactionWebhookEventType' ArbitrumWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - ARBITRUM_WALLET address: type: string description: Arbitrum wallet address example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' DkkAccountInfoBase: type: object required: - accountType - iban properties: accountType: type: string enum: - DKK_ACCOUNT iban: type: string description: Danish IBAN (18 characters, starting with DK) example: DK5000400040116243 minLength: 18 maxLength: 18 pattern: ^DK[0-9]{16}$ swiftCode: type: string description: The SWIFT/BIC code of the bank example: DABADKKK minLength: 8 maxLength: 11 pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$ example: accountType: DKK_ACCOUNT iban: DK5000400040116243 swiftCode: DABADKKK CustomerType: type: string enum: - INDIVIDUAL - BUSINESS description: Whether the customer is an individual or a business entity example: INDIVIDUAL EgpAccountInfo: allOf: - $ref: '#/components/schemas/EgpAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER - MOBILE_MONEY VerificationErrorType: type: string enum: - MISSING_FIELD - INVALID_FIELD - MISSING_LEGAL_PRESENCE_DOCUMENT - MISSING_CONTROL_STRUCTURE_DOCUMENT - MISSING_OWNERSHIP_STRUCTURE_DOCUMENT - MISSING_PROOF_OF_ADDRESS_DOCUMENT - MISSING_IDENTITY_DOCUMENT - INVALID_DOCUMENT - EXPIRED_DOCUMENT - POOR_QUALITY_DOCUMENT - SUSPECTED_FRAUD_DOCUMENT - WRONG_DOCUMENT_TYPE - INCOMPLETE_DOCUMENT - UNREADABLE_DOCUMENT - DOCUMENT_VERIFICATION_FAILED - APPLICANT_SANCTIONED - APPLICANT_FRAUD - APPLICANT_CRIMINAL_RECORD - APPLICANT_REJECTED - MISSING_BENEFICIAL_OWNER - MISSING_CONTROL_PERSON - MISSING_GOOD_STANDING_DOCUMENT description: Type of verification error. The category-specific MISSING_*_DOCUMENT types indicate which document category is needed. Document quality types (POOR_QUALITY_DOCUMENT, SUSPECTED_FRAUD_DOCUMENT, etc.) indicate specific issues with uploaded documents. APPLICANT_* types indicate issues with the applicant themselves (sanctions, fraud, criminal records). example: MISSING_FIELD GbpBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' BaseWalletExternalAccountInfo: title: Base Wallet allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/BaseWalletInfo' - $ref: '#/components/schemas/WalletBeneficiaryFields' - $ref: '#/components/schemas/WalletCustodyFields' ExternalAccountInfoOneOf: oneOf: - $ref: '#/components/schemas/AedExternalAccountInfo' - $ref: '#/components/schemas/BdtExternalAccountInfo' - $ref: '#/components/schemas/BrlExternalAccountInfo' - $ref: '#/components/schemas/BwpExternalAccountInfo' - $ref: '#/components/schemas/CadExternalAccountInfo' - $ref: '#/components/schemas/CopExternalAccountInfo' - $ref: '#/components/schemas/DkkExternalAccountInfo' - $ref: '#/components/schemas/EgpExternalAccountInfo' - $ref: '#/components/schemas/EurExternalAccountInfo' - $ref: '#/components/schemas/GbpExternalAccountInfo' - $ref: '#/components/schemas/GhsExternalAccountInfo' - $ref: '#/components/schemas/GtqExternalAccountInfo' - $ref: '#/components/schemas/HkdExternalAccountInfo' - $ref: '#/components/schemas/HtgExternalAccountInfo' - $ref: '#/components/schemas/IdrExternalAccountInfo' - $ref: '#/components/schemas/InrExternalAccountInfo' - $ref: '#/components/schemas/JmdExternalAccountInfo' - $ref: '#/components/schemas/KesExternalAccountInfo' - $ref: '#/components/schemas/MwkExternalAccountInfo' - $ref: '#/components/schemas/MxnExternalAccountInfo' - $ref: '#/components/schemas/MyrExternalAccountInfo' - $ref: '#/components/schemas/NgnExternalAccountInfo' - $ref: '#/components/schemas/PhpExternalAccountInfo' - $ref: '#/components/schemas/PkrExternalAccountInfo' - $ref: '#/components/schemas/RwfExternalAccountInfo' - $ref: '#/components/schemas/SgdExternalAccountInfo' - $ref: '#/components/schemas/SlvExternalAccountInfo' - $ref: '#/components/schemas/ThbExternalAccountInfo' - $ref: '#/components/schemas/TzsExternalAccountInfo' - $ref: '#/components/schemas/UgxExternalAccountInfo' - $ref: '#/components/schemas/UsdExternalAccountInfo' - $ref: '#/components/schemas/VndExternalAccountInfo' - $ref: '#/components/schemas/XafExternalAccountInfo' - $ref: '#/components/schemas/XofExternalAccountInfo' - $ref: '#/components/schemas/ZarExternalAccountInfo' - $ref: '#/components/schemas/ZmwExternalAccountInfo' - $ref: '#/components/schemas/SwiftExternalAccountInfo' - $ref: '#/components/schemas/BaseWalletExternalAccountInfo' - $ref: '#/components/schemas/EthereumWalletExternalAccountInfo' - $ref: '#/components/schemas/LightningExternalAccountInfo' - $ref: '#/components/schemas/PolygonWalletExternalAccountInfo' - $ref: '#/components/schemas/PlasmaWalletExternalAccountInfo' - $ref: '#/components/schemas/ArbitrumWalletExternalAccountInfo' - $ref: '#/components/schemas/SolanaWalletExternalAccountInfo' - $ref: '#/components/schemas/SparkWalletExternalAccountInfo' - $ref: '#/components/schemas/TronWalletExternalAccountInfo' - $ref: '#/components/schemas/CnyExternalAccountInfo' - $ref: '#/components/schemas/IlsExternalAccountInfo' - $ref: '#/components/schemas/TryExternalAccountInfo' discriminator: propertyName: accountType mapping: AED_ACCOUNT: '#/components/schemas/AedExternalAccountInfo' BDT_ACCOUNT: '#/components/schemas/BdtExternalAccountInfo' BRL_ACCOUNT: '#/components/schemas/BrlExternalAccountInfo' BWP_ACCOUNT: '#/components/schemas/BwpExternalAccountInfo' CAD_ACCOUNT: '#/components/schemas/CadExternalAccountInfo' COP_ACCOUNT: '#/components/schemas/CopExternalAccountInfo' DKK_ACCOUNT: '#/components/schemas/DkkExternalAccountInfo' EGP_ACCOUNT: '#/components/schemas/EgpExternalAccountInfo' EUR_ACCOUNT: '#/components/schemas/EurExternalAccountInfo' GBP_ACCOUNT: '#/components/schemas/GbpExternalAccountInfo' GHS_ACCOUNT: '#/components/schemas/GhsExternalAccountInfo' GTQ_ACCOUNT: '#/components/schemas/GtqExternalAccountInfo' HKD_ACCOUNT: '#/components/schemas/HkdExternalAccountInfo' HTG_ACCOUNT: '#/components/schemas/HtgExternalAccountInfo' IDR_ACCOUNT: '#/components/schemas/IdrExternalAccountInfo' INR_ACCOUNT: '#/components/schemas/InrExternalAccountInfo' JMD_ACCOUNT: '#/components/schemas/JmdExternalAccountInfo' KES_ACCOUNT: '#/components/schemas/KesExternalAccountInfo' MWK_ACCOUNT: '#/components/schemas/MwkExternalAccountInfo' MXN_ACCOUNT: '#/components/schemas/MxnExternalAccountInfo' MYR_ACCOUNT: '#/components/schemas/MyrExternalAccountInfo' NGN_ACCOUNT: '#/components/schemas/NgnExternalAccountInfo' PHP_ACCOUNT: '#/components/schemas/PhpExternalAccountInfo' PKR_ACCOUNT: '#/components/schemas/PkrExternalAccountInfo' RWF_ACCOUNT: '#/components/schemas/RwfExternalAccountInfo' SGD_ACCOUNT: '#/components/schemas/SgdExternalAccountInfo' SLV_ACCOUNT: '#/components/schemas/SlvExternalAccountInfo' THB_ACCOUNT: '#/components/schemas/ThbExternalAccountInfo' TZS_ACCOUNT: '#/components/schemas/TzsExternalAccountInfo' UGX_ACCOUNT: '#/components/schemas/UgxExternalAccountInfo' USD_ACCOUNT: '#/components/schemas/UsdExternalAccountInfo' VND_ACCOUNT: '#/components/schemas/VndExternalAccountInfo' XAF_ACCOUNT: '#/components/schemas/XafExternalAccountInfo' XOF_ACCOUNT: '#/components/schemas/XofExternalAccountInfo' ZAR_ACCOUNT: '#/components/schemas/ZarExternalAccountInfo' ZMW_ACCOUNT: '#/components/schemas/ZmwExternalAccountInfo' SWIFT_ACCOUNT: '#/components/schemas/SwiftExternalAccountInfo' BASE_WALLET: '#/components/schemas/BaseWalletExternalAccountInfo' ETHEREUM_WALLET: '#/components/schemas/EthereumWalletExternalAccountInfo' LIGHTNING: '#/components/schemas/LightningExternalAccountInfo' LIGHTNING_ACCOUNT: '#/components/schemas/LightningExternalAccountInfo' POLYGON_WALLET: '#/components/schemas/PolygonWalletExternalAccountInfo' PLASMA_WALLET: '#/components/schemas/PlasmaWalletExternalAccountInfo' ARBITRUM_WALLET: '#/components/schemas/ArbitrumWalletExternalAccountInfo' SOLANA_WALLET: '#/components/schemas/SolanaWalletExternalAccountInfo' SPARK_WALLET: '#/components/schemas/SparkWalletExternalAccountInfo' TRON_WALLET: '#/components/schemas/TronWalletExternalAccountInfo' CNY_ACCOUNT: '#/components/schemas/CnyExternalAccountInfo' ILS_ACCOUNT: '#/components/schemas/IlsExternalAccountInfo' TRY_ACCOUNT: '#/components/schemas/TryExternalAccountInfo' VndAccountInfoBase: type: object required: - accountType - bankName - accountNumber - swiftCode properties: accountType: type: string enum: - VND_ACCOUNT bankName: type: string description: The name of the bank. Must be one of the `bankName` values `GET /discoveries` returns for this country and currency. Send it exactly as returned; any other name is rejected. minLength: 1 maxLength: 255 example: Vietcombank accountNumber: type: string description: Vietnamese bank account number minLength: 1 maxLength: 34 example: '1234567890' swiftCode: type: string description: The SWIFT/BIC code of the bank example: BFTVVNVX minLength: 8 maxLength: 11 pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$ example: accountType: VND_ACCOUNT bankName: Vietcombank accountNumber: '1234567890' swiftCode: BFTVVNVX LightningInfo: type: object description: 'Lightning payment destination. Exactly one of `invoice`, `bolt12`, or `lightningAddress` must be provided. ' required: - accountType properties: accountType: type: string enum: - LIGHTNING invoice: type: string description: 1-time use lightning bolt11 invoice payout destination example: lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs bolt12: type: string description: A bolt12 offer which can be reused as a payment destination example: lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs lightningAddress: type: string description: A lightning address which can be used as a payment destination. Note that for UMA addresses, no external account is needed. You can use the UMA address directly as a destination. example: john.doe@lightningwallet.com HtgBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' MwkAccountInfoBase: type: object required: - accountType - phoneNumber - provider properties: accountType: type: string enum: - MWK_ACCOUNT phoneNumber: type: string description: The phone number in international format example: '+1234567890' minLength: 7 maxLength: 15 pattern: ^\+[0-9]{6,14}$ provider: type: string description: The mobile money provider name minLength: 1 maxLength: 255 example: accountType: MWK_ACCOUNT phoneNumber: '+1234567890' provider: Example Provider ContactVerificationStatus: type: string description: Status of an individual contact-verification channel (email or phone). `PENDING` means verification is required but not yet completed; `VERIFIED` means the channel has been confirmed. enum: - PENDING - VERIFIED example: VERIFIED DocumentType: type: string enum: - PASSPORT - DRIVERS_LICENSE - NATIONAL_ID - PROOF_OF_ADDRESS - BANK_STATEMENT - TAX_RETURN - CERTIFICATE_OF_INCORPORATION - ARTICLES_OF_INCORPORATION - ARTICLES_OF_ASSOCIATION - STATE_REGISTRY_EXCERPT - GOOD_STANDING_CERTIFICATE - INFORMATION_STATEMENT - INCUMBENCY_CERTIFICATE - BUSINESS_LICENSE - SHAREHOLDER_REGISTER - POWER_OF_ATTORNEY - UTILITY_BILL - ELECTRICITY_BILL - RENT_OR_LEASE_AGREEMENT - DIRECTOR_REGISTRY - TRUST_AGREEMENT - STATE_COMPANY_REGISTRY - PARTNERSHIP_CONTROL_AGREEMENT - PARTNERSHIP_AGREEMENT - SELFIE - OTHER description: 'Type of identity or business verification document. Document types are grouped by verification category: **Identity** — PASSPORT, DRIVERS_LICENSE, NATIONAL_ID **Business — Legal presence** — CERTIFICATE_OF_INCORPORATION, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, STATE_REGISTRY_EXCERPT **Business — Control structure** — DIRECTOR_REGISTRY, TRUST_AGREEMENT, STATE_COMPANY_REGISTRY, PARTNERSHIP_CONTROL_AGREEMENT **Business — Ownership structure** — SHAREHOLDER_REGISTER, TRUST_AGREEMENT, PARTNERSHIP_AGREEMENT **Proof of address** — UTILITY_BILL, RENT_OR_LEASE_AGREEMENT, ELECTRICITY_BILL, BANK_STATEMENT, TAX_RETURN' example: PASSPORT CopBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' documentType: type: string maxLength: 32 description: Identity document type (Colombia) enum: - CC - CE - TI - NIT - PP documentNumber: type: string maxLength: 50 description: The identity document number minLength: 1 BasePaymentAccountInfo: type: object required: - accountType properties: accountType: $ref: '#/components/schemas/PaymentAccountType' PaymentPolygonWalletInfo: title: Polygon Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/PolygonWalletInfo' - type: object properties: assetType: type: string description: Type of asset enum: - USDC DestinationType: type: string enum: - ACCOUNT - UMA_ADDRESS description: Type of payment destination example: ACCOUNT SolanaWalletExternalAccountInfo: title: Solana Wallet allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/SolanaWalletInfo' - $ref: '#/components/schemas/WalletBeneficiaryFields' - $ref: '#/components/schemas/WalletCustodyFields' FieldError: type: object required: - field description: One field-level validation failure. Field-validation errors on submit endpoints (e.g. `POST /customers`, `PATCH /customers/{id}`) emit an array of these under `details.errors` so platforms can render form-field-level UX for every failure in a single round-trip. properties: field: type: string description: Dot-notation path to the offending field. example: identifier constraint: $ref: '#/components/schemas/FieldConstraint' message: type: string description: Human-readable explanation of what's wrong with this field. example: Value is not one of the allowed enum members. ThbBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' LightningExternalAccountInfo: title: Lightning allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/LightningInfo' HtgAccountInfoBase: type: object required: - accountType - phoneNumber properties: accountType: type: string enum: - HTG_ACCOUNT phoneNumber: type: string description: The phone number in international format example: '+1234567890' minLength: 7 maxLength: 15 pattern: ^\+[0-9]{6,14}$ example: accountType: HTG_ACCOUNT phoneNumber: '+1234567890' TestWebhookRequest: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object properties: type: type: string enum: - TEST EndUserTermsConsent: type: object deprecated: true required: - acceptedAt - ipAddress - termsVersion - acceptanceMethod description: Deprecated; use `agreementConsents` instead, which records acceptance of each agreement separately. Reported only for a customer whose acceptance predates that field, and always as the `LIGHTSPARK_END_USER_TERMS` agreement. properties: acceptedAt: type: string format: date-time description: Date and time when the customer accepted the End User Terms. ipAddress: type: string maxLength: 45 description: IP address of the device the customer used when accepting the terms. example: 198.51.100.24 termsVersion: type: string description: Version identifier of the accepted Grid End User Terms. example: V1 acceptanceMethod: $ref: '#/components/schemas/AgreementAcceptanceMethod' JmdExternalAccountInfo: title: JMD Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/JmdAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/JmdBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/BusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/JmdBeneficiary' BUSINESS: '#/components/schemas/BusinessBeneficiary' InternalAccountStatusWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/InternalAccount' type: $ref: '#/components/schemas/InternalAccountStatusWebhookEventType' BaseTransactionDestination: type: object required: - destinationType properties: destinationType: $ref: '#/components/schemas/TransactionDestinationType' currency: type: string description: Currency code for the destination example: EUR CustomerEdd: type: object description: Enhanced-due-diligence (EDD) fields available as optional patchable attributes on an individual customer. Referenced via `allOf` from `IndividualCustomerFields`, so these appear as top-level optional fields on the customer resource itself; there is no separate EDD resource. The specific set required for a given customer is driven by the KYC provider's per-jurisdiction / per-flow / per-volume-tier rules (surfaced through `MISSING_FIELD` errors on `POST /verifications`). properties: sourceOfFundsCategories: type: array minItems: 1 items: $ref: '#/components/schemas/IndividualSourceOfFundsCategory' description: Structured source-of-funds categories (FLOW of funds for this account). example: - SALARY sourceOfFundsOtherDescription: type: string maxLength: 500 description: Free-form description of the customer's source of funds. Required when `sourceOfFundsCategories` includes `OTHER`; otherwise omitted. example: Contest winnings sourceOfWealthCategories: type: array minItems: 1 items: $ref: '#/components/schemas/SourceOfWealthCategory' description: Structured source-of-wealth categories (STOCK — origin of accumulated wealth). example: - SALARY - INVESTMENTS sourceOfWealthOtherDescription: type: string maxLength: 500 description: Free-form description of the customer's source of wealth. Required when `sourceOfWealthCategories` includes `OTHER`; otherwise omitted. example: Royalty income from published works purposeOfAccount: $ref: '#/components/schemas/PurposeOfAccount' purposeOfAccountOtherDescription: type: string maxLength: 500 description: Free-form description of the customer's intended purpose for the Grid account. Required when `purposeOfAccount` is `OTHER`; otherwise omitted. example: Household budgeting between spouses expectedMonthlyTransactionCount: $ref: '#/components/schemas/ExpectedMonthlyTransactionCount' expectedMonthlyTransactionVolume: $ref: '#/components/schemas/ExpectedMonthlyTransactionVolume' annualIncomeRange: $ref: '#/components/schemas/AnnualIncomeRange' netWorthRange: $ref: '#/components/schemas/NetWorthRange' pepStatus: $ref: '#/components/schemas/PepStatus' CustomerWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/CustomerOneOf' type: $ref: '#/components/schemas/CustomerWebhookEventType' PaymentInstructions: type: object required: - accountOrWalletInfo properties: instructionsNotes: type: string description: Additional human-readable instructions for making the payment example: Please ensure the reference code is included in the payment memo/description field isPlatformAccount: type: boolean description: Indicates whether the account is a platform account or a customer account. example: true accountOrWalletInfo: description: Where to send the funds. Quotes can carry any of these types. Internal accounts return only `USD_ACCOUNT`, `EUR_ACCOUNT`, `SWIFT_ACCOUNT`, and the network wallet types; MXN, BRL, COP, ARS, Lightning, and Bitcoin L1 instructions appear only on real-time funded quotes. oneOf: - $ref: '#/components/schemas/PaymentUsdAccountInfo' - $ref: '#/components/schemas/PaymentEurAccountInfo' - $ref: '#/components/schemas/PaymentSwiftAccountInfo' - $ref: '#/components/schemas/PaymentMxnAccountInfo' - $ref: '#/components/schemas/PaymentBrlAccountInfo' - $ref: '#/components/schemas/PaymentCopAccountInfo' - $ref: '#/components/schemas/PaymentArsAccountInfo' - $ref: '#/components/schemas/PaymentSparkWalletInfo' - $ref: '#/components/schemas/PaymentLightningInvoiceInfo' - $ref: '#/components/schemas/PaymentBitcoinDepositAddressInfo' - $ref: '#/components/schemas/PaymentSolanaWalletInfo' - $ref: '#/components/schemas/PaymentEthereumWalletInfo' - $ref: '#/components/schemas/PaymentBaseWalletInfo' - $ref: '#/components/schemas/PaymentPolygonWalletInfo' - $ref: '#/components/schemas/PaymentArbitrumWalletInfo' - $ref: '#/components/schemas/PaymentTronWalletInfo' - $ref: '#/components/schemas/PaymentPlasmaWalletInfo' - $ref: '#/components/schemas/PaymentEmbeddedWalletInfo' discriminator: propertyName: accountType mapping: USD_ACCOUNT: '#/components/schemas/PaymentUsdAccountInfo' EUR_ACCOUNT: '#/components/schemas/PaymentEurAccountInfo' SWIFT_ACCOUNT: '#/components/schemas/PaymentSwiftAccountInfo' MXN_ACCOUNT: '#/components/schemas/PaymentMxnAccountInfo' BRL_ACCOUNT: '#/components/schemas/PaymentBrlAccountInfo' COP_ACCOUNT: '#/components/schemas/PaymentCopAccountInfo' ARS_ACCOUNT: '#/components/schemas/PaymentArsAccountInfo' SPARK_WALLET: '#/components/schemas/PaymentSparkWalletInfo' LIGHTNING: '#/components/schemas/PaymentLightningInvoiceInfo' BITCOIN_L1: '#/components/schemas/PaymentBitcoinDepositAddressInfo' SOLANA_WALLET: '#/components/schemas/PaymentSolanaWalletInfo' ETHEREUM_WALLET: '#/components/schemas/PaymentEthereumWalletInfo' BASE_WALLET: '#/components/schemas/PaymentBaseWalletInfo' POLYGON_WALLET: '#/components/schemas/PaymentPolygonWalletInfo' ARBITRUM_WALLET: '#/components/schemas/PaymentArbitrumWalletInfo' TRON_WALLET: '#/components/schemas/PaymentTronWalletInfo' PLASMA_WALLET: '#/components/schemas/PaymentPlasmaWalletInfo' EMBEDDED_WALLET: '#/components/schemas/PaymentEmbeddedWalletInfo' AedBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - address - legalName properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' WebhookType: type: string enum: - OUTGOING_PAYMENT.PENDING - OUTGOING_PAYMENT.PENDING_AUTHORIZATION - OUTGOING_PAYMENT.PROCESSING - OUTGOING_PAYMENT.COMPLETED - OUTGOING_PAYMENT.FAILED - OUTGOING_PAYMENT.EXPIRED - OUTGOING_PAYMENT.REFUND_PENDING - OUTGOING_PAYMENT.REFUND_COMPLETED - OUTGOING_PAYMENT.REFUND_FAILED - INCOMING_PAYMENT.PENDING - INCOMING_PAYMENT.PROCESSING - INCOMING_PAYMENT.COMPLETED - INCOMING_PAYMENT.FAILED - INCOMING_PAYMENT.REFUND_PENDING - INCOMING_PAYMENT.REFUND_COMPLETED - INCOMING_PAYMENT.REFUND_FAILED - CUSTOMER.KYC_APPROVED - CUSTOMER.KYC_REJECTED - CUSTOMER.KYC_PENDING - CUSTOMER.KYB_APPROVED - CUSTOMER.KYB_REJECTED - CUSTOMER.KYB_PENDING - VERIFICATION.APPROVED - VERIFICATION.REJECTED - VERIFICATION.RESOLVE_ERRORS - VERIFICATION.IN_PROGRESS - VERIFICATION.PENDING_MANUAL_REVIEW - VERIFICATION.READY_FOR_VERIFICATION - EXTERNAL_ACCOUNT.STATUS_UPDATED - EXTERNAL_ACCOUNT.ACCOUNT_INFO_UPDATED - INTERNAL_ACCOUNT.BALANCE_UPDATED - INTERNAL_ACCOUNT.STATUS_UPDATED - INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED - INVITATION.CLAIMED - BULK_UPLOAD.COMPLETED - BULK_UPLOAD.FAILED - AGENT_ACTION.PENDING_APPROVAL - AGENT_ACTION.APPROVED - AGENT_ACTION.REJECTED - AGENT_ACTION.FAILED - CARD.STATUS_CHANGE - CARD.PIN_STATUS_CHANGE - CARD_TRANSACTION.AUTHORIZED - CARD_TRANSACTION.PARTIALLY_SETTLED - CARD_TRANSACTION.SETTLED - CARD_TRANSACTION.DECLINED - CARD_TRANSACTION.VOIDED - CARD_TRANSACTION.EXCEPTION - WALLET_OPERATION.COMPLETED - WALLET_OPERATION.FAILED - TEST description: Type of webhook event in OBJECT.EVENT dot-notation. The part before the dot identifies the resource, the part after identifies the event. This lets consumers route purely on type without inspecting data.status. TzsAccountInfoBase: type: object required: - accountType - phoneNumber - provider properties: accountType: type: string enum: - TZS_ACCOUNT phoneNumber: type: string description: Tanzanian mobile money phone number example: '+255712345678' minLength: 7 maxLength: 15 pattern: ^\+255[0-9]{9}$ provider: type: string description: The mobile money provider name minLength: 1 maxLength: 255 example: accountType: TZS_ACCOUNT phoneNumber: '+255712345678' provider: Example Provider AccountDestination: title: Account allOf: - $ref: '#/components/schemas/BaseDestination' - type: object required: - accountId - destinationType properties: destinationType: type: string enum: - ACCOUNT accountId: type: string description: Destination account identifier example: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123 paymentRail: allOf: - $ref: '#/components/schemas/PaymentRail' - description: The payment rail to use for the transfer. Must be one of the rails supported by the destination account. If not specified, the system will select a default rail. description: Destination account details CounterpartyInformation: type: object description: Additional information about the counterparty, if available and relevant to the transaction and platform. additionalProperties: true example: FULL_NAME: John Sender BIRTH_DATE: '1985-06-15' NATIONALITY: DE CustomerWebhookEventType: type: string enum: - CUSTOMER.KYC_APPROVED - CUSTOMER.KYC_REJECTED - CUSTOMER.KYC_PENDING - CUSTOMER.KYB_APPROVED - CUSTOMER.KYB_REJECTED - CUSTOMER.KYB_PENDING BrlBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' PaymentSwiftAccountInfo: title: SWIFT Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/SwiftAccountInfo' - type: object required: - accountHolderName properties: accountHolderName: type: string description: The name of the account holder as it must appear on the wire. Remitting banks match this against the beneficiary name field, so payers should copy it exactly. example: Acme Exports Pte Ltd minLength: 1 maxLength: 255 bankAddress: type: string description: The address of the bank holding the account, when known. example: 12 Marina Boulevard, Singapore 018982 minLength: 1 maxLength: 1024 reference: type: string description: Reference code to include with the payment when present. SWIFT payments are attributed by the destination account number/IBAN, so this account type typically requires no reference. example: UMA-Q12345-REF BeneficialOwnerPersonalInfo: type: object required: - firstName - lastName - birthDate - nationality - address - idType - identifier properties: firstName: type: string maxLength: 250 description: First name of the individual example: Jane middleName: type: string maxLength: 250 description: Middle name of the individual example: Marie lastName: type: string maxLength: 250 description: Last name of the individual example: Smith birthDate: type: string format: date description: Date of birth in ISO 8601 format (YYYY-MM-DD) example: '1978-06-15' nationality: type: string description: Country of nationality (ISO 3166-1 alpha-2) example: US email: type: string format: email maxLength: 255 description: Email address of the individual example: jane.smith@acmecorp.com phoneNumber: type: string description: Phone number in E.164 format example: '+14155550192' pattern: ^\+[1-9]\d{1,14}$ address: $ref: '#/components/schemas/Address' idType: $ref: '#/components/schemas/IdentificationType' identifier: type: string maxLength: 100 description: The identification number or value example: 123-45-6789 countryOfIssuance: type: string description: Country that issued the identification (ISO 3166-1 alpha-2) example: US TryAccountInfo: allOf: - $ref: '#/components/schemas/TryAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER EgpBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' AccountQuoteSource: title: Account allOf: - $ref: '#/components/schemas/BaseQuoteSource' - type: object required: - accountId - sourceType properties: sourceType: type: string enum: - ACCOUNT accountId: type: string description: Source account identifier example: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 customerId: type: string description: The customer on whose behalf the transaction is being initiated. Required when funding from a `BULK_SETTLEMENT` account. The customer is never the account owner, because the platform owns the account. When funding from an FBO account, this field is optional. If you omit it, the transaction is initiated on behalf of the platform. For any other account, it defaults to the account owner's customerId. example: Customer:019542f5-b3e7-1d02-0000-000000000001 description: Source account details CardPinStatus: type: string enum: - NOT_SET - OK - BLOCKED example: OK description: 'State of the card''s PIN. On the Card resource, this is the last known status and is present whenever PIN management is supported. An absent value means PIN management is unavailable for this card; it does not mean `NOT_SET`. Use `GET /cards/{id}` to retrieve `pinStatus`. | Status | Description | |--------|-------------| | `NOT_SET` | No PIN has been set on the card. PIN verification is not enabled. Set one with `POST /cards/{id}/set-pin` or the hosted form returned by `GET /cards/{id}/pin-entry-url`. | | `OK` | A PIN is set and usable. | | `BLOCKED` | The PIN was entered incorrectly three consecutive times and is refused until cleared with `POST /cards/{id}/pin/unblock`, or replaced with `POST /cards/{id}/set-pin`. | ' Address: type: object required: - line1 - postalCode - country properties: line1: type: string description: Street address line 1 example: 123 Main Street line2: type: string description: Street address line 2 example: Apt 4B city: type: string description: City example: San Francisco state: type: string description: State/Province/Region example: CA postalCode: type: string description: Postal/ZIP code example: '94105' country: type: string description: Country code (ISO 3166-1 alpha-2) example: US CardTransactionWebhookEventType: type: string enum: - CARD_TRANSACTION.AUTHORIZED - CARD_TRANSACTION.PARTIALLY_SETTLED - CARD_TRANSACTION.SETTLED - CARD_TRANSACTION.DECLINED - CARD_TRANSACTION.VOIDED - CARD_TRANSACTION.EXCEPTION PepStatus: type: string enum: - NONE - DOMESTIC - FOREIGN - HIO - FAMILY_OR_ASSOCIATE description: Political exposure declaration (Politically Exposed Person status). `HIO` = head of an international organization. `FAMILY_OR_ASSOCIATE` covers close family members and known close associates of a PEP. example: NONE MyrAccountInfo: allOf: - $ref: '#/components/schemas/MyrAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER NgnBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' InternalAccount: type: object required: - id - type - status - balance - totalBalance - fundingPaymentInstructions - createdAt - updatedAt properties: id: type: string description: The ID of the internal account example: InternalAccount:12dcbd6-dced-4ec4-b756-3c3a9ea3d123 customerId: type: string description: The ID of the customer associated with the internal account. If this field is empty, the internal account belongs to the platform. example: Customer:019542f5-b3e7-1d02-0000-000000000001 type: $ref: '#/components/schemas/InternalAccountType' status: $ref: '#/components/schemas/InternalAccountStatus' balance: $ref: '#/components/schemas/CurrencyAmount' description: The balance available to spend, excluding pending and held funds totalBalance: $ref: '#/components/schemas/CurrencyAmount' description: The total balance, including pending and held funds fundingPaymentInstructions: type: array description: Payment instructions for funding the account. Empty while funding is withheld. Only bank (`USD_ACCOUNT`, `EUR_ACCOUNT`, `SWIFT_ACCOUNT`) and network wallet types appear here. items: $ref: '#/components/schemas/PaymentInstructions' onBehalfOfCustomerId: type: string description: The customer whose payments this platform-owned account receives. Only set by regulated financial institutions. Omitted for accounts that name no such customer, which includes every account owned by a customer. example: Customer:019542f5-b3e7-1d02-0000-000000000002 label: type: string maxLength: 255 description: The platform-supplied label recorded when the account was created. Null for accounts that carry none. example: invoice-4417 sweepRule: allOf: - $ref: '#/components/schemas/SweepRule' description: The routing rule attached to this account. Null for accounts that carry no rule, which is every account other than a `RULE_BASED` one. privateEnabled: type: boolean description: Whether wallet privacy is enabled for the Embedded Wallet. Only present for `EMBEDDED_WALLET` internal accounts. example: true cardCapabilities: $ref: '#/components/schemas/CardCapabilities' description: Actions supported for a card issued now with this account as its funding source. They can change if the platform's card routing changes and do not describe cards already issued using the account. The funding source a create request supplies selects the issuer and therefore the resulting card's capabilities; read this field from that account. Absent when this account cannot fund a card. createdAt: type: string format: date-time description: Timestamp when the internal account was created example: '2025-10-03T12:30:00Z' updatedAt: type: string format: date-time description: Timestamp when the internal account was last updated example: '2025-10-03T12:30:00Z' MwkBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName - registrationNumber - taxId properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' WalletOperationFailedData: title: Wallet Operation Failed Data type: object required: - operationId - requestId - operationType - resourceType - resourceId - status - error properties: operationId: type: string description: Grid-internal identifier for this operation. Useful when contacting support about a specific operation; not a correlation key — use `requestId` to match this webhook to the request you made. example: Operation:019542f5-b3e7-1d02-0000-000000000099 requestId: type: string description: 'The `Request-Id` you supplied on the signed retry that produced this terminal result — the same value you would have echoed on every retry had you received a `200 { status: "PROCESSING" }` response while it was settling. This is the primary way to correlate this webhook to the request you made.' example: Request:9f7a2c10-5e88-4fb1-bd0e-1c3a8e7b2d45 operationType: type: string description: The kind of operation that reached a terminal state. enum: - auth_credential.create - auth_credential.delete - session.revoke - wallet.export - customer.contact_update example: wallet.export resourceType: $ref: '#/components/schemas/WalletOperationResourceType' resourceId: type: string description: LSID of the business resource this operation affected. For `auth_credential.create`, this is the **primary way to learn the new credential's id** — the request that created it can't have supplied one in advance. For `auth_credential.delete` and `session.revoke` it echoes the `AuthMethod:` / `Session:` you already knew and referenced in the request; for `wallet.export` it's the `InternalAccount:` whose wallet was exported; for `customer.contact_update` it's the `Customer:` whose email or phone number changed. example: InternalAccount:019542f5-b3e7-1d02-0000-00000000009a status: type: string enum: - failed description: Terminal status of the operation. example: failed error: $ref: '#/components/schemas/OperationError' VerificationWebhookEventType: type: string enum: - VERIFICATION.APPROVED - VERIFICATION.REJECTED - VERIFICATION.RESOLVE_ERRORS - VERIFICATION.IN_PROGRESS - VERIFICATION.PENDING_MANUAL_REVIEW XafBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName - registrationNumber - taxId properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' TransactionSourceOneOf: oneOf: - $ref: '#/components/schemas/AccountTransactionSource' - $ref: '#/components/schemas/UmaAddressTransactionSource' - $ref: '#/components/schemas/RealtimeFundingTransactionSource' discriminator: propertyName: sourceType mapping: ACCOUNT: '#/components/schemas/AccountTransactionSource' UMA_ADDRESS: '#/components/schemas/UmaAddressTransactionSource' REALTIME_FUNDING: '#/components/schemas/RealtimeFundingTransactionSource' MxnAccountInfoBase: type: object required: - accountType - clabeNumber properties: accountType: type: string enum: - MXN_ACCOUNT clabeNumber: type: string description: The CLABE number of the bank example: '123456789012345678' minLength: 18 maxLength: 18 pattern: ^[0-9]{18}$ example: accountType: MXN_ACCOUNT clabeNumber: '123456789012345678' ExternalAccountType: type: string enum: - AED_ACCOUNT - BDT_ACCOUNT - BRL_ACCOUNT - BWP_ACCOUNT - CAD_ACCOUNT - COP_ACCOUNT - DKK_ACCOUNT - EGP_ACCOUNT - EUR_ACCOUNT - GBP_ACCOUNT - GHS_ACCOUNT - GTQ_ACCOUNT - HKD_ACCOUNT - HTG_ACCOUNT - IDR_ACCOUNT - INR_ACCOUNT - JMD_ACCOUNT - KES_ACCOUNT - MWK_ACCOUNT - MXN_ACCOUNT - MYR_ACCOUNT - NGN_ACCOUNT - PHP_ACCOUNT - PKR_ACCOUNT - RWF_ACCOUNT - SGD_ACCOUNT - SLV_ACCOUNT - THB_ACCOUNT - TZS_ACCOUNT - UGX_ACCOUNT - USD_ACCOUNT - VND_ACCOUNT - XAF_ACCOUNT - XOF_ACCOUNT - ZAR_ACCOUNT - ZMW_ACCOUNT - SWIFT_ACCOUNT - BASE_WALLET - ETHEREUM_WALLET - LIGHTNING - PLASMA_WALLET - ARBITRUM_WALLET - POLYGON_WALLET - SOLANA_WALLET - SPARK_WALLET - TRON_WALLET - CNY_ACCOUNT - ILS_ACCOUNT - TRY_ACCOUNT description: Type of external account or wallet example: AED_ACCOUNT NetWorthRange: type: string enum: - UNDER_100K - RANGE_100K_500K - RANGE_500K_1M - RANGE_1M_5M - RANGE_5M_25M - OVER_25M description: Bucketed total net worth (USD equivalent). Used for enhanced due diligence on higher-risk profiles. example: RANGE_500K_1M UgxAccountInfoBase: type: object required: - accountType - phoneNumber - provider properties: accountType: type: string enum: - UGX_ACCOUNT phoneNumber: type: string description: The phone number in international format example: '+1234567890' minLength: 7 maxLength: 15 pattern: ^\+[0-9]{6,14}$ provider: type: string description: The mobile money provider name minLength: 1 maxLength: 255 example: accountType: UGX_ACCOUNT phoneNumber: '+1234567890' provider: Example Provider RwfAccountInfo: allOf: - $ref: '#/components/schemas/RwfAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - MOBILE_MONEY PaymentArsAccountInfo: title: ARS Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - type: object required: - accountNumber properties: accountType: type: string enum: - ARS_ACCOUNT accountNumber: type: string description: The static CVU (Clave Virtual Uniforme) bank account number to pay to. minLength: 22 maxLength: 22 pattern: ^\d{22}$ example: '0000003100074052501434' BeneficialOwnerRole: type: string enum: - UBO - DIRECTOR - COMPANY_OFFICER - CONTROL_PERSON - TRUSTEE - GENERAL_PARTNER description: Role of the beneficial owner within the business example: UBO KesBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' TzsAccountInfo: allOf: - $ref: '#/components/schemas/TzsAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - MOBILE_MONEY UsdAccountInfo: allOf: - $ref: '#/components/schemas/UsdAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - ACH - ACH_SAME_DAY - WIRE - RTP - FEDNOW bankAccountType: type: string description: Whether the account is a checking or a savings account. Grid uses this to set the ACH transaction code, so a value that does not match the account causes the receiving bank to return a notification of change. enum: - CHECKING - SAVINGS example: CHECKING UmaAddressTransactionDestination: title: UMA Address Destination allOf: - $ref: '#/components/schemas/BaseTransactionDestination' - type: object required: - umaAddress - destinationType properties: destinationType: type: string enum: - UMA_ADDRESS umaAddress: type: string description: UMA address of the recipient example: $receiver@uma.domain.com description: UMA address destination details UgxExternalAccountInfo: title: UGX Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/UgxAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/UgxBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/UgxBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/UgxBeneficiary' BUSINESS: '#/components/schemas/UgxBusinessBeneficiary' HtgExternalAccountInfo: title: HTG Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/HtgAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/HtgBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/BusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/HtgBeneficiary' BUSINESS: '#/components/schemas/BusinessBeneficiary' IdrAccountInfo: allOf: - $ref: '#/components/schemas/IdrAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER VerificationWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/Verification' type: $ref: '#/components/schemas/VerificationWebhookEventType' CardStatus: type: string enum: - PENDING_KYC - PROCESSING - PENDING_AUTH - ACTIVE - FROZEN - CLOSED description: 'Lifecycle status of a card. | Status | Description | |-------|-------------| | `PENDING_KYC` | The cardholder has not yet completed KYC. Cards in this status cannot transact. | | `PROCESSING` | The card has been requested and is being provisioned with the issuer. | | `PENDING_AUTH` | The issuer has provisioned the card, but its USDB Embedded Wallet funding source lacks an active delegated signing key. Complete `POST /auth/delegated-keys` before using the card. | | `ACTIVE` | The card is live and can authorize transactions. | | `FROZEN` | The card is temporarily disabled by the platform or by Grid. New authorizations are declined with `cardDeclinedReason: CARD_NOT_ACTIVE`. Existing settlements and refunds continue to reconcile. A card Grid froze for review, or one frozen as `COMPROMISED`, cannot be unfrozen by the platform. | | `CLOSED` | The card is permanently closed. Terminal, irreversible status. | ' MyrBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' InrBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' RealtimeFundingQuoteSource: title: Real-time Funding allOf: - $ref: '#/components/schemas/BaseQuoteSource' - type: object required: - currency - sourceType properties: sourceType: type: string enum: - REALTIME_FUNDING customerId: type: string description: Source customer ID. If this transaction is being initiated on behalf of a customer, this is required. If customerId is not provided, the quote will be created on behalf of the platform itself. example: Customer:019542f5-b3e7-1d02-0000-000000000009 currency: type: string description: Currency code for the funding source. See [Supported Currencies](https://docs.lightspark.com/platform-overview/core-concepts/currencies-and-rails) for the full list of supported fiat and crypto currencies. example: USD cryptoNetwork: type: string description: 'The crypto network to use for the funding source. Required when `currency` is a stablecoin (e.g. USDC, USDT). Specifies which network the customer will deposit on, so the correct deposit address can be generated. Example values: `SOLANA`, `ETHEREUM`, `BASE`, `POLYGON`, `TRON`, `PLASMA`, `ARBITRUM`, `SPARK`, `LIGHTNING`, `BITCOIN`.' example: SOLANA description: Fund the quote using a real-time funding source (RTP, SEPA Instant, Spark, Stables, etc.). This will require manual just-in-time funding using `paymentInstructions` in the response. Because quotes expire quickly, this option is only valid for instant payment methods. Do not try to fund a quote with a non-instant payment method (ACH, etc.). CardMerchant: type: object required: - descriptor properties: descriptor: type: string description: Merchant descriptor string captured from the card network at authorization time. On the sandbox simulate endpoints, where this is supplied rather than reported, it must be 1–25 characters — the width of the card network's acceptor-name field. example: BLUE BOTTLE COFFEE SF mcc: type: string description: Merchant Category Code (ISO 18245) — four-digit numeric string. example: '5814' city: type: string description: Merchant city as reported by the card network, when present. example: San Francisco state: type: string description: Merchant state or region as reported by the card network, when present. example: CA country: type: string description: Two-letter ISO 3166-1 alpha-2 country code of the merchant. example: US SourceOfWealthCategory: type: string enum: - SALARY - BUSINESS_INCOME - INVESTMENTS - INHERITANCE - PROPERTY_SALE - GIFT - RETIREMENT - SAVINGS - OTHER description: Origin of the customer's accumulated wealth (STOCK). Distinct from `SourceOfFundsCategory` which describes the FLOW of funds for this specific account. example: SALARY PurposeOfAccount: type: string enum: - CONTRACTOR_PAYOUTS - CREATOR_PAYOUTS - EMPLOYEE_PAYOUTS - MARKETPLACE_SELLER_PAYOUTS - SUPPLIER_PAYMENTS - CROSS_BORDER_B2B - AR_AUTOMATION - AP_AUTOMATION - EMBEDDED_PAYMENTS - PLATFORM_FEE_COLLECTION - P2P_TRANSFERS - CHARITABLE_DONATIONS - OTHER description: The intended purpose for using the Grid account example: CONTRACTOR_PAYOUTS TransactionType: type: string enum: - INCOMING - OUTGOING - CARD description: Type of transaction WalletBeneficiaryOneOf: description: The person or business that owns a crypto wallet external account. oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/WalletIndividualBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/BusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/WalletIndividualBeneficiary' BUSINESS: '#/components/schemas/BusinessBeneficiary' RtpRailDetails: title: RTP Transfer description: An instant payment over The Clearing House RTP network. allOf: - $ref: '#/components/schemas/BaseUsdBankRailDetails' - type: object required: - paymentRail - status properties: paymentRail: type: string enum: - RTP status: $ref: '#/components/schemas/RtpRailStatus' endToEndId: type: string description: The originator's end-to-end reference for the payment. example: E2E-9f2c6b6f remittanceInformation: type: string description: Unstructured remittance information sent with the payment. example: INV-12345 NgnExternalAccountInfo: title: NGN Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/NgnAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/NgnBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/NgnBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/NgnBeneficiary' BUSINESS: '#/components/schemas/NgnBusinessBeneficiary' CardStatusReason: type: string enum: - DELEGATION_REQUIRED - ISSUER_REJECTED - CLOSED_BY_PLATFORM - CLOSED_BY_GRID description: 'Reason a card reached a terminal or non-active status. Present on `PENDING_AUTH` and `CLOSED` cards, and on cards that fail provisioning before reaching `ACTIVE`. | Reason | Description | |--------|-------------| | `DELEGATION_REQUIRED` | The card funding source has no usable delegated signing key. Present while the card is `PENDING_AUTH`. | | `ISSUER_REJECTED` | The card issuer rejected provisioning during `PROCESSING`. | | `CLOSED_BY_PLATFORM` | The card was closed via `PATCH /cards/{id}` (`status: CLOSED`) by the platform. | | `CLOSED_BY_GRID` | The card was closed by Grid (e.g. compliance or risk action). | ' SgdExternalAccountInfo: title: SGD Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/SgdAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/SgdBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/SgdBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/SgdBeneficiary' BUSINESS: '#/components/schemas/SgdBusinessBeneficiary' InrExternalAccountInfo: title: INR Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/InrAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/InrBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/InrBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/InrBeneficiary' BUSINESS: '#/components/schemas/InrBusinessBeneficiary' VerificationError: type: object required: - resourceId - type - reason properties: resourceId: type: string description: ID of the resource with the issue (Customer, BeneficialOwner, or Document) example: Customer:019542f5-b3e7-1d02-0000-000000000001 type: $ref: '#/components/schemas/VerificationErrorType' field: type: string description: Dot-notation path to the field with the issue. Present when type is MISSING_FIELD or INVALID_FIELD. example: customer.address.line1 acceptedDocumentTypes: type: array items: $ref: '#/components/schemas/DocumentType' description: 'Document types that would satisfy this requirement. The integrator can upload any one of the listed types. Present when type is MISSING_LEGAL_PRESENCE_DOCUMENT, MISSING_CONTROL_STRUCTURE_DOCUMENT, MISSING_OWNERSHIP_STRUCTURE_DOCUMENT, MISSING_PROOF_OF_ADDRESS_DOCUMENT, MISSING_IDENTITY_DOCUMENT, INVALID_DOCUMENT, or EXPIRED_DOCUMENT. | Error Type | Accepted Document Types | |---|---| | MISSING_LEGAL_PRESENCE_DOCUMENT | CERTIFICATE_OF_INCORPORATION, ARTICLES_OF_INCORPORATION, ARTICLES_OF_ASSOCIATION, STATE_REGISTRY_EXCERPT | | MISSING_CONTROL_STRUCTURE_DOCUMENT | DIRECTOR_REGISTRY, TRUST_AGREEMENT, STATE_COMPANY_REGISTRY, PARTNERSHIP_CONTROL_AGREEMENT | | MISSING_OWNERSHIP_STRUCTURE_DOCUMENT | SHAREHOLDER_REGISTER, TRUST_AGREEMENT, PARTNERSHIP_AGREEMENT | | MISSING_PROOF_OF_ADDRESS_DOCUMENT | UTILITY_BILL, RENT_OR_LEASE_AGREEMENT, ELECTRICITY_BILL, BANK_STATEMENT, TAX_RETURN | | MISSING_IDENTITY_DOCUMENT | PASSPORT, DRIVERS_LICENSE, NATIONAL_ID |' reason: type: string description: Human-readable description of the issue example: Business address line 1 is required BusinessInfoResponse: type: object description: 'Business information returned on a customer. `taxId` and `incorporatedOn` are required on creation only when the customer''s currency uses direct customer-owned accounts, so both are optional in responses. ' required: - legalName properties: legalName: type: string description: Legal name of the business example: Acme Corporation, Inc. doingBusinessAs: type: string description: Trade name or DBA name of the business, if different from the legal name example: Acme country: type: string description: Country of incorporation or registration (ISO 3166-1 alpha-2) example: US registrationNumber: type: string description: Business registration number example: '5523041' incorporatedOn: type: string format: date description: Date of incorporation in ISO 8601 format (YYYY-MM-DD) example: '2018-03-14' entityType: $ref: '#/components/schemas/EntityType' taxId: type: string description: Tax identification number example: 47-1234567 countriesOfOperation: type: array items: type: string description: List of countries where the business operates (ISO 3166-1 alpha-2) example: - US businessType: $ref: '#/components/schemas/BusinessType' purposeOfAccount: $ref: '#/components/schemas/PurposeOfAccount' sourceOfFunds: type: string description: The primary source of funds for the business example: Funds derived from customer payments for software services expectedMonthlyTransactionCount: $ref: '#/components/schemas/ExpectedMonthlyTransactionCount' expectedMonthlyTransactionVolume: $ref: '#/components/schemas/ExpectedMonthlyTransactionVolume' expectedRecipientJurisdictions: type: array items: type: string description: List of countries where the business expects to send payments (ISO 3166-1 alpha-2) example: - US naicsCode: type: string pattern: ^\d{2,6}$ description: NAICS code describing the nature of the business (2-6 digits) example: '541511' sourceOfFundsCategories: type: array items: $ref: '#/components/schemas/SourceOfFundsCategory' description: Structured source-of-funds categories for the business example: - OPERATING_REVENUE sourceOfFundsOtherDescription: type: string minLength: 1 maxLength: 500 description: Description of the source of funds when OTHER is selected example: Proceeds from a legal settlement purposeOfAccountOtherDescription: type: string minLength: 1 maxLength: 500 description: Description of the account purpose when OTHER is selected example: Escrow for equipment leases expectedCounterpartyCountries: type: array items: type: string description: List of countries of the business's expected transaction counterparties (ISO 3166-1 alpha-2) example: - US primaryContactFirstName: type: string maxLength: 250 description: First name of the business's primary contact — a registered director or authorised representative of the business. Required in regions where a named individual is verified against the business during onboarding (e.g. the EU). The customer's `email` and `phoneNumber` are this person's contact details. example: Jane primaryContactLastName: type: string maxLength: 250 description: Last name of the business's primary contact. example: Smith MwkBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' RefundStatus: type: string enum: - PENDING - COMPLETED - FAILED description: Current status of the refund example: COMPLETED TryExternalAccountInfo: title: TRY Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/TryAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/TryBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/TryBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/TryBeneficiary' BUSINESS: '#/components/schemas/TryBusinessBeneficiary' InrBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' ScaFactor: type: string enum: - SMS_OTP - TOTP - PASSKEY description: 'A Strong Customer Authentication factor. | Factor | Description | |--------|-------------| | `SMS_OTP` | One-time code sent by SMS to the customer''s verified phone. Requires no prior enrollment. | | `TOTP` | Time-based one-time code from an authenticator app. Requires enrollment. Not valid for per-transaction challenges (cannot carry dynamic linking). | | `PASSKEY` | WebAuthn passkey assertion. Requires enrollment. | ' OutgoingPaymentWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/OutgoingTransaction' type: $ref: '#/components/schemas/OutgoingPaymentWebhookEventType' OperationError: type: object description: Failure details for a terminally failed operation. required: - code properties: code: type: string description: 'Machine-readable failure code for a `FAILED` operation. Codes are Grid-defined and stable regardless of which vendor Grid uses under the hood for a given operation. ' example: SIGNER_PROVIDER_REJECTED SgdAccountInfo: allOf: - $ref: '#/components/schemas/SgdAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - PAYNOW - FAST - BANK_TRANSFER OutgoingPaymentWebhookEventType: type: string enum: - OUTGOING_PAYMENT.PENDING - OUTGOING_PAYMENT.PENDING_AUTHORIZATION - OUTGOING_PAYMENT.PROCESSING - OUTGOING_PAYMENT.COMPLETED - OUTGOING_PAYMENT.FAILED - OUTGOING_PAYMENT.EXPIRED - OUTGOING_PAYMENT.REFUND_PENDING - OUTGOING_PAYMENT.REFUND_COMPLETED - OUTGOING_PAYMENT.REFUND_FAILED VndBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' EthereumWalletExternalAccountInfo: title: Ethereum L1 Wallet allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/EthereumWalletInfo' - $ref: '#/components/schemas/WalletBeneficiaryFields' - $ref: '#/components/schemas/WalletCustodyFields' IncomingTransactionFailureReason: type: string enum: - LNURLP_FAILED - PAY_REQUEST_FAILED - PAYMENT_APPROVAL_WEBHOOK_ERROR - PAYMENT_APPROVAL_TIMED_OUT - OFFRAMP_FAILED - MISSING_MANDATORY_PAYEE_DATA - QUOTE_EXPIRED - QUOTE_EXECUTION_FAILED - COMPLIANCE_REJECTED - COLLECTION_FAILED - SWEEP_AMOUNT_OUT_OF_RANGE - SWEEP_QUOTE_FAILED description: 'Reason for failure of an incoming transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted. COMPLIANCE_REJECTED means compliance blocked the incoming funds. COLLECTION_FAILED means an inbound bank-rail collection deposit (e.g. a SWIFT wire) failed after arrival and did not credit — most commonly a compliance-screening rejection or an unresolved request for information, on either the collection provider''s side or Grid''s. Failed collections are returned to the sender per the collection provider''s process. A payment that settled into a rule-based account but could not be swept to the destination of the account''s rule fails with one of the `SWEEP_*` reasons. A rule-based account never holds a balance, so the funds are moved to the account holder''s own account in the same currency. SWEEP_AMOUNT_OUT_OF_RANGE means the amount was outside the band the corridor to the destination can carry — the rule''s minimumAmount and maximumAmount give the current band — and SWEEP_QUOTE_FAILED that Grid could not price it. A sweep that was priced and then failed on the way to settlement reports QUOTE_EXECUTION_FAILED, the same as any other payment.' RtpRailStatus: type: string enum: - PENDING - SETTLED - FAILED description: 'Status of the payment on the RTP network. | Status | Description | |--------|-------------| | `PENDING` | Submitted and awaiting the receiving bank''s response. | | `SETTLED` | The receiving bank accepted the payment and the funds settled. | | `FAILED` | The receiving bank or the network rejected the payment and no funds moved. |' example: SETTLED CardBrand: type: string enum: - VISA - MASTERCARD description: 'Card network brand. Read-only — determined by Grid when the card is provisioned with the issuer. ' PaymentArbitrumWalletInfo: title: Arbitrum Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/ArbitrumWalletInfo' - type: object properties: assetType: $ref: '#/components/schemas/StablecoinAssetType' EurAccountInfo: allOf: - $ref: '#/components/schemas/EurAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - SEPA - SEPA_INSTANT UgxAccountInfo: allOf: - $ref: '#/components/schemas/UgxAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - MOBILE_MONEY OutgoingTransaction: title: Outgoing Transaction allOf: - $ref: '#/components/schemas/Transaction' - type: object required: - type - sentAmount - source properties: status: $ref: '#/components/schemas/OutgoingTransactionStatus' type: type: string enum: - OUTGOING source: $ref: '#/components/schemas/TransactionSourceOneOf' sentAmount: $ref: '#/components/schemas/CurrencyAmount' description: Amount sent in the sender's currency receivedAmount: $ref: '#/components/schemas/CurrencyAmount' description: Amount to be received by recipient in the recipient's currency fees: type: integer format: int64 description: The fees associated with the quote in the smallest unit of the sending currency (eg. cents). minimum: 0 example: 10 platformFees: type: integer format: int64 description: The portion of `fees` collected by the platform (platform-configured transaction fees), in the smallest unit of the sending currency. 0 when the platform has no applicable fee configured. Already included in `fees`. minimum: 0 example: 5 reconciliationInstructions: $ref: '#/components/schemas/ReconciliationInstructions' description: Reconciliation details for this transaction. For the on-chain hash of a crypto payout to an external wallet, see the destination's `railDetails` instead. paymentInstructions: type: array description: Payment instructions for executing the payment. items: $ref: '#/components/schemas/PaymentInstructions' example: - accountOrWalletInfo: accountType: USD_ACCOUNT paymentRails: - ACH - WIRE accountNumber: '1234567890' routingNumber: '021000021' bankName: Chase Bank reference: UMA-Q12345-REF instructionsNotes: Include reference UMA-Q12345-REF in memo - accountOrWalletInfo: accountType: SPARK_WALLET assetType: BTC address: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu invoice: lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs rateDetails: $ref: '#/components/schemas/OutgoingRateDetails' description: Details about the rate and fees for the transaction. failureReason: $ref: '#/components/schemas/OutgoingTransactionFailureReason' description: If the transaction failed, this field provides the reason for failure. paymentRail: anyOf: - $ref: '#/components/schemas/PaymentRail' - type: 'null' description: The payment rail used to settle this transaction (e.g. ACH, WIRE, NEFT, FASTER_PAYMENTS). Uses the same values as the PaymentRail sent on quote requests. Null when no external rail is used (e.g. instant or intra-network transfers, or non-direct-destination transactions) or before a rail is resolved. railSelectionMode: $ref: '#/components/schemas/RailSelectionMode' description: How the rail was chosen — MANUAL when the platform specified a paymentRail on the destination, AUTO when Lightspark selects it. expectedSettlementAt: type: - string - 'null' format: date-time description: Expected settlement time at the beneficiary. Null for instant rails (settlement is immediate) and before a rail with deferred settlement is resolved. settlementTimelineSeconds: type: - integer - 'null' description: Expected number of seconds from quote creation to settlement. Null when not yet known. PaymentBaseWalletInfo: title: Base Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/BaseWalletInfo' - type: object properties: assetType: type: string description: Type of asset enum: - USDC ThbExternalAccountInfo: title: THB Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/ThbAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/ThbBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/ThbBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/ThbBeneficiary' BUSINESS: '#/components/schemas/ThbBusinessBeneficiary' AchRailDetails: title: ACH Transfer description: A transfer over the ACH network. allOf: - $ref: '#/components/schemas/BaseUsdBankRailDetails' - type: object required: - paymentRail - status properties: paymentRail: $ref: '#/components/schemas/AchPaymentRail' status: $ref: '#/components/schemas/AchRailStatus' traceNumber: type: string description: 15-digit ACH trace number of the entry. example: '021000020123456' statementDescriptor: type: string maxLength: 10 description: The entry's Company Entry Description, which the receiving bank shows on the account holder's statement. On payments you originate, this is the quote's `statementDescriptor`, or Grid's default. example: PAYROLL addenda: type: string description: Payment-related text carried in the entry's addenda record. On payments you originate, this is the `remittanceInformation` you provided. example: INV-12345 returnedAt: type: string format: date-time description: When the receiving bank returned the entry. Present once the entry has been returned, including after a later dishonor or contest. example: '2026-10-01T14:00:00Z' dishonoredAt: type: string format: date-time description: When the originating bank dishonored the return. Present once `status` has reached `RETURN_DISHONORED`. example: '2026-10-04T14:00:00Z' contestedAt: type: string format: date-time description: When the receiving bank contested the dishonor. Present when `status` is `RETURN_CONTESTED`. example: '2026-10-07T14:00:00Z' reversedAt: type: string format: date-time description: When the originator reversed the entry. Present when `status` is `REVERSED`. example: '2026-10-01T14:00:00Z' TransactionOneOf: oneOf: - $ref: '#/components/schemas/IncomingTransaction' - $ref: '#/components/schemas/OutgoingTransaction' - $ref: '#/components/schemas/CardTransaction' discriminator: propertyName: type mapping: INCOMING: '#/components/schemas/IncomingTransaction' OUTGOING: '#/components/schemas/OutgoingTransaction' CARD: '#/components/schemas/CardTransaction' AgreementConsentRequest: type: object required: - type - acceptedAt - ipAddress - termsVersion - acceptanceMethod properties: type: $ref: '#/components/schemas/AgreementType' acceptedAt: type: string format: date-time description: Date and time when the customer accepted this agreement. Must include a timezone offset and must not be in the future. ipAddress: type: string maxLength: 45 description: IP address of the device the customer used when accepting this agreement. example: 198.51.100.24 termsVersion: type: string maxLength: 64 description: Version identifier of the accepted agreement, as returned for this type by the agreement documents endpoint. A version is scoped to its type; a version valid for one agreement is not valid for another. example: '2025-10-13' acceptanceMethod: $ref: '#/components/schemas/AgreementAcceptanceMethod' SwiftExternalAccountInfo: title: SWIFT Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/SwiftAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/SwiftBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/BusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/SwiftBeneficiary' BUSINESS: '#/components/schemas/BusinessBeneficiary' PhpBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' SweepRuleDestination: title: Sweep Rule Destination type: object description: Where a rule-based account's credits are swept. required: - accountId properties: accountId: type: string description: The account that receives the swept funds. example: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123 paymentRail: allOf: - $ref: '#/components/schemas/PaymentRail' description: The rail each sweep is sent over. Null when a rail is selected automatically per sweep, in which case none is resolved ahead of time. example: ACH CardPinStatusChangeWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/Card' description: The updated card, including its new pinStatus. type: type: string enum: - CARD.PIN_STATUS_CHANGE ExternalAccountStatusWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/ExternalAccount' type: $ref: '#/components/schemas/ExternalAccountStatusWebhookEventType' ZarBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName - registrationNumber - taxId properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' OnChainRailDetails: title: On-Chain Transfer type: object required: - paymentRail - transactionHash - network properties: paymentRail: type: string enum: - ONCHAIN transactionHash: type: string description: On-chain transaction hash of the crypto transfer for this leg of the transaction. example: h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx network: $ref: '#/components/schemas/CryptoNetwork' description: Blockchain network the transaction settled on (mainnet vs test network is determined by your platform environment). description: A crypto transfer to or from an external wallet. GhsAccountInfo: allOf: - $ref: '#/components/schemas/GhsAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER - MOBILE_MONEY Error409: type: object required: - reason - code properties: code: type: string description: '| Error Code | Description | |------------|-------------| | TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL | Transaction is not pending platform approval | | TRANSACTION_NOT_CANCELLABLE | Transaction has already settled or is otherwise past the point where it can be cancelled | | UMA_ADDRESS_EXISTS | UMA address already exists | | EMAIL_OTP_EMAIL_ALREADY_EXISTS | Email address is already associated with an EMAIL_OTP credential | | EMAIL_OTP_CREDENTIAL_SET_CHANGED | Tied EMAIL_OTP credential set changed after the signed-retry challenge was issued | | PASSKEY_ALREADY_ENROLLED | The customer already has an enrolled passkey factor; only one passkey per customer is supported. Delete the existing one before enrolling another | | SCA_SESSION_REQUIRED | The customer''s Strong Customer Authentication login session is missing or expired. Re-authenticate the customer, then retry the request. Distinct from a `401`, which means the platform''s own API credentials were rejected | | BENEFICIARY_TRUSTED | The external account is currently a trusted beneficiary, so it cannot be deleted. Untrust it first via `POST /customers/external-accounts/{externalAccountId}/untrust` (and its `/confirm`), then delete | | BANK_ACCOUNT_VALIDATION_PENDING | The US bank account on this request is still being validated. Grid verifies a newly added ACH account by sending a micro-entry and waiting out the return window, which takes a few banking days. The account is not rejected; retry once validation completes. A permanently failed account returns `400 INVALID_BANK_ACCOUNT` instead | | INVALID_STATE_TRANSITION | The requested card `status` transition is not one of `ACTIVE ⇄ FROZEN` or `ACTIVE \| FROZEN → CLOSED`, or the card cannot be unfrozen by the platform because Grid froze it for review, it was frozen as `COMPROMISED`, or its customer is not `ACTIVE` | | CARD_ALREADY_CLOSED | `status: CLOSED` was requested for a card that is already `CLOSED` | | CARD_NOT_MUTABLE | The card is `CLOSED`, so it can no longer be mutated | | PIN_CHANGE_REQUIRED | The card''s PIN unblock allowance is consumed for seven days. Change the PIN to recover sooner. `details.pinUnblockAvailableAt` gives the next allowed unblock time | | CARD_LIMIT_REACHED | The platform has reached the maximum number of live cards it may hold, or the cardholder already holds a card and the platform is limited to one per cardholder. Closing a card frees its slot; contact Lightspark to raise the limit | | STABLECOIN_GRID_ENABLEMENT_NOT_REQUESTABLE | Grid enablement can only be requested while the stablecoin is `NOT_ENABLED` (a repeat request while already `PENDING_APPROVAL` succeeds). `ENABLING`, `ENABLED` and `DISABLED` are driven by Lightspark and cannot be requested | | NOT_YET_AVAILABLE | The request is valid, but its result is not available yet because the data it depends on could still change. Retry later. `reason` says what is outstanding. For balance changes, card settlement for a window boundary has not closed | | CONFLICT | Generic resource-state conflict. Returned, for example, when `platformCustomerId` on a customer create call collides with an existing active customer on the same platform | | DOCUMENT_ALREADY_EXISTS | A document of this type already exists for the holder; replace it with PUT | | DUPLICATE_EXTERNAL_ACCOUNT | An equivalent external account already exists. When the conflicting account belongs to your platform, `details.externalAccountId` and `details.platformAccountId` identify it; otherwise `details` is omitted | | DUPLICATE_PAY_REQUEST | A pay request with this idempotency key already exists | | OPERATION_IN_PROGRESS | A conflicting Embedded Wallet operation is still in progress | | SMS_OTP_CREDENTIAL_SET_CHANGED | The SMS_OTP credential set changed while the request was in flight | | SMS_OTP_PHONE_NUMBER_ALREADY_EXISTS | The phone number is already associated with an SMS_OTP credential | | STABLECOIN_SYMBOL_ALREADY_EXISTS | A stablecoin with this symbol is already registered | | STABLECOIN_TOKEN_IDENTIFIER_ALREADY_EXISTS | A stablecoin with this token identifier is already registered | | WALLET_NOT_PROVISIONED | The embedded wallet has not been provisioned | | PAYMENT_DOCUMENT_ALREADY_USED | The payment document is already attached to a quote. A document can be used on one quote only, so upload the file again to use it on another quote | ' enum: - TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL - TRANSACTION_NOT_CANCELLABLE - UMA_ADDRESS_EXISTS - EMAIL_OTP_EMAIL_ALREADY_EXISTS - EMAIL_OTP_CREDENTIAL_SET_CHANGED - PASSKEY_ALREADY_ENROLLED - SCA_SESSION_REQUIRED - BENEFICIARY_TRUSTED - BANK_ACCOUNT_VALIDATION_PENDING - INVALID_STATE_TRANSITION - CARD_ALREADY_CLOSED - CARD_NOT_MUTABLE - PIN_CHANGE_REQUIRED - CARD_LIMIT_REACHED - STABLECOIN_GRID_ENABLEMENT_NOT_REQUESTABLE - NOT_YET_AVAILABLE - CONFLICT - DOCUMENT_ALREADY_EXISTS - DUPLICATE_EXTERNAL_ACCOUNT - DUPLICATE_PAY_REQUEST - OPERATION_IN_PROGRESS - SMS_OTP_CREDENTIAL_SET_CHANGED - SMS_OTP_PHONE_NUMBER_ALREADY_EXISTS - STABLECOIN_SYMBOL_ALREADY_EXISTS - STABLECOIN_TOKEN_IDENTIFIER_ALREADY_EXISTS - WALLET_NOT_PROVISIONED - PAYMENT_DOCUMENT_ALREADY_USED reason: type: string description: Error message details: type: object description: Additional error details additionalProperties: true InternalAccountType: title: Internal Account Type type: string enum: - INTERNAL_FIAT - INTERNAL_CRYPTO - EMBEDDED_WALLET - RULE_BASED - BULK_SETTLEMENT description: 'Classification of an internal account. - `INTERNAL_FIAT`: A Grid-managed fiat holding account (for example, the USD holding account used as the source for Payouts flows). - `INTERNAL_CRYPTO`: A Grid-managed crypto holding account denominated in a stablecoin such as USDC. - `EMBEDDED_WALLET`: A self-custodial Embedded Wallet provisioned for the customer. Outbound transfers require a session signature produced by the customer''s device — see the Embedded Wallets guide. - `RULE_BASED`: An additional account number for an existing account holder, with a routing rule attached, so incoming payments can be attributed to a specific payer and swept automatically. Created with `POST /internal-accounts`. - `BULK_SETTLEMENT`: An account for receiving bulk payments (for example, a single settlement from a payment processor) that the platform then pays out to its customers. Only a platform can hold one, and funds in it can move only to the platform''s customers.' TransactionStatus: type: string enum: - CREATED - PENDING - PENDING_AUTHORIZATION - PROCESSING - COMPLETED - REJECTED - FAILED - REFUNDED - EXPIRED description: 'Status of a payment transaction. | Status | Description | |--------|-------------| | `CREATED` | Initial lookup has been created | | `PENDING` | Quote has been created | | `PENDING_AUTHORIZATION` | Awaiting Strong Customer Authentication. Only occurs for customers in a region where SCA is required (e.g. EU). The challenge is carried by the quote, not the transaction — fetch `GET /quotes/{quoteId}` using the transaction''s `quoteId`, then authorize its `scaChallenge` via `POST /quotes/{quoteId}/authorize`. | | `PROCESSING` | Funding has been received and payment initiated | | `COMPLETED` | The funds are where settlement put them. A return that takes them back moves the transaction to `FAILED`, and the returned side''s `railDetails` shows `RETURNED`. A transaction stays `COMPLETED` through a return only when a later step that can''t be undone already used the funds | | `REJECTED` | Receiving institution or wallet rejected payment, payment has been refunded | | `FAILED` | The payment did not reach its destination, or the funds were sent back after it did. Not terminal for an incoming payment: a dishonored return restores the credit and moves it to `COMPLETED`. A returned payout stays `FAILED`, since it has already been refunded. Each step shows on the returned side''s `railDetails` | | `REFUNDED` | Deprecated. A refund is reported on the transaction''s `refund` object, and the status stays `FAILED` | | `EXPIRED` | Quote has expired. Terminal | ' AgentActionStatus: type: string enum: - PENDING_APPROVAL - APPROVED - REJECTED - FAILED description: 'Status of an agent action. | Status | Description | |--------|-------------| | `PENDING_APPROVAL` | Submitted by the agent, awaiting platform approval before execution | | `APPROVED` | Approved by the platform; execution is in progress or completed | | `REJECTED` | Rejected by the platform; the underlying transaction was not executed | | `FAILED` | Not executed, or execution failed; see `failureReason` | ' SwiftBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' WalletIndividualBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName - countryOfResidence properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary example: John Michael Doe countryOfResidence: type: string description: The country of residence of the beneficiary (ISO 3166-1 alpha-2) example: US ReconciliationInstructions: type: object minProperties: 1 description: Instructions for reconciling a payment with this transaction. For the on-chain transaction to or from an external crypto wallet that is the transaction's own source or destination, use the `railDetails` on the relevant source or destination instead. properties: reference: type: string description: Unique reference code to include with the payment to match it with the correct incoming transaction, when available. example: UMA-Q12345-REF transactionHash: deprecated: true type: string description: 'Transaction hash of the settlement transfer, when available. This field reports two different transfers, and only one of them has a replacement today: For a crypto transfer to or from a customer''s own external wallet, use the `railDetails` on the relevant source or destination instead — it names the network alongside the hash. That is the transfer this field is deprecated for. For the inter-VASP settlement leg of a UMA payment (e.g. USDC on Solana to the receiving partner), this field remains the only place the hash is reported: a UMA address is not a wallet you hold, so its source and destination carry no `railDetails`. The field will not be removed before that leg has a replacement.' example: '0x9f2c6b6f4b6c8f2a8d9e0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566' KycStatus: type: string enum: - UNVERIFIED - PENDING - APPROVED - REJECTED - HOLD description: The current KYC status of a customer. `HOLD` means the customer is placed on hold and may be required to update or provide more information. example: APPROVED BulkCustomerImportErrorEntry: allOf: - $ref: '#/components/schemas/GridError' - type: object description: Error information for a failed bulk import entry required: - correlationId properties: correlationId: type: string description: Platform customer ID or row number for the failed entry example: biz456 IncomingPaymentWebhookData: title: Incoming Payment Webhook Data allOf: - $ref: '#/components/schemas/IncomingTransaction' - type: object properties: requestedReceiverCustomerInfoFields: type: array items: $ref: '#/components/schemas/CounterpartyFieldDefinition' description: Information required by the sender's VASP about the recipient. Platform must provide these in the 200 OK response if approving. Note that this only includes fields which Grid does not already have from initial customer registration. SwiftAccountInfo: allOf: - $ref: '#/components/schemas/SwiftAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - SWIFT AgentQuote: title: Agent Quote allOf: - $ref: '#/components/schemas/Quote' - type: object properties: minimumReceivingAmount: type: - integer - 'null' format: int64 description: 'Smallest amount the recipient receives, in the smallest unit of `receivingCurrency`, for a quote to a `CHAIN_ADDRESS` destination: `totalReceivingAmount` is an estimate, and the quote executes only if a fresh price at execution still delivers at least this amount. Otherwise the action fails with `PRICE_MOVED`. Null for a quote whose destination is not `CHAIN_ADDRESS`.' example: 990000 destinationSparkAddress: type: string description: The Spark address this quote pays, when its `destination` is one of the customer's `SPARK_WALLET` external accounts. example: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu destinationChainAddress: $ref: '#/components/schemas/AgentChainAddressDestination' description: The chain, address and stablecoin this quote pays, when it was created with a `CHAIN_ADDRESS` destination. description: A quote created by an agent. For a `CHAIN_ADDRESS` destination, the quote's `destination` names the external account Grid recorded for the address, and `destinationChainAddress` names the address itself. AedExternalAccountInfo: title: AED Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/AedAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/AedBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/AedBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/AedBeneficiary' BUSINESS: '#/components/schemas/AedBusinessBeneficiary' CnyAccountInfo: allOf: - $ref: '#/components/schemas/CnyAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER - MOBILE_MONEY PolygonWalletExternalAccountInfo: title: Polygon Wallet allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/PolygonWalletInfo' - $ref: '#/components/schemas/WalletBeneficiaryFields' - $ref: '#/components/schemas/WalletCustodyFields' MyrBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' IncomingPaymentWebhookUnprocessableResponse: allOf: - $ref: '#/components/schemas/GridError' - type: object properties: requiredFields: type: array items: type: string description: List of fields that are required by the platform, but are not present in the counterparty information. example: - TAX_ID - REGISTRATION_NUMBER SolanaWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - SOLANA_WALLET address: type: string description: Solana wallet address example: 4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8Wg BeneficiaryVerifiedData: type: object properties: fullName: type: string description: The verified full name of the account holder as returned by the payment rail example: John Doe ContactVerification: type: object description: 'Email and/or phone verification state for the customer. This object is **only present when the customer''s regulatory jurisdiction requires contact verification** (e.g. EU customers). For customers who have no such requirement, this object is omitted entirely — no action is needed. Each channel is reported independently: only the channels the customer''s provider actually requires are present. A provider may require both email and phone, just one of them, or — when the object is absent — neither. Every channel that **is** present must reach `VERIFIED` before the customer can begin KYC. Drive each present channel with `POST /customers/{customerId}/verify-email` and/or `POST /customers/{customerId}/verify-phone` (and their `/confirm` sub-routes).' properties: email: $ref: '#/components/schemas/ContactVerificationStatus' description: Verification status of the customer's email address. Present only when the provider requires email verification. phone: $ref: '#/components/schemas/ContactVerificationStatus' description: Verification status of the customer's phone number. Present only when the provider requires phone verification. QuoteSourceOneOf: oneOf: - $ref: '#/components/schemas/AccountQuoteSource' - $ref: '#/components/schemas/RealtimeFundingQuoteSource' discriminator: propertyName: sourceType mapping: ACCOUNT: '#/components/schemas/AccountQuoteSource' REALTIME_FUNDING: '#/components/schemas/RealtimeFundingQuoteSource' AnnualIncomeRange: type: string enum: - UNDER_50K - RANGE_50K_100K - RANGE_100K_250K - RANGE_250K_1M - OVER_1M description: Bucketed annual income (USD equivalent). Used for enhanced due diligence on higher-risk profiles. example: RANGE_100K_250K CopExternalAccountInfo: title: COP Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/CopAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/CopBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/CopBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/CopBeneficiary' BUSINESS: '#/components/schemas/CopBusinessBeneficiary' ZmwAccountInfoBase: type: object required: - accountType - phoneNumber - provider properties: accountType: type: string enum: - ZMW_ACCOUNT phoneNumber: type: string description: Zambian mobile money phone number example: '+260971234567' minLength: 7 maxLength: 15 pattern: ^\+260[0-9]{9}$ provider: type: string description: The mobile money provider name minLength: 1 maxLength: 255 example: accountType: ZMW_ACCOUNT phoneNumber: '+260971234567' provider: Example Provider VndExternalAccountInfo: title: VND Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/VndAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/VndBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/VndBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/VndBeneficiary' BUSINESS: '#/components/schemas/VndBusinessBeneficiary' InternalAccountStatus: title: Internal Account Status type: string enum: - PENDING - ACTIVE - CLOSED - FROZEN - FAILED description: 'Status of a Grid internal account. The status determines whether the account can send or receive payments. - `PENDING`: The account is under review and is being provisioned. The account cannot send or receive payments until provisioning completes. - `ACTIVE`: The account is ready to send and receive payments. - `CLOSED`: The account cannot send or receive payments. A customer can initiate the closing of an internal account, after which the account transitions to this status. - `FROZEN`: The account cannot send or receive payments. Grid may freeze an account in response to compliance or fraud signals; payments are blocked while the account remains frozen. - `FAILED`: The account could not be provisioned. Grid was unable to create the underlying account, so it cannot send or receive payments and requires remediation.' example: ACTIVE EurExternalAccountInfo: title: EUR Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/EurAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/EurBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/EurBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/EurBeneficiary' BUSINESS: '#/components/schemas/EurBusinessBeneficiary' EgpBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - address - legalName properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' MxnBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' OwnershipType: type: string enum: - FIRST_PARTY - THIRD_PARTY description: Whether the external account belongs to the customer themselves (`FIRST_PARTY`) or to someone else (`THIRD_PARTY`). Required when creating self-custody crypto wallet external accounts on platforms subject to counterparty requirements — for example, under the EU Travel Rule or similar requirements in other regions; recommended for all other accounts, where providing it can unlock additional capabilities and smoother compliance handling. example: FIRST_PARTY KesAccountInfo: allOf: - $ref: '#/components/schemas/KesAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - MOBILE_MONEY AgentActionWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/AgentAction' type: $ref: '#/components/schemas/AgentActionWebhookEventType' WireRailStatus: type: string enum: - PENDING - SETTLED - FAILED description: 'Status of the wire on Fedwire. | Status | Description | |--------|-------------| | `PENDING` | Submitted to Fedwire and not yet delivered. | | `SETTLED` | Fedwire delivered the wire. | | `FAILED` | Fedwire or the receiving bank rejected the wire and no funds moved. |' example: SETTLED IlsExternalAccountInfo: title: ILS Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/IlsAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/IlsBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/IlsBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/IlsBeneficiary' BUSINESS: '#/components/schemas/IlsBusinessBeneficiary' Customer: type: object required: - umaAddress - platformCustomerId - customerType properties: id: type: string description: System-generated unique identifier example: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: type: string description: Platform-specific customer identifier example: 9f84e0c2a72c4fa customerType: $ref: '#/components/schemas/CustomerType' endUserTermsConsent: deprecated: true readOnly: true allOf: - $ref: '#/components/schemas/EndUserTermsConsent' description: Deprecated; read `agreementConsents` instead. Mirrors the customer's `LIGHTSPARK_END_USER_TERMS` acceptance when one is on file, and is omitted otherwise. agreementConsents: type: array readOnly: true description: The customer's recorded agreement acceptances, one entry per accepted type holding that type's most recent acceptance. Omitted when the customer has not accepted any agreement yet. items: $ref: '#/components/schemas/AgreementConsent' region: type: string description: Country code (ISO 3166-1 alpha-2) representing the customer's regional identity and regulatory jurisdiction. example: US currencies: type: array items: type: string description: List of currency codes enabled for this customer. example: - USD - USDC email: type: string format: email description: Email address for the customer. example: john.doe@example.com phoneNumber: type: string pattern: ^\+[1-9]\d{1,14}$ description: Phone number for the customer in strict E.164 format. example: '+14155551234' umaAddress: type: string description: Full UMA address (always present in responses, even if system-generated). This is an optional identifier to route payments to the customer. example: $john.doe@uma.domain.com createdAt: type: string format: date-time description: Creation timestamp example: '2025-07-21T17:32:28Z' updatedAt: type: string format: date-time description: Last update timestamp example: '2025-07-21T17:32:28Z' isDeleted: type: boolean description: Whether the customer is marked as deleted example: false contactVerification: allOf: - $ref: '#/components/schemas/ContactVerification' description: Email and phone verification state. **Only present when the customer's payment provider requires it** (e.g. EU customers); omitted otherwise. WalletOperationCompletedData: title: Wallet Operation Completed Data type: object required: - operationId - requestId - operationType - resourceType - resourceId - status properties: operationId: type: string description: Grid-internal identifier for this operation. Useful when contacting support about a specific operation; not a correlation key — use `requestId` to match this webhook to the request you made. example: Operation:019542f5-b3e7-1d02-0000-000000000099 requestId: type: string description: 'The `Request-Id` you supplied on the signed retry that produced this terminal result — the same value you would have echoed on every retry had you received a `200 { status: "PROCESSING" }` response while it was settling. This is the primary way to correlate this webhook to the request you made.' example: Request:9f7a2c10-5e88-4fb1-bd0e-1c3a8e7b2d45 operationType: type: string description: The kind of operation that reached a terminal state. enum: - auth_credential.create - auth_credential.delete - session.revoke - wallet.export - customer.contact_update example: wallet.export resourceType: $ref: '#/components/schemas/WalletOperationResourceType' resourceId: type: string description: LSID of the business resource this operation affected. For `auth_credential.create`, this is the **primary way to learn the new credential's id** — the request that created it can't have supplied one in advance. For `auth_credential.delete` and `session.revoke` it echoes the `AuthMethod:` / `Session:` you already knew and referenced in the request; for `wallet.export` it's the `InternalAccount:` whose wallet was exported; for `customer.contact_update` it's the `Customer:` whose email or phone number changed. example: InternalAccount:019542f5-b3e7-1d02-0000-000000000005 status: type: string enum: - completed description: Terminal status of the operation. example: completed SweepRule: title: Sweep Rule type: object description: The routing rule attached to a rule-based account. Returned on the account rather than as a resource of its own, because the rule has no lifecycle apart from the account. required: - destination properties: destination: allOf: - $ref: '#/components/schemas/SweepRuleDestination' description: Where funds that settle into this account are swept. minimumAmount: allOf: - $ref: '#/components/schemas/CurrencyAmount' description: '**In this rule-based account''s currency, not the destination''s.** The smallest balance the corridor to the destination can carry; a settled balance below it is not swept. Zero means no floor, which is the case for a same-currency internal destination — a book transfer with no rail, fee or conversion to justify one. Configuration rather than a moving estimate, so there is nothing to re-poll.' maximumAmount: allOf: - $ref: '#/components/schemas/CurrencyAmount' description: '**In this rule-based account''s currency, not the destination''s.** The largest balance the corridor to the destination can carry; a settled balance above it is not swept. Null means no ceiling.' purposeOfPayment: allOf: - $ref: '#/components/schemas/PurposeOfPayment' description: The purpose of payment applied to each sweep. example: SELF description: type: string description: Free-form description recorded on each sweep. Not delivered to the recipient. example: Rent sweep remittanceInformation: type: string description: Free-form information that travels with each sweep to the recipient. example: Unit 4B March platformFeeOverride: allOf: - $ref: '#/components/schemas/PlatformFeeOverride' description: Fee terms applied to every sweep this rule drives. Null when the platform's configured fees apply. UsdBankAccountDetails: title: US Bank Account Details type: object description: 'The account on the other end of the transfer: the sender''s account on a source, the recipient''s account on a destination.' properties: accountHolderName: type: string description: Name of the account holder. example: John Sender routingNumber: type: string description: 9-digit ABA routing number of the account's bank. example: '021000021' accountNumber: type: string description: Account number, masked to its last four digits. example: '****6789' CopAccountInfo: allOf: - $ref: '#/components/schemas/CopAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER - MOBILE_MONEY SgdBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' GhsBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' HkdAccountInfo: allOf: - $ref: '#/components/schemas/HkdAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER BeneficialOwner: type: object required: - id - customerId - roles - ownershipPercentage - personalInfo - kycStatus - createdAt properties: id: type: string description: Unique identifier for this beneficial owner example: BeneficialOwner:019542f5-b3e7-1d02-0000-000000000001 customerId: type: string description: The ID of the business customer this beneficial owner is associated with example: Customer:019542f5-b3e7-1d02-0000-000000000001 roles: type: array items: $ref: '#/components/schemas/BeneficialOwnerRole' description: Roles of this person within the business example: - UBO - DIRECTOR ownershipPercentage: type: integer description: Percentage of ownership in the business (0-100) minimum: 0 maximum: 100 example: 51 personalInfo: $ref: '#/components/schemas/BeneficialOwnerPersonalInfo' kycStatus: $ref: '#/components/schemas/KycStatus' createdAt: type: string format: date-time description: When this beneficial owner was created example: '2025-10-03T12:00:00Z' updatedAt: type: string format: date-time description: When this beneficial owner was last updated example: '2025-10-03T12:00:00Z' TransactionDestinationOneOf: oneOf: - $ref: '#/components/schemas/AccountTransactionDestination' - $ref: '#/components/schemas/UmaAddressTransactionDestination' discriminator: propertyName: destinationType mapping: ACCOUNT: '#/components/schemas/AccountTransactionDestination' UMA_ADDRESS: '#/components/schemas/UmaAddressTransactionDestination' PlasmaWalletExternalAccountInfo: title: Plasma Wallet allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/PlasmaWalletInfo' - $ref: '#/components/schemas/WalletBeneficiaryFields' - $ref: '#/components/schemas/WalletCustodyFields' AchPaymentRail: type: string enum: - ACH - ACH_SAME_DAY ThbBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' BwpBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' AedAccountInfo: allOf: - $ref: '#/components/schemas/AedAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER EgpAccountInfoBase: type: object required: - accountType - bankName description: 'Required fields depend on the selected paymentRails: - BANK_TRANSFER: bankName, iban - MOBILE_MONEY: bankName, phoneNumber' properties: accountType: type: string enum: - EGP_ACCOUNT iban: type: string description: Egyptian IBAN (29 characters, starting with EG) example: EG380019000500000000263180002 minLength: 29 maxLength: 29 pattern: ^EG[0-9]{27}$ bankName: type: string description: The name of the bank. Must be one of the `bankName` values `GET /discoveries` returns for this country and currency. Send it exactly as returned; any other name is rejected. minLength: 1 maxLength: 255 example: BANQUE MISR phoneNumber: type: string description: The phone number in international format example: '+1234567890' minLength: 7 maxLength: 15 pattern: ^\+[0-9]{6,14}$ example: accountType: EGP_ACCOUNT iban: EG380019000500000000263180002 bankName: BANQUE MISR phoneNumber: '+1234567890' BulkCustomerImportJob: type: object required: - id - status - progress properties: id: type: string description: Unique identifier for the bulk import job example: Job:019542f5-b3e7-1d02-0000-000000000006 status: $ref: '#/components/schemas/BulkCustomerImportJobStatus' progress: type: object required: - total - processed - successful - failed properties: total: type: integer description: Total number of customers to process example: 5000 processed: type: integer description: Number of customers processed so far example: 2500 successful: type: integer description: Number of customers successfully created example: 2450 failed: type: integer description: Number of customers that failed to create example: 50 errors: type: array description: Detailed error information for failed entries items: $ref: '#/components/schemas/BulkCustomerImportErrorEntry' completedAt: type: string format: date-time description: Timestamp when the job completed (only present for COMPLETED or FAILED status) example: '2025-08-15T14:32:00Z' JmdAccountInfo: allOf: - $ref: '#/components/schemas/JmdAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER Error401: type: object required: - reason - code properties: code: type: string description: '| Error Code | Description | |------------|-------------| | UNAUTHORIZED | Issue with API credentials | | INVALID_SIGNATURE | Signature header is invalid | | WALLET_SIGNATURE_MISSING | The `Grid-Wallet-Signature` header is required for this Embedded Wallet action but was not supplied | | WALLET_SIGNATURE_MALFORMED | The `Grid-Wallet-Signature` header could not be parsed (bad encoding, structure, or fields) | | WALLET_SIGNATURE_BODY_MISMATCH | The `Grid-Wallet-Signature` was computed over a different request body than the one received | | WALLET_SIGNATURE_INVALID | The `Grid-Wallet-Signature` failed cryptographic verification against the registered credential | | REQUEST_ID_MISSING | The `Request-Id` header is required on the signed retry but was not supplied (paired with `Grid-Wallet-Signature`) | ' enum: - UNAUTHORIZED - INVALID_SIGNATURE - WALLET_SIGNATURE_MISSING - WALLET_SIGNATURE_MALFORMED - WALLET_SIGNATURE_BODY_MISMATCH - WALLET_SIGNATURE_INVALID - REQUEST_ID_MISSING reason: type: string description: Error message details: type: object description: Additional error details additionalProperties: true RefundReason: type: string enum: - TRANSACTION_FAILED - USER_CANCELLATION - TIMEOUT description: Reason for the refund example: TRANSACTION_FAILED UmaInvitation: type: object required: - code - createdAt - inviterUma - status - url properties: code: type: string description: The unique code of the invitation example: 019542f5 createdAt: type: string format: date-time description: When the invitation was created example: '2025-09-01T14:30:00Z' claimedAt: type: string format: date-time description: When the invitation was claimed if it has been claimed example: '2025-09-01T14:30:00Z' url: type: string description: The URL where this invitation can be claimed. example: https://uma.me/i/019542f5 expiresAt: type: string format: date-time description: When the invitation expires (if at all) example: '2025-09-01T14:30:00Z' inviterUma: type: string description: The UMA address of the inviter example: $inviter@uma.domain inviteeUma: type: string description: The UMA address of the invitee example: $invitee@uma.domain status: $ref: '#/components/schemas/UmaInvitationStatus' firstName: type: string description: The inviter's first name. Will be displayed when the recipient clicks the invite link example: Jane amountToSend: $ref: '#/components/schemas/CurrencyAmount' description: 'The amount to send to the invitee when the invitation is claimed. This is optional and if not provided, the invitee will not receive any amount. Note that the actual sending of the amount must be done by the inviter platform once the INVITATION_CLAIMED webhook is received. If the inviter platform either does not send the payment or the payment fails, the invitee will not receive this amount. This field is primarily used for display purposes on the claiming side of the invitation. This field is useful for "send-by-link" style customer flows where an inviter can send a payment simply by sharing a link without knowing the receiver''s UMA address. Note that these sends can only be sender-locked, meaning that the sender will not know ahead of time how much the receiver will receive in the receiving currency.' MyrExternalAccountInfo: title: MYR Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/MyrAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/MyrBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/MyrBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/MyrBeneficiary' BUSINESS: '#/components/schemas/MyrBusinessBeneficiary' AccountTransactionDestination: title: Account Destination allOf: - $ref: '#/components/schemas/BaseTransactionDestination' - type: object required: - accountId - destinationType properties: destinationType: type: string enum: - ACCOUNT accountId: type: string description: Destination account identifier example: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123 railDetails: $ref: '#/components/schemas/RailDetailsOneOf' onChainTransaction: $ref: '#/components/schemas/OnChainTransaction' deprecated: true description: Deprecated. Use `railDetails`, which carries the same hash and network when `paymentRail` is `ONCHAIN`. description: Destination account details Card: type: object required: - id - customerId - status - form - fundingSource - maxSpendPerTransaction - maxSpendPerDay - maxTransactionsPerDay - createdAt - updatedAt properties: id: type: string description: System-generated unique card identifier example: Card:019542f5-b3e7-1d02-0000-000000000010 customerId: type: string description: The id of the `Customer` who holds this card. example: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCardId: type: string description: Platform-specific card identifier generated by the server. example: card-emp-001 status: $ref: '#/components/schemas/CardStatus' statusReason: $ref: '#/components/schemas/CardStatusReason' description: Reason associated with the current `status`. Present when the card is `PENDING_AUTH`, `CLOSED`, or when provisioning was rejected; absent otherwise. brand: $ref: '#/components/schemas/CardBrand' form: $ref: '#/components/schemas/CardForm' pinStatus: $ref: '#/components/schemas/CardPinStatus' pinUnblockAvailableAt: type: string format: date-time readOnly: true description: Earliest time another PIN unblock attempt is allowed. Absent until the unblock allowance is used. Changing the PIN does not reset this time. example: '2026-10-15T15:00:00Z' last4: type: string description: Last four digits of the card PAN. example: '4242' expMonth: type: integer minimum: 1 maximum: 12 description: Card expiration month (1–12). example: 12 expYear: type: integer description: Card expiration year (four digits). example: 2029 fundingSource: type: string description: Internal account id that funds this card. example: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 cardCapabilities: $ref: '#/components/schemas/CardCapabilities' description: Actions supported for this card by the issuer selected at issuance. Present for cards whose program has been resolved; absent otherwise. These capabilities are fixed at issuance for the card's lifetime. maxSpendPerTransaction: anyOf: - type: integer format: int64 minimum: 1 maximum: 9007199254740991 - type: 'null' description: The largest amount this card can authorize on a single transaction, in the smallest unit of its `currency` (cents for USD). An authorization for exactly the limit is allowed. A later clearing can still settle above it — a restaurant tip, for example — so this caps the authorization, not the final settled amount. `null` means the card sets no limit of its own. If your platform config also sets `cardConfigs.maxSpendPerTransaction` (the platform-level limit), the lower of the two applies and this value stays as you set it. example: 5000 maxSpendPerDay: anyOf: - type: integer format: int64 minimum: 1 maximum: 9007199254740991 - type: 'null' description: Card-specific cap on cumulative new spend during one UTC calendar day, in the smallest unit of the card's `currency`. The window resets at 00:00 UTC. Null means the card has no card-specific daily cap. When the platform config also supplies `cardConfigs.maxSpendPerDay`, Grid enforces the lower of the two values without replacing this configured value. Refunds, reversals, and authorization expiries do not restore capacity during the day. Spend exactly equal to the effective limit is allowed. example: 25000 maxTransactionsPerDay: anyOf: - type: integer format: int32 minimum: 1 maximum: 2147483647 - type: 'null' description: Card-specific cap on the number of transactions the card may authorize during one UTC calendar day. The window resets at 00:00 UTC. Null means the card has no card-specific daily transaction cap. When the platform config also supplies `cardConfigs.maxTransactionsPerDay`, Grid enforces the lower of the two values without replacing this configured value. Each approved authorization counts once for the day it was authorized; refunds, reversals, and authorization expiries do not restore capacity during the day. A transaction that brings the day's count exactly to the effective limit is allowed. example: 20 allowedMccs: type: array minItems: 1 description: Merchant category codes the card may spend at. Present only on a card issued for an agent; absent when that card may spend at any category not blocked. items: type: string pattern: ^[0-9]{4}$ example: - '5411' blockedMccs: type: array description: 'Merchant category codes a card issued for an agent declines, with `cardDeclinedReason: BLOCKED`. Present only on such a card, which also declines Grid''s default agent categories unless `defaultMccBlocksLifted` is true.' items: type: string pattern: ^[0-9]{4}$ example: - '7995' agentId: type: string description: The agent the card was issued for, when there is one. example: Agent:019542f5-b3e7-1d02-0000-000000000042 defaultMccBlocksLifted: type: boolean description: Whether the platform lifted Grid's default agent merchant-category blocks on this card. Present only for a card issued for an agent. example: false currency: type: string description: Currency the card transacts in, fixed at issuance by its card program. USDB-funded cards transact in USD, with funding converted at 1 USDB = 1 USD. Spending limits use the smallest unit of the card's currency (USD cents for USDB-funded cards). Changing the funding source does not change the card's currency or spending-limit units. example: USD processorRef: type: string description: Opaque processor-side reference for the card (e.g. the Lithic card token). Useful for cross-referencing in the processor's dashboards; not used for any Grid request routing. example: card_b81c2a4f issuerRef: type: string description: Opaque identifier for the card on the issuer of record (e.g. the Lead Bank account/card identifier). Useful for cross-referencing in issuer dashboards; not used for any Grid request routing. example: lead_card_7a1b9c3d createdAt: type: string format: date-time description: Creation timestamp example: '2026-05-08T14:10:00Z' updatedAt: type: string format: date-time description: Last update timestamp example: '2026-05-08T14:11:00Z' WalletOperationResourceType: type: string description: 'The kind of business resource `resourceId` identifies. Determined by `operationType`: `auth_credential.create` and `auth_credential.delete` → `AUTH_METHOD`, `session.revoke` → `SESSION`, `wallet.export` → `INTERNAL_ACCOUNT`, `customer.contact_update` → `CUSTOMER`.' enum: - AUTH_METHOD - SESSION - INTERNAL_ACCOUNT - CUSTOMER example: INTERNAL_ACCOUNT SgdBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' ZarAccountInfo: allOf: - $ref: '#/components/schemas/ZarAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER QuoteDestinationOneOf: oneOf: - $ref: '#/components/schemas/AccountDestination' - $ref: '#/components/schemas/UmaAddressDestination' discriminator: propertyName: destinationType mapping: ACCOUNT: '#/components/schemas/AccountDestination' UMA_ADDRESS: '#/components/schemas/UmaAddressDestination' BaseWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - BASE_WALLET address: type: string description: Base eth wallet address example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' BusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business registrationNumber: type: string maxLength: 100 description: The registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' VndAccountInfo: allOf: - $ref: '#/components/schemas/VndAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER ExternalAccountStatusWebhookEventType: type: string enum: - EXTERNAL_ACCOUNT.STATUS_UPDATED - EXTERNAL_ACCOUNT.ACCOUNT_INFO_UPDATED DkkBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' XofAccountInfoBase: type: object required: - accountType - phoneNumber - provider - region properties: accountType: type: string enum: - XOF_ACCOUNT phoneNumber: type: string description: The phone number in international format example: '+1234567890' minLength: 7 maxLength: 15 pattern: ^\+[0-9]{6,14}$ provider: type: string description: The mobile money provider name minLength: 1 maxLength: 255 region: type: string description: Country code within the West African CFA franc zone minLength: 2 maxLength: 2 pattern: ^[A-Z]{2}$ enum: - BJ - CI - SN - TG example: accountType: XOF_ACCOUNT phoneNumber: '+1234567890' provider: Example Provider region: BJ UgxBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName - registrationNumber - taxId properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' MyrAccountInfoBase: type: object required: - accountType - bankName - accountNumber - swiftCode properties: accountType: type: string enum: - MYR_ACCOUNT bankName: type: string description: The name of the bank. Must be one of the `bankName` values `GET /discoveries` returns for this country and currency. Send it exactly as returned; any other name is rejected. minLength: 1 maxLength: 255 example: Maybank accountNumber: type: string description: Malaysian bank account number minLength: 1 maxLength: 34 example: '1234567890' swiftCode: type: string description: The SWIFT/BIC code of the bank example: MABORUMMYYY minLength: 8 maxLength: 11 pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$ example: accountType: MYR_ACCOUNT bankName: Maybank accountNumber: '1234567890' swiftCode: MABORUMMYYY IdrExternalAccountInfo: title: IDR Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/IdrAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/IdrBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/IdrBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/IdrBeneficiary' BUSINESS: '#/components/schemas/IdrBusinessBeneficiary' HkdBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' IdentificationType: type: string enum: - SSN - ITIN - EIN - NON_US_TAX_ID description: Type of tax identification example: SSN PhpAccountInfoBase: type: object required: - accountType - bankName - accountNumber properties: accountType: type: string enum: - PHP_ACCOUNT rail: type: string description: 'The payment rail to route the payout over: INSTAPAY or PESONET. Omitted, the payout resolves it by amount.' minLength: 1 maxLength: 32 example: INSTAPAY bankName: type: string description: Name of the beneficiary's bank. Must be one of the `bankName` values `GET /discoveries` returns for this country and currency. Send it exactly as returned; any other name is rejected. minLength: 1 maxLength: 255 example: Bank of the Philippine Islands (BPI) accountNumber: type: string description: Bank account number minLength: 8 maxLength: 16 example: 001234567890 pattern: ^[0-9]{8,16}$ example: accountType: PHP_ACCOUNT rail: INSTAPAY bankName: Bank of the Philippine Islands (BPI) accountNumber: 001234567890 GtqBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - countryOfResidence - fullName - phoneNumber properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' ZarExternalAccountInfo: title: ZAR Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/ZarAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/ZarBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/ZarBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/ZarBeneficiary' BUSINESS: '#/components/schemas/ZarBusinessBeneficiary' SlvAccountInfoBase: type: object required: - accountType description: 'Required fields depend on the selected paymentRails: - BANK_TRANSFER: bankAccountType, accountNumber - MOBILE_MONEY: phoneNumber' properties: accountType: type: string enum: - SLV_ACCOUNT bankName: type: string description: The name of the bank (BANK_TRANSFER only) minLength: 1 maxLength: 255 accountNumber: type: string description: The account number of the bank (BANK_TRANSFER only) minLength: 1 maxLength: 34 bankAccountType: type: string description: The bank account type (BANK_TRANSFER only) enum: - CHECKING - SAVINGS phoneNumber: type: string description: The phone number in international format (MOBILE_MONEY only — e.g. Tigo Money) example: '+50312345678' minLength: 7 maxLength: 15 pattern: ^\+[0-9]{6,14}$ example: accountType: SLV_ACCOUNT bankName: Banco Cuscatlan accountNumber: 0123456789 bankAccountType: CHECKING BaseTransactionSource: type: object required: - sourceType properties: sourceType: $ref: '#/components/schemas/TransactionSourceType' currency: type: string description: Currency code for the source example: USD TzsBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName - registrationNumber - taxId properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' RealtimeFundingTransactionSource: title: External Funding Source allOf: - $ref: '#/components/schemas/BaseTransactionSource' - type: object required: - currency - sourceType properties: sourceType: type: string enum: - REALTIME_FUNDING customerId: type: string description: The customer on whose behalf the transaction was initiated. example: Customer:019542f5-b3e7-1d02-0000-000000000009 currency: type: string description: Currency code for the funding source example: USDC accountHolderName: type: string deprecated: true description: Deprecated. Use `railDetails.bankAccount.accountHolderName`. The name of the originator (sender) of the payment. Still populated on rails without a `railDetails` variant, such as SWIFT. example: John Sender accountIdentifier: type: string deprecated: true description: Deprecated. Use `railDetails.bankAccount.accountNumber`. The originator's account number or IBAN. May be masked or partial depending on the rail. Still populated on rails without a `railDetails` variant, such as SWIFT. example: '****6789' bankName: type: string deprecated: true description: Deprecated. Use `railDetails.bankAccount.bankName` on wires. The name of the originating bank. Still populated on rails without a `railDetails` variant, such as SWIFT. example: Chase Bank bankIdentifier: type: string deprecated: true description: Deprecated. Use `railDetails.bankAccount.routingNumber`. The identifier of the originating bank, such as a routing number, BIC, or SWIFT code. Still populated on rails without a `railDetails` variant, such as SWIFT. example: '021000021' paymentRail: deprecated: true description: Deprecated. Use `railDetails.paymentRail`. The payment rail the funds arrived on. Still populated on rails without a `railDetails` variant, such as SWIFT. allOf: - $ref: '#/components/schemas/PaymentRail' remittanceInformation: type: string deprecated: true description: Deprecated. Use `railDetails.addenda` for ACH, `railDetails.originatorToBeneficiaryInformation` for wires and `railDetails.remittanceInformation` for RTP and FedNow. Free-form information about the payment provided by the originator. Still populated on rails without a `railDetails` variant, such as SWIFT. example: '12345' endToEndId: type: string deprecated: true description: Deprecated. Use `railDetails.endToEndId`. The originator's own end-to-end reference for the payment. Still populated on rails without a `railDetails` variant, such as SWIFT. example: E2E-9f2c6b6f traceNumber: type: string deprecated: true description: Deprecated. Use `railDetails.traceNumber` for ACH and `railDetails.imad` for wires. Rail-level tracking identifier for the payment. Still populated on rails without a `railDetails` variant, such as SWIFT. example: '021000020123456' railDetails: $ref: '#/components/schemas/RailDetailsOneOf' onChainTransaction: $ref: '#/components/schemas/OnChainTransaction' deprecated: true description: Deprecated. Use `railDetails`, which carries the same hash and network when `paymentRail` is `ONCHAIN`. description: Transaction was funded using an external funding source. `railDetails` describes the transfer that delivered the funds; its fields are populated on a best-effort basis depending on what the funding source provides. Rails without a `railDetails` variant, such as SWIFT, carry the originator's details in the deprecated flat fields only. BusinessCustomerFields: type: object required: - customerType properties: customerType: type: string enum: - BUSINESS kybStatus: $ref: '#/components/schemas/KybStatus' address: $ref: '#/components/schemas/Address' businessInfo: $ref: '#/components/schemas/BusinessInfoUpdate' BaseExternalAccountInfo: type: object required: - accountType properties: accountType: $ref: '#/components/schemas/ExternalAccountType' WalletOperationWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/WalletOperationWebhookData' type: $ref: '#/components/schemas/WalletOperationWebhookEventType' CustomerOneOf: oneOf: - $ref: '#/components/schemas/IndividualCustomer' - $ref: '#/components/schemas/BusinessCustomer' discriminator: propertyName: customerType mapping: INDIVIDUAL: '#/components/schemas/IndividualCustomer' BUSINESS: '#/components/schemas/BusinessCustomer' UmaAddressTransactionSource: title: UMA Address Source allOf: - $ref: '#/components/schemas/BaseTransactionSource' - type: object required: - umaAddress - sourceType properties: sourceType: type: string enum: - UMA_ADDRESS umaAddress: type: string description: UMA address of the sender example: $sender@uma.domain.com description: UMA address source details CopBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName - taxId properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 64 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' TzsBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' CadAccountInfo: allOf: - $ref: '#/components/schemas/CadAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER InternalAccountStatusWebhookEventType: type: string enum: - INTERNAL_ACCOUNT.BALANCE_UPDATED - INTERNAL_ACCOUNT.STATUS_UPDATED - INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED MwkExternalAccountInfo: title: MWK Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/MwkAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/MwkBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/MwkBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/MwkBeneficiary' BUSINESS: '#/components/schemas/MwkBusinessBeneficiary' TryBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - countryOfResidence - legalName properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' IlsAccountInfoBase: type: object required: - accountType - iban - bankName properties: accountType: type: string enum: - ILS_ACCOUNT iban: type: string description: Israeli IBAN (23 characters, starting with IL) example: IL620108000000099999999 minLength: 23 maxLength: 23 pattern: ^IL[0-9]{21}$ bankName: type: string description: The name of the bank. Must be one of the `bankName` values `GET /discoveries` returns for this country and currency. Send it exactly as returned; any other name is rejected. minLength: 1 maxLength: 255 example: Bank Leumi Le-Israel B.M example: accountType: ILS_ACCOUNT iban: IL620108000000099999999 bankName: Bank Leumi Le-Israel B.M BdtBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' GtqAccountInfo: allOf: - $ref: '#/components/schemas/GtqAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER KybStatus: type: string enum: - UNVERIFIED - PENDING - APPROVED - REJECTED - HOLD description: The current KYB status of a business customer. `HOLD` means the customer is placed on hold and may be required to update or provide more information. example: APPROVED ZmwBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName - registrationNumber - taxId properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' PaymentEmbeddedWalletInfo: title: Embedded Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - type: object required: - accountType - payloadToSign properties: accountType: type: string enum: - EMBEDDED_WALLET description: Discriminator value identifying this as Embedded Wallet payment instructions. payloadToSign: type: string description: JSON-encoded transaction signing payload that must be stamped, as-is (byte-for-byte, without re-serialization), with the session private key of a verified authentication credential on the source Embedded Wallet. The resulting Grid wallet signature is passed as the `Grid-Wallet-Signature` header on `POST /quotes/{quoteId}/execute` to authorize the outbound transfer from the wallet. example: '{"type":"ACTIVITY_TYPE_SIGN_TRANSACTION_V2","timestampMs":"1746736509954","organizationId":"org_abc123","parameters":{"signWith":"wallet_abc123def456","unsignedTransaction":"ea69b4bf05f775209f26ff0a34a05569180f7936579d5c4af9377ae550194f72","type":"TRANSACTION_TYPE_ETHEREUM"},"generateAppProofs":true}' BdtAccountInfo: allOf: - $ref: '#/components/schemas/BdtAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER - MOBILE_MONEY TransactionSourceType: type: string enum: - ACCOUNT - UMA_ADDRESS - REALTIME_FUNDING description: Type of transaction source example: ACCOUNT PaymentRail: type: string enum: - ACH - ACH_COLOMBIA - ACH_SAME_DAY - BANK_TRANSFER - BRE_B - CIPS - FAST - FASTER_PAYMENTS - FEDNOW - INSTAPAY - MOBILE_MONEY - NEFT - PAYNOW - PESONET - PIX - RTGS - RTP - SEPA - SEPA_INSTANT - SPEI - SWIFT - UNIONPAY - UPI - WIRE description: 'The payment rail used for the transfer. Payment rails represent the underlying payment network or system used to move funds between accounts. `ACH_SAME_DAY` requests same-business-day settlement for a USD payout and is priced separately. It is subject to the NACHA per-entry same-day limit, which the network applies to every originator: $1,000,000 per entry, rising to $10,000,000 on 2027-09-17. A payout above that limit is rejected rather than slowed — check the amount before requesting this rail, or send it over `ACH`, which settles on the standard schedule and has no such limit. `ACH` will settle on the standard next-business-day schedule. Until a date we announce in advance, `ACH` continues to settle same-business-day on production platforms; it already settles next-business-day on sandbox platforms. To guarantee same-day settlement after that date, request `ACH_SAME_DAY`.' example: ACH IncomingPaymentWebhookForbiddenResponse: allOf: - $ref: '#/components/schemas/GridError' - type: object properties: reason: type: string description: Optional reason for rejecting the payment. This is just for debugging purposes or can be used for a platform's own purposes. example: RESTRICTED_JURISDICTION PolygonWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - POLYGON_WALLET address: type: string description: Polygon eth wallet address example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' ExternalAccount: allOf: - type: object required: - id - status - currency - accountInfo properties: id: type: string description: The system generated identifier of this account example: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 customerId: type: string description: The customer this account is tied to, or null if the account is on behalf of the platform. example: Customer:da459a29-1fb7-41ce-a4cb-eb3a3c9fd7a7 status: $ref: '#/components/schemas/ExternalAccountStatus' description: Status of the external account example: ACTIVE platformAccountId: type: string description: Optional platform-specific identifier for this account example: acc_123456789 ownershipType: $ref: '#/components/schemas/OwnershipType' currency: type: string description: The ISO 4217 currency code example: USD defaultUmaDepositAccount: type: boolean description: Whether this account is the default UMA deposit account for the customer. If true, incoming UMA payments to this customer's UMA address will be automatically deposited into this account instead of the primary internal account. False if not provided. Note that at most, one external account can be set as the default UMA deposit account for a customer. If there is no default UMA deposit account, incoming UMA payments will be deposited into the primary internal account for the customer. example: false beneficiaryVerificationStatus: $ref: '#/components/schemas/BeneficiaryVerificationStatus' description: The result of verifying the beneficiary name against the account holder name beneficiaryVerifiedData: $ref: '#/components/schemas/BeneficiaryVerifiedData' description: Verified beneficiary data returned by the payment rail, if available accountInfo: $ref: '#/components/schemas/ExternalAccountInfoOneOf' EgpExternalAccountInfo: title: EGP Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/EgpAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/EgpBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/EgpBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/EgpBeneficiary' BUSINESS: '#/components/schemas/EgpBusinessBeneficiary' TronWalletExternalAccountInfo: title: Tron Wallet allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/TronWalletInfo' - $ref: '#/components/schemas/WalletBeneficiaryFields' - $ref: '#/components/schemas/WalletCustodyFields' CnyBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - address - legalName properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' HtgAccountInfo: allOf: - $ref: '#/components/schemas/HtgAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - MOBILE_MONEY GbpAccountInfoBase: type: object required: - accountType - sortCode - accountNumber properties: accountType: type: string enum: - GBP_ACCOUNT sortCode: type: string description: The UK sort code example: '123456' minLength: 6 maxLength: 6 pattern: ^[0-9]{6}$ accountNumber: type: string description: UK bank account number (8 digits) minLength: 8 maxLength: 8 example: '12345678' pattern: ^[0-9]{8}$ example: accountType: GBP_ACCOUNT sortCode: '123456' accountNumber: '12345678' IdrBusinessBeneficiary: title: Business Beneficiary type: object required: - beneficiaryType - legalName properties: beneficiaryType: type: string enum: - BUSINESS legalName: type: string maxLength: 250 description: The legal name of the business email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The company registration number of the business taxId: type: string maxLength: 100 description: The tax identification number of the business countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' WireBankAccountDetails: title: Wire Bank Account Details allOf: - $ref: '#/components/schemas/UsdBankAccountDetails' - type: object properties: bankName: type: string description: Name of the account's bank. example: Chase Bank KesExternalAccountInfo: title: KES Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/KesAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/KesBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/KesBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/KesBeneficiary' BUSINESS: '#/components/schemas/KesBusinessBeneficiary' ThbAccountInfoBase: type: object required: - accountType - bankName - accountNumber - swiftCode properties: accountType: type: string enum: - THB_ACCOUNT bankName: type: string description: The name of the bank. Must be one of the `bankName` values `GET /discoveries` returns for this country and currency. Send it exactly as returned; any other name is rejected. minLength: 1 maxLength: 255 example: Bangkok Bank Public Company Limited accountNumber: type: string description: Thai bank account number minLength: 1 maxLength: 34 example: '1234567890' swiftCode: type: string description: The SWIFT/BIC code of the bank example: BKKBTHBK minLength: 8 maxLength: 11 pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$ example: accountType: THB_ACCOUNT bankName: Bangkok Bank Public Company Limited accountNumber: '1234567890' swiftCode: BKKBTHBK XafAccountInfo: allOf: - $ref: '#/components/schemas/XafAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - MOBILE_MONEY CardForm: type: string enum: - VIRTUAL description: 'Physical form factor of the card. Only `VIRTUAL` is supported in v1; `PHYSICAL` will be added in a later release. ' CadBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary registrationNumber: type: string maxLength: 100 description: The registration number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' PaymentSparkWalletInfo: title: Spark Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/SparkWalletInfo' - type: object required: - assetType properties: assetType: type: string description: Type of asset or configured Spark token currency code invoice: type: string description: Invoice for the payment example: sparkrt1pgss8ter0fhc4c220f3zftmpz49h8wqte8eg3m5zkrraplgc048jucgszg3ssqgjzqqekv73mmh842yj7drsjwh7t7tz5zt8wf5kghm5v4ehggszppjp5s80cg3qjdzc55g2567tn3lj705hdsr577tg8ah795mlnt6807y657qhkmgfkf9w75p4wz3l8vhua85zdn6ryj32zuj0p00pv2l5z4u47mw6h4s CryptoNetwork: type: string enum: - BITCOIN - ETHEREUM - SOLANA - BASE - POLYGON - TRON - PLASMA - ARBITRUM - SPARK description: The blockchain network an on-chain transaction settled on. Whether this is the mainnet or a test network (e.g. Solana devnet) is determined by your platform's environment — sandbox platforms operate on test networks, production platforms on mainnet — mirroring how `cryptoNetwork` is interpreted elsewhere in the API. example: SOLANA XafBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' PkrAccountInfoBase: type: object required: - accountType - bankName description: 'Required fields depend on the selected paymentRails: - BANK_TRANSFER: accountNumber, bankName - MOBILE_MONEY: bankName, phoneNumber' properties: accountType: type: string enum: - PKR_ACCOUNT bankName: type: string description: The name of the bank. Must be one of the `bankName` values `GET /discoveries` returns for this country and currency. Send it exactly as returned; any other name is rejected. minLength: 1 maxLength: 255 example: Habib Bank Limited accountNumber: type: string description: The account number of the bank minLength: 1 maxLength: 34 iban: type: string description: Pakistani IBAN (24 characters, starting with PK) example: PK36SCBL0000001123456702 minLength: 24 maxLength: 24 pattern: ^PK[0-9]{2}[A-Z]{4}[0-9]{16}$ phoneNumber: type: string description: The phone number in international format example: '+1234567890' minLength: 7 maxLength: 15 pattern: ^\+[0-9]{6,14}$ example: accountType: PKR_ACCOUNT bankName: Habib Bank Limited accountNumber: '1234567890' iban: PK36SCBL0000001123456702 phoneNumber: '+1234567890' WalletOperationWebhookData: title: Wallet Operation Data oneOf: - $ref: '#/components/schemas/WalletOperationCompletedData' - $ref: '#/components/schemas/WalletOperationFailedData' discriminator: propertyName: status mapping: completed: '#/components/schemas/WalletOperationCompletedData' failed: '#/components/schemas/WalletOperationFailedData' XofAccountInfo: allOf: - $ref: '#/components/schemas/XofAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - MOBILE_MONEY PkrExternalAccountInfo: title: PKR Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/PkrAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/PkrBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/BusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/PkrBeneficiary' BUSINESS: '#/components/schemas/BusinessBeneficiary' UgxBeneficiary: title: Individual Beneficiary type: object required: - beneficiaryType - fullName properties: beneficiaryType: type: string enum: - INDIVIDUAL fullName: type: string maxLength: 250 description: The full name of the beneficiary birthDate: type: string description: The birth date of the beneficiary nationality: type: string description: The nationality of the beneficiary email: type: string maxLength: 320 description: The email of the beneficiary phoneNumber: type: string maxLength: 50 description: The phone number of the beneficiary countryOfResidence: type: string description: The country of residence of the beneficiary address: $ref: '#/components/schemas/Address' TransactionDestinationType: type: string enum: - ACCOUNT - UMA_ADDRESS description: Type of transaction destination example: ACCOUNT RailDetailsOneOf: description: 'The rail transfer that moved funds for this side of the transaction. `paymentRail` determines the shape: each rail carries its own identifiers. Absent until a rail transfer exists for this side, and on sides whose funds move within Grid.' oneOf: - $ref: '#/components/schemas/OnChainRailDetails' - $ref: '#/components/schemas/AchRailDetails' - $ref: '#/components/schemas/WireRailDetails' - $ref: '#/components/schemas/FedNowRailDetails' - $ref: '#/components/schemas/RtpRailDetails' discriminator: propertyName: paymentRail mapping: ONCHAIN: '#/components/schemas/OnChainRailDetails' ACH: '#/components/schemas/AchRailDetails' ACH_SAME_DAY: '#/components/schemas/AchRailDetails' WIRE: '#/components/schemas/WireRailDetails' FEDNOW: '#/components/schemas/FedNowRailDetails' RTP: '#/components/schemas/RtpRailDetails' CardCapabilities: type: object description: Actions supported by the card program associated with this resource. required: - supportsSpendLimits - supportsSpendLimitsAtIssuance - supportsTransactionCountLimit - supports3dSecurePassword - supportsPanReveal - supportsDigitalWalletTokenization properties: supportsSpendLimits: type: boolean description: Whether a card in this program can have `maxSpendPerTransaction` and `maxSpendPerDay` at all. On card programs where the card issuer makes authorization decisions, these limits can only be set after issuance through `PATCH /cards/{id}`. Check `supportsSpendLimitsAtIssuance` to determine whether you can supply them when issuing a card. example: true supportsSpendLimitsAtIssuance: type: boolean description: Whether `maxSpendPerTransaction` and `maxSpendPerDay` may be supplied on `POST /cards`. This is true for card programs where Grid makes the authorization decision and false for card programs where the card issuer makes authorization decisions. example: true supportsTransactionCountLimit: type: boolean description: Whether cards in this program accept `maxTransactionsPerDay`. example: true supports3dSecurePassword: type: boolean description: Whether cards in this program accept a caller-supplied `threeDSecurePassword`. example: false supportsPanReveal: type: boolean description: Whether cards in this program can be revealed through `POST /cards/{id}/reveal`. example: true supportsDigitalWalletTokenization: type: boolean description: Whether cards in this program can be added to Apple Pay, Google Pay, or Samsung Pay from your app through `POST /cards/{id}/tokenize`. Manual entry into a wallet works regardless of this flag. example: true IndividualCustomerFields: allOf: - type: object required: - customerType properties: customerType: type: string enum: - INDIVIDUAL kycStatus: $ref: '#/components/schemas/KycStatus' fullName: type: string maxLength: 250 description: Individual's full name example: John Michael Doe birthDate: type: string format: date description: Date of birth in ISO 8601 format (YYYY-MM-DD) example: '1990-01-15' nationality: type: string description: Country code (ISO 3166-1 alpha-2) example: US address: $ref: '#/components/schemas/Address' idType: $ref: '#/components/schemas/IdentificationType' identifier: type: string maxLength: 100 writeOnly: true description: The individual's identification number, required to onboard them as a US account holder. Only SSN (format `###-##-####`) and ITIN are currently accepted; other identification types are rejected. Write-only — never returned in customer responses. example: 123-45-6789 countryOfIssuance: type: string description: 'Country that issued the identification (ISO 3166-1 alpha-2). Optional for an individual account holder: SSN and ITIN are US-issued, so this defaults to `US` and is rejected if set to anything else.' example: US - $ref: '#/components/schemas/CustomerEdd' XafExternalAccountInfo: title: XAF Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/XafAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/XafBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/XafBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/XafBeneficiary' BUSINESS: '#/components/schemas/XafBusinessBeneficiary' BulkUploadWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/BulkCustomerImportJob' type: $ref: '#/components/schemas/BulkUploadWebhookEventType' BulkUploadWebhookEventType: type: string enum: - BULK_UPLOAD.COMPLETED - BULK_UPLOAD.FAILED BusinessType: type: string description: The high-level industry category of the business enum: - AGRICULTURE_FORESTRY_FISHING_AND_HUNTING - MINING_QUARRYING_AND_OIL_AND_GAS_EXTRACTION - UTILITIES - CONSTRUCTION - MANUFACTURING - WHOLESALE_TRADE - RETAIL_TRADE - TRANSPORTATION_AND_WAREHOUSING - INFORMATION - FINANCE_AND_INSURANCE - REAL_ESTATE_AND_RENTAL_AND_LEASING - PROFESSIONAL_SCIENTIFIC_AND_TECHNICAL_SERVICES - MANAGEMENT_OF_COMPANIES_AND_ENTERPRISES - ADMINISTRATIVE_AND_SUPPORT_AND_WASTE_MANAGEMENT_AND_REMEDIATION_SERVICES - EDUCATIONAL_SERVICES - HEALTH_CARE_AND_SOCIAL_ASSISTANCE - ARTS_ENTERTAINMENT_AND_RECREATION - ACCOMMODATION_AND_FOOD_SERVICES - OTHER_SERVICES - PUBLIC_ADMINISTRATION GbpExternalAccountInfo: title: GBP Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/GbpAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/GbpBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/GbpBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/GbpBeneficiary' BUSINESS: '#/components/schemas/GbpBusinessBeneficiary' ZmwExternalAccountInfo: title: ZMW Account allOf: - $ref: '#/components/schemas/BaseExternalAccountInfo' - $ref: '#/components/schemas/ZmwAccountInfo' - type: object required: - beneficiary properties: beneficiary: oneOf: - title: Individual Beneficiary $ref: '#/components/schemas/ZmwBeneficiary' - title: Business Beneficiary $ref: '#/components/schemas/ZmwBusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: INDIVIDUAL: '#/components/schemas/ZmwBeneficiary' BUSINESS: '#/components/schemas/ZmwBusinessBeneficiary' PkrAccountInfo: allOf: - $ref: '#/components/schemas/PkrAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER - MOBILE_MONEY VerificationStatus: type: string enum: - RESOLVE_ERRORS - PENDING_MANUAL_REVIEW - IN_PROGRESS - APPROVED - REJECTED - READY_FOR_VERIFICATION description: Current status of the KYC/KYB verification example: RESOLVE_ERRORS CardFundingSourceChangeWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/Card_2' type: type: string enum: - CARD.FUNDING_SOURCE_CHANGE CardStateChangeWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/Card_2' type: type: string enum: - CARD.STATE_CHANGE Card_2: type: object required: - id - cardholderId - state - form - fundingSources - createdAt - updatedAt properties: id: type: string description: System-generated unique card identifier readOnly: true example: Card:019542f5-b3e7-1d02-0000-000000000010 cardholderId: type: string description: The id of the `Customer` who holds this card. example: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCardId: type: string description: Platform-specific card identifier. Optional on create — system-generated if omitted, mirroring `platformCustomerId` semantics. example: card-emp-aary-001 state: $ref: '#/components/schemas/CardState' stateReason: anyOf: - $ref: '#/components/schemas/CardStateReason' - type: 'null' description: Reason associated with the current `state`. Populated when the card is `CLOSED` or when provisioning was rejected; otherwise null. brand: $ref: '#/components/schemas/CardBrand' form: $ref: '#/components/schemas/CardForm' last4: type: string description: Last four digits of the card PAN. example: '4242' expMonth: type: integer minimum: 1 maximum: 12 description: Card expiration month (1–12). example: 12 expYear: type: integer description: Card expiration year (four digits). example: 2029 fundingSources: type: array description: Internal account ids bound to this card as funding sources, in priority order — the first entry is tried first by Authorization Decisioning. Every card has at least one funding source. items: type: string example: - InternalAccount:019542f5-b3e7-1d02-0000-000000000002 - InternalAccount:019542f5-b3e7-1d02-0000-000000000003 currency: type: string description: Currency the card transacts in (ISO 4217 for fiat, tickers for crypto). Derived from the funding sources at issue time — all funding sources bound to a card must be denominated in the same card-eligible currency. example: USD readOnly: true processorRef: type: string description: Opaque processor-side reference for the card (e.g. the Lithic card token). Useful for cross-referencing in the processor's dashboards; not used for any Grid request routing. example: card_b81c2a4f readOnly: true issuerRef: type: string description: Opaque identifier for the card on the issuer of record (e.g. the Lead Bank account/card identifier). Useful for cross-referencing in issuer dashboards; not used for any Grid request routing. example: lead_card_7a1b9c3d readOnly: true createdAt: type: string format: date-time description: Creation timestamp readOnly: true example: '2026-05-08T14:10:00Z' updatedAt: type: string format: date-time description: Last update timestamp readOnly: true example: '2026-05-08T14:11:00Z' CardStateReason: type: string enum: - ISSUER_REJECTED - CLOSED_BY_PLATFORM - CLOSED_BY_GRID description: 'Reason a card reached a terminal or non-active state. Present on `CLOSED` cards, and on cards that fail provisioning before reaching `ACTIVE`. | Reason | Description | |--------|-------------| | `ISSUER_REJECTED` | The card issuer rejected provisioning during `PROCESSING`. | | `CLOSED_BY_PLATFORM` | The card was closed via `PATCH /cards/{id}` (`state: CLOSED`) by the platform. | | `CLOSED_BY_GRID` | The card was closed by Grid (e.g. compliance or risk action). | ' WebhookType_2: type: string enum: - OUTGOING_PAYMENT.PENDING - OUTGOING_PAYMENT.PROCESSING - OUTGOING_PAYMENT.COMPLETED - OUTGOING_PAYMENT.FAILED - OUTGOING_PAYMENT.EXPIRED - OUTGOING_PAYMENT.REFUND_PENDING - OUTGOING_PAYMENT.REFUND_COMPLETED - OUTGOING_PAYMENT.REFUND_FAILED - INCOMING_PAYMENT.PENDING - INCOMING_PAYMENT.COMPLETED - INCOMING_PAYMENT.FAILED - CUSTOMER.KYC_APPROVED - CUSTOMER.KYC_REJECTED - CUSTOMER.KYC_PENDING - CUSTOMER.KYB_APPROVED - CUSTOMER.KYB_REJECTED - CUSTOMER.KYB_PENDING - VERIFICATION.APPROVED - VERIFICATION.REJECTED - VERIFICATION.RESOLVE_ERRORS - VERIFICATION.IN_PROGRESS - VERIFICATION.PENDING_MANUAL_REVIEW - VERIFICATION.READY_FOR_VERIFICATION - INTERNAL_ACCOUNT.BALANCE_UPDATED - INTERNAL_ACCOUNT.STATUS_UPDATED - INVITATION.CLAIMED - BULK_UPLOAD.COMPLETED - BULK_UPLOAD.FAILED - AGENT_ACTION.PENDING_APPROVAL - CARD.STATE_CHANGE - CARD.FUNDING_SOURCE_CHANGE - CARD_TRANSACTION.AUTHORIZED - CARD_TRANSACTION.PARTIALLY_SETTLED - CARD_TRANSACTION.SETTLED - CARD_TRANSACTION.REFUNDED - CARD_TRANSACTION.EXCEPTION - TEST description: Type of webhook event in OBJECT.EVENT dot-notation. The part before the dot identifies the resource, the part after identifies the event. This lets consumers route purely on type without inspecting data.status. CardState: type: string enum: - PENDING_KYC - PROCESSING - ACTIVE - FROZEN - CLOSED description: 'Lifecycle state of a card. | State | Description | |-------|-------------| | `PENDING_KYC` | The cardholder has not yet completed KYC. Cards in this state cannot transact. | | `PROCESSING` | The card has been requested and is being provisioned with the issuer. | | `ACTIVE` | The card is live and can authorize transactions. | | `FROZEN` | The card is temporarily disabled by the platform. New authorizations are declined with `CARD_PAUSED`. Existing settlements and refunds continue to reconcile. | | `CLOSED` | The card is permanently closed. Terminal, irreversible state. | ' Error409_2: type: object required: - message - status - code properties: status: type: integer enum: - 409 description: HTTP status code code: type: string description: '| Error Code | Description | |------------|-------------| | TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL | Transaction is not pending platform approval | | UMA_ADDRESS_EXISTS | UMA address already exists | | EMAIL_OTP_EMAIL_ALREADY_EXISTS | Email address is already associated with an EMAIL_OTP credential | | EMAIL_OTP_CREDENTIAL_SET_CHANGED | Tied EMAIL_OTP credential set changed after the signed-retry challenge was issued | | PASSKEY_ALREADY_ENROLLED | The customer already has an enrolled passkey factor; only one passkey per customer is supported. Delete the existing one before enrolling another | | CONFLICT | Generic resource-state conflict. Returned, for example, when `platformCustomerId` on a customer create call collides with an existing active customer on the same platform | ' enum: - TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL - UMA_ADDRESS_EXISTS - EMAIL_OTP_EMAIL_ALREADY_EXISTS - EMAIL_OTP_CREDENTIAL_SET_CHANGED - PASSKEY_ALREADY_ENROLLED - CONFLICT message: type: string description: Error message details: type: object description: Additional error details additionalProperties: true Error400_2: type: object required: - message - status - code properties: status: type: integer enum: - 400 description: HTTP status code code: type: string description: '| Error Code | Description | |------------|-------------| | INVALID_INPUT | Invalid input provided | | MISSING_MANDATORY_USER_INFO | Required customer information is missing | | INVITATION_ALREADY_CLAIMED | Invitation has already been claimed | | INVITATIONS_NOT_CONFIGURED | Invitations are not configured | | INVALID_UMA_ADDRESS | UMA address format is invalid | | INVITATION_CANCELLED | Invitation has been cancelled | | QUOTE_REQUEST_FAILED | An issue occurred during the quote process; this is retryable | | INVALID_PAYREQ_RESPONSE | Counterparty Payreq response was invalid | | INVALID_RECEIVER | Receiver is invalid | | PARSE_PAYREQ_RESPONSE_ERROR | Error parsing receiver PayReq response | | CERT_CHAIN_INVALID | Counterparty certificate chain is invalid | | CERT_CHAIN_EXPIRED | Counterparty certificate chain has expired | | INVALID_PUBKEY_FORMAT | Counterparty Public key format is invalid | | MISSING_REQUIRED_UMA_PARAMETERS | Counterparty required UMA parameters are missing | | SENDER_NOT_ACCEPTED | Sender is not accepted | | AMOUNT_OUT_OF_RANGE | Amount is out of range | | INVALID_CURRENCY | Currency is invalid | | INVALID_TIMESTAMP | Timestamp is invalid | | INVALID_NONCE | Nonce is invalid | | INVALID_REQUEST_FORMAT | Request format is invalid | | INVALID_BANK_ACCOUNT | Bank account is invalid | | SELF_PAYMENT | Self payment not allowed | | LOOKUP_REQUEST_FAILED | Lookup request failed | | PARSE_LNURLP_RESPONSE_ERROR | Error parsing LNURLP response | | INVALID_AMOUNT | Amount is invalid | | WEBHOOK_ENDPOINT_NOT_SET | Webhook endpoint is not set | | WEBHOOK_DELIVERY_ERROR | Webhook delivery error | | LOW_QUALITY | Document quality too low to process | | DATA_MISMATCH | Document details don''t match provided information | | EXPIRED | Document has expired | | SUSPECTED_FRAUD | Document suspected of being forged or edited | | UNSUITABLE_DOCUMENT | Document type is not accepted or not supported | | INCOMPLETE | Document is missing pages or sides | | EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS | An EMAIL_OTP credential is already registered on the target internal account; only one email OTP credential is supported per internal account at this time | | SMS_OTP_CREDENTIAL_ALREADY_EXISTS | An SMS_OTP credential is already registered on the target internal account; only one SMS OTP credential is supported per internal account at this time | | PASSKEY_CREDENTIAL_ALREADY_EXISTS | A PASSKEY credential with the same WebAuthn credentialId is already registered on the target internal account | | STABLECOIN_PROVIDER_ACCOUNT_INVALID | The stablecoin provider account link is not usable | | STABLECOIN_PROVIDER_ACCOUNT_REVOKED | The stablecoin provider account link has been revoked | | STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED | Multiple active provider account links exist; pass `stablecoinProviderAccountId` to select one | ' enum: - INVALID_INPUT - MISSING_MANDATORY_USER_INFO - INVITATION_ALREADY_CLAIMED - INVITATIONS_NOT_CONFIGURED - INVALID_UMA_ADDRESS - INVITATION_CANCELLED - QUOTE_REQUEST_FAILED - INVALID_PAYREQ_RESPONSE - INVALID_RECEIVER - PARSE_PAYREQ_RESPONSE_ERROR - CERT_CHAIN_INVALID - CERT_CHAIN_EXPIRED - INVALID_PUBKEY_FORMAT - MISSING_REQUIRED_UMA_PARAMETERS - SENDER_NOT_ACCEPTED - AMOUNT_OUT_OF_RANGE - INVALID_CURRENCY - INVALID_TIMESTAMP - INVALID_NONCE - INVALID_REQUEST_FORMAT - INVALID_BANK_ACCOUNT - SELF_PAYMENT - LOOKUP_REQUEST_FAILED - PARSE_LNURLP_RESPONSE_ERROR - INVALID_AMOUNT - WEBHOOK_ENDPOINT_NOT_SET - WEBHOOK_DELIVERY_ERROR - LOW_QUALITY - DATA_MISMATCH - EXPIRED - SUSPECTED_FRAUD - UNSUITABLE_DOCUMENT - INCOMPLETE - EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS - SMS_OTP_CREDENTIAL_ALREADY_EXISTS - PASSKEY_CREDENTIAL_ALREADY_EXISTS - STABLECOIN_PROVIDER_ACCOUNT_INVALID - STABLECOIN_PROVIDER_ACCOUNT_REVOKED - STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED message: type: string description: Error message details: type: object description: Additional error details additionalProperties: true Error401_2: type: object required: - message - status - code properties: status: type: integer enum: - 401 description: HTTP status code code: type: string description: '| Error Code | Description | |------------|-------------| | UNAUTHORIZED | Issue with API credentials | | INVALID_SIGNATURE | Signature header is invalid | | WALLET_SIGNATURE_MISSING | The `Grid-Wallet-Signature` header is required for this Embedded Wallet action but was not supplied | | WALLET_SIGNATURE_MALFORMED | The `Grid-Wallet-Signature` header could not be parsed (bad encoding, structure, or fields) | | WALLET_SIGNATURE_BODY_MISMATCH | The `Grid-Wallet-Signature` was computed over a different request body than the one received | | WALLET_SIGNATURE_INVALID | The `Grid-Wallet-Signature` failed cryptographic verification against the registered credential | | REQUEST_ID_MISSING | The `Request-Id` header is required on the signed retry but was not supplied (paired with `Grid-Wallet-Signature`) | ' enum: - UNAUTHORIZED - INVALID_SIGNATURE - WALLET_SIGNATURE_MISSING - WALLET_SIGNATURE_MALFORMED - WALLET_SIGNATURE_BODY_MISMATCH - WALLET_SIGNATURE_INVALID - REQUEST_ID_MISSING message: type: string description: Error message details: type: object description: Additional error details additionalProperties: true securitySchemes: BasicAuth: type: http scheme: basic description: API token authentication using format `:` AgentAuth: type: http scheme: bearer description: 'Bearer token authentication for agent-scoped endpoints. The token is the `accessToken` returned when redeeming a device code via `POST /agents/device-codes/redeem`. Agent credentials are user-scoped: all requests are automatically bound to the agent''s associated customer and subject to the agent''s policy.' WebhookSignature: type: apiKey in: header name: X-Grid-Signature description: 'Secp256r1 (P-256) asymmetric signature of the webhook payload, which can be used to verify that the webhook was sent by Grid. To verify the signature: 1. Get the Grid public key provided to you during integration 2. Decode the base64 signature from the header 3. Create a SHA-256 hash of the request body 4. Verify the signature using the public key and the hash If the signature verification succeeds, the webhook is authentic. If not, it should be rejected. ' x-refined-from: - lightspark-openapi.yml - lightspark-webhooks-api-openapi.yml