Agent Management12

Agent Operations13

API Tokens4

Cards6

Contact Verification4

Cross-Currency Transfers6

Customers9

Discoveries1

Documents5

Embedded Wallet Auth12

Exchange Rates1

External Accounts12

Internal Accounts5

Invitations4

KYC/KYB Verifications9

Platform Configuration2

Same-Currency Transfers2

Sandbox20

Stablecoins12

Strong Customer Authentication16

Transactions6

Webhooks

Webhooks13

Transactions

Approve a pending incoming payment

Changed on Sep 23, 2026

Approve a pending incoming payment that was previously acknowledged with a 202 response. This endpoint allows platforms to asynchronously approve payments after async processing.

post/transactions/{transactionId}/approve

Request

Base URL: https://api.lightspark.com/grid/2025-10-13
URL: https://api.lightspark.com/grid/2025-10-13/transactions/{transactionId}/approve
Auth: HTTP basic

Path parameters

transactionIdstring required

Unique identifier of the transaction to approve

Request body

receiverCustomerInfoobject

Information about the recipient, provided by the platform if requested in the original webhook via requestedReceiverCustomerInfoFields.

Response

Payment approved successfully

idstring required

Unique identifier for the transaction

Status of a payment transaction.

Status	Description
CREATED	Initial lookup has been created
PENDING	Quote has been created
PENDING_AUTHORIZATION	Awaiting Strong Customer Authentication. Only occurs for customers in a region where SCA is required (e.g. EU). The challenge is carried by the quote, not the transaction — fetch GET /quotes/{quoteId} using the transaction's quoteId, then authorize its scaChallenge via POST /quotes/{quoteId}/authorize.
PROCESSING	Funding has been received and payment initiated
COMPLETED	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

pendingReason'COUNTERPARTY_DECLARATION_REQUIRED' | 'WALLET_VERIFICATION_REQUIRED' | 'COUNTERPARTY_INFORMATION_REQUIRED' | 'COMPLIANCE_REVIEW'

Why a transaction is pending.

Reason	Description
COUNTERPARTY_DECLARATION_REQUIRED	The customer must declare who controls the sending wallet.
WALLET_VERIFICATION_REQUIRED	The customer must verify ownership of the sending wallet.
COUNTERPARTY_INFORMATION_REQUIRED	Information about the sender is required.
COMPLIANCE_REVIEW	The customer's action is complete and the deposit remains under compliance review.

type'INCOMING' required

Type of transaction

direction'CREDIT' | 'DEBIT' required

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.

customerIdstring required

System ID of the customer this transaction belongs to

platformCustomerIdstring required

Platform-specific ID of the customer this transaction belongs to

settledAtstring date-time

When the payment was or will be settled

createdAtstring date-time

When the transaction was created

updatedAtstring date-time

When the transaction was last updated

receiptDeliveryConfirmedAtstring date-time

The time at which the platform confirmed delivery of the receipt to their customer.

agentIdstring

If this transaction was initiated by an agent, the system-generated ID of that agent. Absent for platform-initiated transactions.

descriptionstring

Optional memo or description for the payment

exchangeRatenumber

Number of sending currency units per receiving currency unit. The rate is fee-exclusive: Grid deducts fees from the sending amount before converting at this rate.

quoteIdstring

The ID of the quote that was used to trigger this payment

counterpartyInformationCounterpartyInformation

Additional information about the counterparty, if available and relevant to the transaction and platform.

feesinteger

The total fees available from the receive quote in the smallest unit of the sending currency (eg. cents).

Reason for failure of an incoming transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted. COMPLIANCE_REJECTED means compliance blocked the incoming funds. COLLECTION_FAILED means an inbound bank-rail collection deposit (e.g. a SWIFT wire) failed after arrival and did not credit — most commonly a compliance-screening rejection or an unresolved request for information, on either the collection provider's side or Grid's. Failed collections are returned to the sender per the collection provider's process. A payment that settled into a rule-based account but could not be swept to the destination of the account's rule fails with one of the SWEEP_* reasons. A rule-based account never holds a balance, so the funds are moved to the account holder's own account in the same currency. SWEEP_AMOUNT_OUT_OF_RANGE means the amount was outside the band the corridor to the destination can carry — the rule's minimumAmount and maximumAmount give the current band — and SWEEP_QUOTE_FAILED that Grid could not price it. A sweep that was priced and then failed on the way to settlement reports QUOTE_EXECUTION_FAILED, the same as any other payment.

Example response

{
  "id": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
  "destination": {
    "destinationType": "ACCOUNT",
    "currency": "EUR",
    "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "onChainTransaction": {
      "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
      "network": "SOLANA"
    }
  },
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "platformCustomerId": "18d3e5f7b4a9c2",
  "settledAt": "2025-08-15T14:30:00Z",
  "createdAt": "2025-08-15T14:25:18Z",
  "updatedAt": "2025-08-15T14:30:00Z",
  "receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z",
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "description": "Payment for invoice #1234",
  "sentAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "exchangeRate": 1.08,
  "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
  "refund": {
    "reference": "UMA-Q12345-REFUND",
    "initiatedAt": "2025-08-15T14:30:00Z",
    "settledAt": "2025-08-15T14:35:00Z",
    "status": "COMPLETED",
    "reason": "TRANSACTION_FAILED"
  },
  "counterpartyInformation": {
    "FULL_NAME": "John Sender",
    "BIRTH_DATE": "1985-06-15",
    "NATIONALITY": "DE"
  },
  "source": {
    "sourceType": "ACCOUNT",
    "currency": "USD",
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "onChainTransaction": {
      "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
      "network": "SOLANA"
    }
  },
  "receivedAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "fees": 10,
  "reconciliationInstructions": {
    "reference": "UMA-Q12345-REF",
    "transactionHash": "0x9f2c6b6f4b6c8f2a8d9e0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566"
  }
}

Changes

Sep 23, 2026556180e5b2ae Revision changes
- warning
  added the new ACH_SAME_DAY enum value to the //////// response property for the response status
Sep 15, 20263966e5d38aad Revision changes
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- breaking
  removed the required property from the response with the status
- warning
  added the new ACCOUNT_NOT_FOUND enum value to the response property for the response status
- warning
  added the new AUTH_METHOD_NOT_FOUND enum value to the response property for the response status
- warning
  added the new CUSTOMER_NOT_FOUND enum value to the response property for the response status
- warning
  added the new DOCUMENT_ALREADY_EXISTS enum value to the response property for the response status
- warning
  added the new DOCUMENT_HOLDER_NOT_FOUND enum value to the response property for the response status
- warning
  added the new DUPLICATE_EXTERNAL_ACCOUNT enum value to the response property for the response status
- warning
  added the new DUPLICATE_PAY_REQUEST enum value to the response property for the response status
- warning
  added the new INSUFFICIENT_FUNDS enum value to the response property for the response status
- warning
  added the new NOT_FOUND enum value to the response property for the response status
- warning
  added the new PAYMENT_URL_NOT_FOUND enum value to the response property for the response status
- warning
  added the new PLATFORM_NOT_FOUND enum value to the response property for the response status
- warning
  added the new QUOTE_EXPIRED enum value to the response property for the response status
- warning
  added the new QUOTE_RATE_UNAVAILABLE enum value to the response property for the response status
- warning
  added the new REQUEST_NOT_FOUND enum value to the response property for the response status
- warning
  added the new SESSION_NOT_FOUND enum value to the response property for the response status
- warning
  added the new SMS_OTP_CREDENTIAL_SET_CHANGED enum value to the response property for the response status
- warning
  added the new SMS_OTP_PHONE_NUMBER_ALREADY_EXISTS enum value to the response property for the response status
- warning
  added the new STABLECOIN_AMOUNT_NOT_REPRESENTABLE enum value to the response property for the response status
- warning
  added the new STABLECOIN_BURN_SOURCE_NOT_SUPPORTED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_LINK_FAILED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_LINK_METHOD_REQUIRED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_FOUND enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_LINKED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_NOT_SUPPORTED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_FAILED enum value to the response property for the response status
- warning
  added the new STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_REQUIRED enum value to the response property for the response status
- warning
  added the new STABLECOIN_GRID_OPERATIONS_NOT_ENABLED enum value to the response property for the response status
- warning
  added the new STABLECOIN_NOT_FOUND enum value to the response property for the response status
- warning
  added the new STABLECOIN_NOT_PROVISIONED enum value to the response property for the response status
- warning
  added the new STABLECOIN_OPERATION_NOT_FOUND enum value to the response property for the response status
- warning
  added the new STABLECOIN_OPERATION_NOT_SUPPORTED enum value to the response property for the response status
- warning
  added the new STABLECOIN_PROVIDER_ERROR enum value to the response property for the response status
- warning
  added the new STABLECOIN_PROVIDER_SOURCE_NOT_LINKED enum value to the response property for the response status
- warning
  added the new STABLECOIN_SYMBOL_ALREADY_EXISTS enum value to the response property for the response status
- warning
  added the new STABLECOIN_TOKEN_IDENTIFIER_ALREADY_EXISTS enum value to the response property for the response status
- warning
  added the new STABLECOIN_VERIFICATION_FAILED enum value to the response property for the response status
- warning
  added the new VERIFICATION_NOT_FOUND enum value to the response property for the response status
- warning
  added the new WALLET_NOT_PROVISIONED enum value to the response property for the response status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status
- info
  added the required property to the response with the status

Operation history (16 revisions)