Links

Collect payments

How to prepare for and initiate merchant 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].

Prepare to collect payments

There are several preparatory steps to complete before you can collect third-party payments using the Swan Merchant Payment Collection feature.
  1. 1.
    Create a merchant profile,
  2. 2.
    Request at least one payment method, and
  3. 3.
    Create a payment mandate.

1. Create a merchant profile

  1. 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. 2.
    Run the addMerchantProfile mutation. You don't need consent.
  3. 3.
    The new merchant is created with the status PendingReview.
  4. 4.
    Swan reviews the new merchant profile and updates the status.
All new merchant profiles are reviewed by Swan. We might contact you for more information before accepting or rejecting the merchant profile.
Request
Response
mutation MyMutation {
addMerchantProfile(
input: {
accountId: "{{YOUR_ACCOUNT_ID}}"
merchantName: "{{YOUR_MERCHANT_NAME}}"
productType: Goods
expectedMonthlyPaymentVolume: {
value: "{{YOUR_EXPECTED_PAYMENT_VOLUME}}"
currency: "EUR"
}
expectedAverageBasket: {
value: "{{YOUR_EXPECTED_AVERAGE_BASKET}}"
currency: "EUR"
}
}
) {
... on AddMerchantProfileSuccessPayload {
__typename
merchantProfile {
accountId
id
statusInfo {
status
... on EnabledMerchantProfileStatusInfo {
__typename
enabledAt
status
}
}
productType
}
}
... on ForbiddenRejection {
__typename
message
}
... on AccountNotFoundRejection {
id
message
}
... on InternalErrorRejection {
__typename
message
}
}
}
{
"data": {
"addMerchantProfile": {
"__typename": "AddMerchantProfileSuccessPayload",
"merchantProfile": {
"accountId": "3ec375bb-887e-43e5-9ce4-b8fd0bbb2cba",
"id": "cadd7d07-2fa7-4817-805c-886f38e04374",
"statusInfo": {
"status": "PendingReview"
},
"productType": "Goods"
}
}
}
}

Sandbox: Update merchant profile status

In the Sandbox only, you need to update the merchant profile status to Enabled.
  1. 1.
    Open your Swan Dashboard.
  2. 2.
    Go to Developers > Event Simulator.
  3. 3.
    Go to Merchant Acquiring.
  4. 4.
    Go to the tab to update the merchant profile status.
  5. 5.
    Change the merchant profile status to Enabled.

2. Request a payment method

  1. 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. 2.
    Run the requestMerchantPaymentProducts mutation. You can request a payment method regardless of the status of the merchant profile.
  3. 3.
    The payment method is created with the status PendingReview and the version number 1.
  4. 4.
    Swan reviews the new merchant payment method and updates the status.
All new merchant payment methods are reviewed by Swan. We might contact you for more information before accepting or rejecting the payment method.
Request
Response
mutation MyMutation {
requestMerchantPaymentProducts(
input: {
merchantProfileId: "{{YOUR_MERCHANT_PROFILE_ID}}"
internalDirectDebit: { activate: true }
}
) {
... on RequestMerchantPaymentProductsSuccessPayload {
__typename
merchantProfile {
id
merchantName
merchantPaymentProducts {
productId
statusInfo {
status
... on EnabledMerchantPaymentProductStatusInfo {
__typename
enabledAt
status
}
}
}
}
}
... on ForbiddenRejection {
__typename
message
}
... on NotFoundRejection {
id
message
}
... on InternalErrorRejection {
__typename
message
}
}
}
{
"data": {
"requestMerchantPaymentProducts": {
"__typename": "RequestMerchantPaymentProductsSuccessPayload",
"merchantProfile": {
"id": "cadd7d07-2fa7-4817-805c-886f38e04374",
"merchantName": "Test",
"merchantPaymentProducts": [
{
"productId": "idd_cadd7d07-2fa7-4817-805c-886f38e04374",
"statusInfo": {
"status": "PendingReview"
}
}
]
}
}
}
}

Sandbox: Update merchant payment method status

In the Sandbox only, you need to update the merchant payment method status to Enabled.
  1. 1.
    Open your Swan Dashboard.
  2. 2.
    Go to Developers > Event Simulator.
  3. 3.
    Go to Merchant Acquiring.
  4. 4.
    Go to the tab to update the merchant payment method status.
  5. 5.
    Change the payment method status to Enabled.

3. Declare a signed payment mandate

Finally, before collecting payments, you need to add an Internal Direct Debit payment mandate to your Swan account. Each debtor must have their own payment mandate.
The payment mandates informational page will help you create a valid payment mandate.
  1. 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. 2.
    Confirm the following requirements are met:
    • The debtor belongs to the same project as the creditor.
    • The debtor's account cannot have the status Closing or Closed.
    • For InternalDirectDebitB2b, the debtor's account type must be Company.
  3. 3.
    Run the addInternalDirectDebitPaymentMandate mutation. You don't need consent.
  4. 4.
    The payment mandate is created with the status Enabled.
The merchant can use the account to begin collecting payments immediately. The Received Direct Debit Mandate (debtor's debit mandate) is not created until a first collection is received.
Request
Response
mutation MyMutation {
addInternalDirectDebitPaymentMandate(
input: {
merchantProfileId: "{{YOUR_MERCHANT_PROFILE_ID}}"
debtorAccountId: "{{YOUR_DEBTOR_ACCOUNT_ID}}"
scheme: InternalDirectDebitB2b
}
) {
... on AddInternalDirectDebitPaymentMandateSuccessPayload {
__typename
internalDirectDebitPaymentMandateId
}
... on ForbiddenRejection {
__typename
message
}
... on NotFoundRejection {
id
message
}
... on DebtorAccountNotAllowedRejection {
__typename
message
}
... on DebtorAccountClosedRejection {
__typename
message
}
... on SchemeWrongRejection {
__typename
message
}
... on PaymentMandateReferenceAlreadyUsedRejection {
__typename
message
}
... on InternalErrorRejection {
__typename
message
}
}
}
{
"data": {
"addInternalDirectDebitPaymentMandate": {
"__typename": "AddInternalDirectDebitPaymentMandateSuccessPayload",
"internalDirectDebitPaymentMandateId": "ddi-mand_b560d19e9efdf5ea46b014adbb4d00d5"
}
}
}

Collect payments

After completing all preparatory steps, the merchant can initiate payment collection.
Prerequisites
  • Debtor's account status: any except Closing or Closed
  • Payment mandate status: Enabled
  • Merchant profile status: Enabled
  • Payment method status: Enabled

Initiate an internal direct debit

  1. 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. 2.
    Run the initiateMerchantPaymentCollection mutation with internalDirectDebit.
  3. 3.
    Two transactions are created sequentially:
    • First, an incoming Internal Direct Debit (InternalDirectDebitIn) is created in the merchant's account with the status Upcoming.
    • Then, an outgoing Internal Direct Debit (InternalDirectDebitOut) is created in the debtor's account with the status Upcoming.
  4. 4.
    On the settlement date, Swan confirms the transaction can be completed.
    • Debtor's Swan account status: Enabled
    • Direct debit mandate state: Enabled
    • Debtor's available balance is enough to cover the transaction
  5. 5.
    Swan updates the status for both the InternalDirectDebitIn and InternalDirectDebitOut to Booked.
IDD Request
IDD Response
API request using the initiateMerchantPaymentCollection mutation and a internalDirectDebit payment method
1
mutation MyMutation {
2
initiateMerchantPaymentCollection(
3
input: {
4
amount: { value: "250", currency: "eur" }
5
internalDirectDebit: { mandateId: "$YOUR_MANDATE_ID" }
6
}
7
) {
8
... on InitiateMerchantPaymentCollectionSuccessPayload {
9
__typename
10
merchantPaymentCollection {
11
id
12
statusInfo {
13
... on PaymentConsentPending {
14
__typename
15
consent {
16
consentUrl
17
}
18
}
19
}
20
}
21
}
22
... on ForbiddenRejection {
23
__typename
24
message
25
}
26
... on NotFoundRejection {
27
id
28
message
29
}
30
... on InternalErrorRejection {
31
__typename
32
message
33
}
34
}
35
}
36
API response to the initiateMerchantPaymentCollection mutation with a internalDirectDebit payment product
1
{
2
"data": {
3
"initiateMerchantPaymentCollection": {
4
"__typename": "InitiateMerchantPaymentCollectionSuccessPayload",
5
"merchantPaymentCollection": {
6
"id": "spi_796ae6fb4b5bbb79dcb4f4c3c5e081a3",
7
"statusInfo": {}
8
}
9
}
10
}
11
}
Payment initiation errors
If any of the prerequisites are not met, you'll receive an error. Please confirm each status listed in this section, then try again.
If an error persists, contact your dedicated Technical Account Manager, or send an email to [email protected].

Refund an internal direct debit transaction

If you are using the B2B scheme, refunds are not available. Only core internal direct debit transactions can be refunded.
Core internal direct debit transactions can be refunded, just like Core SEPA Direct Debit Core transactions. In fact, the debtor is entitled to refund, no questions asked, even for authorized transactions. They must request the refund within eight weeks of being debited.
Refunding an InternalDirectDebitOut transaction triggers the creation of two new transactions:
  1. 1.
    First, a new debit transaction (Return Executed on the InternalDirectDebitOut).
  2. 2.
    Then, a new credit transaction (Return Received on the InternalDirectDebitIn).
Refunds must be processed by Swan; send an email to [email protected].

Initiate a French check deposit

  1. 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. 2.
    Run the initiateMerchantPaymentCollection mutation with check.
  3. 3.
    Swan confirms that the check amount does not exceed 10 000€ and that the field formats are consistent with our check provider's specifications.
  4. 4.
    A checkIn transaction is created with the status Upcoming. checkIn transactions retain the status Upcoming until the check amount is credited to the Swan settlement account.
  5. 5.
    The Merchant sends the check to our check provider by physical mail.
  6. 6.
    The check provider processes the check, after which the status changes to Booked. This can take up to two days.
  7. 7.
    After a check is Booked, the rolling reserve window starts.
  8. 8.
    Finally, the amount is added to the account available balance. If funds are insufficient for the check deposit, a checkInReturn will appear on your transaction history.
Check Request
Check Response
API request using the initiateMerchantPaymentCollection mutation and a check payment method
1
mutation MyMutation {
2
initiateMerchantPaymentCollection(
3
input: {
4
amount: { value: "250", currency: "EUR" }
5
check: {
6
merchantProfileId: "$YOUR_ID",
7
cmc7: "$YOUR_CMC7",
8
rlmcKey: "$YOUR_RLMC_KEY"
9
}
10
}
11
) {
12
... on InitiateMerchantPaymentCollectionSuccessPayload {
13
__typename
14
merchantPaymentCollection {
15
id
16
statusInfo {
17
... on PaymentConsentPending {
18
__typename
19
consent {
20
consentUrl
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
API response to the initiateMerchantPaymentCollection mutation with a check payment product
1
{
2
"data": {
3
"initiateMerchantPaymentCollection": {
4
"__typename": "InitiateMerchantPaymentCollectionSuccessPayload",
5
"merchantPaymentCollection": {
6
"id": "spi_796ae6fb4b5bbb79dcb4f4c3c5e081a3",
7
"statusInfo": {}
8
}
9
}
10
}
11
}