Send and receive account-to-account payments across supported schemes - UK Faster Payments, Bacs and CHAPS, SEPA Credit Transfer, SEPA Instant, and US instant rails - and handle payment exceptions such as rejections, returns, reversals and recalls. Represented by the PaymentReads and PaymentWrites operations under /transaction/payments in the Form3 Public API.
basePath: /v1
consumes: []
definitions:
AcceptanceQualifier:
description: All accepted payments will receive the matching qualifier code
enum:
- some_other_time
- same_day
- next_calendar_day
- next_working_day
- after_next_working_day
- none
type: string
x-access:
- Public
Account:
properties:
attributes:
$ref: '#/definitions/AccountAttributes'
id:
description: Unique resource ID
example: 7826c3cb-d6fd-41d0-b187-dc23ba928772
format: uuid
type: string
organisation_id:
description: Unique ID of the organisation this resource is created by
example: ee2fb143-6dfe-4787-b183-ca8ddd4164d2
format: uuid
type: string
relationships:
$ref: '#/definitions/AccountRelationships'
type:
description: Name of the resource type
example: accounts
pattern: ^[A-Za-z_]*$
type: string
version:
description: Version number
example: 0
minimum: 0
type: integer
required:
- id
- organisation_id
- attributes
type: object
x-access:
- Public
AccountAmendment:
properties:
data:
$ref: '#/definitions/AccountUpdate'
type: object
x-access:
- Public
AccountAttributes:
properties:
acceptance_qualifier:
$ref: '#/definitions/AcceptanceQualifier'
account_classification:
default: Personal
description: Is the account business or personal?
enum:
- Personal
- Business
type: string
account_matching_opt_out:
default: false
description: '- deprecated - Is the account opted out of account matching,
e.g. CoP?'
type: boolean
account_number:
description: Account number of the account. A unique number will automatically
be generated if not provided.
example: '41426819'
pattern: ^[A-Z0-9]{0,64}$
type: string
alternative_bank_account_names:
description: '- deprecated - Alternative account names. Used for Confirmation
of Payee matching.'
items:
maxLength: 140
minLength: 1
type: string
maxItems: 3
type: array
x-nullable: true
x-omitempty: true
alternative_names:
description: Alternative names. Used for Confirmation of Payee matching.
items:
maxLength: 140
minLength: 1
type: string
maxItems: 3
type: array
x-nullable: true
x-omitempty: true
bank_account_name:
description: '- deprecated - Primary account name. Used for Confirmation of
Payee matching. Required if confirmation_of_payee_enabled is true for the
organisation.'
maxLength: 140
minLength: 1
type: string
bank_id:
description: Local country bank identifier. In the UK this is the sort code.
example: '400300'
pattern: ^[A-Z0-9]{0,16}$
type: string
bank_id_code:
description: ISO 20022 code used to identify the type of bank ID being used
example: GBDSC
pattern: ^[A-Z]{0,16}$
type: string
base_currency:
description: ISO 4217 code used to identify the base currency of the account
example: GBP
pattern: ^[A-Z]{3}$
type: string
bic:
description: SWIFT BIC in either 8 or 11 character format
example: NWBKGB22
pattern: ^([A-Z]{6}[A-Z0-9]{2}|[A-Z]{6}[A-Z0-9]{5})$
type: string
country:
description: ISO 3166-1 code used to identify the domicile of the account
example: GB
pattern: ^[A-Z]{2}$
type: string
customer_id:
description: A free-format reference that can be used to link this account
to an external system
example: '12345'
pattern: ^[a-zA-Z0-9-$@., ]{0,256}$
type: string
first_name:
description: '- deprecated - Customer first name.'
maxLength: 40
minLength: 1
type: string
iban:
description: IBAN of the account. Will be calculated from other fields if
not supplied.
example: GB11NWBK40030041426819
pattern: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{0,64}$
type: string
joint_account:
default: false
description: Is the account joint?
type: boolean
name:
description: Account holder names (for example title, first name, last name).
Used for Confirmation of Payee matching.
items:
maxLength: 256
minLength: 1
type: string
maxItems: 4
type: array
x-nullable: true
x-omitempty: true
name_matching_status:
default: supported
description: Describes the status of the account for name matching via CoP.
The value determines the code with which Form3 responds to matched CoP requests
to this account.
enum:
- supported
- switched
- opted_out
- not_supported
type: string
organisation_identification:
$ref: '#/definitions/AccountAttributesOrganisationIdentification'
private_identification:
$ref: '#/definitions/AccountAttributesPrivateIdentification'
processing_service:
description: '- deprecated - Accounting system or service. It will be added
to each payment received to an account.'
maxLength: 35
type: string
x-nullable: true
reference_mask:
description: When set will apply a validation mask on the payment reference
to each payment received to an account.
example: 4929############
maxLength: 35
type: string
x-nullable: true
secondary_identification:
description: Secondary identification, e.g. building society roll number.
Used for Confirmation of Payee.
maxLength: 140
minLength: 1
type: string
status:
description: Current status of the account
enum:
- pending
- failed
- confirmed
- closed
type: string
status_reason:
$ref: '#/definitions/StatusReason'
switched:
default: false
description: '- deprecated - Indicates whether the account has been switched
using the Current Account Switch Service.'
type: boolean
switched_account_details:
$ref: '#/definitions/SwitchedAccountDetails'
title:
description: '- deprecated - Customer title.'
example: Ms
maxLength: 40
minLength: 1
type: string
type:
description: Account type
maxLength: 35
type: string
user_defined_data:
description: All purpose list of key-value pairs to store specific data for
the associated account. It will be added to each payment received to an
account.
items:
$ref: '#/definitions/UserDefinedData'
maxItems: 5
type: array
x-omitempty: true
user_defined_information:
description: '- deprecated - All purpose field to store specific data for
the associated account. It will be added to each payment received to an
account.'
maxLength: 35
type: string
x-nullable: true
validation_type:
$ref: '#/definitions/ValidationType'
required:
- country
type: object
x-access:
- Public
AccountAttributesOrganisationIdentification:
properties:
actors:
items:
$ref: '#/definitions/AccountAttributesOrganisationIdentificationActor'
type: array
address:
items:
maxLength: 140
minLength: 1
type: string
type: array
city:
maxLength: 35
minLength: 1
type: string
country:
example: GB
pattern: ^[A-Z]{2}$
type: string
identification:
maxLength: 140
minLength: 1
type: string
identification_issuer:
type: string
identification_scheme:
maxLength: 35
minLength: 1
type: string
identification_scheme_code:
maxLength: 35
minLength: 1
type: string
registration_number:
type: string
tax_residency:
description: ISO 3166-1 code used to identify the domicile of the account
example: GB
pattern: ^[A-Z]{2}$
type: string
type: object
x-access:
- Public
AccountAttributesOrganisationIdentificationActor:
properties:
birth_date:
example: '2017-07-23'
format: date
type: string
x-nullable: true
name:
description: Actor names (for example title, first name, last name). Used
for Confirmation of Payee matching.
items:
maxLength: 255
minLength: 1
type: string
maxItems: 4
type: array
x-nullable: true
residency:
description: ISO 3166-1 code used to identify the domicile of the actor
example: GB
pattern: ^[A-Z]{2}$
type: string
role:
type: string
type: object
x-access:
- Public
AccountAttributesPrivateIdentification:
properties:
address:
items:
maxLength: 140
minLength: 1
type: string
type: array
birth_country:
example: GB
pattern: ^[A-Z]{2}$
type: string
birth_date:
description: Customer birth date
example: '2017-07-23'
format: date
type: string
x-nullable: true
city:
maxLength: 35
minLength: 1
type: string
country:
example: GB
pattern: ^[A-Z]{2}$
type: string
identification:
example: L-123456789
maxLength: 140
minLength: 1
type: string
identification_issuer:
minLength: 1
type: string
identification_scheme:
maxLength: 35
minLength: 1
type: string
identification_scheme_code:
maxLength: 35
minLength: 1
type: string
type: object
x-access:
- Public
AccountClassification:
enum:
- personal
- business
type: string
x-access:
- Public
AccountCreation:
properties:
data:
$ref: '#/definitions/Account'
required:
- data
type: object
x-access:
- Public
AccountCreationResponse:
properties:
data:
$ref: '#/definitions/Account'
links:
$ref: '#/definitions/Links'
type: object
x-access:
- Public
AccountDetailsListResponse:
properties:
data:
items:
$ref: '#/definitions/Account'
type: array
links:
$ref: '#/definitions/Links'
type: object
x-access:
- Public
AccountDetailsResponse:
properties:
data:
$ref: '#/definitions/Account'
links:
$ref: '#/definitions/Links'
type: object
x-access:
- Public
AccountEvent:
properties:
attributes:
$ref: '#/definitions/AccountEventAttributes'
id:
description: Unique resource ID
example: 6d4f9916-3af9-416e-a347-2d8df90fc4ab
format: uuid
type: string
organisation_id:
description: Unique ID of the organisation this resource is created by
example: cfc09fb8-bbca-40bd-a518-6e58d8a9c7f4
format: uuid
type: string
relationships:
$ref: '#/definitions/AccountEventRelationships'
type:
description: Name of the resource type
example: account_events
pattern: ^[A-Za-z]*$
type: string
version:
minimum: 0
type: integer
required:
- type
- id
- version
- organisation_id
- attributes
type: object
x-access:
- Public
AccountEventAttributes:
properties:
account_id:
description: ID of the account this event relates to
example: cfc09fb8-bbca-40bd-a518-6e58d8a9c7f4
format: uuid
type: string
date_time:
format: date-time
type: string
description:
description: Contains the event description
enum:
- pending
- failed
- confirmed
example: confirmed
type: string
reason:
description: Failure reason. Should only be present when description is failed
example: Invalid BIC
type: string
routing_status:
description: Contains the routing status
enum:
- unroutable
- routable
- deleted
example: routable
type: string
status:
description: Contains the event status
enum:
- pending
- failed
- confirmed
example: confirmed
type: string
required:
- status
- routing_status
- date_time
- account_id
type: object
x-access:
- Public
AccountEventDetailsResponse:
properties:
data:
$ref: '#/definitions/AccountEvent'
links:
$ref: '#/definitions/Links'
type: object
x-access:
- Public
AccountEventListResponse:
properties:
data:
items:
$ref: '#/definitions/AccountEvent'
type: array
links:
$ref: '#/definitions/Links'
type: object
x-access:
- Public
AccountEventRelationships:
properties:
account:
$ref: '#/definitions/RelationshipAccount'
description: Account this event relates to
type: object
x-access:
- Public
AccountHoldingEntity:
description: Information about the financial institution servicing the account.
properties:
bank_address:
description: Financial institution address
example:
- Liverpool Customer Service Centre
- Stevenson Way
- Wavertree
- L13 1NW
items:
type: string
type: array
x-omitempty: true
bank_id:
pattern: ^[A-Z0-9]{0,16}$
type: string
bank_id_code:
$ref: '#/definitions/BankIdCode'
enum:
- GBDSC
example: GBDSC
type: string
x-length: 5
bank_ids:
description: Array for additional ID(s) for agent
items:
$ref: '#/definitions/AccountWithBankId'
type: array
x-availability:
get:
sepa: sometimes
post:
sepa: optional
x-description:
sepa: Array for additional ID(s) for agent
x-omitempty: true
bank_name:
description: Financial institution name
example: NATIONAL WESTMINSTER BANK PLC
type: string
bank_party_id:
description: Identifier of the financial institution which services the account
example: //AT12345
type: string
required:
- bank_id
- bank_id_code
type: object
x-access:
- Public
AccountIdentification:
properties:
attributes:
$ref: '#/definitions/AccountIdentificationAttributes'
created_on:
format: date-time
type: string
x-nullable: true
id:
description: Unique resource ID
example: 7826c3cb-d6fd-41d0-b187-dc23ba928772
format: uuid
type: string
modified_on:
format: date-time
type: string
x-nullable: true
organisation_id:
description: Unique ID of the organisation this resource is created by
example: ee2fb143-6dfe-4787-b183-ca8ddd4164d2
format: uuid
type: string
type:
description: Type of this resource, always account_identifications
example: account_identifications
format: ^account_identifications$
type: string
version:
description: Version number
example: 0
minimum: 0
type: integer
required:
- id
- attributes
- organisation_id
type: object
x-access:
- Public
AccountIdentificationAttributes:
properties:
secondary_identification:
description: Used to validate where expecting an exact match against payment's
reference information.
maxLength: 35
minLength: 1
type: string
required:
- secondary_identification
type: object
x-access:
- Public
AccountIdentificationData:
allOf:
- $ref: '#/definitions/AccountIdentification'
- properties:
relationships:
$ref: '#/definitions/AccountIdentificationRelationships'
type: object
x-access:
- Public
AccountIdentificationEventData:
allOf:
- $ref: '#/definitions/AccountIdentification'
- properties:
relationships:
$ref: '#/definitions/AccountIdentificationEventRelationships'
type: object
x-access:
- Public
AccountIdentificationEventRelationships:
properties:
account:
$ref: '#/definitions/RelationshipAccount'
x-access:
- Public
AccountIdentificationEventResponse:
properties:
data:
$ref: '#/definitions/AccountIdentificationEventData'
type: object
x-access:
- Public
AccountIdentificationListResponse:
properties:
data:
items:
$ref: '#/definitions/AccountIdentification'
type: array
links:
$ref: '#/definitions/Links'
type: object
x-access:
- Public
AccountIdentificationRelationships:
properties:
account:
$ref: '#/definitions/RelationshipLinks'
x-access:
- Public
AccountIdentificationRequest:
properties:
data:
$ref: '#/definitions/AccountIdentification'
required:
- data
type: object
x-access:
- Public
AccountIdentificationResponse:
properties:
data:
$ref: '#/definitions/AccountIdentificationData'
type: object
x-access:
- Public
AccountNumber:
properties:
id:
type: string
relationships:
properties:
sort_code:
$ref: '#/definitions/SortCode'
type: object
type:
pattern: ^[A-Za-z_]*$
type: string
type: object
x-access:
- Public
AccountNumberCode:
description: The type of identification given at `account_number` attribute
enum:
- BBAN
- IBAN
example: IBAN
maxLength: 4
type: string
x-access:
- Public
AccountNumberDetailsResponse:
properties:
data:
$ref: '#/definitions/AccountNumber'
links:
$ref: '#/definitions/Links'
type: object
x-access:
- Public
AccountRelationships:
properties:
account_events:
$ref: '#/definitions/RelationshipLinks'
description: Events related to the lifecycle of this account
master_account:
$ref: '#/definitions/RelationshipLinks'
description: ID of the master account related to this account
type: object
x-access:
- Public
AccountUpdate:
properties:
attributes:
properties:
acceptance_qualifier:
$ref: '#/definitions/AcceptanceQualifier'
account_classification:
description: Is the account business or personal?
enum:
- Personal
- Business
type: string
account_matching_opt_out:
description: '- deprecated - Is the account opted out of account matching,
e.g. CoP?'
type: boolean
x-nullable: true
account_number:
description: Account number of the account. A unique number will automatically
be generated if not provided.
example: '41426819'
pattern: ^[A-Z0-9]{0,64}$
type: string
alternative_bank_account_names:
description: '- deprecated - Alternative account names. Used for Confirmation
of Payee matching.'
items:
maxLength: 140
minLength: 1
type: string
maxItems: 3
type: array
x-nullable: true
alternative_names:
description: Alternative names. Used for Confirmation of Payee matching.
items:
maxLength: 140
minLength: 1
type: string
maxItems: 3
type: array
x-nullable: true
bank_account_name:
description: '- deprecated - Primary account name. Used for Confirmation
of Payee matching. Required if confirmation_of_payee_enabled is true
for the organisation.'
maxLength: 140
minLength: 1
type: string
bank_id:
description: Local country bank identifier. In the UK this is the sort
code.
example: '400300'
pattern: ^[A-Z0-9]{0,16}$
type: string
bank_id_code:
description: ISO 20022 code used to identify the type of bank ID being
used
example: GBDSC
pattern: ^[A-Z]{0,16}$
type: string
base_currency:
description: ISO 4217 code used to identify the base currency of the account
example: GBP
pattern: ^[A-Z]{3}$
type: string
bic:
description: SWIFT BIC in either 8 or 11 character format
example: NWBKGB22
pattern: ^([A-Z]{6}[A-Z0-9]{2}|[A-Z]{6}[A-Z0-9]{5})$
type: string
country:
description: ISO 3166-1 code used to identify the domicile of the account
example: GB
pattern: ^[A-Z]{2}$
type: string
customer_id:
description: A free-format reference that can be used to link this account
to an external system
example: '12345'
pattern: ^[a-zA-Z0-9-$@., ]{0,256}$
type: string
first_name:
description: '- deprecated - Customer first name.'
maxLength: 40
minLength: 1
type: string
iban:
description: IBAN of the account. Will be calculated from other fields
if not supplied.
example: GB11NWBK40030041426819
pattern: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{0,64}$
type: string
joint_account:
description: Is the account joint?
type: boolean
x-nullable: true
name:
description: Account holder names (for example title, first name, last
name). Used for Confirmation of Payee matching.
items:
maxLength: 256
minLength: 1
type: string
maxItems: 4
type: array
x-nullable: true
name_matching_status:
description: Describes the status of the account for name matching via
CoP. The value determines the code with which Form3 responds to matched
CoP requests to this account.
enum:
- supported
- switched
- opted_out
- not_supported
type: string
organisation_identification:
$ref: '#/definitions/AccountAttributesOrganisationIdentification'
private_identification:
$ref: '#/definitions/AccountAttributesPrivateIdentification'
processing_service:
description: '- deprecated - Accounting system or service. It will be
added to each payment received to an account.'
maxLength: 35
type: string
x-nullable: true
reference_mask:
description: When set will apply a validation mask on the payment reference
to each payment received to an account.
example: 4929############
maxLength: 35
type: string
x-nullable: true
secondary_identification:
description: Secondary identification, e.g. building society roll number.
Used for Confirmation of Payee.
maxLength: 140
minLength: 1
type: string
status:
description: Current status of the account
enum:
- pending
- failed
- confirmed
- closed
type: string
status_reason:
$ref: '#/definitions/StatusReason'
switched:
description: '- deprecated - Indicates whether the account has been switched
using the Current Account Switch Service.'
type: boolean
x-nullable: true
switched_account_details:
$ref: '#/definitions/SwitchedAccountDetails'
title:
description: '- deprecated - Customer title.'
example: Ms
maxLength: 40
minLength: 1
type: string
type:
description: Account type
maxLength: 35
type: string
x-nullable: true
user_defined_data:
description: All purpose list of key-value pairs to store specific data
for the associated account. It will be added to each payment received
to an account.
items:
$ref: '#/definitions/UserDefinedData'
maxItems: 5
type: array
x-omitempty: true
user_defined_information:
description: '- deprecated - All purpose field to store specific data
for the associated account. It will be added to each payment received
to an account.'
maxLength: 35
type: string
x-nullable: true
validation_type:
$ref: '#/definitions/ValidationType'
type: object
x-access:
- Public
id:
description: Unique resource ID
example: 7826c3cb-d6fd-41d0-b187-dc23ba928772
format: uuid
type: string
organisation_id:
description: Unique ID of the organisation this resource is created by
example: ee2fb143-6dfe-4787-b183-ca8ddd4164d2
format: uuid
type: string
relationships:
$ref: '#/definitions/AccountRelationships'
type:
description: Name of the resource type
example: accounts
pattern: ^[A-Za-z_]*$
type: string
version:
description: Version number
example: 0
minimum: 0
type: integer
required:
- id
- organisation_id
- version
- attributes
type: object
x-access:
- Public
AccountValidationOutcome:
description: Outcome of the validation of the beneficiary's account number, which
is sometimes performed on a customer's behalf
enum:
- passed
- failed
- failed_auto_reject_disabled
- failed_auto_reject_enabled
type: string
x-access:
- Public
AccountWithBankId:
properties:
bank_id:
description: Other ID of agent
example: H7FNTJ4851HG0EXQ1Z70
maxLength: 30
type: string
x-availability:
get:
sepa: sometimes
post:
sepa: optional
x-description:
sepa: Other ID of agent
x-length: 11
x-omitempty: true
bank_id_code:
description: Code for the type of other ID for agent
example: LEI
maxLength: 5
type: string
x-availability:
get:
sepa: sometimes
post:
sepa: optional
x-description:
sepa: Code for the type of other ID for agent
x-length: 5
x-omitempty: true
type: object
x-access:
- Public
Ace:
properties:
attributes:
properties:
action:
description: Action that this ACE controls
example: CREATE
type: string
filter:
type: string
record_type:
description: Type of record that this ACE gives access to
example: User
type: string
role_id:
description: Role ID of the role that this ACE belongs to
example: 813e371b-c16c-4b86-adbf-82bcda159b27
format: uuid
type: string
type: object
id:
description: Unique resource ID
example: 7826c3cb-d6fd-41d0-b187-dc23ba928772
format: uuid
type: string
organisation_id:
description: Unique ID of the organisation this resource is created by
example: ee2fb143-6dfe-4787-b183-ca8ddd4164d2
format: uuid
type: string
type:
description: Name of the resource type
example: ace
pattern: ^[A-Za-z]*$
type: string
version:
description: Version number
example: 0
minimum: 0
type: integer
required:
- id
- organisation_id
- attributes
type: object
x-access:
- Public
AceCreation:
properties:
data:
$ref: '#/definitions/Ace'
required:
- data
type: object
x-access:
- Public
AceCreationResponse:
properties:
data:
$ref: '#/definitions/Ace'
links:
$ref: '#/definitions/Links'
required:
- data
type: object
x-access:
- Public
AceDetailsListResponse:
properties:
data:
items:
$ref: '#/definitions/Ace'
type: array
links:
$ref: '#/definitions/Links'
required:
- data
type: object
x-access:
- Public
AceDetailsResponse:
properties:
data:
$ref: '#/definitions/Ace'
links:
$ref: '#/definitions/Links'
required:
- data
type: object
x-access:
- Public
AdviceCreation:
properties:
data:
$ref: '#/definitions/PaymentAdvice'
type: object
x-access:
- Public
AdviceCreationResponse:
properties:
data:
$ref: '#/definitions/PaymentAdvice'
links:
$ref: '#/definitions/Links'
type: object
x-access:
- Public
AdviceDetailsResponse:
properties:
data:
$ref: '#/definitions/PaymentAdvice'
links:
$ref: '#/definitions/Links'
type: object
x-access:
- Public
AdviceSubmission:
properties:
attributes:
$ref: '#/definitions/AdviceSubmissionAttributes'
created_on:
format: date-time
type: string
x-nullable: true
id:
format: uuid
type: string
modified_on:
format: date-time
type: string
x-nullable: true
organisation_id:
format: uuid
type: string
relationships:
$ref: '#/definitions/AdviceSubmissionRelationships'
type:
pattern: ^[A-Za-z_]*$
type: string
version:
minimum: 0
type: integer
required:
- id
- organisation_id
type: object
x-access:
- Public
AdviceSubmissionAttributes:
properties:
status:
$ref: '#/definitions/AdviceSubmissionStatus'
status_reason:
type: string
submission_datetime:
format: date-time
readOnly: true
type: string
transaction_start_datetime:
format: date-time
readOnly: true
type: string
type: object
x-access:
- Public
AdviceSubmissionCreation:
properties:
data:
$ref: '#/definitions/NewAdviceSubmission'
type: object
x-access:
- Public
AdviceSubmissionCreationResponse:
properties:
data:
$ref: '#/definitions/AdviceSubmission'
links:
$ref: '#/definitions/Links'
type: object
x-access:
- Public
AdviceSubmissionDetailsResponse:
properties:
data:
$ref: '#/definitions/AdviceSubmission'
links:
$ref: '#/definitions/Links'
type: object
x-access:
- Public
AdviceSubmissionFetch:
properties:
attributes:
$ref: '#/definitions/AdviceSubmissionAttributes'
created_on:
format: date-time
type: string
x-nullable: true
id:
format: uuid
type: string
modified_on:
format: d
# --- truncated at 32 KB (737 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/form3/refs/heads/main/openapi/form3-payments.yml