TransferRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/token-io/main/json-schema/token-io-transfer-request-schema.json",
  "title": "TransferRequest",
  "description": "Transfer operation request.",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/token-io-transfers-api-openapi.yml#/components/schemas/TransferRequest",
  "required": [
    "destinatons",
    "source",
    "transactionAmount",
    "transferId"
  ],
  "type": "object",
  "properties": {
    "transferId": {
      "type": "string",
      "description": "The Token transfer identifier."
    },
    "transactionAmount": {
      "$ref": "#/$defs/Money"
    },
    "source": {
      "$ref": "#/$defs/BankAccount"
    },
    "destinations": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/TransferDestinations"
      }
    },
    "description": {
      "type": "string",
      "description": "Optional transfer description."
    },
    "tokenRefId": {
      "type": "string",
      "description": "Reference id of the token, set by the initiator."
    },
    "tokenInitiatorId": {
      "type": "string",
      "description": "Id of the member requesting token creation."
    },
    "transferRefId": {
      "type": "string",
      "description": "Transfer reference id."
    },
    "metadata": {
      "$ref": "#/$defs/TransferMetadata"
    }
  },
  "$defs": {
    "ACH": {
      "required": [
        "accountNumber",
        "routingNumber"
      ],
      "type": "object",
      "properties": {
        "accountNumber": {
          "type": "integer",
          "description": "The account number."
        },
        "routingNumber": {
          "type": "integer",
          "description": "The routing number."
        }
      },
      "description": "The Automated Clearing House Network."
    },
    "Address": {
      "type": "object",
      "properties": {
        "houseNumber": {
          "type": "string",
          "description": "The house number (may contain letters, dashes or other characters). Addresses describe ways to tag a single building with multiple addresses."
        },
        "houseName": {
          "type": "string",
          "description": "The name of a house. This is sometimes used in some countries like England instead of (or in addition to) a house number."
        },
        "flats": {
          "type": "string",
          "description": "The house numbers (range or list) of flats behind a door."
        },
        "conscriptionNumber": {
          "type": "string",
          "description": "This special kind of house number relates to a settlement instead of a street. Conscription numbers were introduced in the Austrio-Hungarian Empire and are still in use in some parts of Europe, sometimes together with street-related house numbers which are also called orientation numbers."
        },
        "street": {
          "type": "string",
          "description": "The name of the respective street."
        },
        "place": {
          "type": "string",
          "description": "This is part of an address which refers to the name of some territorial zone (usually like island or square) instead of a street. Should not be used together with street."
        },
        "postCode": {
          "type": "string",
          "description": "The postal code of the building/area."
        },
        "city": {
          "type": "string",
          "description": "The name of the city as given in postal addresses of the building/area."
        },
        "country": {
          "maxLength": 2,
          "minLength": 2,
          "type": "string",
          "description": "The ISO 3166-1 alpha-2 two letter country code in upper case."
        },
        "full": {
          "type": "string",
          "description": "Use this for a full-text, often multi-line address if you find the structured address fields unsuitable for denoting the address of this particular location. Examples: 'Fifth house on the left after the village oak, Smalltown, Smallcountry' or '1200 West Sunset Boulevard Suite 110A'. Beware that these strings can hardly be parsed by software."
        },
        "hamlet": {
          "type": "string",
          "description": "The hamlet."
        },
        "suburb": {
          "type": "string",
          "description": "If an address exists several times in a city. You have to add the name of the settlement. See Australian definition of suburb."
        },
        "subdistrict": {
          "type": "string",
          "description": "The subdistrict."
        },
        "district": {
          "type": "string",
          "description": "The district."
        },
        "province": {
          "type": "string",
          "description": "The province. For Canada, uppercase two-letter postal abbreviations  (BC, AB, ON, QC, etc.) are used. In Russia a synonym region is widely used."
        },
        "state": {
          "maxLength": 2,
          "minLength": 2,
          "type": "string",
          "description": "The state. For the US, uppercase two-letter postal abbreviations (AK, CA, HI, NY, TX, WY, etc.) are used."
        }
      },
      "description": "Represents a postal address."
    },
    "BankAccount": {
      "required": [
        "account"
      ],
      "type": "object",
      "properties": {
        "account": {
          "description": "The bank account identifier.",
          "oneOf": [
            {
              "$ref": "#/$defs/Custom"
            },
            {
              "$ref": "#/$defs/Iban"
            },
            {
              "$ref": "#/$defs/Domestic"
            }
          ]
        }
      },
      "description": "Represents Token account identifier."
    },
    "Custom": {
      "required": [
        "bankId",
        "payload"
      ],
      "type": "object",
      "properties": {
        "bankId": {
          "type": "string",
          "description": "the Token bank identifier."
        },
        "payload": {
          "type": "string",
          "description": "the bank-custom account identifier."
        }
      },
      "description": "Represents an account identifier in bank-custom format."
    },
    "Customer": {
      "required": [
        "legalNames"
      ],
      "type": "object",
      "properties": {
        "legalNames": {
          "type": "array",
          "description": "A list of names of primary account holders.",
          "items": {
            "type": "string"
          }
        },
        "address": {
          "$ref": "#/$defs/Address"
        }
      },
      "description": "Represents account holder information."
    },
    "Domestic": {
      "required": [
        "accountNumber",
        "bankCode",
        "country"
      ],
      "type": "object",
      "properties": {
        "bankCode": {
          "type": "string",
          "description": "The bank identifier."
        },
        "accountNumber": {
          "type": "string",
          "description": "The account identifier."
        },
        "country": {
          "maxLength": 2,
          "minLength": 2,
          "type": "string",
          "description": "2-letter ISO 3166-1 alpha-2 country code"
        }
      },
      "description": "Represents an account in the regional format."
    },
    "FPS": {
      "required": [
        "accountNumber",
        "sortCode"
      ],
      "type": "object",
      "properties": {
        "sortCode": {
          "type": "string",
          "description": "The sort code associated wth the account."
        },
        "accountNumber": {
          "type": "string",
          "description": "The account number."
        }
      },
      "description": "Faster Payments Service."
    },
    "Iban": {
      "required": [
        "iban"
      ],
      "type": "object",
      "properties": {
        "iban": {
          "type": "string",
          "description": "The IBAN account number."
        },
        "bic": {
          "type": "string",
          "description": "optional BIC number for this account."
        }
      },
      "description": "Represents an account using IBAN format."
    },
    "Money": {
      "required": [
        "currency",
        "value"
      ],
      "type": "object",
      "properties": {
        "currency": {
          "maxLength": 3,
          "minLength": 3,
          "type": "string",
          "description": "ISO4217 - 3 letter currency code such as \"USD\" or \"EUR\"."
        },
        "value": {
          "type": "string",
          "description": "Double amount in the string format."
        }
      },
      "description": "Represents a monetary value."
    },
    "SEPA": {
      "required": [
        "iban"
      ],
      "type": "object",
      "properties": {
        "iban": {
          "type": "string",
          "description": "International Bank Account Number."
        },
        "bic": {
          "type": "string",
          "description": "Bank Identifier Code."
        }
      },
      "description": "Single Euro Payments Area."
    },
    "SWIFT": {
      "required": [
        "accountNumber",
        "bic"
      ],
      "type": "object",
      "properties": {
        "accountNumber": {
          "type": "string",
          "description": "The account number."
        },
        "bic": {
          "type": "string",
          "description": "Bank Identifier Code."
        }
      },
      "description": "Society for Worldwide Interbank Financial Telecommunication."
    },
    "TransferDestination": {
      "required": [
        "destination"
      ],
      "type": "object",
      "properties": {
        "scheme": {
          "description": "The transfer destination details.",
          "oneOf": [
            {
              "$ref": "#/$defs/SEPA"
            },
            {
              "$ref": "#/$defs/FPS"
            },
            {
              "$ref": "#/$defs/SWIFT"
            },
            {
              "$ref": "#/$defs/ACH"
            }
          ]
        }
      },
      "description": "Represents payment scheme details for a given account."
    },
    "TransferDestinations": {
      "required": [
        "customerData",
        "destinations"
      ],
      "type": "object",
      "properties": {
        "destinations": {
          "type": "array",
          "description": "A list of transfer destinations.",
          "items": {
            "$ref": "#/$defs/TransferDestination"
          }
        },
        "customerData": {
          "$ref": "#/$defs/Customer"
        }
      },
      "description": "A list of possible transfer destinations for a given customer."
    },
    "TransferMetadata": {
      "type": "object",
      "properties": {
        "purposeOfPayment": {
          "type": "string",
          "description": "Purpose of Payment for this transfer.",
          "enum": [
            "OTHER",
            "PERSONAL_EXPENSES",
            "PURCHASE_OF_SHARES",
            "TRANSFER_TO_YOUR_OWN_ACCOUNT",
            "PURCHASE_OF_PROPERTY",
            "FAMILY_MAINTENANCE",
            "SAVINGS"
          ]
        },
        "paymentContext": {
          "type": "string",
          "description": "Optional payment context of this transfer.",
          "enum": [
            "OTHER_CONTEXT",
            "BILL_PAYMENT",
            "ECOMMERCE_GOODS",
            "ECOMMERCE_SERVICES",
            "PERSON_TO_PERSON"
          ]
        },
        "merchantCategoryCode": {
          "type": "string",
          "description": "Optional ISO 18245 Merchant Category Code (MCC)."
        },
        "merchantCustomerId": {
          "description": "Optional unique merchant customer identifier."
        },
        "deliveryAddress": {
          "$ref": "#/$defs/Address"
        }
      },
      "description": "Represents additional metadata related to a transfer."
    }
  }
}