Create a transfer-out request

Deprecated. Use POST /quotes instead.

Same-currency transfers are now served by the quote endpoint. Create a quote with an internal account source and an external account destination and set immediatelyExecute: true to move the funds in a single request, exactly as this endpoint does. This endpoint continues to work and its request and response shapes are unchanged.

To migrate a request to POST /quotes:

• add sourceType: ACCOUNT to source and destinationType: ACCOUNT to destination; the account IDs and destination.paymentRail are unchanged
• rename amount to lockedCurrencyAmount and add lockedCurrencySide: SENDING
• remittanceInformation and purposeOfPayment carry over unchanged
• add immediatelyExecute: true to keep the single-request behavior

The quote response is a Quote rather than a Transaction; read transactionId from it to track the resulting transaction.

Transfer funds from an internal account to an external account for a specific customer.

POST /transfer-out

Create a transfer-out request

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/transfer-out \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "source": {
    "accountId": "InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
  },
  "destination": {
    "accountId": "ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "paymentRail": "ACH"
  },
  "amount": 12550,
  "remittanceInformation": "12345"
}
'

200

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

Authorizations

Authorization · string · header · required

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

Headers

Idempotency-Key · string

A unique identifier for the request. If the same key is sent multiple times, the server will return the same response as the first request.

Maximum string length: 255

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json

source · object · required

Source internal account details

Show child attributes

destination · object · required

Destination external account details

Show child attributes

amount · integer<int64>

Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)

Example:

12550

remittanceInformation · string

Free-form information about the payment that travels with it to the recipient. The field this populates depends on the payment rail: for ACH it populates the Addenda record, for FedNow and RTP it populates the remittanceInformation field, and for wires it populates the OBI (Originator to Beneficiary Information) / beneficiary information.

Maximum string length: 80

Example:

"12345"

purposeOfPayment · enum<string>

The purpose of the payment. This may be required when sending to certain geographies (e.g. India).

Some destinations accept only certain purposes. A business payout to China must use one of the purposes listed in Supporting Documents, and each needs its own supporting documents.

Available options: GIFT, SELF, GOODS_OR_SERVICES, EDUCATION, HEALTH_OR_MEDICAL, REAL_ESTATE_PURCHASE, TAX_PAYMENT, LOAN_PAYMENT, UTILITY_BILL, DONATION, TRAVEL, FAMILY_SUPPORT, SALARY_PAYMENT, EXPORTED_GOODS_PREPAYMENT, EXPORTED_GOODS_POSTPAYMENT, SERVICE_CHARGES, OFFICE_EXPENSES, DELIVERY_FEES, HOTEL_ACCOMMODATION, COMMISSION_ON_GOODS, COMMISSION_ON_SERVICES, ACCOUNTING_SERVICES, EXHIBITION_SERVICES, OTHER

Response

200

application/json

Transfer-out request created successfully.

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). 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