Provide missing information

When your merchant payment method has the status WaitingForInformation, you need to provide missing verification requirements and supporting documents before the review can be finalized.

This guide shows you how to identify what's missing and provide it.

Webhook

Subscribe to the MerchantPaymentMethod.Updated webhook to know when the status of the payment method changes.

Guide

1. See which information is missing by checking the verification requirements.
2. Check if your project requires additional information.
3. Update the merchant profile with the missing information.
4. Get the supporting documents collection ID.
5. Upload documents.
6. Request a collection review.

Step 1: See which information is missing

To find the missing information, check the verification requirements associated with the WaitingForInformation status.

There are three types of verification requirements: fields, supporting document purposes, and additional information.

Additional information is only required for some projects. (See step 2.)

Query

Open in API Explorer

query GetPaymentMethodRequirements {
  merchantPaymentMethod(id: "$MERCHANT_PAYMENT_METHOD_ID") {
    id
    statusInfo {
      __typename
      status
      
      ... on WaitingForInformationMerchantPaymentMethodStatusInfo {
        verificationRequirements {
          ... on MerchantRequirements {
            fields
          }
          ... on SupportingDocumentRequirements {
            supportingDocumentPurposes
          }
          ... on AdditionalInformationRequirements {
            additionalInformation
          }
        }
      }
    }
  }
}

Payload

{
  "data": {
    "merchantPaymentMethod": {
      "id": "$MERCHANT_PAYMENT_METHOD_ID",
      "statusInfo": {
        "__typename": "WaitingForInformationMerchantPaymentMethodStatusInfo",
        "status": "WaitingForInformation",
        "verificationRequirements": [
          {
            "fields": [
              "MerchantWebsite"
            ]
          },
          {
            "supportingDocumentPurposes": [
              "CompanyTreasury"
            ]
          }
        ]
      }
    }
  }
}

Step 2: Check if this project requires additional information

Some projects require additional information. Use the projectInfo query to check if this applies to your project.

Query

Open in API Explorer

query CheckIfAdditionalInformationApplies {
  projectInfo {
    expectedMerchantProfileAdditionalInformation
  }
}

Payload

{
  "data": {
    "projectInfo": {
      "expectedMerchantProfileAdditionalInformation": [
        "NumberOfEmployees"
      ]
    }
  }
}

Step 3: Update the merchant profile with the missing information

For verification requirements indicated under fields and additionalInformation, provide them by requesting a merchant profile update.

Mutation

1. Add the required fields to the input.
2. If your project requires additional information, add it here.
3. Add ValidationRejection to catch any invalid fields (for example, if the provided URL has an invalid format).
4. Add requestMerchantProfileUpdate to the success payload to retrieve the update status.

Open in API Explorer

mutation RequestMerchantProfileUpdate {
  requestMerchantProfileUpdate(input: {
    merchantProfileId: "$MERCHANT_PROFILE_ID"
    merchantWebsiteUrl: "https://www.mywebsite.com"
    additionalInformation: [
      {
        defaultInformation: {
          type: NumberOfEmployees
          value: "5"
        }
      }
    ]
  }) {
    __typename
    ... on RequestMerchantProfileUpdateSuccessPayload {
      merchantProfile {
        id
        merchantWebsiteUrl
        requestMerchantProfileUpdate {
          id
          status
          merchantWebsiteUrl
          additionalInformation {
            ... on DefaultAdditionalInformation {
              type
              value
            }
          }
        }
      }
    }
    ... on Rejection {
      message
    }
    ... on ValidationRejection {
      fields {
        path
        code
        message
      }
    }
  }
}

Payload

The new provided values appear under requestMerchantProfileUpdate. The values will only be reflected on the merchant profile after the request is approved by Swan.

{
  "data": {
    "requestMerchantProfileUpdate": {
      "__typename": "RequestMerchantProfileUpdateSuccessPayload",
      "merchantProfile": {
        "id": "$MERCHANT_PROFILE_ID",
        "merchantWebsiteUrl": null,
        "requestMerchantProfileUpdate": {
          "id": "$UPDATE_REQUEST_ID",
          "status": "PendingReview",
          "merchantWebsiteUrl": "https://www.mygreatwebsite.fr/",
          "additionalInformation": [
            {
              "type": "NumberOfEmployees",
              "value": "5"
            }
          ]
        }
      }
    }
  }
}

Step 4: Get the supporting documents collection ID

When supporting documents are required by a payment method, the merchant profile has a supporting documents collection with the WaitingForDocument status.

Query the merchant profile to get the collection ID and see which documents are required.

Document purposes

A purpose indicates what's needed (for example, CompanyRegistration). The acceptableSupportingDocumentTypes field lists which document types can satisfy each purpose.

For more details about required documents, refer to the Document Center.

Query

1. Call the merchantProfile query with your merchant profile ID (line 2).
2. Add the supportingDocumentCollections field to your query (line 3).
3. Add a filter for status: WaitingForDocument to return only collections waiting for documents (line 4).
4. Include requiredSupportingDocumentPurposes with the fields name and acceptableSupportingDocumentTypes to see which documents are needed (line 12).

Open in API Explorer

query GetSupportingDocumentCollection {
  merchantProfile(id: "$MERCHANT_PROFILE_ID") {
    supportingDocumentCollections(filters: {
      status: WaitingForDocument
    }) {
      totalCount
      edges {
        node {
          id
          supportingDocumentCollectionUrl
          statusInfo { status }
          requiredSupportingDocumentPurposes {
            name
            label
            description
            acceptableSupportingDocumentTypes
          }
          supportingDocuments {
            id
            supportingDocumentType
            statusInfo { status }
          }
        }
      }
    }
  }
}

Payload

{
  "data": {
    "merchantProfile": {
      "supportingDocumentCollections": {
        "totalCount": 1,
        "edges": [
          {
            "node": {
              "id": "$SUPPORTING_DOCUMENT_COLLECTION_ID",
              "supportingDocumentCollectionUrl": "$UPLOAD_FORM_URL",
              "statusInfo": {
                "status": "WaitingForDocument"
              },
              "requiredSupportingDocumentPurposes": [
                {
                  "name": "CompanyRegistration",
                  "label": "Proof of registration (less than 3 months old)",
                  "description": "A document that provides evidence of the legal registration of a company or business entity with the relevant government authority. The document has to be less than 3 months old.",
                  "acceptableSupportingDocumentTypes": [
                    "RegisterExtract",
                    "ArticlesOfIncorporation",
                    "CapitalShareDepositCertificate",
                    "UBODeclaration"
                  ]
                }
              ],
              "supportingDocuments": []
            }
          }
        ]
      }
    }
  }
}

Step 5: Upload documents

There are two ways to upload documents:

Option 1: Generate upload URL with the API

Supporting documents work the same way as for onboarding and transactions.

Use the collection ID from the previous step to generate the supporting document upload link.

Refer to the guide: Upload a supporting document for an onboarding.

Option 2: Use Web Banking

You can direct users to upload documents directly through our Web Banking interface. Use the supportingDocumentCollectionUrl field from the supporting document collection (step 4) to get the upload form link. Share the link with your users so they can upload their documents directly in Web Banking.

When users upload documents through Web Banking, the collection review is requested automatically (skip step 6).

Step 6: Request a collection review

If you used option 1 to upload documents, request a review for the collection.

Refer to the guide: Request a supporting document collection review.