---
title: "Create External Account Link"
method: POST
path: "/createExternalAccountLink"
tags: ["External Account Links"]
---

# Create External Account Link

`POST /createExternalAccountLink`

## Request

- Base URL: `{corename}.payment-hub.{env}.gpsrv.com/payment-hub/1.0`
- URL: `{corename}.payment-hub.{env}.gpsrv.com/payment-hub/1.0/createExternalAccountLink`
- Auth: none declared. Required headers: `x-gft-idempotency-key`, `Authorization`

> 👍 Availability
>
>Some of the field descriptions for this endpoint reference FedNow or Fedwire, which are future capabilities not yet available for clients. Right now, this endpoint supports only Mastercard Data Connect: Account Linking and Mastercard Data Connect: Balance Check.

Use this endpoint to create a link from an account at an external bank to the caller account when a user manually inputs their external account information. This account will be usable for transfers over FedWire or credit rails, depending on your configuration.

## Headers

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

## Request body

- object
  - `accountNo` string, required: The <<glossary:PRN>> of the account. Pattern: PRN Example: `"074103447228"`
  - `nickname` string, nullable: Display name for the remote account. Not considered to be sensitive data. Pattern: 1–34 characters with at least one non-whitespace character. Example: `"Celia College Fund"`
  - `owner` object, required: Owner information for the external account.
    - `type` 'CORPORATE' | 'CONSUMER' | 'GALILEO', required: Type of entity that owns the external account. Example: `"CONSUMER"`
    - `ownershipType` 'FIRST_PARTY' | 'THIRD_PARTY': Relationship of the account owner to the program account. Example: `"FIRST_PARTY"`
    - `address` object, nullable: Primary address for the account owner.
      - `line1` string, nullable: 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, nullable: 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, nullable: 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, nullable: 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, nullable: 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, nullable: Country code following ISO 3166-1 alpha-2 format. Pattern: Exactly 2 uppercase letters. Examples: 'US' (United States), 'MX' (Mexico)
  - `details` union, required
    - BankAccountDetails: Bank, card, or wallet card details for the external account.
      - `type` 'BANK' | 'CARD' | 'WALLET_CARD', required: Type of external account being linked.
      - `bankDepositType` 'CHECKING' | 'SAVINGS' | 'MONEY_MARKET' | 'CMA', required
      - `bankAddress` object, nullable
        - `line1` string, nullable: 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, nullable: 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, nullable: 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, nullable: 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, nullable: 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, nullable: Country code following ISO 3166-1 alpha-2 format. Pattern: Exactly 2 uppercase letters. Examples: 'US' (United States), 'MX' (Mexico)
      - `bankAccountNumber` string, required: Full account number for the external bank account. Accepts both domestic account numbers and IBANs. When providing an IBAN, set `bankAccountNumberType` to `IBAN`. Pattern: Alphanumeric string Example: `"324839572834"` or `"DE89370400440532013000"` (IBAN)
      - `bankAccountNumberType` 'IBAN' | 'ACCOUNT_NUMBER': Type of account number provided in bankAccountNumber. - IBAN: International Bank Account Number, validated per ISO 13616 - ACCOUNT_NUMBER: Standard account identifier (default when omitted)
      - `bankRoutingInfo` object[], required: Routing path for the external account. Supports routing numbers (ABA/RTN) and BIC/SWIFT codes. Pattern: At least one routing path is required.
        - `type` 'ROUTING_NO' | 'BIC', required: Type of routing information provided. Values: ROUTING_NO, BIC - ROUTING_NO: ABA/RTN routing number - BIC: SWIFT/BIC code Example: `ROUTING_NO`
        - `paymentType` 'ACH' | 'FEDNOW' | 'FEDWIRE' | 'CARD', required: Payment rail that will use this routing information. Example: FEDWIRE
        - `value` string, required: Routing identifier value. - For ROUTING_NO: 9-digit ABA routing number. Example: `"124001234"` - For BIC: 8 or 11-character SWIFT/BIC code. Example: `"CHASUS33"`, `"NWBKGB2LXXX"`
      - `bankName` string, nullable: Name of the financial institution for the external account. Pattern: - Default: 1–40 characters with at least one non-whitespace character - FEDNOW: 1–140 characters - FEDWIRE: 1–140 characters, limited to alphanumeric and special characters. Example: `"AbcBank"`
    - CardAccountDetails: Bank, card, or wallet card details for the external account.
      - `type` 'BANK' | 'CARD' | 'WALLET_CARD', required: Type of external account being linked.
      - `cardNumber` string, required: Full card number of the external debit or credit card. Pattern: 15–16 digits Example: 4111111111111111
      - `cardUseOwnerAddress` boolean, required: Specifies whether to use the account owner's address on file for the card. Pattern: true or false Example: true
      - `cardAddress` object, nullable: Billing address for the card if different from the owner's address. Should not be provided when `cardUseOwnerAddress` is `true`. Required when `cardUseOwnerAddress` is `false`. Pattern: true or false
        - `line1` string, nullable: 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, nullable: 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, nullable: 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, nullable: 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, nullable: 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, nullable: Country code following ISO 3166-1 alpha-2 format. Pattern: Exactly 2 uppercase letters. Examples: 'US' (United States), 'MX' (Mexico)
      - `cardCvv` string, required: The <<glossary:CVV>> for the external card. Pattern: 3–4 digits Example: `123` (for most cards), `1234` (for Amex)
      - `cardExpirationDate` string, required: Expiration date of the external card. Must be a valid month (01–12) and year from 2025 to 2099. Pattern: `YYYY-MM` Example: `2028-12`
    - WalletCardDetails: Bank, card, or wallet card details for the external account.
      - `type` 'BANK' | 'CARD' | 'WALLET_CARD', required: Type of external account being linked.
      - `provider` 'APPLE_PAY' | 'GOOGLE_PAY', required: Wallet provider for a WALLET_CARD external account.
      - `cardUseOwnerAddress` boolean, required: Whether to use the funded STS account owner's address for the card. When true, `cardAddress` must be omitted. When false, `cardAddress` is required. Pattern: true or false Example: true
      - `cardAddress` object, nullable: Billing address for the wallet card. Required when `cardUseOwnerAddress` is false. Must be omitted when `cardUseOwnerAddress` is true.
        - `line1` string, nullable: 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, nullable: 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, nullable: 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, nullable: 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, nullable: 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, nullable: Country code following ISO 3166-1 alpha-2 format. Pattern: Exactly 2 uppercase letters. Examples: 'US' (United States), 'MX' (Mexico)
      - `paymentToken` union, required: Complete provider payment token as sent by the wallet. For APPLE_PAY, this is the full PKPaymentToken JSON object. For GOOGLE_PAY, this is the exact tokenizationData.token string. The client must not extract, parse, or rebuild fields inside the token.
        - object
        - string
  - `validation` object, required: Details for validating the external account link.
    - `type` 'CLIENT' | 'LEGACY' | 'CARD' | 'FINICITY' | 'NONE' | 'MICRO_ENTRY': Specifies the validation method required for the external account link. Pattern: enum Example: `"CLIENT"`
    - `status` 'PENDING' | 'FAILED' | 'PASSED' | 'NO_VALIDATION': Indicates the current status of the validation process. Pattern: enum Example: `"PENDING"`
    - `status_reason` string, nullable: Provides additional context or a reason for the current validation status. Pattern: Alphanumeric string Example: `"Validated successfully"`
    - `sameDay` boolean: Whether to originate the microdeposits as same-day ACH instead of next business day. Only valid when `type` is `MICRO_ENTRY`. Requests after the Nacha same-day cutoff are originated the next business day. Pattern: true or false Example: true

## Response `200`

Successful Response

- object
  - `externalAccountLinkId` string, required: The unique identifier that identifies the external account link in the system.

## 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.dev/galileo-ft/apis/payment-hub-api-2-0.md) - [All operations](https://skmtc.dev/galileo-ft/apis/payment-hub-api-2-0/llms.txt) - [OpenAPI document](https://skmtc.dev/galileo-ft/apis/payment-hub-api-2-0/revisions/20e06b09d5e4?raw)