cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/transactions/{transactionId}/cancel \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "REQUESTED_AFTER_HOURS"
}
'

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.cancel('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.TransactionCancelParams
import com.lightspark.grid.models.transferin.Transaction

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

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

{
  "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": 400,
  "message": "<string>",
  "details": {}
}

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

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

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

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

Transactions

Cancel a bank transfer

Request cancellation of a pending bank transfer — an ACH transfer (push or pull) or a wire — before it has settled, for example a payment or collection initiated outside of the receiving bank’s processing window. Whether a transfer can still be cancelled is determined by the banking partner that is settling it: the request is forwarded to the partner’s own cancellation facility, and a transfer that the partner has already processed (or that is otherwise past its cancellation window) cannot be cancelled. Cancellation applies to bank-rail transfers; requests for transaction types that cannot be cancelled are rejected.

POST

transactions

{transactionId}

cancel

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/transactions/{transactionId}/cancel \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "REQUESTED_AFTER_HOURS"
}
'

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.cancel('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.TransactionCancelParams
import com.lightspark.grid.models.transferin.Transaction

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

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

{
  "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": 400,
  "message": "<string>",
  "details": {}
}

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

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

{
  "status": 409,
  "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 to cancel

Body

application/json

reason

string

Optional reason for cancelling the transaction. This is just for debugging purposes or can be used for a platform's own purposes.

Example:

"REQUESTED_AFTER_HOURS"

Response

Cancellation requested successfully

Incoming Transaction
Outgoing Transaction
Card Transaction

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

Reject a pending incoming payment

Send a test webhook

⌘I

Using the API

API documentation

Cancel a bank transfer

Authorizations

Path Parameters

Body

Response