Initiate a credit transfer

Send SEPA Credit Transfers, Instant SEPA Credit Transfers, and Swan Internal Credit Transfers with the API.

If you use Swan's Web Banking frontend, your users can send transfers from their account directly.

Prerequisites

1. You're an account member with the canInitiatePayments membership permission.
2. You're authenticating with a user access token.

VoP Integration

Swan automatically includes Verification of Payee (VoP) in all single SEPA Credit Transfers. For an optimal user experience, consider integrating the verifyBeneficiary mutation.

Send a SEPA Credit Transfer

Send a SEPA Credit Transfer to a beneficiary within the SEPA network.

1. Call the initiateCreditTransfers mutation.
2. Add all required information, marked by an (*) asterisk in API Explorer, including your Swan accountId (line 6), and information such as your redirect URL and your transfer amount.
3. Add an idempotencyKey to prevent duplicate payments (line 4).
4. For this use case, add information about your sepaBeneficiary, including their name and IBAN (lines 10-11).
5. For mode, choose Regular to send a basic SEPA Credit Transfer.
6. Add the InitiateCreditTransfersSuccessPayload payload.
7. Add the consent URL to the success payload (line 28): statusInfo > PaymentConsentPending > consent > consentUrl.
8. Add rejections (not shown).

Open in API Explorer

mutation SepaDefault {
  initiateCreditTransfers(
    input: {
      idempotencyKey: "$YOUR_IDEMPOTENCY_KEY"
      consentRedirectUrl: "$YOUR_REDIRECT_URL"
      accountId: "$YOUR_ACCOUNT_ID"
      creditTransfers: {
        amount: { value: "100", currency: "EUR" }
        sepaBeneficiary: {
          iban: "IT23P0300203280632123553748"
          name: "Francesca Verrilli"
          isMyOwnIban: false
          save: false
        }
        mode: Regular
      }
    }
  ) {
    ... on InitiateCreditTransfersSuccessPayload {
      __typename
      payment {
        createdAt
        id
        statusInfo {
          ... on PaymentConsentPending {
            __typename
            consent {
              consentUrl
            }
          }
        }
      }
    }
  }
}

Add an invoice reference

Send a SEPA Credit Transfer with an optional structured or unstructured invoice reference by using the labelType and label fields.

1. Call the initiateCreditTransfers mutation.
2. Add all required information, marked by an (*) asterisk in API Explorer, including any information such as your consent redirect URL (line 4), your Swan accountId (line 5), and your transfer amount (line 7).
3. For this use case, add information about your sepaBeneficiary, including their name and IBAN (lines 8-10).
4. Add labelType, choose an option (lines 13-14), and add the reference value in the label input.
5. Add the InitiateCreditTransfersSuccessPayload (line 18).
6. Add the consent URL to the success payload (line 22): statusInfo > PaymentConsentPending > consent > consentUrl.
7. Include error handling for all rejection types defined in the initiateCreditTransfersPayload union (lines 31-55)

Open in API Explorer

mutation initiateWithLabelType {
  initiateCreditTransfers(
    input: {
      consentRedirectUrl: "$YOUR_REDIRECT_URL"
      accountId: "$YOUR_ACCOUNT_ID"
      creditTransfers: {
        amount: { value: "100", currency: "EUR" }
        sepaBeneficiary: {
          iban: "IT23P0300203280632123553748"
          name: "Francesca Verrilli"
          save: false
        }
        labelType: OgmVcs
        label: "000000000097"
      }
    }
  ) {
    ... on InitiateCreditTransfersSuccessPayload {
      __typename
      payment {
        statusInfo {
          ... on PaymentConsentPending {
            __typename
            consent {
              consentUrl
            }
          }
        }
      }
    }
    ... on ValidationRejection {
      __typename
      fields {
        code
        message
        path
      }
      message
    }
    ... on BeneficiaryVerificationTokenAlreadyConsumedRejection {
      __typename
      message
      beneficiaryVerificationTokens
    }
    ... on InternalErrorRejection {
      __typename
      message
    }
    ... on ForbiddenRejection {
      __typename
      message
    }
    ... on AccountNotFoundRejection {
      id
      message
    }
  }
}

Send an Instant SEPA Credit Transfer

Send an Instant SEPA Credit Transfer to a beneficiary within the SEPA network.

1. Call the initiateCreditTransfers mutation.
2. Add all required information, marked by an (*) asterisk in API Explorer, including your Swan accountId (line 6), and information such as your redirect URL and your transfer amount.
3. Add an idempotencyKey to prevent duplicate payments (line 4).
4. For this use case, add information about your sepaBeneficiary, including their name and IBAN (lines 10-11).
5. For mode, choose InstantWithFallback, which begins as an instant transfer but falls back to a regular transfer if instant isn't available.
6. Add the InitiateCreditTransfersSuccessPayload payload.
7. Add the consent URL to the success payload (line 28): statusInfo > PaymentConsentPending > consent > consentUrl.
8. Add rejections (not shown).

Open in API Explorer

mutation SepaInstant {
  initiateCreditTransfers(
    input: {
      idempotencyKey: "$YOUR_IDEMPOTENCY_KEY"
      consentRedirectUrl: "$YOUR_REDIRECT_URL"
      accountId: "$YOUR_ACCOUNT_ID"
      creditTransfers: {
        amount: { value: "100", currency: "EUR" }
        sepaBeneficiary: {
          iban: "IT23P0300203280632123553748"
          name: "Francesca Verrilli"
          isMyOwnIban: false
          save: false
        }
        mode: InstantWithFallback
      }
    }
  ) {
    ... on InitiateCreditTransfersSuccessPayload {
      __typename
      payment {
        createdAt
        id
        statusInfo {
          ... on PaymentConsentPending {
            __typename
            consent {
              consentUrl
            }
          }
        }
      }
    }
  }
}

Send a Swan Internal Credit Transfer

Send an internal credit transfer within Swan's network using the beneficiary's Swan account number.

1. Call the initiateCreditTransfers mutation.
2. Add all required information, marked by an (*) asterisk in API Explorer, including your Swan accountId (line 6), and information such as your redirect URL and your transfer amount.
3. Add an idempotencyKey to prevent duplicate payments (line 4).
4. For this use case, add information about your swanAccountBeneficiary instead of a SEPA beneficiary, including their name and Swan account number (lines 10-11).
5. Add the InitiateCreditTransfersSuccessPayload payload.
6. Add the consent URL to the success payload (line 28): statusInfo > PaymentConsentPending > consent > consentUrl.
7. Add rejections (not shown).

Open in API Explorer

mutation SwanInternal {
  initiateCreditTransfers(
    input: {
      idempotencyKey: "$YOUR_IDEMPOTENCY_KEY"
      consentRedirectUrl: "$YOUR_REDIRECT_URL"
      accountId: "$YOUR_ACCOUNT_ID"
      creditTransfers: {
        amount: { value: "100", currency: "EUR" }
        swanAccountBeneficiary: {
          accountNumber: "$SWAN_ACCOUNT_NUMBER"
          name: "Henri Dupont"
          save: false
        }
      }
    }
  ) {
    ... on InitiateCreditTransfersSuccessPayload {
      __typename
      payment {
        createdAt
        id
        statusInfo {
          status
          ... on PaymentConsentPending {
            __typename
            status
            consent {
              consentUrl
            }
          }
        }
      }
    }
  }
}

Send multiple credit transfers

Bulk credit transfers with VoP

For bulk credit transfers requiring Verification of Payee (VoP), you must use verification tokens from the verifyBeneficiary mutation. Learn more about bulk credit transfers with VoP →

Send up to 2500 credit transfers in a single API call. You can send a mix of SEPA Credit Transfers, Instant SEPA Credit Transfers, and Swan Internal Credit Transfers in the same mutation.

1. Call the initiateCreditTransfers mutation.
2. Add all required information, marked by an (*) asterisk in API Explorer, including your Swan accountId (line 6), and information such as your redirect URL.
3. Add an idempotencyKey to prevent duplicate payments (line 4).
4. Add a beneficiary block for each of your beneficiaries. The beneficiary block includes:
   • amount, meaning you can send a different amount to each beneficiary (in euros).
   • sepaBeneficiary or swanAccountBeneficiary object.
   • mode (optional), meaning you can send instant and regular transfers with the same API call.
   • The example blocks (lines 9-16, 19-26, and 29-35) model different configurations.
5. Add the InitiateCreditTransfersSuccessPayload payload.
6. Add the consent URL to the success payload (line 49): statusInfo > PaymentConsentPending > consent > consentUrl.
7. Add rejections (not shown).

Open in API Explorer

mutation MultipleTransfers {
  initiateCreditTransfers(
    input: {
      idempotencyKey: "$YOUR_IDEMPOTENCY_KEY"
      consentRedirectUrl: "$YOUR_REDIRECT_URL"
      accountId: "$YOUR_ACCOUNT_ID"
      creditTransfers: [
        {
          amount: { value: "200", currency: "EUR" }
          sepaBeneficiary: {
            iban: "IT23P0300203280632123553748"
            name: "Francesca Verrilli"
            isMyOwnIban: false
            save: false
          }
          mode: InstantWithFallback
        }
        {
          amount: { value: "100", currency: "EUR" }
          sepaBeneficiary: {
            iban: "GB61BARC20035368766178"
            name: "Dillon Byrne"
            isMyOwnIban: false
            save: false
          }
          mode: Regular
        }
        {
          amount: { value: "100", currency: "EUR" }
          swanAccountBeneficiary: {
            accountNumber: "21077522761"
            name: "Henri Dupont"
            save: false
          }
          mode: Regular
        }
      ]
    }
  ) {
    ... on InitiateCreditTransfersSuccessPayload {
      __typename
      payment {
        createdAt
        id
        statusInfo {
          ... on PaymentConsentPending {
            __typename
            consent {
              consentUrl
            }
          }
        }
      }
    }
  }
}

Identify the initiating user

User identification helps you maintain effective internal controls and traceability over payment operations.

Identify which user initiated a credit transfer by querying the payment before consent is granted, or by storing user details at the time of initiation.

Query the payment before consent is granted

While a payment is in ConsentPending status, you can query the payment's statusInfo to access the consent object, which contains the userId and full user details for the user who must consent to the transfer.

Once the payment moves to Initiated or Rejected, the PaymentConsentPending fragment returns null and user information is no longer available through this method.

1. Call the payment query.
2. Add the payment ID.
3. Include statusInfo with the PaymentConsentPending fragment to access consent details.
4. Add userId and user fields to identify the initiating user (lines 9-14).

Open in API Explorer

query GetPaymentInitiator {
  payment(id: "$YOUR_PAYMENT_ID") {
    id
    createdAt
    statusInfo {
      status
      ... on PaymentConsentPending {
        consent {
          userId
          user {
            id
            firstName
            lastName
          }
        }
      }
    }
  }
}

Store user information at initiation

For reliable, long-term access to initiator information, store the user details at the time you initiate the transfer.

The initiateCreditTransfers mutation requires a user access token, which identifies the initiating user. When you call the mutation successfully, store the user ID or account membership ID alongside the paymentId returned in the response.

This approach provides immediate access to user information without additional queries, and remains available regardless of the payment's consent status.

Payload

The payload is similar for all the sample mutations on this page.

The payload shows that the credit transfer is created with the status ConsentPending (line 9), and provides the consentUrl (line 12). Send the consentUrl to your user.

If you're sending multiple transfers, your user consents to all of them with a single consentUrl.

{
  "data": {
    "initiateCreditTransfers": {
      "__typename": "InitiateCreditTransfersSuccessPayload",
      "payment": {
        "createdAt": "2024-01-25T16:16:09.859Z",
        "id": "$YOUR_PAYMENT_ID",
        "statusInfo": {
          "status": "ConsentPending",
          "__typename": "PaymentConsentPending",
          "consent": {
            "consentUrl": "https://identity.swan.io/consent?consentId=$YOUR_CONSENT_ID&env=Sandbox"
          }
        }
      }
    }
  }
}

Rejected

If your transaction is created with the status Rejected, learn why in the rejectedReasonCode field. For example, the rejection could be due to insufficient funds, or communication between Swan and the other bank timed out.