Reject a pending incoming payment

Reject a pending incoming payment that was previously acknowledged with a 202 response. This endpoint allows platforms to asynchronously reject payments after additional processing.

POST /transactions/{transactionId}/reject

Reject a pending incoming payment

cURL

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

200

{
  "id": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
  "status": "CREATED",
  "type": "INCOMING",
  "destination": {
    "destinationType": "ACCOUNT",
    "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "currency": "EUR"
  },
  "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",
  "description": "Payment for invoice #1234",
  "counterpartyInformation": {
    "FULL_NAME": "John Sender",
    "BIRTH_DATE": "1985-06-15",
    "NATIONALITY": "DE"
  },
  "source": {
    "sourceType": "ACCOUNT",
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "currency": "USD"
  },
  "reconciliationInstructions": {
    "reference": "UMA-Q12345-REF"
  },
  "rateDetails": {
    "gridApiMultiplier": 0.925,
    "gridApiFixedFee": 10,
    "gridApiVariableFeeRate": 0.003,
    "gridApiVariableFeeAmount": 30
  },
  "failureReason": "LNURLP_FAILED"
}

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 reject

Body

application/json

reason · string

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"

Response

200

application/json

Payment rejected successfully

Option 1

Option 2

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
PROCESSING	Funding has been received and payment initiated
SENT	Cross border settlement has been 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, PROCESSING, SENT, COMPLETED, REJECTED, FAILED, REFUNDED, EXPIRED

type · enum<string> · required

Type of transaction (incoming payment or outgoing payment)

Available options: INCOMING

destination · Account Destination · object · required

Destination account details

Account Destination

Account Destination

Account Destination

UMA Address Destination

External Account Details Destination

Show child attributes

customerId · string · required

System ID of the customer (sender for outgoing, recipient for incoming)

Example:

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

platformCustomerId · string · required

Platform-specific ID of the customer (sender for outgoing, recipient for incoming)

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"

description · string

Optional memo or description for the payment

Example:

"Payment for invoice #1234"

counterpartyInformation · object

Additional information about the counterparty, if available and relevant to the transaction and platform. Only applicable for transactions to/from UMA addresses.

Example:

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

source · Account Source · object

Source account details

Account Source

Account Source

Account Source

UMA Address Source

Real-time Funding Source

Show child attributes

reconciliationInstructions · object

Included for all transactions except those with "CREATED" status

Show child attributes

rateDetails · object

Details about the rate and fees for the transaction.

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