---
title: "Create Transfer"
method: POST
path: "/createTransfer"
tags: ["Transfers"]
---

# Create Transfer

`POST /createTransfer`

> 👍 Availability
>
>Some of the field descriptions for this endpoint reference FedNow or Fedwire, which are future capabilities not yet available for clients.

Use the Create Transfer endpoint to move funds between a source account and a destination account. You can use an active account link that was created by <a href="ref:paymenthub_post_createexternalaccountlink" target="_blank">Create External Account Link</a> or create a new one via the request.

For card transfers, the referenced external debit card link must have a validation status of `"PASSED"` before it can be used for transfers.

For new transfers: Omit the `returnDetails` field.
For payment returns: Include the `returnDetails` field with the original transaction reference.
When `returnDetails` is present, the request initiates a return of the original transfer.

## Headers

- `x-gft-idempotency-key` string, uuid4, required
- `Authorization` string, required

## Request body

- object — Create a new payment transfer OR return a previous transfer. For new transfers: Omit the `returnDetails` field. For payment returns: Include the `returnDetails` field with the original transaction reference. When `returnDetails` is present, the request initiates a return of the original transfer. See `ReturnDetails` class documentation for field meanings and return-specific behavior. **Character Set Restrictions for FEDWIRE and FEDNOW rails:** All free-text fields (e.g. `purpose`, `remittanceInfo`, address fields, owner names, `bankName`) must conform to the payment rail's character set when using FEDWIRE or FEDNOW: - **FEDWIRE**: Alphanumeric characters and special characters: @&/\'"` ~()<>$#%+-={}*|[]^.,?!;:_ - **FEDNOW**: FedNow Service Character Set — alphanumeric, space, all printable ASCII special characters (!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~), and extended Latin characters (U+00C0–U+00FF)
  - `accountNo` string, required — The <<glossary:PRN>> associated with this transfer. Pattern: PRN Example: `"074103447228"`
  - `paymentMethod` 'ACH' | 'FEDNOW' | 'FEDWIRE' | 'CARD', required — Payment network to use for the transfer. Rail-specific validation: `CARD` requires the `sourceAccount` to be `GALILEO` and `creditOrDebit` to be `DEBIT` or `CREDIT`. Example: `"CARD"`
  - `currencyAmount` object, required — Request-side currency amount. Raises BadRequestException (400) on invalid client input.
    - `amount` number, required
    - `currency` string — Currency code following ISO 4217 standard. Validation: Exactly 3 uppercase letters. Pattern: ^[A-Z]{3}$ Example: 'USD' (US Dollar), 'EUR' (Euro), 'GBP' (British Pound)
  - `creditOrDebit` 'DEBIT' | 'CREDIT', required — Posting type indicating debit or credit. - DEBIT: Debit transaction (funds withdrawn) - CREDIT: Credit transaction (funds deposited)
  - `sourceAccount` object, required — Identifies the account's role in the transaction. If used as the **sourceAccount**, this is the account being debited. For push transfers (withdrawals), use the SoFi Tech Solutions account; for pull transfers (deposits), use the linked external account. If used as the **destinationAccount**, this is the account being credited. For push transfers, use the linked external account; for pull transfers, use the SoFi Tech Solutions account.
    - `type` 'GALILEO_ACCOUNT' | 'EXTERNAL_ACCOUNT_REFERENCE' | 'EXTERNAL_ACCOUNT_LINK_REQUEST' | 'LEGACY', required — Indicates the account category.
  - `destinationAccount` object, required — Identifies the account's role in the transaction. If used as the **sourceAccount**, this is the account being debited. For push transfers (withdrawals), use the SoFi Tech Solutions account; for pull transfers (deposits), use the linked external account. If used as the **destinationAccount**, this is the account being credited. For push transfers, use the linked external account; for pull transfers, use the SoFi Tech Solutions account.
    - `type` 'GALILEO_ACCOUNT' | 'EXTERNAL_ACCOUNT_REFERENCE' | 'EXTERNAL_ACCOUNT_LINK_REQUEST' | 'LEGACY', required — Indicates the account category.
  - `externalId` string — Client-defined identifier for tracking and reconciliation. Pattern: Alphanumeric string Example: `My-Internal-ID-123`
  - `purpose` string — Reason for the transfer. Pattern: Alphanumeric string Validation: - Default: Alphanumeric string - FEDWIRE: Limited to alphanumeric and special characters: @&/\'"\`~()<>$#%+-={}*|[]^.,?!;:_ Example: "`Bill Payment`"
  - `remittanceInfo` string — Additional details about the transfer, such as an invoice number. Pattern: Alphanumeric string Validation: - Default: Alphanumeric string - FEDWIRE: 1-140 characters, limited to alphanumeric and special characters: @&/\'"`~()<>$#%+-={}*|[]^.,?!;:_ Example: "`Invoice #456-ABC`"
  - `returnDetails` object — Payment return information for reversing a previous transfer.
    - `code` string — Reason code describing why the transaction was returned. Validation: - FEDNOW: Required. Uses ISO 20022 External Status Reason Codes (pacs.002 StsRsnInf/Rsn/Cd). Must be 1-4 characters. Common codes include AC01 (Incorrect account number), AC03 (Invalid creditor account number), AC04 (Closed account number), AC06 (Blocked account), AC13 (Invalid debtor account type), AC14 (Invalid agent), AC15 (Account details changed), AG01 (Transaction forbidden). Refer to ISO 20022 ExternalCodeSets for the complete list of reason codes.
    - `additionalInfo` string — Optional additional context for the return. Validation: - FEDNOW: Maximum 105 characters. Maps to ISO 20022 pacs.002 StsRsnInf/AddtlInf.
    - `originalTransactionId` string, uuid, required — Reference to the original transaction being returned (transferId).
  - `destinationEntities` object — Agent routing for international wire transfers. Only allowed for outbound international FedWire transfers. When intermediaryAgent1 is present, instructedAgent is required.
    - `instructedAgent` object — Financial institution involved in the transfer
      - `memberId` string — Clearing system member identification number. Required if bic is not provided. For US banks: 9-digit ABA/RTN. For foreign banks: local clearing code. When provided without clearingSystemId, defaults to USABA.
      - `clearingSystemId` 'USABA' — Identifies the clearing system for the memberId. Only applicable when memberId is provided. Defaults to USABA if omitted.
      - `bic` string — SWIFT/BIC code of the financial institution. Exactly 8 or 11 characters. Required if memberId is not provided.
      - `lei` string — Legal Entity Identifier. 20-character alphanumeric code.
      - `name` string — Financial institution name. Max 140 characters.
      - `address` object — Financial institution address (bank location, not account owner).
        - `line1` string — First line of the address. Pattern: - Default: 1-105 characters with at least one non-whitespace character - FEDWIRE: 1-105 characters, limited to alphanumeric and special characters
        - `line2` string — Second line of the address (apartment, suite, etc.). Pattern: - Default: 1-35 characters with at least one non-whitespace character - FEDWIRE: 1-35 characters, limited to alphanumeric and special characters
        - `city` string — City name. Pattern: - Default: 1-35 characters with at least one non-whitespace character - FEDWIRE: 1-35 characters, limited to alphanumeric and special characters
        - `state` string — State or province code. Pattern: - Default: 2-35 characters with at least one non-whitespace character. For US addresses, typically 2-letter state code (e.g., 'NY', 'CA') - FEDWIRE: 2-35 characters, limited to alphanumeric and special characters
        - `zipCode` string — Postal code or ZIP code. Pattern: - Default: 1-15 characters with at least one non-whitespace character. For US addresses, typically 5-digit ZIP code (e.g., '11201') - FEDWIRE: 1-15 characters, limited to alphanumeric and special characters
        - `country` string — Country code following ISO 3166-1 alpha-2 format. Pattern: Exactly 2 uppercase letters. Examples: 'US' (United States), 'MX' (Mexico)
    - `intermediaryAgent1` object — Financial institution involved in the transfer
      - `memberId` string — Clearing system member identification number. Required if bic is not provided. For US banks: 9-digit ABA/RTN. For foreign banks: local clearing code. When provided without clearingSystemId, defaults to USABA.
      - `clearingSystemId` 'USABA' — Identifies the clearing system for the memberId. Only applicable when memberId is provided. Defaults to USABA if omitted.
      - `bic` string — SWIFT/BIC code of the financial institution. Exactly 8 or 11 characters. Required if memberId is not provided.
      - `lei` string — Legal Entity Identifier. 20-character alphanumeric code.
      - `name` string — Financial institution name. Max 140 characters.
      - `address` object — Financial institution address (bank location, not account owner).
        - `line1` string — First line of the address. Pattern: - Default: 1-105 characters with at least one non-whitespace character - FEDWIRE: 1-105 characters, limited to alphanumeric and special characters
        - `line2` string — Second line of the address (apartment, suite, etc.). Pattern: - Default: 1-35 characters with at least one non-whitespace character - FEDWIRE: 1-35 characters, limited to alphanumeric and special characters
        - `city` string — City name. Pattern: - Default: 1-35 characters with at least one non-whitespace character - FEDWIRE: 1-35 characters, limited to alphanumeric and special characters
        - `state` string — State or province code. Pattern: - Default: 2-35 characters with at least one non-whitespace character. For US addresses, typically 2-letter state code (e.g., 'NY', 'CA') - FEDWIRE: 2-35 characters, limited to alphanumeric and special characters
        - `zipCode` string — Postal code or ZIP code. Pattern: - Default: 1-15 characters with at least one non-whitespace character. For US addresses, typically 5-digit ZIP code (e.g., '11201') - FEDWIRE: 1-15 characters, limited to alphanumeric and special characters
        - `country` string — Country code following ISO 3166-1 alpha-2 format. Pattern: Exactly 2 uppercase letters. Examples: 'US' (United States), 'MX' (Mexico)
    - `intermediaryAccount1` object — Account identification — account number or IBAN.
      - `number` string, required — Account number or IBAN.
      - `type` 'IBAN' | 'ACCOUNT_NUMBER' — Type of account number. - IBAN: International Bank Account Number, validated per ISO 13616 - ACCOUNT_NUMBER: Standard account identifier (default when omitted)
  - `isCrossBorder` boolean — Indicates whether this is a cross-border (international) transfer. Currently supported for FEDWIRE only.

## Response `200`

Successful Response

- object
  - `transferId` string, required — Unique identifier assigned to the newly created transfer.

## Other responses

- `400` — Bad Request
- `401` — No valid API credentials provided.
- `403` — The provided API credential does not allow this operation.
- `404` — Not Found
- `409` — Conflict
- `422` — Validation Error
- `429` — Too many requests.
- `500` — Internal Server Error
- `502` — Bad Gateway.
- `503` — Service Unavailable.

---

[API](https://skmtc.net/galileo-ft/apis/program-api.md) · [All operations](https://skmtc.net/galileo-ft/apis/program-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/galileo-ft/program-api/revisions/bcd728f97a18/schema)