Verification of a creditor/beneficiary account.

POST/accounts/verification

Authorization

oauthBearerToken

AuthorizationBearer <token>

The access token obtained as a result of OAuth 2.0 flows. SWIFT supports the below OAuth grant type for the two environments where the API is exposed.

MV-SIPN - jwt-bearer grant type RFC 7523 with Signed JWT assertion
Internet - jwt-bearer grant type RFC 7523 with Signed JWT assertion

This API uses JWT-Bearer grant type.

Please visit SWIFT OAuth Token API page for more information and examples on how to generate an OAuth token.

In this declaration only the basic security element to transport the bearer token of an OAuth2 process is declared.

In: header

The header is a unique identifier used to track an API request throughout its entire lifecycle. It serves as a "trace" for a given request/response cycle, allowing each system component that handles the request to associate logs, metrics, and actions with the same ID, facilitating debugging, monitoring, and tracing across distributed systems. The id is an uuid as described in IETF RFC 4122 Universally Unique Identifier (UUID) URN Namespace.Pattern - ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$.

Usage -

When a consumer makes an API request, the client or API gateway generates a unique trace ID and includes it in the X-Request-ID header.
If the request does not include a trace ID (e.g., from consumer), a new trace ID should be created by the API Gateway and returned to the client in the response header for future tracking.

Formatuuid

Request Body

application/json

party?

Details of the party that will be verified.

party_account*

Identification of the account of the party to be verified.

party_agent*

Identification of the verification responder or Identification of the responding service responder.

Usage: Party Agent can be the account servicing agent of the account owner, or a payments service provider offering the validation of party service.

Whenever clearing member identification is used as per the above guidelines, the clearing system identifiers are published as external codes on www.iso20022.org . Since December 2024, this code list also foresees the use of the country code as clearing system identifiers for countries without explicitly listed clearing systems.

requestor*

Unique and unambiguous way to identify an organisation.

unstructured_remittance_information?array<>

Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle, such as commercial invoices in an accounts receivable system, in an unstructured form.

Usage: Can be used to identify sub-accounts of Party Account.

Itemsitems <= 8

context*string

Context of the party verification process.

Context of a party verification service, in a codified form.

Code Name Definition: *CRDT - CreditTransfer - Verification is in scope of a credit transfer process. *DDEB - DirectDebit - Verification is in scope of a direct debit process. *OTHR - Other - Verification is in scope of a different process than those covered by the other codes. *REGI - Registration - Verification is in scope of a party account registration or maintenance process.

Value in"CRDT" | "DDEB" | "OTHR" | "REGI"

uetr?string

Universally unique identifier to provide an end-to-end reference of a payment transaction.

Usage: A service provider could use the UETR to link a verification of party to a payment transaction.

Based on datatype UUIDv4Identifier: Universally Unique IDentifier (UUID) version 4, as described in IETC RFC 4122 "Universally Unique IDentifier (UUID) URN Namespace".

Match^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$

proprietary_service_parameters*

Proprietary configuration parameters used by the service provider.

Usage for SWIFT BAV service V3: Code: SCHM, for VerificationScheme Qualifier: PVAH, PVHI, PVAG

'PVAH'-Scheme is Swift Payment Pre-validation. Validation source must be data provider or aggregator for data providers first and Central BAV only that uses statistics of past transactions second. 'PVHI'-Scheme is Swift Payment Pre-validation. Validation source must be Central BAV only that uses statistics of past transactions. 'PVAG'-Scheme is Swift Payment Pre-validation. Validation source must be data provider or aggregator for data providers only.

Response Body

`application/json`

PartyAccount matches and the matching was done by the party agent holding the account.

{
  "account_match": "MTCH",
  "verification_source": "HOLD"
}

{
  "severity": "Fatal",
  "code": "SwAP501",
  "text": "API request is malformed."
}

{
  "severity": "Fatal",
  "code": "SwAP502",
  "text": "Invalid OAuth access token."
}

{
  "severity": "Fatal",
  "code": "SwAP503",
  "text": "OAuth access token has insufficient scope for the requested service."
}

{
  "severity": "Fatal",
  "code": "SwAP506",
  "text": "Resource does not exist."
}

{
  "severity": "Transient",
  "code": "SwAP507",
  "text": "Request cannot be processed at this time. Please try again."
}

{
  "severity": "Transient",
  "code": "SwAP590",
  "text": "Service is temporarily unavailable."
}

{
  "severity": "Transient",
  "code": "SwAP591",
  "text": "Service Provider time out."
}

{
  "severity": "Fatal",
  "code": "Sw.payVal.defaultError",
  "text": "Service is temporarily unavailable."
}

Payments Scheme

Verification of a creditor/beneficiary account.

Authorization

Header Parameters

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Verification of a creditor/beneficiary account.

Authorization

Header Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

503application/json

504application/json

defaultapplication/json

3.1.2.1-PartyAccount_matches

3.1.2.2-PartyName_matches

3.1.2.3-PartyId_matches

3.1.2.4-AccountCurrency_matches

3.1.2.5-PartyAddress_matches

3.1.2.6-All_matching_results_provided

3.1.2.7-Some_matching_results_provided

3.1.2.8-PartyAccount_does_not_match

3.1.2.9-PartyAccount_matches_Subaccount_does_not_match

3.1.2.10-PartyAccount_matches_no_other_matching_done_Snapshot

3.1.2.11-PartyAccount_matches_likely_to_receive_funds

3.1.2.12-PartyAccount_matches_not_likely_to_receive_funds

3.1.2.13-PartyAccount_was_not_found

3.1.2.14-PartyAccount_was_not_found_out_of_scope

3.1.2.15-PartyAccount_matches_more_likely_to_receive_funds_mixed_transactions

3.1.2.16-PartyAccount_matches_more_likely_to_not_receive_funds_mixed_transactions

Bad Request

Bad Request, Parameters Missing Or Not Supported

Invalid Token

Inconsistent Client

Service Unavailable

Data Provider Unavailable

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`