---
title: "Create a transfer-in request"
method: POST
path: "/transfer-in"
tags: ["Same-Currency Transfers"]
---

# Create a transfer-in request

`POST /transfer-in`

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.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `source` object, required — Source external account details
    - `accountId` string, required — Reference to an external account ID
  - `destination` object, required — Destination internal account details
    - `accountId` string, required — Reference to an internal account ID
  - `amount` integer — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)

## Response `201`

Transfer-in request created successfully

- Transaction
  - `id` string, required — Unique identifier for the transaction
  - `status` 'CREATED' | 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'REJECTED' | 'FAILED' | 'REFUNDED' | 'EXPIRED', required — Status of a payment transaction
  - `type` 'INCOMING' | 'OUTGOING', required — Type of transaction (incoming payment or outgoing payment)
  - `destination` union, required
    - AccountTransactionDestination — Destination account details
      - `destinationType` 'ACCOUNT', required — Type of transaction destination
      - `currency` string — Currency code for the destination
      - `accountId` string, required — Destination account identifier
    - UmaAddressTransactionDestination — UMA address destination details
      - `destinationType` 'UMA_ADDRESS', required — Type of transaction destination
      - `currency` string — Currency code for the destination
      - `umaAddress` string, required — UMA address of the recipient
  - `customerId` string, required — System ID of the customer (sender for outgoing, recipient for incoming)
  - `platformCustomerId` string, required — Platform-specific ID of the customer (sender for outgoing, recipient for incoming)
  - `settledAt` string, date-time — When the payment was or will be settled
  - `createdAt` string, date-time — When the transaction was created
  - `updatedAt` string, date-time — When the transaction was last updated
  - `description` string — Optional memo or description for the payment
  - `counterpartyInformation` object — Additional information about the counterparty, if available and relevant to the transaction and platform. Only applicable for transactions to/from UMA addresses.

## Other responses

- `400` — Bad request - Invalid parameters
- `401` — Unauthorized
- `404` — Customer or account not found
- `500` — Internal service error

## Changes

- **2026-02-06** `9d1655bef82d` — 2 breaking
  - the response property `destination/oneOf[subschema #1: Account Destination]/allOf[subschema #2]/destinationType` became optional for the status `201`
  - the response property `destination/oneOf[subschema #2: UMA Address Destination]/allOf[subschema #2]/destinationType` became optional for the status `201`
- **2026-02-05** `42f104b10868` — 40 breaking, 39 warning, 4 info
  - the `status` response property const value `400` was removed for the status `400`
  - the `status` response property const value `400` was removed for the status `400`
  - the `status` response property const value `400` was removed for the status `400`
  - the `status` response property const value `400` was removed for the status `400`
  - …79 more

[Change history](https://skmtc.dev/lightsparkdev/apis/grid-api/changes/transfer-in/post.md)

---

[API](https://skmtc.dev/lightsparkdev/apis/grid-api.md) · [All operations](https://skmtc.dev/lightsparkdev/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lightsparkdev/grid-api/revisions/9d1655bef82d/schema)