Create a transfer-in request

Transfer funds from an external account to an internal account for a specific customer. This endpoint should only be used for external account sources with pull functionality (e.g. ACH Pull). Otherwise, use the paymentInstructions on the internal account to deposit funds.

POST /transfer-in

Create a transfer-in request

cURL

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

201

{
  "receivedAmount": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "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",
  "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,
    "platformFixedFee": 150,
    "platformVariableFeeRate": 0.005,
    "platformVariableFeeAmount": 50
  },
  "failureReason": "LNURLP_FAILED",
  "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"
  }
}

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.

Example:

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

Body

application/json

source · object · required

Source external account details

Show child attributes

destination · object · required

Destination internal 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

Response

201

application/json

Transfer-in request created successfully

Option 1

Option 2

receivedAmount · object · required

Amount received in the recipient's currency

Show child attributes

id · string · required

Unique identifier for the transaction

Example:

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

status · enum<string> · required

Status of a payment transaction

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

type · enum<string> · required

Type of transaction (incoming payment or outgoing payment)

Available options: INCOMING, OUTGOING

destination · Account Destination · object · required

Destination account details

Account Destination

Account Destination

UMA Address 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"

source · Account Source · object

Source account details

Account Source

Account Source

UMA Address 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

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