Get transaction by ID

Retrieve detailed information about a specific transaction.

GET /transactions/{transactionId}

cURL

cURL

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/transactions/{transactionId} \
  --header 'Authorization: Basic <encoded-value>'

import LightsparkGrid from '@lightsparkdev/grid';

const client = new LightsparkGrid({
  username: process.env['GRID_CLIENT_ID'], // This is the default and can be omitted
  password: process.env['GRID_CLIENT_SECRET'], // This is the default and can be omitted
});

const transaction = await client.transactions.retrieve('transactionId');

console.log(transaction);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.transactions.TransactionRetrieveParams
import com.lightspark.grid.models.transferin.Transaction

fun main() {
    val client: LightsparkGridClient = LightsparkGridOkHttpClient.fromEnv()

    val transaction: Transaction = client.transactions().retrieve("transactionId")
}

200

{
  "id": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
  "type": "INCOMING",
  "destination": {
    "destinationType": "ACCOUNT",
    "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "currency": "EUR",
    "onChainTransaction": {
      "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
      "network": "SOLANA"
    }
  },
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "platformCustomerId": "18d3e5f7b4a9c2",
  "receivedAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "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",
    "status": "COMPLETED",
    "settledAt": "2025-08-15T14:35:00Z",
    "reason": "TRANSACTION_FAILED"
  },
  "counterpartyInformation": {
    "FULL_NAME": "John Sender",
    "BIRTH_DATE": "1985-06-15",
    "NATIONALITY": "DE"
  },
  "source": {
    "sourceType": "ACCOUNT",
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "currency": "USD",
    "onChainTransaction": {
      "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
      "network": "SOLANA"
    }
  },
  "fees": 10,
  "reconciliationInstructions": {
    "reference": "UMA-Q12345-REF",
    "transactionHash": "0x9f2c6b6f4b6c8f2a8d9e0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566"
  }
}

{
  "status": 401,
  "message": "<string>",
  "details": {}
}

{
  "status": 404,
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "message": "<string>",
  "details": {}
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Path Parameters

transactionId · string · required

Unique identifier of the transaction

Response

200

application/json

Successful operation

Incoming Transaction

Outgoing Transaction

Card Transaction

id · string · required

Unique identifier for the transaction

Example:

"Transaction:019542f5-b3e7-1d02-0000-000000000004"

status · enum<string> · required

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

Available options: CREATED, PENDING, PENDING_AUTHORIZATION, PROCESSING, COMPLETED, REJECTED, FAILED, REFUNDED, EXPIRED

type · enum<string> · required

Type of transaction (incoming payment or outgoing payment)

Available options: INCOMING

direction · enum<string> · required

Whether this transaction credits or debits the customer's account.

Available options: CREDIT, DEBIT

destination · Account Destination · object · required

Destination account details

Account Destination

UMA Address Destination

Show child attributes

customerId · string · required

System ID of the customer this transaction belongs to

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000001"

platformCustomerId · string · required

Platform-specific ID of the customer this transaction belongs to

Example:

"18d3e5f7b4a9c2"

receivedAmount · object · required

Amount received in the recipient's currency

Show child attributes

settledAt · string<date-time>

When the payment was or will be settled

Example:

"2025-08-15T14:30:00Z"

createdAt · string<date-time>

When the transaction was created

Example:

"2025-08-15T14:25:18Z"

updatedAt · string<date-time>

When the transaction was last updated

Example:

"2025-08-15T14:30:00Z"

receiptDeliveryConfirmedAt · string<date-time>

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

Example:

"2025-08-15T14:31:00Z"

agentId · string

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 · string

Optional memo or description for the payment

Example:

"Payment for invoice #1234"

sentAmount · object

Amount sent in the sender's currency

Show child attributes

exchangeRate · number

Number of sending currency units per receiving currency unit.

Example:

1.08

quoteId · string

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

Example:

"Quote:019542f5-b3e7-1d02-0000-000000000006"

refund · object

The refund if transaction was refunded.

Show child attributes

counterpartyInformation · object

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

Example:

{
  "FULL_NAME": "John Sender",
  "BIRTH_DATE": "1985-06-15",
  "NATIONALITY": "DE"
}

source · Account Source · object

Source account details

Account Source

UMA Address Source

External Funding Source

Show child attributes

fees · integer<int64>

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

Required range: x >= 0

Example:

10

reconciliationInstructions · object

Included for all transactions except those with "CREATED" status

Show child attributes

failureReason · enum<string>

If the transaction failed, this field provides the reason for failure.

Available options: LNURLP_FAILED, PAY_REQUEST_FAILED, PAYMENT_APPROVAL_WEBHOOK_ERROR, PAYMENT_APPROVAL_TIMED_OUT, OFFRAMP_FAILED, MISSING_MANDATORY_PAYEE_DATA, QUOTE_EXPIRED, QUOTE_EXECUTION_FAILED