Verify beneficiary details

Use the verifyBeneficiary mutation to verify beneficiary details before initiating SEPA Credit Transfers.

This mutation gives you full control to customize how verification results are presented to end-users. This is required for bulk credit transfers when verification tokens are mandatory for the account.

Prerequisites

• You're planning to initiate an Instant SEPA Credit Transfer, SEPA Credit Transfer or Internal Credit Transfer.
• Authentication required with a user access token or project access token.

Detailed verification flow diagram

Step 1: Call verifyBeneficiary

Call the mutation with the beneficiary details (beneficiaryInput) you want to verify. The mutation returns a verification result and a 24-hour token for use in payment initiation.

The verifyBeneficiary mutation accepts different types of beneficiary inputs:

• SEPA beneficiary (sepa): For external SEPA Credit Transfers using IBAN and name. The maximum length for the beneficiary name must be ≤ 70 characters.
• Swan account (swanAccount): For internal transfers between Swan accounts. The maximum length for the beneficiary name must be ≤ 70 characters.
• Trusted beneficiary (trustedBeneficiaryId): For pre-verified beneficiaries saved in your account.

Open in API Explorer

mutation BeneficiaryVerificationMutation {
  verifyBeneficiary(
    input: { 
      beneficiary: { 
        sepa: { 
          iban: "IT23P0300203280632123553748", 
          name: "CloseMatch" 
        } 
      } 
    }
  ) {
    ... on VerifyBeneficiarySuccessPayload {
      __typename
      beneficiaryVerificationToken
      expiresAt
      verifyBeneficiaryResult {
        ... on VerifyBeneficiaryNotPossible {
          __typename
          status
        }
        ... on VerifyBeneficiaryNoMatch {
          __typename
          status
        }
        ... on VerifyBeneficiaryMatch {
          __typename
          status
        }
        ... on VerifyBeneficiaryCloseMatch {
          __typename
          nameSuggestion
          status
        }
        status
      }
    }
  }
}

Step 2: Handle verification results

The mutation returns one of four possible verification results. For an optimal user experience, display the results and the recommended end-user action.

Result	Description	Recommended end-user action
Match	Exact match found between the provided details and account holder information.	Safe to proceed with the transfer.
CloseMatch	Close match with suggested correction from the beneficiary's bank.	Consider the suggested name correction before proceeding.
NoMatch	No match found between the provided details and account holder information.	Verify beneficiary details carefully before proceeding.
VerificationNotPossible	Beneficiary verification failed. Check the IBAN format or try again.	Verify beneficiary details carefully before proceeding.

Returned parameters

• status: Verification result (see previous table).
• beneficiaryVerificationToken: A unique token identifying the VoP result, valid for use in subsequent credit transfer initiations.
• expiresAt: Token expiration timestamp (24 hours from generation).
• nameSuggestion: Available for CloseMatch results only.

Example response for a close match:

Payload

{
  "data": {
    "verifyBeneficiary": {
      "__typename": "VerifyBeneficiarySuccessPayload",
      "beneficiaryVerificationToken": "$YOUR_BENEFICIARY_VERIFICATION_TOKEN",
      "expiresAt": "2025-09-09T14:37:00.033Z",
      "verifyBeneficiaryResult": {
        "__typename": "VerifyBeneficiaryCloseMatch",
        "nameSuggestion": "Henri Dupont",
        "status": "CloseMatch"
      }
    }
  }
}

Step 3: Use the verification token

Include the beneficiaryVerificationToken when initiating the credit transfer instead of providing full beneficiary details.

Open in API Explorer

mutation InitiateCreditTransferWithVerificationToken {
  initiateCreditTransfers(
    input: {
      creditTransfers: {
        amount: { value: "10", currency: "EUR" }
        beneficiaryVerificationToken: "$YOUR_BENEFICIARY_VERIFICATION_TOKEN"
      }
      consentRedirectUrl: "https://www.swan.io/"
      accountId: "$YOUR_ACCOUNT_ID"
    }
  ) {
    ... on InitiateCreditTransfersSuccessPayload {
      __typename
      beneficiaryVerificationResults {
        status
        ... on VerifyBeneficiaryMatch {
          __typename
          status
        }
      }
      payment {
        statusInfo {
          ... on PaymentConsentPending {
            __typename
            consent {
              consentUrl
            }
          }
        }
      }
    }
  }
}

The InitiateCreditTransfersSuccessPayload includes the beneficiaryVerificationResults, an array of VerifyBeneficiaryResult objects. Results are ordered in the same sequence as the credit transfers in your request.

Result ordering

On the consent screen, results are reordered by risk status for a clearer display: NoMatch → NotPossible → CloseMatch → Match.

Payload

{
  "data": {
    "initiateCreditTransfers": {
      "__typename": "InitiateCreditTransfersSuccessPayload",
      "beneficiaryVerificationResults": [
        {
          "status": "CloseMatch",
          "__typename": "VerifyBeneficiaryCloseMatch",
          "nameSuggestion": "Henri Dupont"
        }
      ],
      "payment": {
        "statusInfo": {
          "__typename": "PaymentConsentPending",
          "consent": {
            "consentUrl": "https://identity.swan.io/consent?consentId=$YOUR_CONSENT_ID&env=Sandbox"
          }
        }
      }
    }
  }
}

Token usage permissions

When you initiate a credit transfer using a token, the same membership rights apply as described in Beneficiaries permissions.

Permission type	Add trusted beneficiaries using save parameter	Initiation using token from swanAccount or SEPA verification	Initiation using token from trustedBeneficiaryId verification
canManageBeneficiaries only	✓	✗	✗
canInitiatePayments only	✗	✗	✓
canInitiatePayments + canManageBeneficiaries	✓	✓	✓

Token validation

Requirements

• Tokens are validated for authenticity, status, and expiration.
• Invalid, expired, or undecryptable tokens result in a ValidationRejection.
• A token is consumed after it has been used in one initiation. Already consumed tokens result in a BeneficiaryVerificationTokenAlreadyConsumedRejection.
• Tokens expire 24 hours after generation.

tip

The same token can be used multiple times in the same initiation. This means you can initiate multiple credit transfers to the same beneficiary, within the same API call.

Saving beneficiaries during verification

When you verify a SEPA Beneficiary or a swanAccount, you can set the boolean save to true. This will indicate that if the returned token is successfully used to initiate a credit transfer, a trusted beneficiary will be created.

No trusted beneficiary is added when calling verifyBeneficiary, but your request to save it is contained within the token. The beneficiary is only saved after successful payment authorization, similar to the functionality described in Add a beneficiary.

Get a beneficiary verification result

You can retrieve the beneficiary verification result from a transaction by using the beneficiaryVerificationResult field available in transaction, transactions, standingOrder, TrustedBeneficiary, account, and accounts queries.

Example

query GetBeneficiaryVerificationResult {
  transaction(id: "$YOUR_TRANSACTION_ID") {
    ... on SEPACreditTransferTransaction {
      id
      beneficiaryVerificationResult {
        status
        ... on VerifyBeneficiaryCloseMatch {
          nameSuggestion
          status
        }
      }
    }
  }
}

Call the transaction query with the beneficiaryVerificationResult field on the SEPACreditTransferTransaction inline fragment.

For close matches, use the VerifyBeneficiaryCloseMatch inline fragment to retrieve the nameSuggestion field containing the correct name returned by the receiving bank.

Bulk credit transfers

For bulk credit transfers, verification tokens are required based on account type and account-level settings:

• Individual accounts: Verification tokens are always required.
• Company accounts: Verification tokens are optional by default, but can be made required through account settings.

Breaking change for individual accounts

If your integration supports individual account holders performing bulk credit transfers, you must implement the verifyBeneficiary mutation and provide verification tokens. Bulk transfers without tokens will be rejected for individual accounts.

Learn more about bulk credit transfers with VoP →

Verification of Payee with Server-to-server (S2S) consent

You can initiate credit transfers using the server-to-server consent feature with Verification of Payee.

Integration options

Server-to-Server consent works with both VoP integration options.

Sandbox testing

In the Sandbox environment, the verifyBeneficiary mutation returns simulated verification results based on the beneficiary name pattern.

Name is exactly	Returns result
"Match"	Match
"CloseMatch"	CloseMatch
"NoMatch"	NoMatch
"NotPossible"	VerificationNotPossible

Any other beneficiary name returns a Match result.

Examples:

• Beneficiary name "Henri Dupont" returns a Match result.
• Beneficiary name "CloseMatch" returns a CloseMatch result.

tip

If a trusted beneficiary ID is used as input, the verification will be based on the Trusted Beneficiary name.