Bulk credit transfers with VoP

Manage VoP requirements for bulk transfers in your account settings to fit your business needs.

Requirements

Bulk credit transfers require custom verification using the verifyBeneficiary mutation. The default verification flow doesn't support bulk payments.

VoP requirements for bulk transfers

Under the European Instant Payments Regulation (IPR), payers that are not consumers and submit multiple payment orders can opt out from verification services during their contractual relationship with their PSP.

This regulatory framework allows Swan to offer different default VoP requirements based on account type:

Field Requirements Legend

● REQ Required:Must be completed.

◐ CND Conditional:Required only in specific situations.

○ OPT Optional:Isn't required; may have a default value.

Account type	Default token requirement	Can change setting	Consent requirements
Company	○ OPT	✓	Opted in: No consent required. Opted out: User consent required via SCA.
Individual	● REQ	✗	Cannot change settings

Why these defaults?

• Swan opts out company accounts by default to accelerate bulk file processing and reduce friction in high-volume business flows.
• Individual accounts remain opted in for enhanced consumer protection, and this setting cannot be changed.
• When multiple company accounts exist for the same account holder, all accounts are opted out by default regardless of any previous account settings.

Account-level verification settings

Company account holders can control VoP requirements for bulk transfers:

• VoP optional (opted out): Bulk transfers can proceed with or without verification tokens.
• VoP required (opted in): All bulk transfers must include verification tokens from verifyBeneficiary.

Individual accounts always require VoP and cannot modify this setting.

Before implementing VoP

To enable mandatory VoP for company accounts, you must first implement the verifyBeneficiary mutation.

Communicate to companies: Until implementation is complete, bulk transfers are limited to accounts that remain opted out of mandatory VoP.

Changing VoP settings

Use the updateAccountSettings mutation to modify company account settings.

Requirements

• Company account holder only.
• User must have both canViewAccount and canInitiatePayments permissions.
• Account membership must be Enabled.

Consent flow

• Opting in (require VoP): No consent needed.
• Opting out (make VoP optional): User consent required through SCA.

Integration requirement

You must implement the updateAccountSettings mutation to allow company account holders to change their bulk transfer VoP requirements. Without this implementation, users cannot opt in or out of mandatory VoP and must use our support request form instead, creating friction and delays.

Updating account settings

Use the updateAccountSettings mutation to allow company account holders to modify their bulk transfer VoP requirements.

Open in API Explorer

mutation UpdateAccountSettings {
  updateAccountSettings(
    input: {
      accountId: "$YOUR_ACCOUNT_ID"
      allowBulkCreditTransfersWithoutBeneficiaryVerification: false
      consentRedirectUrl: "https://mycompany.com/consent"
    }
  ) {
    ... on UpdateAccountSettingsSuccess {
      account {
        settings {
          allowBulkCreditTransfersWithoutBeneficiaryVerification
        }
      }
    }
    ... on UpdateAccountSettingsConsentPending {
      __typename
      consent {
        consentUrl
      }
    }
    ... on AccountNotFoundRejection {
      message
    }
    ... on ForbiddenRejection {
      message
    }
    ... on AccountHolderNotFoundRejection {
      message
    }
  }
}

Parameters

• accountId: The company account ID to update.
• allowBulkCreditTransfersWithoutBeneficiaryVerification:
  • true = VoP optional for bulk transfers (opt out).
  • false = VoP required for bulk transfers (opt in).
• consentRedirectUrl: Required for the consent flow when opting out.

Success response

For opt-in requests (no consent required).

Payload

{
  "data": {
    "updateAccountSettings": {
      "__typename": "UpdateAccountSettingsSuccess",
      "account": {
        "settings": {
          "allowBulkCreditTransfersWithoutBeneficiaryVerification": false
        }
      }
    }
  }
}

For opt-out requests (consent required).

Payload

{
  "data": {
    "updateAccountSettings": {
      "__typename": "UpdateAccountSettingsConsentPending",
      "consent": {
        "consentUrl": "https://identity.swan.io/consent?consentId=$YOUR_CONSENT_ID&env=Sandbox"
      }
    }
  }
}

Error handling

The mutation can return several rejection types.

Rejection	Description
AccountNotFoundRejection	The provided account ID doesn't exist.
AccountHolderNotFoundRejection	The account holder doesn't exist.
AccountHolderTypeNotEligibleRejection	Only company account holders can modify this setting
AccountMembershipNotEligibleRejection	User lacks required permissions (canViewAccount + canInitiatePayments)
AccountMembershipStatusNotEligibleRejection	User's account membership must be Enabled.
ForbiddenRejection	User not allowed or wrong context used

Webhook notifications

Subscribe to the AccountSetting.Updated webhook to receive notifications when the allowBulkCreditTransfersWithoutBeneficiaryVerification setting changes.

Setting changes can be triggered by:

• The user through the updateAccountSettings mutation.
• A Swan agent following a user support request.

This webhook helps you track account setting changes and maintain an audit trail for dispute protection.

Sandbox testing

VoP requirements in sandbox match the live environment behavior. Company accounts default to optional VoP but can modify settings via the account settings mutation, while individual accounts always require VoP tokens for bulk transfers.

Preparing for disputes

Swan logs all VoP setting changes and verification history for dispute protection. These logs aren't currently available through the API, so we recommend you record these changes in your own systems. This audit trail helps determine liability if an end-user disputes a payment to the wrong beneficiary.