`Recipient`

Saved payment recipient.

Profile of: ISO 20022 Creditor and CreditorAccount (subset). Account routing goes through the typed accountIdentifier discriminated union (IBAN, BBAN, country-specific account number, or alias); national identification is opaque to bank2ai and lives in the typed nationalId sub-object.

Properties

Field	Type	Required	Description
`accountIdentifier`	`IbanIdentifier` \| `BbanIdentifier` \| `AccountNumberIdentifier` \| `AliasIdentifier`	✓	Typed account identifier for routing the transfer.
`bic`	`string` \| `null`		BIC / SWIFT code of the recipient's bank, ISO 9362. Default: `null`. Examples: `"NWBKGB2L"`.
`defaultDescription`	`string` \| `null`		Pre-filled free-text shown on the recipient's statement for transfers prepared against this recipient. Clients MAY use this as the default `description` when preparing a transfer; users can override per transfer. Default: `null`.
`id`	`string`	✓	Unique recipient identifier (server-scoped).
`isFavorite`	`boolean`		Whether this recipient is marked as favorite. Default: `false`.
`lastUsedAt`	`string` \| `null`		ISO 8601 timestamp of the most recent transfer to this recipient. Default: `null`.
`name`	`string`	✓	Recipient's full name or business name. Examples: `"Jane Doe"`, `"Acme Corp"`.
`nationalId`	`NationalId` \| `null`		Recipient's national identifier when known. Default: `null`.
`nickname`	`string` \| `null`		Optional user-friendly handle for the recipient. Default: `null`. Examples: `"Mom"`, `"Landlord"`.

`accountIdentifier` — `type: "iban"`

IBAN-routed account, ISO 13616.

Field	Type	Required	Description
`iban`	`string`	✓	IBAN, ISO 13616. Examples: `"GB29NWBK60161331926819"`, `"DE89370400440532013000"`. Pattern: `^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$`.
`type`	`string`		Discriminator: `iban`. Default: `"iban"`.

`accountIdentifier` — `type: "bban"`

Domestic Basic Bank Account Number, used in markets without an IBAN.

Field	Type	Required	Description
`bban`	`string`	✓	Domestic account identifier in the country's native format. Examples: `"0133-26-007890"`.
`country`	`string`	✓	ISO 3166-1 alpha-2 country code. Examples: `"IS"`, `"GB"`. Pattern: `^[A-Z]{2}$`.
`type`	`string`		Discriminator: `bban`. Default: `"bban"`.

`accountIdentifier` — `type: "accountNumber"`

Country-specific composite for non-IBAN markets (US, UK pre-IBAN, etc.).

Field	Type	Required	Description
`accountNumber`	`string`	✓	Account number in the country's native format.
`country`	`string`	✓	ISO 3166-1 alpha-2 country code. Examples: `"US"`, `"GB"`. Pattern: `^[A-Z]{2}$`.
`routing`	`string` \| `null`		US ABA routing number, when applicable. Default: `null`.
`sortCode`	`string` \| `null`		UK sort code, when applicable. Default: `null`.
`type`	`string`		Discriminator: `accountNumber`. Default: `"accountNumber"`.

`accountIdentifier` — `type: "alias"`

Alias-based identifier (UPI VPA, Pix key, email-routed payments, etc.).

Field	Type	Required	Description
`alias`	`string`	✓	The alias value as the user knows it. Examples: `"alex@upi"`, `"+44-7700-900000"`.
`aliasType`	`AliasType`	✓	Kind of alias.
`type`	`string`		Discriminator: `alias`. Default: `"alias"`.

`nationalId` — `NationalId`

Person or business national identifier.

Field	Type	Required	Description
`country`	`string`	✓	ISO 3166-1 alpha-2 country code. Examples: `"IS"`, `"US"`. Pattern: `^[A-Z]{2}$`.
`type`	`NationalIdType` \| `null`		Hint for the kind of identifier. bank2ai does not validate the value. Default: `null`.
`value`	`string`	✓	National identifier value, in the country's native format. Examples: `"010190-1234"`, `"123-45-6789"`.

Raw JSON Schema

{
  "$defs": {
    "AccountNumberIdentifier": {
      "description": "Country-specific composite for non-IBAN markets (US, UK pre-IBAN, etc.).",
      "properties": {
        "accountNumber": {
          "description": "Account number in the country's native format.",
          "title": "Accountnumber",
          "type": "string"
        },
        "country": {
          "description": "ISO 3166-1 alpha-2 country code.",
          "examples": [
            "US",
            "GB"
          ],
          "pattern": "^[A-Z]{2}$",
          "title": "Country",
          "type": "string"
        },
        "routing": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "US ABA routing number, when applicable.",
          "title": "Routing"
        },
        "sortCode": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "UK sort code, when applicable.",
          "title": "Sortcode"
        },
        "type": {
          "const": "accountNumber",
          "default": "accountNumber",
          "description": "Discriminator: `accountNumber`.",
          "title": "Type",
          "type": "string"
        }
      },
      "required": [
        "accountNumber",
        "country"
      ],
      "title": "AccountNumberIdentifier",
      "type": "object"
    },
    "AliasIdentifier": {
      "description": "Alias-based identifier (UPI VPA, Pix key, email-routed payments, etc.).",
      "properties": {
        "alias": {
          "description": "The alias value as the user knows it.",
          "examples": [
            "alex@upi",
            "+44-7700-900000"
          ],
          "title": "Alias",
          "type": "string"
        },
        "aliasType": {
          "$ref": "#/$defs/AliasType",
          "description": "Kind of alias."
        },
        "type": {
          "const": "alias",
          "default": "alias",
          "description": "Discriminator: `alias`.",
          "title": "Type",
          "type": "string"
        }
      },
      "required": [
        "alias",
        "aliasType"
      ],
      "title": "AliasIdentifier",
      "type": "object"
    },
    "AliasType": {
      "description": "Type tag for alias-based account identifiers (UPI VPA, Pix key, email-routed payments, etc.).",
      "enum": [
        "email",
        "phone",
        "vpa",
        "pix",
        "other"
      ],
      "title": "AliasType",
      "type": "string"
    },
    "BbanIdentifier": {
      "description": "Domestic Basic Bank Account Number, used in markets without an IBAN.",
      "properties": {
        "bban": {
          "description": "Domestic account identifier in the country's native format.",
          "examples": [
            "0133-26-007890"
          ],
          "title": "Bban",
          "type": "string"
        },
        "country": {
          "description": "ISO 3166-1 alpha-2 country code.",
          "examples": [
            "IS",
            "GB"
          ],
          "pattern": "^[A-Z]{2}$",
          "title": "Country",
          "type": "string"
        },
        "type": {
          "const": "bban",
          "default": "bban",
          "description": "Discriminator: `bban`.",
          "title": "Type",
          "type": "string"
        }
      },
      "required": [
        "bban",
        "country"
      ],
      "title": "BbanIdentifier",
      "type": "object"
    },
    "IbanIdentifier": {
      "description": "IBAN-routed account, ISO 13616.",
      "properties": {
        "iban": {
          "description": "IBAN, ISO 13616.",
          "examples": [
            "GB29NWBK60161331926819",
            "DE89370400440532013000"
          ],
          "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$",
          "title": "Iban",
          "type": "string"
        },
        "type": {
          "const": "iban",
          "default": "iban",
          "description": "Discriminator: `iban`.",
          "title": "Type",
          "type": "string"
        }
      },
      "required": [
        "iban"
      ],
      "title": "IbanIdentifier",
      "type": "object"
    },
    "NationalId": {
      "description": "Person or business national identifier.",
      "properties": {
        "country": {
          "description": "ISO 3166-1 alpha-2 country code.",
          "examples": [
            "IS",
            "US"
          ],
          "pattern": "^[A-Z]{2}$",
          "title": "Country",
          "type": "string"
        },
        "type": {
          "anyOf": [
            {
              "$ref": "#/$defs/NationalIdType"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Hint for the kind of identifier. bank2ai does not validate the value."
        },
        "value": {
          "description": "National identifier value, in the country's native format.",
          "examples": [
            "010190-1234",
            "123-45-6789"
          ],
          "title": "Value",
          "type": "string"
        }
      },
      "required": [
        "value",
        "country"
      ],
      "title": "NationalId",
      "type": "object"
    },
    "NationalIdType": {
      "description": "Opaque label for the kind of national identifier carried in `NationalId.value`.\n\nbank2ai does not validate national-ID formats; this is a hint so\nclients can render or route appropriately. Servers SHOULD set the\nclosest-matching value or use `other`.",
      "enum": [
        "ssn",
        "kennitala",
        "cpr",
        "personnummer",
        "cpf",
        "other"
      ],
      "title": "NationalIdType",
      "type": "string"
    }
  },
  "description": "Saved payment recipient.\n\nProfile of: ISO 20022 `Creditor` and `CreditorAccount` (subset).\nAccount routing goes through the typed `accountIdentifier`\ndiscriminated union (IBAN, BBAN, country-specific account number,\nor alias); national identification is opaque to bank2ai and lives\nin the typed `nationalId` sub-object.",
  "properties": {
    "accountIdentifier": {
      "description": "Typed account identifier for routing the transfer.",
      "discriminator": {
        "mapping": {
          "accountNumber": "#/$defs/AccountNumberIdentifier",
          "alias": "#/$defs/AliasIdentifier",
          "bban": "#/$defs/BbanIdentifier",
          "iban": "#/$defs/IbanIdentifier"
        },
        "propertyName": "type"
      },
      "oneOf": [
        {
          "$ref": "#/$defs/IbanIdentifier"
        },
        {
          "$ref": "#/$defs/BbanIdentifier"
        },
        {
          "$ref": "#/$defs/AccountNumberIdentifier"
        },
        {
          "$ref": "#/$defs/AliasIdentifier"
        }
      ],
      "title": "Accountidentifier"
    },
    "bic": {
      "anyOf": [
        {
          "pattern": "^[A-Z]{6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3})?$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "BIC / SWIFT code of the recipient's bank, ISO 9362.",
      "examples": [
        "NWBKGB2L"
      ],
      "title": "Bic"
    },
    "defaultDescription": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Pre-filled free-text shown on the recipient's statement for transfers prepared against this recipient. Clients MAY use this as the default `description` when preparing a transfer; users can override per transfer.",
      "title": "Defaultdescription"
    },
    "id": {
      "description": "Unique recipient identifier (server-scoped).",
      "title": "Id",
      "type": "string"
    },
    "isFavorite": {
      "default": false,
      "description": "Whether this recipient is marked as favorite.",
      "title": "Isfavorite",
      "type": "boolean"
    },
    "lastUsedAt": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "ISO 8601 timestamp of the most recent transfer to this recipient.",
      "title": "Lastusedat"
    },
    "name": {
      "description": "Recipient's full name or business name.",
      "examples": [
        "Jane Doe",
        "Acme Corp"
      ],
      "title": "Name",
      "type": "string"
    },
    "nationalId": {
      "anyOf": [
        {
          "$ref": "#/$defs/NationalId"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Recipient's national identifier when known."
    },
    "nickname": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional user-friendly handle for the recipient.",
      "examples": [
        "Mom",
        "Landlord"
      ],
      "title": "Nickname"
    }
  },
  "required": [
    "id",
    "name",
    "accountIdentifier"
  ],
  "title": "Recipient",
  "type": "object"
}

Properties​

accountIdentifier — type: "iban"​

accountIdentifier — type: "bban"​

accountIdentifier — type: "accountNumber"​

accountIdentifier — type: "alias"​

nationalId — NationalId​