Cancel a bank transfer

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"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({reason: 'REQUESTED_AFTER_HOURS'})
};

fetch('https://api.lightspark.com/grid/2025-10-13/transactions/{transactionId}/cancel', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"reason\": \"REQUESTED_AFTER_HOURS\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/transactions/{transactionId}/cancel")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "id": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
  "status": "CREATED",
  "type": "INCOMING",
  "direction": "CREDIT",
  "destination": {
    "destinationType": "ACCOUNT",
    "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "currency": "EUR",
    "railDetails": {
      "paymentRail": "ONCHAIN",
      "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
      "network": "SOLANA"
    },
    "onChainTransaction": {
      "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
      "network": "SOLANA"
    }
  },
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "platformCustomerId": "18d3e5f7b4a9c2",
  "pendingReason": "COUNTERPARTY_DECLARATION_REQUIRED",
  "ruleBasedAccountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000011",
  "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",
    "railDetails": {
      "paymentRail": "ONCHAIN",
      "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
      "network": "SOLANA"
    },
    "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"
  },
  "failureReason": "LNURLP_FAILED"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<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

Cancel a bank transfer

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"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({reason: 'REQUESTED_AFTER_HOURS'})
};

fetch('https://api.lightspark.com/grid/2025-10-13/transactions/{transactionId}/cancel', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"reason\": \"REQUESTED_AFTER_HOURS\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/transactions/{transactionId}/cancel")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "id": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
  "status": "CREATED",
  "type": "INCOMING",
  "direction": "CREDIT",
  "destination": {
    "destinationType": "ACCOUNT",
    "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "currency": "EUR",
    "railDetails": {
      "paymentRail": "ONCHAIN",
      "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
      "network": "SOLANA"
    },
    "onChainTransaction": {
      "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
      "network": "SOLANA"
    }
  },
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "platformCustomerId": "18d3e5f7b4a9c2",
  "pendingReason": "COUNTERPARTY_DECLARATION_REQUIRED",
  "ruleBasedAccountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000011",
  "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",
    "railDetails": {
      "paymentRail": "ONCHAIN",
      "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
      "network": "SOLANA"
    },
    "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"
  },
  "failureReason": "LNURLP_FAILED"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<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). The challenge is carried by the quote, not the transaction — fetch `GET /quotes/{quoteId}` using the transaction's `quoteId`, then authorize its `scaChallenge` via `POST /quotes/{quoteId}/authorize`.
`PROCESSING`	Funding has been received and payment initiated
`COMPLETED`	The funds are where settlement put them. A return that takes them back moves the transaction to `FAILED`, and the returned side's `railDetails` shows `RETURNED`. A transaction stays `COMPLETED` through a return only when a later step that can't be undone already used the funds
`REJECTED`	Receiving institution or wallet rejected payment, payment has been refunded
`FAILED`	The payment did not reach its destination, or the funds were sent back after it did. Not terminal for an incoming payment: a dishonored return restores the credit and moves it to `COMPLETED`. A returned payout stays `FAILED`, since it has already been refunded. Each step shows on the returned side's `railDetails`
`REFUNDED`	Deprecated. A refund is reported on the transaction's `refund` object, and the status stays `FAILED`
`EXPIRED`	Quote has expired. Terminal

Available options:

CREATED,

PENDING,

PENDING_AUTHORIZATION,

PROCESSING,

COMPLETED,

REJECTED,

FAILED,

REFUNDED,

EXPIRED

type

enum<string>

required

Type of transaction

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"

pendingReason

enum<string>

Present when compliance review or required customer action is delaying settlement.

Available options:

COUNTERPARTY_DECLARATION_REQUIRED,

WALLET_VERIFICATION_REQUIRED,

COUNTERPARTY_INFORMATION_REQUIRED,

COMPLIANCE_REVIEW

ruleBasedAccountId

string

The RULE_BASED internal account whose deposit this transaction sweeps. Present only on sweep transactions. For these, source describes the party that made the deposit when it is known, and is this account otherwise.

Example:

"InternalAccount:019542f5-b3e7-1d02-0000-000000000011"

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. The rate is fee-exclusive: Grid deducts fees from the sending amount before converting at this rate.

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

receivedAmount

object

Amount received in the recipient's currency. This is only absent for rule-based account sweeps if the sweep couldn't be quoted. It's always present otherwise.

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,

COMPLIANCE_REJECTED,

COLLECTION_FAILED,

SWEEP_AMOUNT_OUT_OF_RANGE,

SWEEP_QUOTE_FAILED

Using the API

API documentation

Cancel a bank transfer

Authorizations

Path Parameters

Body

Response