openapi: 3.2.0 info: title: Grid Webhooks API description: 'API for managing global payments on the open Money Grid. Built by Lightspark. See the full documentation at https://docs.lightspark.com/. ' version: '2025-10-13' contact: name: Lightspark Support email: support@lightspark.com license: name: Proprietary url: https://lightspark.com/terms 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 transactionId: Transaction:019542f5-b3e7-1d02-0000-000000000099 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' incoming-payment: post: summary: Incoming payment webhook and approval mechanism description: 'Webhook that is called when an incoming payment is received by a customer''s UMA address. 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. ' 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 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 responses: '200': description: 'Webhook received successfully. For PENDING transactions, this indicates approval to proceed with the payment. 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. ' '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. ' 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. ' content: application/json: schema: $ref: '#/components/schemas/IncomingPaymentWebhookUnprocessableResponse' outgoing-payment: post: summary: Outgoing payment status webhook description: 'Webhook that is called when an outgoing payment''s 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 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 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: [] 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' 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' 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' 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' 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 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: San Francisco state: CA postalCode: '94105' 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 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 region: US currencies: - USD - USDC umaAddress: $acme.corp@uma.domain.com kybStatus: APPROVED address: line1: 456 Business Ave city: New York state: NY postalCode: '10001' 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 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' 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. ' 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' 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' 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' 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' '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' 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' '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' card-transaction: post: summary: Card transaction description: 'Webhook that is called on every state transition 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 settled funds are returned (`CARD_TRANSACTION.REFUNDED`), and when a pull or confirmation fails (`CARD_TRANSACTION.EXCEPTION`). The payload carries the full `CardTransaction` resource. 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: CardTransaction: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 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 pullSummary: count: 1 totalAmount: 12550 pendingCount: 1 refundSummary: count: 0 totalAmount: 0 settlementSummary: count: 0 totalAmount: 0 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: CardTransaction: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 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 pullSummary: count: 1 totalAmount: 12550 pendingCount: 0 refundSummary: count: 0 totalAmount: 0 settlementSummary: count: 1 totalAmount: 12550 authorizedAt: '2026-05-09T10:00:00Z' lastEventAt: '2026-05-09T15:42:11Z' createdAt: '2026-05-09T10:00:00Z' updatedAt: '2026-05-09T15:42:11Z' refunded: summary: Settled funds returned by the merchant value: id: Webhook:019542f5-b3e7-1d02-0000-000000000042 type: CARD_TRANSACTION.REFUNDED timestamp: '2026-05-10T09:15:00Z' data: type: CARD id: CardTransaction: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: REFUNDED direction: DEBIT 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 refundedAmount: amount: 12550 currency: code: USD name: United States Dollar symbol: $ decimals: 2 accountId: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 pullSummary: count: 1 totalAmount: 12550 pendingCount: 0 refundSummary: count: 1 totalAmount: 12550 settlementSummary: count: 1 totalAmount: 12550 authorizedAt: '2026-05-09T10:00:00Z' lastEventAt: '2026-05-10T09:15:00Z' createdAt: '2026-05-09T10:00:00Z' updatedAt: '2026-05-10T09:15: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: CardTransaction: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 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 pullSummary: count: 1 totalAmount: 0 pendingCount: 0 refundSummary: count: 0 totalAmount: 0 settlementSummary: count: 1 totalAmount: 4200 authorizedAt: '2026-05-09T15:30:00Z' lastEventAt: '2026-05-09T16:05: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' components: schemas: 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: 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 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. 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 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 remittanceInformation: type: string maxLength: 80 description: 'Free-form information about the payment that travels with it to the recipient, as provided on the quote request. The field this populates depends on the payment rail: for ACH it populates the Addenda record, for FedNow and RTP it populates the remittanceInformation field, and for wires it populates the OBI (Originator to Beneficiary Information) / beneficiary information.' example: '12345' 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. scaChallenge: $ref: '#/components/schemas/ScaChallenge' readOnly: true 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).' 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: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED description: Current status of the job example: PROCESSING 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' 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: type: string enum: - PENDING - COMPLETED - FAILED description: Current status of the refund example: COMPLETED reason: type: string enum: - TRANSACTION_FAILED - USER_CANCELLATION - TIMEOUT description: Reason for the refund example: TRANSACTION_FAILED InternalAccountStatusWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/InternalAccount' type: type: string enum: - INTERNAL_ACCOUNT.BALANCE_UPDATED - INTERNAL_ACCOUNT.STATUS_UPDATED BasePaymentAccountInfo: type: object required: - accountType properties: accountType: $ref: '#/components/schemas/PaymentAccountType' 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 QuoteDestinationOneOf: oneOf: - $ref: '#/components/schemas/AccountDestination' - $ref: '#/components/schemas/UmaAddressDestination' discriminator: propertyName: destinationType mapping: ACCOUNT: '#/components/schemas/AccountDestination' UMA_ADDRESS: '#/components/schemas/UmaAddressDestination' BdtAccountInfo: allOf: - $ref: '#/components/schemas/BdtAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER - MOBILE_MONEY PhpAccountInfo: allOf: - $ref: '#/components/schemas/PhpAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER 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 PaymentEthereumWalletInfo: title: Ethereum Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/EthereumWalletInfo' - type: object properties: assetType: type: string description: Type of asset enum: - USDC HkdAccountInfo: allOf: - $ref: '#/components/schemas/HkdAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER 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 PaymentCadAccountInfo: title: CAD Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/CadAccountInfo' - 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 PaymentGhsAccountInfo: title: GHS Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/GhsAccountInfo' - 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 TransactionType: type: string enum: - INCOMING - OUTGOING description: Type of transaction (incoming payment or outgoing payment) 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}' 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 CardTransaction: title: Card Transaction type: object required: - type - id - status - direction - merchant - authorizedAmount - accountId - customerId - platformCustomerId - authorizedAt - createdAt - updatedAt description: Parent transaction row for a card authorization and all of the pulls / settlements / refunds that reconcile against it. Child events are rolled up into the `pullSummary`, `refundSummary`, and `settlementSummary` aggregates. Delivered as the payload of the generic transaction webhook stream (extends the Transaction model with a card destination type) on every transition. 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 readOnly: true example: CardTransaction: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 readOnly: true status: $ref: '#/components/schemas/CardTransactionStatus' direction: $ref: '#/components/schemas/TransactionDirection' description: Card transactions debit the customer's account. example: DEBIT 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 pullSummary: $ref: '#/components/schemas/CardPullSummary' refundSummary: $ref: '#/components/schemas/CardRefundSummary' settlementSummary: $ref: '#/components/schemas/CardSettlementSummary' authorizedAt: type: string format: date-time description: When the auth was approved. example: '2026-05-08T14:30:00Z' lastEventAt: type: string format: date-time description: Timestamp of the most recent reconcile event (pull / clearing / refund) against this transaction. example: '2026-05-08T15:42:11Z' createdAt: type: string format: date-time description: Creation timestamp (same as `authorizedAt` for card transactions). readOnly: true example: '2026-05-08T14:30:00Z' updatedAt: type: string format: date-time description: Last update timestamp. readOnly: true example: '2026-05-08T15:42:11Z' UgxAccountInfo: allOf: - $ref: '#/components/schemas/UgxAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - MOBILE_MONEY MyrAccountInfoBase: type: object required: - accountType - bankName - accountNumber - swiftCode properties: accountType: type: string enum: - MYR_ACCOUNT bankName: type: string description: The name of the bank minLength: 1 maxLength: 255 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: Example Bank accountNumber: '1234567890' swiftCode: MABORUMMYYY InternalAccountType: title: Internal Account Type type: string enum: - INTERNAL_FIAT - INTERNAL_CRYPTO - EMBEDDED_WALLET 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.' 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. 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' HkdAccountInfoBase: type: object required: - accountType - bankName - accountNumber - swiftCode properties: accountType: type: string enum: - HKD_ACCOUNT bankName: type: string description: The name of the bank minLength: 1 maxLength: 255 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: Example Bank accountNumber: '123456789012' swiftCode: HSBCHKHHHKH PaymentUgxAccountInfo: title: UGX Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/UgxAccountInfo' - 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 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}$ example: accountType: USD_ACCOUNT accountNumber: '1234567890' routingNumber: '021000021' 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 CounterpartyFieldDefinition: type: object properties: name: $ref: '#/components/schemas/CustomerInfoFieldName' mandatory: type: boolean description: Whether the field is mandatory example: true required: - name - mandatory 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' EgpAccountInfo: allOf: - $ref: '#/components/schemas/EgpAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER - MOBILE_MONEY 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 onChainTransaction: $ref: '#/components/schemas/OnChainTransaction' description: On-chain transaction that delivered funds from this source, when the source is an external crypto wallet. Populated once the crypto transfer has settled. description: Source account details 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 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. IdentificationType: type: string enum: - SSN - ITIN - EIN - NON_US_TAX_ID description: Type of tax identification example: SSN GtqAccountInfo: allOf: - $ref: '#/components/schemas/GtqAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER BaseTransactionSource: type: object required: - sourceType properties: sourceType: $ref: '#/components/schemas/TransactionSourceType' currency: type: string description: Currency code for the source example: USD 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 minLength: 1 maxLength: 255 example: Bank Central Asia 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 accountNumber: '1234567890' swiftCode: CENAIDJA phoneNumber: '+6281234567890' 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' JmdAccountInfo: allOf: - $ref: '#/components/schemas/JmdAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER 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 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 PaymentHkdAccountInfo: title: HKD Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/HkdAccountInfo' - 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 PaymentInrAccountInfo: title: INR Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/InrAccountInfo' CardRefundSummary: type: object required: - count - totalAmount properties: count: type: integer description: Number of refund (return) events received for this transaction. example: 0 totalAmount: type: integer format: int64 description: Sum of all refund amounts in the smallest unit of the funding source's currency. example: 0 NgnAccountInfo: allOf: - $ref: '#/components/schemas/NgnAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER BwpAccountInfo: allOf: - $ref: '#/components/schemas/BwpAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - MOBILE_MONEY 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. Customer: type: object required: - umaAddress - platformCustomerId - customerType properties: id: type: string description: System-generated unique identifier readOnly: true example: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: type: string description: Platform-specific customer identifier example: 9f84e0c2a72c4fa customerType: $ref: '#/components/schemas/CustomerType' 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 readOnly: true example: '2025-07-21T17:32:28Z' updatedAt: type: string format: date-time description: Last update timestamp readOnly: true example: '2025-07-21T17:32:28Z' isDeleted: type: boolean description: Whether the customer is marked as deleted example: false readOnly: true contactVerification: allOf: - $ref: '#/components/schemas/ContactVerification' readOnly: true description: Email and phone verification state. **Only present when the customer's payment provider requires it** (e.g. EU customers); omitted otherwise. 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' PolygonWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - POLYGON_WALLET address: type: string description: Polygon eth wallet address example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' MxnAccountInfo: allOf: - $ref: '#/components/schemas/MxnAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - SPEI 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' 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 IndividualCustomerFields: type: object required: - customerType properties: customerType: type: string enum: - INDIVIDUAL kycStatus: $ref: '#/components/schemas/KycStatus' fullName: type: string 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' Error409: 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 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). | ' CustomerWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/CustomerOneOf' type: type: string enum: - CUSTOMER.KYC_APPROVED - CUSTOMER.KYC_REJECTED - CUSTOMER.KYC_PENDING - CUSTOMER.KYB_APPROVED - CUSTOMER.KYB_REJECTED - CUSTOMER.KYB_PENDING CardBrand: type: string enum: - VISA - MASTERCARD description: 'Card network brand. Read-only — determined by Grid when the card is provisioned with the issuer. ' CardStateChangeWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/Card' type: type: string enum: - CARD.STATE_CHANGE 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 VndAccountInfoBase: type: object required: - accountType - bankName - accountNumber - swiftCode properties: accountType: type: string enum: - VND_ACCOUNT bankName: type: string description: The name of the bank minLength: 1 maxLength: 255 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: Example Bank accountNumber: '1234567890' swiftCode: BFTVVNVX 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' PaymentSwiftAccountInfo: title: SWIFT Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/SwiftAccountInfo' - 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 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. 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 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 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 description: The name of the originator (sender) of the payment. example: John Sender accountIdentifier: type: string description: The originator's account number or IBAN. May be masked or partial depending on the rail. example: '****6789' bankName: type: string description: The name of the originating bank. example: Chase Bank bankIdentifier: type: string description: The identifier of the originating bank, such as a routing number, BIC, or SWIFT code. example: '021000021' paymentRail: description: The payment rail the funds arrived on. allOf: - $ref: '#/components/schemas/PaymentRail' remittanceInformation: type: string description: 'Free-form information about the payment provided by the originator. The source field depends on the payment rail: the Addenda record for ACH, the OBI / beneficiary information for wires, and the remittanceInformation field for RTP and FedNow.' example: '12345' endToEndId: type: string description: The originator's own end-to-end reference for the payment. example: E2E-9f2c6b6f traceNumber: type: string description: Rail-level tracking identifier for the payment, such as an ACH trace number or a wire IMAD/OMAD, useful for reconciliation. example: '021000020123456' onChainTransaction: $ref: '#/components/schemas/OnChainTransaction' description: On-chain transaction that delivered the funding, when the funds arrived from an external crypto wallet. Populated once the crypto transfer has settled. description: Transaction was funded using an external funding source. All originator fields are optional and populated on a best-effort basis depending on what the funding source provides. 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 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 PaymentAedAccountInfo: title: AED Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/AedAccountInfo' - 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 GhsAccountInfo: allOf: - $ref: '#/components/schemas/GhsAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER - MOBILE_MONEY PaymentZarAccountInfo: title: ZAR Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/ZarAccountInfo' - 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 BaseQuoteSource: type: object required: - sourceType properties: sourceType: $ref: '#/components/schemas/QuoteSourceType' VndAccountInfo: allOf: - $ref: '#/components/schemas/VndAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER 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' PaymentJmdAccountInfo: title: JMD Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/JmdAccountInfo' - 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 OutgoingTransactionFailureReason: type: string enum: - QUOTE_EXPIRED - QUOTE_EXECUTION_FAILED - LIGHTNING_PAYMENT_FAILED - FUNDING_AMOUNT_MISMATCH - COUNTERPARTY_POST_TX_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. 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 onChainTransaction: $ref: '#/components/schemas/OnChainTransaction' description: On-chain transaction that delivered funds to this destination, when the destination is an external crypto wallet. Populated once the crypto transfer has settled. description: Destination account details 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' PaymentMwkAccountInfo: title: MWK Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/MwkAccountInfo' - 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 PaymentIdrAccountInfo: title: IDR Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/IdrAccountInfo' - 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 BusinessInfoResponse: type: object description: 'Business information returned on a customer. `taxId` and `incorporatedOn` are required on creation but may be absent on legacy customers that pre-date the requirement, 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: 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 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 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 KesAccountInfo: allOf: - $ref: '#/components/schemas/KesAccountInfoBase' - 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' TransactionDestinationType: type: string enum: - ACCOUNT - UMA_ADDRESS description: Type of transaction destination example: ACCOUNT PaymentBwpAccountInfo: title: BWP Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/BwpAccountInfo' - 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 CardPullSummary: type: object required: - count - totalAmount properties: count: type: integer description: Total number of pulls (debits) executed against the funding source for this transaction. `> 1` indicates one or more post-hoc pulls — e.g. restaurant tip / over-auth clearings. example: 2 totalAmount: type: integer format: int64 description: Sum of all pull amounts in the smallest unit of the funding source's currency. example: 1500 pendingCount: type: integer description: Number of pulls still in the `PENDING` state. Drops to zero when every pull has reached a terminal state. Non-zero values that persist beyond the expected settlement window are an early signal for the `EXCEPTION` path. example: 0 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 QuoteSourceOneOf: oneOf: - $ref: '#/components/schemas/AccountQuoteSource' - $ref: '#/components/schemas/RealtimeFundingQuoteSource' discriminator: propertyName: sourceType mapping: ACCOUNT: '#/components/schemas/AccountQuoteSource' REALTIME_FUNDING: '#/components/schemas/RealtimeFundingQuoteSource' 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 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 minLength: 1 maxLength: 255 example: accountType: JMD_ACCOUNT accountNumber: '1234567890' branchCode: '11111' bankAccountType: CHECKING bankName: Example Bank PaymentEgpAccountInfo: title: EGP Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/EgpAccountInfo' - 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 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 minLength: 1 maxLength: 255 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: Example Bank phoneNumber: '+1234567890' SwiftAccountInfoBase: type: object 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' 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 PaymentRail: type: string enum: - ACH - ACH_COLOMBIA - 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. example: ACH EthereumWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - ETHEREUM_WALLET address: type: string description: Ethereum L1 wallet address example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' 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 exchangeRate: type: number description: Number of sending currency units per receiving currency unit. exclusiveMinimum: 0 example: 1.08 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 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 `onChainTransaction` instead. quoteId: type: string description: The ID of the quote that was used to trigger this payment example: Quote:019542f5-b3e7-1d02-0000-000000000006 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 refund: $ref: '#/components/schemas/Refund' description: The refund if transaction was refunded. 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: anyOf: - $ref: '#/components/schemas/RailSelectionMode' - type: 'null' description: How the rail was chosen — MANUAL when the platform specified a paymentRail on the destination, AUTO when Lightspark selects it. Null when no rail is resolved. 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. PaymentTzsAccountInfo: title: TZS Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/TzsAccountInfo' - 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 PaymentVndAccountInfo: title: VND Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/VndAccountInfo' - 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 TzsAccountInfo: allOf: - $ref: '#/components/schemas/TzsAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - MOBILE_MONEY SgdAccountInfo: allOf: - $ref: '#/components/schemas/SgdAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - PAYNOW - FAST - BANK_TRANSFER 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}$ BeneficialOwnerPersonalInfo: type: object required: - firstName - lastName - birthDate - nationality - address - idType - identifier properties: firstName: type: string description: First name of the individual example: Jane middleName: type: string description: Middle name of the individual example: Marie lastName: type: string 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 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 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 IncomingTransaction: title: Incoming Transaction allOf: - $ref: '#/components/schemas/Transaction' - type: object required: - type - receivedAmount properties: type: type: string enum: - INCOMING source: $ref: '#/components/schemas/TransactionSourceOneOf' receivedAmount: $ref: '#/components/schemas/CurrencyAmount' description: Amount received in the recipient's currency fees: type: integer format: int64 description: The total fees available from the receive quote in the smallest unit of the receiving currency (eg. cents). minimum: 0 example: 10 reconciliationInstructions: $ref: '#/components/schemas/ReconciliationInstructions' description: Included for all transactions except those with "CREATED" status rateDetails: $ref: '#/components/schemas/IncomingRateDetails' description: Details about the rate and fees for the transaction. failureReason: $ref: '#/components/schemas/IncomingTransactionFailureReason' description: If the transaction failed, this field provides the reason for failure. 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.' InrAccountInfo: allOf: - $ref: '#/components/schemas/InrAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - UPI - NEFT - RTGS PaymentCnyAccountInfo: title: CNY Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/CnyAccountInfo' - 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 PaymentThbAccountInfo: title: THB Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/ThbAccountInfo' - 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 PaymentPkrAccountInfo: title: PKR Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/PkrAccountInfo' - 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 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 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 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 QuoteSourceType: type: string enum: - ACCOUNT - REALTIME_FUNDING description: Type of quote funding source example: ACCOUNT AgentTransferDetails: type: object description: Details of a transfer-type agent action (TRANSFER_OUT or TRANSFER_IN). required: - amount - currency - sourceAccountId - destinationAccountId properties: amount: type: integer format: int64 description: Transfer amount in the smallest unit of the specified currency. example: 50000 currency: type: string description: ISO 4217 currency code for the transfer amount. example: USD sourceAccountId: type: string description: ID of the source account (internal or external). example: InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123 destinationAccountId: type: string description: ID of the destination account (internal or external). example: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 DestinationType: type: string enum: - ACCOUNT - UMA_ADDRESS description: Type of payment destination example: ACCOUNT 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`, `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.). 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 PaymentHtgAccountInfo: title: HTG Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/HtgAccountInfo' - 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 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 ThbAccountInfoBase: type: object required: - accountType - bankName - accountNumber - swiftCode properties: accountType: type: string enum: - THB_ACCOUNT bankName: type: string description: The name of the bank minLength: 1 maxLength: 255 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: Example Bank accountNumber: '1234567890' swiftCode: BKKBTHBK EurAccountInfo: allOf: - $ref: '#/components/schemas/EurAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - SEPA - SEPA_INSTANT AgentActionType: type: string enum: - EXECUTE_QUOTE - TRANSFER_OUT - TRANSFER_IN description: 'The type of action the agent is requesting. | Type | Description | |------|-------------| | `EXECUTE_QUOTE` | Execute a cross-currency quote | | `TRANSFER_OUT` | Transfer from an internal account to an external account | | `TRANSFER_IN` | Transfer from an external account to an internal account | ' 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 CryptoNetwork: type: string enum: - BITCOIN - ETHEREUM - SOLANA - BASE - POLYGON - TRON - 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 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 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` | Approved but execution failed (e.g. quote expired, insufficient funds) | ' 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 - SPARK_WALLET - LIGHTNING - SOLANA_WALLET - TRON_WALLET - POLYGON_WALLET - BASE_WALLET - ETHEREUM_WALLET - EMBEDDED_WALLET description: Type of payment account or wallet example: USD_ACCOUNT 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). 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 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); authorize the transaction''s `scaChallenge` to proceed. | | `PROCESSING` | Funding has been received and payment initiated | | `COMPLETED` | Cross border payment has been received, converted and payment has been sent to the offramp network | | `REJECTED` | Receiving institution or wallet rejected payment, payment has been refunded | | `FAILED` | An error occurred during payment | | `REFUNDED` | Payment was unable to complete and refunded | | `EXPIRED` | Quote has expired | ' 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 PaymentZmwAccountInfo: title: ZMW Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/ZmwAccountInfo' - 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 PaymentXofAccountInfo: title: XOF Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/XofAccountInfo' - 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 PaymentGtqAccountInfo: title: GTQ Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/GtqAccountInfo' - 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 PaymentSgdAccountInfo: title: SGD Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/SgdAccountInfo' - 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 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 minLength: 1 maxLength: 255 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: Example Bank branchCode: '11111' swiftCode: DEUTDEFF phoneNumber: '+1234567890' 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. | ' TestWebhookRequest: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object properties: type: type: string enum: - TEST 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 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 WebhookType: 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. PaymentSlvAccountInfo: title: SLV Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/SlvAccountInfo' - 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 CardTransactionWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/CardTransaction' type: type: string enum: - CARD_TRANSACTION.AUTHORIZED - CARD_TRANSACTION.PARTIALLY_SETTLED - CARD_TRANSACTION.SETTLED - CARD_TRANSACTION.REFUNDED - CARD_TRANSACTION.EXCEPTION IncomingPaymentWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/IncomingPaymentWebhookData' type: type: string enum: - INCOMING_PAYMENT.PENDING - INCOMING_PAYMENT.COMPLETED - INCOMING_PAYMENT.FAILED 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 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 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 OutgoingPaymentWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/OutgoingTransaction' type: 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 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: oneOf: - $ref: '#/components/schemas/PaymentUsdAccountInfo' - $ref: '#/components/schemas/PaymentBrlAccountInfo' - $ref: '#/components/schemas/PaymentMxnAccountInfo' - $ref: '#/components/schemas/PaymentDkkAccountInfo' - $ref: '#/components/schemas/PaymentEurAccountInfo' - $ref: '#/components/schemas/PaymentInrAccountInfo' - $ref: '#/components/schemas/PaymentNgnAccountInfo' - $ref: '#/components/schemas/PaymentCadAccountInfo' - $ref: '#/components/schemas/PaymentGbpAccountInfo' - $ref: '#/components/schemas/PaymentHkdAccountInfo' - $ref: '#/components/schemas/PaymentIdrAccountInfo' - $ref: '#/components/schemas/PaymentMyrAccountInfo' - $ref: '#/components/schemas/PaymentPhpAccountInfo' - $ref: '#/components/schemas/PaymentSgdAccountInfo' - $ref: '#/components/schemas/PaymentThbAccountInfo' - $ref: '#/components/schemas/PaymentVndAccountInfo' - $ref: '#/components/schemas/PaymentAedAccountInfo' - $ref: '#/components/schemas/PaymentKesAccountInfo' - $ref: '#/components/schemas/PaymentMwkAccountInfo' - $ref: '#/components/schemas/PaymentRwfAccountInfo' - $ref: '#/components/schemas/PaymentTzsAccountInfo' - $ref: '#/components/schemas/PaymentUgxAccountInfo' - $ref: '#/components/schemas/PaymentXofAccountInfo' - $ref: '#/components/schemas/PaymentZarAccountInfo' - $ref: '#/components/schemas/PaymentZmwAccountInfo' - $ref: '#/components/schemas/PaymentBwpAccountInfo' - $ref: '#/components/schemas/PaymentXafAccountInfo' - $ref: '#/components/schemas/PaymentBdtAccountInfo' - $ref: '#/components/schemas/PaymentArsAccountInfo' - $ref: '#/components/schemas/PaymentCopAccountInfo' - $ref: '#/components/schemas/PaymentEgpAccountInfo' - $ref: '#/components/schemas/PaymentGhsAccountInfo' - $ref: '#/components/schemas/PaymentGtqAccountInfo' - $ref: '#/components/schemas/PaymentHtgAccountInfo' - $ref: '#/components/schemas/PaymentJmdAccountInfo' - $ref: '#/components/schemas/PaymentPkrAccountInfo' - $ref: '#/components/schemas/PaymentSlvAccountInfo' - $ref: '#/components/schemas/PaymentSwiftAccountInfo' - $ref: '#/components/schemas/PaymentCnyAccountInfo' - $ref: '#/components/schemas/PaymentSparkWalletInfo' - $ref: '#/components/schemas/PaymentLightningInvoiceInfo' - $ref: '#/components/schemas/PaymentSolanaWalletInfo' - $ref: '#/components/schemas/PaymentTronWalletInfo' - $ref: '#/components/schemas/PaymentPolygonWalletInfo' - $ref: '#/components/schemas/PaymentBaseWalletInfo' - $ref: '#/components/schemas/PaymentEthereumWalletInfo' - $ref: '#/components/schemas/PaymentEmbeddedWalletInfo' discriminator: propertyName: accountType mapping: USD_ACCOUNT: '#/components/schemas/PaymentUsdAccountInfo' BRL_ACCOUNT: '#/components/schemas/PaymentBrlAccountInfo' MXN_ACCOUNT: '#/components/schemas/PaymentMxnAccountInfo' DKK_ACCOUNT: '#/components/schemas/PaymentDkkAccountInfo' EUR_ACCOUNT: '#/components/schemas/PaymentEurAccountInfo' INR_ACCOUNT: '#/components/schemas/PaymentInrAccountInfo' NGN_ACCOUNT: '#/components/schemas/PaymentNgnAccountInfo' CAD_ACCOUNT: '#/components/schemas/PaymentCadAccountInfo' GBP_ACCOUNT: '#/components/schemas/PaymentGbpAccountInfo' HKD_ACCOUNT: '#/components/schemas/PaymentHkdAccountInfo' IDR_ACCOUNT: '#/components/schemas/PaymentIdrAccountInfo' MYR_ACCOUNT: '#/components/schemas/PaymentMyrAccountInfo' PHP_ACCOUNT: '#/components/schemas/PaymentPhpAccountInfo' SGD_ACCOUNT: '#/components/schemas/PaymentSgdAccountInfo' THB_ACCOUNT: '#/components/schemas/PaymentThbAccountInfo' VND_ACCOUNT: '#/components/schemas/PaymentVndAccountInfo' SPARK_WALLET: '#/components/schemas/PaymentSparkWalletInfo' LIGHTNING: '#/components/schemas/PaymentLightningInvoiceInfo' SOLANA_WALLET: '#/components/schemas/PaymentSolanaWalletInfo' TRON_WALLET: '#/components/schemas/PaymentTronWalletInfo' POLYGON_WALLET: '#/components/schemas/PaymentPolygonWalletInfo' BASE_WALLET: '#/components/schemas/PaymentBaseWalletInfo' ETHEREUM_WALLET: '#/components/schemas/PaymentEthereumWalletInfo' AED_ACCOUNT: '#/components/schemas/PaymentAedAccountInfo' KES_ACCOUNT: '#/components/schemas/PaymentKesAccountInfo' MWK_ACCOUNT: '#/components/schemas/PaymentMwkAccountInfo' RWF_ACCOUNT: '#/components/schemas/PaymentRwfAccountInfo' TZS_ACCOUNT: '#/components/schemas/PaymentTzsAccountInfo' UGX_ACCOUNT: '#/components/schemas/PaymentUgxAccountInfo' XOF_ACCOUNT: '#/components/schemas/PaymentXofAccountInfo' ZAR_ACCOUNT: '#/components/schemas/PaymentZarAccountInfo' ZMW_ACCOUNT: '#/components/schemas/PaymentZmwAccountInfo' BWP_ACCOUNT: '#/components/schemas/PaymentBwpAccountInfo' XAF_ACCOUNT: '#/components/schemas/PaymentXafAccountInfo' BDT_ACCOUNT: '#/components/schemas/PaymentBdtAccountInfo' ARS_ACCOUNT: '#/components/schemas/PaymentArsAccountInfo' COP_ACCOUNT: '#/components/schemas/PaymentCopAccountInfo' EGP_ACCOUNT: '#/components/schemas/PaymentEgpAccountInfo' GHS_ACCOUNT: '#/components/schemas/PaymentGhsAccountInfo' GTQ_ACCOUNT: '#/components/schemas/PaymentGtqAccountInfo' HTG_ACCOUNT: '#/components/schemas/PaymentHtgAccountInfo' JMD_ACCOUNT: '#/components/schemas/PaymentJmdAccountInfo' PKR_ACCOUNT: '#/components/schemas/PaymentPkrAccountInfo' SLV_ACCOUNT: '#/components/schemas/PaymentSlvAccountInfo' EMBEDDED_WALLET: '#/components/schemas/PaymentEmbeddedWalletInfo' SWIFT_ACCOUNT: '#/components/schemas/PaymentSwiftAccountInfo' CNY_ACCOUNT: '#/components/schemas/PaymentCnyAccountInfo' PaymentXafAccountInfo: title: XAF Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/XafAccountInfo' - 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 BusinessInfoUpdate: type: object description: Additional information for business entities 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: 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 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 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 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 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' 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' customerId: type: string description: System ID of the customer (sender for outgoing, recipient for incoming) example: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: type: string description: Platform-specific ID of the customer (sender for outgoing, recipient for incoming) 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' counterpartyInformation: $ref: '#/components/schemas/CounterpartyInformation' UmaAddressDestination: title: UMA Address allOf: - $ref: '#/components/schemas/BaseDestination' - 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 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 BulkUploadWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/BulkCustomerImportJob' type: type: string enum: - BULK_UPLOAD.COMPLETED - BULK_UPLOAD.FAILED 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, for currencies that support more than one (e.g. NEFT or RTGS for INR). example: NEFT minLength: 1 maxLength: 32 bankName: type: string description: The name of the bank minLength: 1 maxLength: 255 example: accountType: INR_ACCOUNT vpa: user@upi accountNumber: '000111222333' ifsc: HDFC0001234 rail: NEFT bankName: Example Bank GbpAccountInfo: allOf: - $ref: '#/components/schemas/GbpAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - FASTER_PAYMENTS 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 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); authorize the transaction''s `scaChallenge` to proceed. | | `EXPIRED` | Quote wasn''t executed before expiry window | | `PROCESSING` | Executing the quote after receiving funds | | `COMPLETED` | Payout successfully reached the destination | | `FAILED` | Something went wrong — accompanied by a `failureReason` | ' 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' 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 minLength: 1 maxLength: 255 example: accountType: NGN_ACCOUNT accountNumber: 0123456789 bankName: Example Bank 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 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 minLength: 1 maxLength: 255 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: Example Bank phoneNumber: '+1234567890' AedAccountInfo: allOf: - $ref: '#/components/schemas/AedAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER CardFundingSourceChangeWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/Card' type: type: string enum: - CARD.FUNDING_SOURCE_CHANGE 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 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 minLength: 1 maxLength: 255 example: accountType: ZAR_ACCOUNT accountNumber: '1234567890' bankName: Example Bank DkkAccountInfo: allOf: - $ref: '#/components/schemas/DkkAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - SEPA - SEPA_INSTANT InvitationClaimedWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/UmaInvitation' type: type: string enum: - INVITATION.CLAIMED 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 SwiftAccountInfo: allOf: - $ref: '#/components/schemas/SwiftAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - SWIFT 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 IdrAccountInfo: allOf: - $ref: '#/components/schemas/IdrAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER 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' VerificationWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/Verification' type: type: string enum: - VERIFICATION.APPROVED - VERIFICATION.REJECTED - VERIFICATION.RESOLVE_ERRORS - VERIFICATION.IN_PROGRESS - VERIFICATION.PENDING_MANUAL_REVIEW 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 - 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/Quote' description: The quote being executed. Populated for `EXECUTE_QUOTE` actions; absent for transfer actions. Contains the full amount, currency, destination, and rate details needed to present an approval decision to the user. transferDetails: allOf: - $ref: '#/components/schemas/AgentTransferDetails' description: Details of the transfer being requested. Populated for `TRANSFER_OUT` and `TRANSFER_IN` actions; absent for `EXECUTE_QUOTE` actions. 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. 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' PaymentNgnAccountInfo: title: NGN Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/NgnAccountInfo' - 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 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. 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 Card: 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' 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 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. ' EntityType: type: string enum: - SOLE_PROPRIETORSHIP - PARTNERSHIP - LLC - CORPORATION - S_CORPORATION - NON_PROFIT - OTHER description: Legal entity type of the business example: LLC CardSettlementSummary: type: object required: - count - totalAmount properties: count: type: integer description: Number of settlement (clearing) events received for this transaction. example: 1 totalAmount: type: integer format: int64 description: Sum of all settled amounts in the smallest unit of the funding source's currency. example: 1500 TransactionSourceType: type: string enum: - ACCOUNT - UMA_ADDRESS - REALTIME_FUNDING description: Type of transaction source example: ACCOUNT PaymentGbpAccountInfo: title: GBP Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/GbpAccountInfo' - 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 PaymentDkkAccountInfo: title: DKK Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/DkkAccountInfo' - 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 SlvAccountInfo: allOf: - $ref: '#/components/schemas/SlvAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER - MOBILE_MONEY CustomerType: type: string enum: - INDIVIDUAL - BUSINESS description: Whether the customer is an individual or a business entity example: INDIVIDUAL BeneficialOwnerRole: type: string enum: - UBO - DIRECTOR - COMPANY_OFFICER - CONTROL_PERSON - TRUSTEE - GENERAL_PARTNER description: Role of the beneficial owner within the business example: UBO CardMerchant: type: object required: - descriptor properties: descriptor: type: string description: Merchant descriptor string captured from the card network at authorization time. example: BLUE BOTTLE COFFEE SF mcc: type: string description: Merchant Category Code (ISO 18245) — four-digit numeric string. example: '5814' country: type: string description: Two-letter ISO 3166-1 alpha-2 country code of the merchant. example: US Error400: 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 PaymentPhpAccountInfo: title: PHP Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/PhpAccountInfo' - 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 XofAccountInfo: allOf: - $ref: '#/components/schemas/XofAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - MOBILE_MONEY BaseTransactionDestination: type: object required: - destinationType properties: destinationType: $ref: '#/components/schemas/TransactionDestinationType' currency: type: string description: Currency code for the destination example: EUR TronWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - TRON_WALLET address: type: string description: Tron wallet address example: TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL CustomerOneOf: oneOf: - $ref: '#/components/schemas/IndividualCustomer' - $ref: '#/components/schemas/BusinessCustomer' discriminator: propertyName: customerType mapping: INDIVIDUAL: '#/components/schemas/IndividualCustomer' BUSINESS: '#/components/schemas/BusinessCustomer' UsdAccountInfo: allOf: - $ref: '#/components/schemas/UsdAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - ACH - WIRE - RTP - FEDNOW 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 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: Required when funding from an FBO account to identify the customer on whose behalf the transaction is being initiated. Otherwise, will default to the customerId of the account owner. example: Customer:019542f5-b3e7-1d02-0000-000000000001 description: Source account details IncomingRateDetails: description: 'Details about the rate and fees for an incoming transaction. Note: `gridApiFixedFee` 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: - gridApiMultiplier - gridApiFixedFee - gridApiVariableFeeRate - gridApiVariableFeeAmount properties: gridApiMultiplier: type: number format: double description: The underlying multiplier from the mSATS to the receiving currency, 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 receiving 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 receiving 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 receiving currency (eg. cents). This is the receiving amount times gridApiVariableFeeRate. minimum: 0 example: 30 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' 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 PkrAccountInfo: allOf: - $ref: '#/components/schemas/PkrAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER - MOBILE_MONEY ZarAccountInfo: allOf: - $ref: '#/components/schemas/ZarAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER SolanaWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - SOLANA_WALLET address: type: string description: Solana wallet address example: 4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8Wg ZmwAccountInfo: allOf: - $ref: '#/components/schemas/ZmwAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - MOBILE_MONEY SparkWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - SPARK_WALLET address: type: string description: Spark wallet address example: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu 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. | ' 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 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 PaymentBdtAccountInfo: title: BDT Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/BdtAccountInfo' - 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 BaseDestination: type: object required: - destinationType properties: destinationType: $ref: '#/components/schemas/DestinationType' 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 minLength: 1 maxLength: 255 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: Example Bank accountNumber: '1234567890' iban: PK36SCBL0000001123456702 phoneNumber: '+1234567890' 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 MyrAccountInfo: allOf: - $ref: '#/components/schemas/MyrAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER 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 HtgAccountInfo: allOf: - $ref: '#/components/schemas/HtgAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - MOBILE_MONEY MwkAccountInfo: allOf: - $ref: '#/components/schemas/MwkAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - MOBILE_MONEY ThbAccountInfo: allOf: - $ref: '#/components/schemas/ThbAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER 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 PhpAccountInfoBase: type: object required: - accountType - bankName - accountNumber properties: accountType: type: string enum: - PHP_ACCOUNT bankName: type: string description: Name of the beneficiary's bank minLength: 1 maxLength: 255 example: BDO Unibank accountNumber: type: string description: Bank account number minLength: 8 maxLength: 16 example: 001234567890 pattern: ^[0-9]{8,16}$ example: accountType: PHP_ACCOUNT bankName: BDO Unibank accountNumber: 001234567890 Error401: 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 CadAccountInfo: allOf: - $ref: '#/components/schemas/CadAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER CardTransactionStatus: type: string enum: - AUTHORIZED - PARTIALLY_SETTLED - SETTLED - REFUNDED - EXCEPTION description: 'Lifecycle status of a card transaction. | 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. | | `REFUNDED` | A `RETURN` was received from the merchant; the net settled amount has been refunded in part or whole. | | `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. | ' PaymentRwfAccountInfo: title: RWF Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/RwfAccountInfo' - 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 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 IndividualCustomer: title: Individual Customer allOf: - $ref: '#/components/schemas/Customer' - $ref: '#/components/schemas/IndividualCustomerFields' CnyAccountInfoBase: 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: - 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 minLength: 1 maxLength: 255 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: Example Bank phoneNumber: '+1234567890' PaymentKesAccountInfo: title: KES Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/KesAccountInfo' - 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 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 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: type: string enum: - PENDING - CLAIMED - EXPIRED - CANCELLED description: The status of the invitation example: PENDING 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.' PaymentSolanaWalletInfo: title: Solana Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/SolanaWalletInfo' - type: object properties: assetType: type: string description: Type of asset enum: - USDC - USDT 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 items: $ref: '#/components/schemas/PaymentInstructions' privateEnabled: type: boolean description: Whether wallet privacy is enabled for the Embedded Wallet. Only present for `EMBEDDED_WALLET` internal accounts. example: true 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' 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 minLength: 1 maxLength: 255 example: accountType: GTQ_ACCOUNT accountNumber: '1234567890' bankAccountType: CHECKING bankName: Example Bank 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 `onChainTransaction` 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: type: string description: Transaction hash of the internal settlement transfer used to deliver a UMA payment — the inter-VASP settlement leg (e.g. USDC on Solana to the receiving partner), when available. This is not a transfer to a customer's own wallet; for that, see the `onChainTransaction` on the transaction's source or destination. example: '0x9f2c6b6f4b6c8f2a8d9e0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566' 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 RwfAccountInfo: allOf: - $ref: '#/components/schemas/RwfAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - MOBILE_MONEY XafAccountInfo: allOf: - $ref: '#/components/schemas/XafAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - MOBILE_MONEY 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 AgentActionWebhook: allOf: - $ref: '#/components/schemas/BaseWebhook' - type: object required: - data properties: data: $ref: '#/components/schemas/AgentAction' type: type: string enum: - AGENT_ACTION.PENDING_APPROVAL TransactionDestinationOneOf: oneOf: - $ref: '#/components/schemas/AccountTransactionDestination' - $ref: '#/components/schemas/UmaAddressTransactionDestination' discriminator: propertyName: destinationType mapping: ACCOUNT: '#/components/schemas/AccountTransactionDestination' UMA_ADDRESS: '#/components/schemas/UmaAddressTransactionDestination' CnyAccountInfo: allOf: - $ref: '#/components/schemas/CnyAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - BANK_TRANSFER - MOBILE_MONEY BaseWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - BASE_WALLET address: type: string description: Base eth wallet address example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' PaymentMyrAccountInfo: title: MYR Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/MyrAccountInfo' - 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 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/{code}/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. '