Global Payee Verification (GPV) API (UK, AU only at this time)

Integration overview

Global Payee Verification is a synchronous REST API that validates whether the supplied payee name aligns with the supplied account identifier before funds movement. Customers can call it independently of MassPay order creation and use the returned outcome to decide whether to proceed, prompt a user, correct payee master data, or stop for review.

Base endpoint

POST /banks/{{CustomerId}}/globalvalidate

The final hostname and environment-specific paths are provided during onboarding. Typical environments are Sandbox/UAT for testing and Production for live customer traffic.

Authentication and headers

Header	Required	Description
Authorization	Yes	Bearer OAuth access token issued for the customer integration.
Content-Type	Yes	application/json
Idempotency-Key	Yes	Unique key per logical verification request. Reuse the same key only when retrying the same request.
X-Correlation-Id	Recommended	Customer-generated trace ID used for support, audit, and end-to-end troubleshooting.

Request payload

{
  "beneficiaryDetails": [
    {
      "countryCode": "GB",
      "creditorName": "SHERLOCK HOLMES",
      "iban": "GB00BARC12345612345678",
      "creditorBic": "ADCBAEAA",
      "localAccountNumber": "12345678",
      "sortCode": "987662",
      "accountHolderType": "Business",
      "postalAddress": {
        "addressType": "string",
        "streetName": "1 London Bridge",
        "buildingName": "Shard",
        "postCode": "SE1 9SG",
        "townName": "London",
        "country": "GB"
      }
    }
  ]
}

Required and optional fields

Field	Type	Required	Notes
beneficiaryDetails	array	Required	Array of beneficiaries to validate
beneficiaryDetails.countryCode	string	Required	ISO 2-letter country code
beneficiaryDetails.creditorName	string	Required	Beneficiary name
beneficiaryDetails.iban	string	Conditional	Required when localAccountNumber+sortCode not provided
beneficiaryDetails.creditorBic	string	Conditional	Optional for IPID (UK/AU), Required for SWIFT (other countries)
beneficiaryDetails.localAccountNumber	string	Conditional	Required with sortCode when iban not provided (UK/AU CoP)
beneficiaryDetails.sortCode	string	Conditional	Required with localAccountNumber when iban not provided (UK/AU CoP)
beneficiaryDetails.accountHolderType	string	Conditional	"Business" or "Personal" — Required only for COP (countryCode GB or AU). Not required for other countries.
beneficiaryDetails.postalAddress	object	Optional	Used for SWIFT Global Validate only
beneficiaryDetails.postalAddress.addressType	string	Optional	Address type
beneficiaryDetails.postalAddress.streetName	string	Optional	Street name
beneficiaryDetails.postalAddress.buildingName	string	Optional	Building name
beneficiaryDetails.postalAddress.postCode	string	Optional	Postal code
beneficiaryDetails.postalAddress.townName	string	Optional	Town/city name
beneficiaryDetails.postalAddress.country	string	Optional	ISO 2-letter country code

Supported identifier patterns

IBAN: Use for IBAN markets where available.

Local account and routing: Use for domestic account number plus sort code, routing number, branch code, or equivalent local routing identifier.

BIC and account: Use where account verification is supported via bank/network lookup.

Proxy identifiers: Use phone, email, national ID, or scheme-specific aliases only where the relevant corridor and provider support them.

Successful response example

{
    "beneficiaryDetails": [
        {
            "responseCode": "2000",
            "responseMessage": "ValidationSucceeded",
            "validationStatus": "MTCH",
            "validationResult": {
                "validatorName": "IPID",
                "validationData": {
                    "matchScore": 1.0,
                    "matchScoreDescription": "Strong Match",
                    "reasonCode": "MATC"
                }
            },
            "accountDetails": {
                "accountNumber": "12345678",
                "name": "FIRST NAME LAST NAME",
                "referenceId": "9ec4abeb-006e-49b5-b4dd-80ac471dc141"
            }
        }
    ]
}

Outcome handling guidance

Status	Meaning	Recommended Customer Action
MATCH	The supplied payee name aligns with the account record.	Proceed according to the customer's payment policy and store the verficationId for audit.
CLOSE_MATCH	The name is similar but not exact; a suggested Name may be returned.	Prompt the user to confirm, update the payee record if policy allows, or route to operational review.
NO_MATCH	The supplied name materially differs from the account record.	Stop or hold the payment/payee update, warn the user, and re-check details with the beneficiary.
UNAVAILABLE	Verification could not be completed for the corridor, identifier, provider, or current service state.	Apply the customer’s fallback policy. Do not treat Unavailable as a Match.

Error handling

HTTP status	Scenario	Customer action
200	Request accepted and a business outcome is returned.	Use the status field to make the workflow decision.
400	Invalid or incomplete request payload.	Correct the request. Do not retry unchanged.
401 / 403	Missing, expired, or insufficient credentials/scopes.	Refresh credentials or request the required access.
408 / 504	Timeout at the gateway or upstream provider.	Retry with the same Idempotency-Key or apply fallback policy.
429	Rate limit exceeded.	Back off and retry after the advised interval.
5xx	Temporary service or upstream failure.	Retry with exponential backoff and the same Idempotency-Key.

Idempotency, retries, and caching

Generate a unique Idempotency-Key for each logical verification request.

When retrying after a timeout or transient failure, resend the same payload with the same Idempotency-Key.

Do not reuse an idempotency key for a different payee, account, or changed payee name.

Where expiresAt is returned, customers may reuse the result only within their internal policy and the validity period shown.

Security, privacy, and audit requirements

Send only the minimum payee and account data required for verification.

Use TLS for all API calls and keep OAuth client credentials in a secure secrets store.

Do not log raw account identifiers, access tokens, or unnecessary personal data in customer application logs.

Store verificationId, referenceId, status, reasonCodes, source, timestamp, and correlation ID for audit and support.

Apply role-based access controls to any UI that displays verification results or suggested payee names.

Recommended customer implementation flow

Capture or retrieve payee name, country, and account identifiers from the customer system.

Validate local formatting before calling the API, for example required fields and account/routing length.

Call POST /masspay/v1/payees/verification with OAuth token, Idempotency-Key, referenceId, and X-Correlation-Id.

Evaluate the returned status and reasonCodes against the customer’s risk policy.

For MATCH, allow the payee or payment workflow to continue.

For CLOSE_MATCH, prompt for confirmation or update to suggestedName where authorised.

For NO_MATCH, stop or hold the workflow until the details are corrected and re-verified.

For UNAVAILABLE, apply the agreed fallback process and avoid presenting it as successful verification.

Persist verification evidence for later payment/order reference, support, and audit.