Beneficiary Bank Accounts

GET Beneficiary Bank Account Minimum Requirements

The Get Beneficiary Bank Account Minimum Requirements API provides metadata for input validations when creating Beneficiary Bank Accounts via the API channel. This includes the minimum data requirements for a beneficiary to be created, however some Banking as a Service (BaaS) providers will require additional details.
Please consult your Implementation Executive to confirm any additional requirements for your configuration.

GET /beneficiary-bank-account-requirements/

Supported query parameters:

Parameter	Description	Requirement
data.beneficiaryBankAccount.currency	Currency of Beneficiary Bank Account	Required Field
data.beneficiaryBankAccount.country	Country of Beneficiary Bank Account	Required Field
data.beneficiaryAddress.country	Country of Beneficiary Address	Optional

Inputs are used to gather Beneficiary Bank Account Validation metadata based on Bank Account Country & Beneficiary Country & Currency.

Example #1 : GET /beneficiary-bank-account-requirements/
When the input contains 'BeneficiaryBankAccountCountry: GB - BeneficiaryCountry: GB -Currency: GBP', fields will be restricted to :

Account Number: 8-digit number
Sort Code: 6-digit number
IBAN (Optional)
BIC (Optional): 8-11 Character Code

SAMPLE OUTPUT:

{
  "workflow": {},
  "data": {
    "beneficiaryBankAccount": {
      "requirements": {
        "beneficiaryAddress": "optional/required"
      },
      "iban": {
        "requirement": "required",
        "regex": ""
      },
      "accountNumber": {
        "requirement": "none/optional/required",
        "regex": "^[0-9]{7,20}$"
      },
      "bankName": {
        "requirement": "none/optional/required",
        "regex": null
      },
      "routingCodes": {
        "bic": {
          "requirement": "none/optional/required",
          "regex": "^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$"
        }
      }
    },
    "beneficiaryAddress": {
      "country": {
        "requirement": "required",
        "regex": "^[A-Z]{2}$"
      },
      "region": {
        "requirement": "none/required",
        "regex": "^.{1,255}"
      },
      "city": {
        "requirement": "required",
        "regex": "^.{1,255}"
      },
      "street": {
        "requirement": "required",
        "regex": "^.{1,255}"
      },
      "houseNumber": {
        "requirement": "optional",
        "regex": "^.{1,255}"
      },
      "postalCode": {
        "requirement": "none/optional/required",
        "regex": "^.{1,12}"
      },
      "refinement": {
        "requirement": "optional",
        "regex": "^.{1,255}"
      }
    }
  },
  "connect": {},
  "metadata": {}
}

Option field values :
- iban : 'none', 'optional' or 'required'
- accountNumber : 'none', 'optional' or 'required'
- bankName : 'none', 'optional' or 'required'

If an option value is 'none' for a field, it should not be sent.

beneficiaryAddress is returned if input ‘data.beneficiaryAddress.country’ is given. Otherwise, it is not included in the returned object.

Routing Code Types

Below is the list of possible routing code types:

Routing Code	Routing Code Key	Regex	Countries
Swift Number (BIC)	bic	^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$	Any
Sort Code	sort-code	^(?!(?:0{6}))(?:\d{6})$	UK, Guernsey, Isle of Man, Jersey
ABA Number	aba	^(?!(?:0{9}))(?:\d{9})$"	US
Routing Number Canada	rtn-canada	^(?!(?:0{8,9}))(?:0?\d{8})$	Canada
Clabe	clabe	^(?!(?:0{18}))(?:\d{18})$	Mexico
BSB Code	bsb-code	^(?!(?:0{6}))(?:\d{6})$	Australia
IFSC	ifsc	^[A-Z]{4}0[A-Z0-9]{6}$	India
CNAPS	cnaps	^(?!(?:0{12}))(?:\d{12})$	China
Bank Code	bank-code	^(?!(?:0{3,5}))(?:\d{3,5})$	Denmark, Hong Kong, Norway, Sweden, Sri Lanka, South Korea, Japan, Pakistan, Brazil
Branch Code	branch-code	^\d{0,6}$	Sri Lanka, Brazil, Uruguay, Ghana, Kenya, Tanzania, Uganda, Japan

Create Beneficiary Bank Account

There are 2 different workflows to create a Beneficiary Bank Account.

1) DIRECT :

POST /beneficiaries/{beneficiaryId}/bank-accounts

{
    "workflow": {
        "code": "direct"
    },
    "data": {
        "bankAccount": {
            "country": "GB",
            "currency": "GBP",
            "accountNumber": "12345678",
            "iban": "GB72RABO1521764247",
            "routingCodes": {
                "bic": "YAPIGBIS",
                "sort-code": "123456"
            }
        }
    },
    "connect": {},
    "metadata": {}
}

2) MIGRATION :

POST /beneficiaries/{beneficiaryId}/bank-accounts

beneficiaryId --> Id of beneficiary which will be connected to the migrated beneficiary bank account

{
    "workflow": {
        "code": "migration"
    },
    "data": {
        "sourceId": "63369f6e-1e50-4617-b195-a0548f588e22",
        "sourceBeneficiaryId": "63369f6e-9761-4c34-a2a6-38b30a6d516f"
    },
    "connect": {
        "type": "explicit",
        "serviceProvider": "railsbank"
    },
    "metadata": {}
}

Update Beneficiary Bank Account

PATCH /beneficiaries/{beneficiaryId}/bank-accounts/{beneficiaryBankAccountId}

{
    "workflow": {
        "code": "direct"
    },
    "data": {
        "bankAccount": {
            "country": "GB",
            "currency": "GBP",
            "accountNumber": "12345678",
            "iban": "GB12AB01234567890",
            "routingCodes": {
                "bic": "ABCDGBBK",
                "sort-code": "123456"
            }
        }
    },
    "connect": {},
    "metadata": {}
}

List Beneficiary Bank Account

GET /beneficiaries/{beneficiaryId}/bank-accounts

Parameter	Description	Requirement
metadata.page.number	0-indexed, default=0	optional
metadata.page.size	default=10	optional

{
    "workflow": {},
    "data": {
        "beneficiaryBankAccounts": [
            {
                "id": "a1d027a1-7227-4d80-8753-62e3a34c01e5",
                "accountHolderType": "individual",
                "beneficiaryId": "2a8f4270-efcc-4f49-b2e1-b1b7f80af759",
                "country": "GB",
                "currency": "GBP",
                "routingCodes": {
                    "sort-code": "040329"
                },
                "accountNumber": "00591043",
                "iban": "GB49LHVB04032900591043",
                "creationDateTime": "2023-01-30T10:56:05.798868",
                "creatingUserUsername": "canay.ozel@integrated.finance"
            }
        ]
    },
    "connect": {},
    "metadata": {
        "page": {
            "size": 20,
            "number": 0,
            "totalElements": 1,
            "totalPages": 1
        }
    }
}

Get Beneficiary Bank Account

GET /beneficiaries/{beneficiaryId}/bank-accounts/{beneficiaryBankAccountId}

{
    "workflow": {},
    "data": {
        "beneficiaryBankAccount": {
            "id": "a1d027a1-7227-4d80-8753-62e3a34c01e5",
            "beneficiaryId": "2a8f4270-efcc-4f49-b2e1-b1b7f80af759",
            "country": "GB",
            "currency": "GBP",
            "routingCodes": {
                "sort-code": "040329"
            },
            "accountNumber": "00591043",
            "iban": "GB49LHVB04032900591043",
            "creationDateTime": "2023-01-30T10:56:05.798868",
            "creatingUserUsername": "canay.ozel@integrated.finance"
        }
    },
    "connect": {},
    "metadata": {}
}