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.
   • If you'd rather cancel the transfer if instant isn't available, choose InstantWithoutFallback instead.
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).

Schedule transfers

You can use the requestedExecutionAt parameter to schedule a transfer up to one year in advance. These upcoming transfers can be canceled before execution using the cancelTransaction mutation.

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: "IE27BOFI900017242521"
          name: "Dillon Byrne"
          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 a credit transfer from one Swan account to another within the same Swan project.

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, including their name and Swan accountNumber (note it's the account number, not the account ID) (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
            }
          }
        }
      }
    }
  }
}

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.