Collect payments (merchants)

On this page, you'll prepare to collect payments. Then, you can follow the guides to work with various types of payment collection.
To use the Merchant Payment Collection feature, you need to complete a risk review first. To get started, contact your dedicated Technical Account Manager, or send an email to [email protected].
Before you can collect third-party payments using the Swan Merchant Payment Collection feature, you need to add a profile for your merchant and request at least one payment method.
Merchant profiles
Add a merchant profile
All new merchant profiles are reviewed by Swan. We might contact you for more information before accepting or rejecting the merchant profile.
1.Confirm your account meets the following prerequisites:
Payment level: Unlimited
Holder type: Company
Project access token, or, if you're an account member, a user access token with Can manage members user rights
2.Run the addMerchantProfile mutation. You don't need consent.
3.Include all mandatory information: accountId, merchantName, productType, expectedMonthlyPaymentVolume, expectedAverageBasket.
4.(Optional) Include a logo for your merchant (merchantLogo; image must be converted to a base64 encoded string).
5.The new merchant is created with the status PendingReview.
6.Swan reviews the new merchant profile and updates the status.
API mutation to add a merchant profile
1
mutation MyMutation {
2
  addMerchantProfile(
3
    input: {
4
      accountId: "$YOUR_ACCOUNT_ID"
5
      merchantName: "$YOUR_MERCHANT_NAME"
6
      productType: Goods
7
      merchantLogo: "$BASE64_STRING"
8
      expectedMonthlyPaymentVolume: {
9
        value: "$YOUR_EXPECTED_PAYMENT_VOLUME"
10
        currency: "EUR"
11
      }
12
      expectedAverageBasket: {
13
        value: "$YOUR_EXPECTED_AVERAGE_BASKET"
14
        currency: "EUR"
15
      }
16
    }
17
  ) {
18
    ... on AddMerchantProfileSuccessPayload {
19
      __typename
20
      merchantProfile {
21
        accountId
22
        id
23
        statusInfo {
24
          status
25
          ... on EnabledMerchantProfileStatusInfo {
26
            __typename
27
            enabledAt
28
            status
29
          }
30
        }
31
        productType
32
      }
33
    }
34
    ... on ForbiddenRejection {
35
      __typename
36
      message
37
    }
38
    ... on AccountNotFoundRejection {
39
      id
40
      message
41
    }
42
    ... on InternalErrorRejection {
43
      __typename
44
      message
45
    }
46
  }
47
}
48
​
Success payload
1
{
2
  "data": {
3
    "addMerchantProfile": {
4
      "__typename": "AddMerchantProfileSuccessPayload",
5
      "merchantProfile": {
6
        "accountId": "3ec375bb-887e-43e5-9ce4-b8fd0bbb2cba",
7
        "id": "cadd7d07-2fa7-4817-805c-886f38e04374",
8
        "statusInfo": {
9
          "status": "PendingReview"
10
        },
11
        "productType": "Goods"
12
      }
13
    }
14
  }
15
}
​Try it now on the API Explorer​
Request a merchant profile update
You can request an update to a merchant profile with the API, and merchants can also request their own update from your web banking interface. All updates must be reviewed by Swan.
1.To request an update with the API, run the requestMerchantProfileUpdate mutation. You don't need consent.
2.Include all mandatory information, changing only the field you wish to update.
3.(Optional) Configure the success payload to display the updated information.
4.Running the mutation produces the following events:
The merchant profile status does not change (remains Enabled), and the merchant can continue to use their merchant profile with the existing information.
The update status is PendingReview, and Swan must review the new information to ensure it meets requirements. 
After Swan reviews the request, the update status changes to Enabled and the updates are pushed live to the merchant profile.
API mutation to request a merchant profile update
1
mutation MyMutation {
2
  requestMerchantProfileUpdate(
3
    input: {
4
      merchantProfileId: "$MERCHANT_PROFILE_ID"
5
      merchantName: "$MERCHANT_NAME"
6
      productType: Services
7
      expectedMonthlyPaymentVolume: { value: "1000", currency: "EUR" }
8
      expectedAverageBasket: { value: "20", currency: "EUR" }
9
      merchantWebsite: "$WEBSITE_URL"
10
      merchantLogo: "$BASE64_STRING"
11
    }
12
  ) {
13
    ... on RequestUpdateMerchantProfileSuccessPayload {
14
      __typename
15
      requestUpdateMerchantProfile {
16
        merchantName
17
        merchantProfileId
18
        status
19
      }
20
    }
21
    ... on InternalErrorRejection {
22
      __typename
23
      message
24
    }
25
    ... on AccountNotFoundRejection {
26
      id
27
      message
28
    }
29
    ... on ForbiddenRejection {
30
      __typename
31
      message
32
    }
33
  }
34
}
35
​
Success payload
1
{
2
  "data": {
3
    "requestMerchantProfileUpdate": {
4
      "__typename": "RequestMerchantProfileUpdateSuccessPayload",
5
      "requestMerchantProfileUpdate": {
6
        "merchantName": "$MERCHANT_NAME",
7
        "merchantProfileId": "$MERCHANT_PROFILE_ID",
8
        "status": "PendingReview"
9
      }
10
    }
11
  }
12
}
Get information about a merchant profile
Use the merchantProfile query to get information about a single merchant profile. For example, you can get information about:
The merchant profile as you created it
Requested updates to the merchant profile
Base64 string for the merchant logo
Payment methods and their status
API query to get information about a merchant profile
1
query merchantProfileInfo {
2
  merchantProfile(id: "$MERCHANT_PROFILE_ID") {
3
    accountId
4
    createdAt
5
    id
6
    merchantLogoUrl
7
    merchantName
8
    productType
9
    {...}
10
    statusInfo {
11
      status
12
    }
13
  }
14
}
15
​
Query return
1
{
2
  "data": {
3
    "merchantProfile": {
4
      "accountId": "$MERCHANT_ACCOUNT_ID",
5
      "createdAt": "2023-07-17T15:01:18.586Z",
6
      "id": "$MERCHANT_PROFILE_ID",
7
      "merchantLogoUrl": "$BASE64_STRING",
8
      "merchantName": "MyBrand, Inc.",
9
      "productType": "Services",
10
      "statusInfo": {
11
        "status": "Enabled"
12
      }
13
    }
14
  }
15
}
16
​
Payment methods
Request a payment method
All new merchant payment methods are reviewed by Swan. We might contact you for more information before accepting or rejecting the payment method.
1.Confirm you have a project access token, or, if you're an account member, a user access token with Can manage members user rights.
2.Run the requestMerchantPaymentMethods mutation. You can request a payment method regardless of the status of the merchant profile.
3.The payment method is created with the status PendingReview and the version number 1.
4.Swan reviews the new merchant payment method and updates the status.
API mutation to request Internal Direct Debit Standard
1
mutation MyMutation {
2
  requestMerchantPaymentMethods(
3
    input: {
4
      merchantProfileId: "$YOUR_MERCHANT_PROFILE_ID"
5
      internalDirectDebitStandard: { activate: true }
6
    }
7
  ) {
8
    ... on RequestMerchantPaymentMethodsSuccessPayload {
9
      __typename
10
      merchantProfile {
11
        id
12
        merchantName
13
        merchantPaymentProducts {
14
          productId
15
          statusInfo {
16
            status
17
            ... on EnabledMerchantPaymentMethodsStatusInfo {
18
              __typename
19
              enabledAt
20
              status
21
            }
22
          }
23
        }
24
      }
25
    }
26
    ... on ForbiddenRejection {
27
      __typename
28
      message
29
    }
30
    ... on NotFoundRejection {
31
      id
32
      message
33
    }
34
    ... on InternalErrorRejection {
35
      __typename
36
      message
37
    }
38
  }
39
}
40
​
Success payload
1
{
2
  "data": {
3
    "requestMerchantPaymentMethods": {
4
      "__typename": "RequestMerchantPaymentMethodsSuccessPayload",
5
      "merchantProfile": {
6
        "merchantPaymentMethods": [
7
                    {
8
            "type": "InternalDirectDebitStandard",
9
            "updatedAt": "2023-06-12T15:25:08.766Z",
10
            "version": 1,
11
            "id": "e8e13312-be45-4a76-bfd6-c3e5c6e6fe13",
12
            "productId": "iddb2b_dfe125ac-da8c-4d52-bb4c-c44c3cc0e8fe",
13
            "statusInfo": {
14
              "status": "PendingReview"
15
            },
16
            "rollingReserve": null
17
          },
18
        ],
19
        "statusInfo": {
20
          "status": "Enabled"
21
        }
22
      }
23
    }
24
  }
25
}
→ Try it now on the API Explorer.
API mutation to request Internal Direct Debit B2B
1
mutation MyMutation {
2
  requestMerchantPaymentMethods(
3
    input: {
4
      merchantProfileId: "$YOUR_MERCHANT_PROFILE_ID"
5
      internalDirectDebitB2B: { activate: true }
6
    }
7
  ) {
8
    ... on RequestMerchantPaymentMethodsSuccessPayload {
9
      __typename
10
      merchantProfile {
11
        id
12
        merchantName
13
        merchantPaymentProducts {
14
          productId
15
          statusInfo {
16
            status
17
            ... on EnabledMerchantPaymentMethodsStatusInfo {
18
              __typename
19
              enabledAt
20
              status
21
            }
22
          }
23
        }
24
      }
25
    }
26
    ... on ForbiddenRejection {
27
      __typename
28
      message
29
    }
30
    ... on NotFoundRejection {
31
      id
32
      message
33
    }
34
    ... on InternalErrorRejection {
35
      __typename
36
      message
37
    }
38
  }
39
}
40
​
Success payload
1
{
2
  "data": {
3
    "requestMerchantPaymentMethods": {
4
      "__typename": "RequestMerchantPaymentMethodsSuccessPayload",
5
      "merchantProfile": {
6
        "merchantPaymentMethods": [
7
          {
8
            "type": "InternalDirectDebitB2b",
9
            "updatedAt": "2023-06-12T15:23:54.274Z",
10
            "version": 1,
11
            "id": "f0c16426-dd54-4c54-9a53-880036b54b75",
12
            "productId": "iddb2b_dfe125ac-da8c-4d52-bb4c-c44c3cc0e8fe",
13
            "statusInfo": {
14
              "status": "PendingReview"
15
            },
16
            "rollingReserve": null
17
          }
18
        ],
19
        "statusInfo": {
20
          "status": "Enabled"
21
        }
22
      }
23
    }
24
  }
25
}
API mutation to request SEPA Direct Debit Core
1
mutation RequestMerchantPaymentMethods {
2
  requestMerchantPaymentMethods(
3
    input: {
4
      merchantProfileId: "$YOUR_MERCHANT_PROFILE_ID" 
5
      sepaDirectDebitCore: {
6
          activate: true
7
          useSwanSepaCreditorIdentifier: true
8
          sepaCreditorIdentifier: "$YOUR_SCI"
9
          }
10
    }
11
  ) {
12
    ... on RequestMerchantPaymentMethodsSuccessPayload {}
Choose either line (7) useSwanSepaCreditorIdentifier: true or line (8) sepaCreditorIdentifier: "$YOUR_SCI", but not both.
Success payload
1
{
2
  "data": {
3
    "requestMerchantPaymentMethods": {
4
      "__typename": "RequestMerchantPaymentMethodsSuccessPayload",
5
      "merchantProfile": {
6
        "merchantPaymentMethods": [
7
          {
8
            "id": "a49224f6-a3b1-417c-8004-c171dab39349",
9
            "productId": "sddcore_dfe125ac-da8c-4d52-bb4c-c44c3cc0e8fe",
10
            "rollingReserve": null,
11
            "sepaCreditorIdentifier": "87468549765",
12
            "statusInfo": {
13
              "status": "PendingReview"
14
            },
15
            "type": "SepaDirectDebitCore",
16
            "updatedAt": "2023-06-12T15:20:40.714Z",
17
            "useSwanSepaCreditorIdentifier": false,
18
            "version": 1
19
          }
20
        ]
21
      }
22
    }
23
  }
24
}
API mutation to request SEPA Direct Debit B2B
1
mutation RequestMerchantPaymentMethods {
2
  requestMerchantPaymentMethods(
3
    input: {
4
      merchantProfileId: "$YOUR_MERCHANT_PROFILE_ID" 
5
      sepaDirectDebitB2b: {
6
          activate: true
7
          useSwanSepaCreditorIdentifier: true
8
          sepaCreditorIdentifier: "$YOUR_SCI"
9
          }
10
    }
11
  ) {
12
    ... on RequestMerchantPaymentMethodsSuccessPayload {}
Choose either line (7) useSwanSepaCreditorIdentifier: true or line (8) sepaCreditorIdentifier: "$YOUR_SCI", but not both.
Success payload
1
{
2
  "data": {
3
    "requestMerchantPaymentMethods": {
4
      "__typename": "RequestMerchantPaymentMethodsSuccessPayload",
5
      "merchantProfile": {
6
        "merchantPaymentMethods": [
7
          {
8
            "rollingReserve": null,
9
            "id": "f1a3c961-7d22-4125-a3fe-6ee990ac3705",
10
            "productId": "sddb2b_dfe125ac-da8c-4d52-bb4c-c44c3cc0e8fe",
11
            "sepaCreditorIdentifier": "FR23ZZZ87D106",
12
            "statusInfo": {
13
              "status": "PendingReview"
14
            },
15
            "type": "SepaDirectDebitB2b",
16
            "updatedAt": "2023-06-12T15:22:24.555Z",
17
            "useSwanSepaCreditorIdentifier": true,
18
            "version": 1
19
          }
20
        ]
21
      }
22
    }
23
  }
24
}
API mutation to request French checks
1
mutation requestMerchantPaymentMethods {
2
  requestMerchantPaymentMethods(
3
    input: {
4
      merchantProfileId: "c1f9ef09-f619-4929-b842-f2249a875a07"
5
      check:{activate:true}
6
    }
7
  )
Success payload
1
// Success payload - French checks
​
After the merchant profile and at least one payment method are activated, the merchant can initiate payment collection.
Sandbox
Update merchant profile status
In Sandbox only, you need to update the merchant profile status to Enabled.
1.Open your Swan Dashboard.
2.Go to Developers > Event Simulator.
3.Go to Merchant Acquiring.
4.Go to the tab to update the merchant profile status.
5.Change the merchant profile status to Enabled.
Update payment method status
In Sandbox only, you need to update the payment method status to Enabled.
Use the Event Simulator:
1.Open your Swan Dashboard.
2.Go to Developers > Event Simulator.
3.Go to Merchant Acquiring.
4.Go to the tab to update the merchant payment method status.
5.Change the payment method status to Enabled.
You can also use the Partner Testing API.
Simulate activating a payment method
1
mutation EnablePaymentMethod {
2
  simulateUpdateMerchantProfile(
3
    input: {
4
      merchantProfileId: "$YOUR_MERCHANT_PROFILE_ID"
5
      merchantPaymentMethod: { methodType: $METHOD_TYPE, status: Enabled }
6
    }
7
  ) {
8
    ... on SimulateUpdateMerchantProfileSuccessPayload {
9
      __typename
10
    }
11
    ... on NotFoundRejection {
12
      id
13
    }
14
    ... on MerchantProfileWrongStatusRejection {
15
      __typename
16
    }
17
  }
18
}
Line 4: Enter the corresponding merchantProfileId.
Line5: Choose the methodType you'd like to simulate activating.
For SEPA Direct Debit, you can only use the Partner Testing API to update the status for your payment methods.
Guide - Previous
Use our webhooks
Collect payments with Internal Direct Debit
Last modified 1mo ago