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.
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.
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
}
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.
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
}
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
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
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 number1
. - 4.
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
}
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
}
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
}
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
}
After the merchant profile and at least one payment method are activated, the merchant can initiate payment collection.
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
.
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.
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.
Last modified 1mo ago