Initiate a credit transfer

Send SEPA Credit Transfers, Instant SEPA Credit Transfers, and Swan Internal Credit Transfers with the API. Review sample mutations for all three, as well as a payload.

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.

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 5), and information such as your redirect URL and your transfer amount.
3. For this use case, add information about your sepaBeneficiary, including their name and IBAN (lines 9-10).
4. For mode, choose Regular to send a basic SEPA Credit Transfer.
5. Add the InitiateCreditTransfersSuccessPayload payload.
6. Add the consent URL to the success payload (line 27): statusInfo > PaymentConsentPending > consent > consentUrl.
7. Add rejections (not shown).

🔎 Open the mutation in API Explorer

mutation SepaDefault {
  initiateCreditTransfers(
    input: {
      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
            }
          }
        }
      }
    }
  }
}

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 5), and information such as your redirect URL and your transfer amount.
3. For this use case, add information about your sepaBeneficiary, including their name and IBAN (lines 9-10).
4. 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.
5. Add the InitiateCreditTransfersSuccessPayload payload.
6. Add the consent URL to the success payload (line 27): statusInfo > PaymentConsentPending > consent > consentUrl.
7. Add rejections (not shown).

🔎 Open the mutation in API Explorer

mutation SepaInstant {
  initiateCreditTransfers(
    input: {
      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 5), and information such as your redirect URL and your transfer amount.
3. 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 9-10).
4. Add the InitiateCreditTransfersSuccessPayload payload.
5. Add the consent URL to the success payload (line 27): statusInfo > PaymentConsentPending > consent > consentUrl.
6. Add rejections (not shown).

🔎 Open the mutation in API Explorer

mutation SwanInternal {
  initiateCreditTransfers(
    input: {
      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

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 5), and information such as your redirect URL.
3. 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 8-15, 18-25, and 28-34) model different configurations.
4. Add the InitiateCreditTransfersSuccessPayload payload.
5. Add the consent URL to the success payload (line 48): statusInfo > PaymentConsentPending > consent > consentUrl.
6. Add rejections (not shown).

🔎 Open the mutation in API Explorer

mutation MultipleTransfers {
  initiateCreditTransfers(
    input: {
      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.

No consent

Most initiateCreditTransfers requests require consent. However, Swan can determine consent isn't required based on the context of the payment, in which case the payment is created with the status Initiated.

{
  "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.