Swan Docs

https://github.com/swan-io/docs
Admin
Swan Docs is the official documentation website for the Swan project, providing installation,...
Tokens:265,698
Snippets:3,103
Trust Score:9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Start Local Development Server

Source: https://github.com/swan-io/docs/blob/main/README.md

Starts a local development server for live previewing changes. No server restart is needed for most updates.

```console
yarn start
```

--------------------------------

### Install Dependencies

Source: https://github.com/swan-io/docs/blob/main/README.md

Installs project dependencies using Yarn.

```console
yarn install
```

--------------------------------

### GraphQL Query Example

Source: https://github.com/swan-io/docs/blob/main/docs/developers/index.mdx

This example demonstrates how to query for account IDs and IBANs using cURL. Replace `$YOUR_ACCESS_TOKEN` with a valid user or project access token.

```APIDOC
## GraphQL Query Example

### Description
This example demonstrates how to query for account IDs and IBANs using cURL. Replace `$YOUR_ACCESS_TOKEN` with a valid user or project access token.

### Method
POST

### Endpoint
https://api.swan.io/sandbox-partner/graphql

### Parameters
#### Request Body
- **query** (string) - Required - The GraphQL query string.

### Request Example
```curl
curl -X POST https://api.swan.io/sandbox-partner/graphql \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $YOUR_ACCESS_TOKEN' \
-d '{"query":"query MyQuery{ accounts { edges { node { id IBAN } } } }"}'
```

### Response
#### Success Response (200)
- **data** (object) - Contains the result of the GraphQL query.
  - **accounts** (object)
    - **edges** (array)
      - **node** (object)
        - **id** (string) - The account ID.
        - **IBAN** (string) - The account IBAN.

#### Response Example
```json
{
    "data": {
        "accounts": {
            "edges": [
                {
                    "node": {
                        "id": "$YOUR_ID",
                        "IBAN": "$YOUR_IBAN"
                    }
                }
            ]
        }
    }
}
```
```

--------------------------------

### Authorization Code Example

Source: https://github.com/swan-io/docs/blob/main/docs/developers/using-api/authentication/guide-get-token-user.mdx

This example shows the format of the full URL received after a user approves a request. It includes the authorization code and state parameters. Ensure the state parameter matches the one sent initially to prevent CSRF attacks.

```bash
# Full URL
https://$YOUR_REDIRECT_URI?code=$YOUR_AUTHORIZATION_CODE&state=kdqsjdlkjsqdlkqjsdlkjsqd

# Spaced-out example
https://$YOUR_REDIRECT_URI?
code=$YOUR_AUTHORIZATION_CODE
&state=kdqsjdlkjsqdlkqjsdlkjsqd
```

--------------------------------

### Install Stripe Terminal SDK for React Native

Source: https://github.com/swan-io/docs/blob/main/docs/topics/merchants/in-person/cards/guide-setup.mdx

Use npm, Yarn, or Expo to install the Stripe Terminal React Native SDK.

```bash
# npm
npm install @stripe/stripe-terminal-react-native

# Yarn
yarn add @stripe/stripe-terminal-react-native

# Expo
npx expo install @stripe/stripe-terminal-react-native
```

--------------------------------

### GraphQL Query Example

Source: https://github.com/swan-io/docs/blob/main/docs/developers/graphql.mdx

This example demonstrates how to query for a user's mobile phone number using a GraphQL query. It shows the basic structure of a query, including the operation type, the target field, and the specific field to retrieve. The 'user' query requires an 'id' argument.

```graphql
query {
  user(id: "$SWAN_USER_ID") {
    mobilePhoneNumber
  }
}
```

--------------------------------

### Response

Source: https://github.com/swan-io/docs/blob/main/docs/developers/using-api/authentication/guide-get-token-project.mdx

This is an example of a successful response when requesting a project access token. The response includes the access token, its type, expiration time, and scope.

```json
{
  "access_token": "$YOUR_PROJECT_ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": ""
}
```

--------------------------------

### Discover and Connect to a Reader (Android)

Source: https://github.com/swan-io/docs/blob/main/docs/topics/merchants/in-person/cards/guide-initialize.mdx

Create a `TapToPayDiscoveryConfiguration` for discovery and use `connectReader` to connect. This snippet includes listener setup for connection events and error handling.

```kotlin
val discoverCancelable: Cancelable? = null
val tapToPayReaderListener: TapToPayReaderListener? = null

fun onDiscoverReaders() {
  val config = TapToPayDiscoveryConfiguration(isSimulated = false)

  discoverCancelable = Terminal.getInstance().discoverReaders(
    config,
    object : DiscoveryListener {
      override fun onUpdateDiscoveredReaders(readers: List<Reader>) {
        val tapToPayReader = readers.first {
          it.deviceType == DeviceType.TAP_TO_PAY_DEVICE
        }

        val connectionConfig = TapToPayConnectionConfiguration(
          "$LOCATION_ID",
          autoReconnectOnUnexpectedDisconnect = true,
          tapToPayReaderListener
        )

        Terminal.getInstance().connectReader(
          tapToPayReader,
          connectionConfig,
          object : ReaderCallback {
            override fun onSuccess(reader: Reader) { /* connected */ }
            override fun onFailure(e: TerminalException) { /* handle error */ }
          }
        )
      }
    },
    object : Callback {
      override fun onSuccess() { /* discovery started */ }
      override fun onFailure(e: TerminalException) { /* handle error */ }
    }
  )
}

override fun onStop() {
  super.onStop()
  // Cancel discovery if the user leaves without selecting a reader.
  discoverCancelable?.cancel(object : Callback {
    override fun onSuccess() {}
    override fun onFailure(e: TerminalException) {}
  })
}
```

--------------------------------

### Initiate Credit Transfer with Verification Token

Source: https://github.com/swan-io/docs/blob/main/docs/topics/payments/credit-transfers/sepa/vop/guide-verify-beneficiary.mdx

Use the `InitiateCreditTransfers` mutation with a `beneficiaryVerificationToken` to start a credit transfer. This bypasses the need to provide full beneficiary details.

```graphql
mutation InitiateCreditTransferWithVerificationToken {
  initiateCreditTransfers(
    input: {
      creditTransfers: {
        amount: { value: "10", currency: "EUR" }
        beneficiaryVerificationToken: "$YOUR_BENEFICIARY_VERIFICATION_TOKEN"
      }
      consentRedirectUrl: "https://www.swan.io/"
      accountId: "$YOUR_ACCOUNT_ID"
    }
  ) {
    ... on InitiateCreditTransfersSuccessPayload {
      __typename
      beneficiaryVerificationResults {
        status
        ... on VerifyBeneficiaryMatch {
          __typename
          status
        }
      }
      payment {
        statusInfo {
          ... on PaymentConsentPending {
            __typename
            consent {
              consentUrl
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### GraphQL API Response Example

Source: https://github.com/swan-io/docs/blob/main/docs/developers/index.mdx

This is a sample JSON response structure for a successful GraphQL query to the Swan API, showing account data.

```json
{
    "data": {
        "accounts": {
            "edges": [
                {
                    "node": {
                        "id": "$YOUR_ID",
                        "IBAN": "$YOUR_IBAN"
                    }
                }
            ]
        }
    }
}
```

--------------------------------

### Initiate SEPA Direct Debit GraphQL Mutation

Source: https://github.com/swan-io/docs/blob/main/docs/topics/merchants/online/sdd/guide-initiate.mdx

Use the initiateSepaDirectDebitMerchantPayment mutation to start a transaction. Ensure you provide a unique idempotency key and valid mandate ID.

```graphql
mutation InitiateSdd {
  initiateSepaDirectDebitMerchantPayment(
    input: {
      idempotencyKey: "$YOUR_IDEMPOTENCY_KEY"
      mandateId: "$YOUR_MANDATE_ID"
      amount: { value: "75", currency: "EUR" }
      label: "Your Merchant's Name"
      requestedExecutionAt: "2024-04-12T16:28:22.867Z"
    }
  ) {
    ... on ForbiddenRejection {
      __typename
      message
    }
    ... on NotFoundRejection {
      id
      message
    }
    ... on InternalErrorRejection {
      __typename
      message
    }
    ... on ValidationRejection {
      __typename
      message
    }
    ... on IdempotencyConflictRejection {
      __typename
      message
    }
    ... on InitiateSepaDirectDebitMerchantPaymentSuccessPayload {
      __typename
      merchantPayment {
        id
      }
    }
  }
}
```

--------------------------------

### Example Payload Structure

Source: https://github.com/swan-io/docs/blob/main/docs/developers/using-api/pagination.mdx

This JSON structure illustrates how paginated data is returned, including total count, edges (data items), and page information for navigation.

```json
{
  "data": {
    "accountMemberships": {
      "totalCount": 8,
      "edges": [
        {...} # list of account memberships
      ],
      "pageInfo": {
        "endCursor": $OPAQUE_STRING,
        "hasNextPage": true
      }
    }
  }
}
```

--------------------------------

### GraphQL Payload Example for Multiple Users

Source: https://github.com/swan-io/docs/blob/main/docs/topics/users/overview/guide-get-info-multiple.mdx

This JSON payload demonstrates the structure of the response when querying for multiple users, showing details for each user including their authentication languages and identification processes.

```json
{
  "data": {
    "users": {
      "edges": [
        {
          "node": {
            "id": "$USER_ID_1",
            "joinedAt": "2024-01-18T13:42:50.106Z",
            "authenticators": [
              {
                "acceptLanguage": "de"
              }
            ],
            "identifications": {
              "totalCount": 1,
              "edges": [
                {
                  "node": {
                    "process": "Expert"
                  }
                }
              ]
            }
          }
        },
        {
          "node": {
            "id": "$USER_ID_2",
            "joinedAt": "2024-01-18T13:44:22.504Z",
            "authenticators": [
              {
                "acceptLanguage": "fr"
              }
            ],
            "identifications": {
              "totalCount": 3,
              "edges": [
                {
                  "node": {
                    "process": "QES"
                  }
                },
                {
                  "node": {
                    "process": "PVID"
                  }
                },
                {
                  "node": {
                    "process": "Expert"
                  }
                }
              ]
            }
          }
        }
      ],
      "totalCount": 2
    }
  }
}
```

--------------------------------

### GraphQL Query for International Beneficiary Dynamic Forms

Source: https://github.com/swan-io/docs/blob/main/docs/topics/payments/credit-transfers/international/guide-beneficiary.mdx

Call the `internationalBeneficiaryDynamicForms` query to get the schema for beneficiary information. This example specifies USD currency and English language. The response includes various field types like Date, Radio, Select, and Text, each with its own properties such as validation rules, examples, and required status.

```graphql
query BeneficiaryDynamicForm {
  internationalBeneficiaryDynamicForms(
    amount: { value: "500", currency: "USD" }
    language: en
  ) {
    schemes {
      type
      title
      remainingFieldsToRefreshCount
      fields {
        key
        name
        required
        ... on DateField {
          example
          validationRegex
          key
          name
          required
        }
        ... on RadioField {
          __typename
          key
          name
          refreshDynamicFieldsOnChange
          required
          allowedValues {
            key
            name
          }
        }
        ... on SelectField {
          __typename
          key
          name
          refreshDynamicFieldsOnChange
          required
          allowedValues {
            key
            name
          }
        }
        ... on TextField {
          displayFormat
          example
          key
          maxLength
          minLength
          name
          refreshDynamicFieldsOnChange
          required
          validationRegex
        }
      }
    }
  }
}
```

--------------------------------

### Authorization URL Example

Source: https://github.com/swan-io/docs/blob/main/docs/developers/using-api/authentication/guide-get-token-user.mdx

Construct the authorization URL with required and optional parameters. Ensure to replace placeholders with your actual client ID and redirect URI. Note that query parameters are case-sensitive.

```bash
# Model
&parameter=value

# Spaced-out example
https://oauth.swan.io/oauth2/auth?
response_type=code
&client_id=$YOUR_CLIENT_ID
&redirect_uri=$YOUR_REDIRECT_URI
&scope=openid%20offline
&state=kdqsjdlkjsqdlkqjsdlkjsqd
&onboardingId=$ONBOARDINGID_OF_YOUR_CUSTOMER
&accountMembershipId=$ACCOUNTMEMBERSHIPID_OF_YOUR_CUSTOMER
&identificationLevel=Auto
&firstName=Jules
&lastName=Fleury

# Example URL including the `onboardingId`
https://oauth.swan.io/oauth2/auth?response_type=code&client_id=$YOUR_CLIENT_ID&redirect_uri=$YOUR_REDIRECT_URI&scope=openid%20offline&state=kdqsjdlkjsqdlkqjsdlkjsqd&onboardingId=$ONBOARDINGID_OF_YOUR_CUSTOMER&identificationLevel=Auto&firstName=Jules&lastName=Fleury

# Example URL including the `accountMembershipId`
https://oauth.swan.io/oauth2/auth?response_type=code&client_id=$YOUR_CLIENT_ID&redirect_uri=$YOUR_REDIRECT_URI&scope=openid%20offline&state=kdqsjdlkjsqdlkqjsdlkjsqd&accountMembershipId=$ACCOUNTMEMBERSHIPID_OF_YOUR_CUSTOMER&identificationLevel=Auto&firstName=Jules&lastName=Fleury
```

--------------------------------

### Monitor Onboarding Details

Source: https://github.com/swan-io/docs/blob/main/docs/topics/onboarding/overview/guide-get-info.mdx

Use this query to retrieve details for individual and company onboardings, including ID, creation date, onboarding URL, status, and account admin email. It also shows how to access type-specific fields and error information for invalid statuses.

```graphql
query MonitorOnboarding {
  accountHolderOnboardings(first: 10) {
    edges {
      node {
        ... on IndividualAccountHolderOnboarding {
          id
          createdAt
          onboardingUrl
          statusInfo {
            status
            ... on OnboardingInvalidStatusInfo {
              __typename
              errors {
                field
                errors
              }
              status
            }
          }
          accountAdmin {
            email
          }
        }
        ... on CompanyAccountHolderOnboarding {
          id
          createdAt
          onboardingUrl
          statusInfo {
            status
            ... on OnboardingInvalidStatusInfo {
              __typename
              errors {
                field
                errors
              }
              status
            }
          }
          accountAdmin {
            email
          }
          company {
            name
          }
        }
      }
    }
    totalCount
  }
}
```

--------------------------------

### Example Beneficiary Payload

Source: https://github.com/swan-io/docs/blob/main/docs/topics/payments/credit-transfers/international/guide-beneficiary.mdx

This is an example of the payload structure for a beneficiary in an international credit transfer. It includes details like account information, name, and address.

```json
{
  "account": {
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX"
  },
  "name": "Max Mustermann",
  "address": {
    "street": "Musterstraße 1",
    "city": "Musterstadt",
    "postalCode": "12345",
    "country": "DE"
  },
  "reference": "Payment for invoice 12345"
}
```

--------------------------------

### Bind Account Member Payload Example

Source: https://github.com/swan-io/docs/blob/main/docs/topics/accounts/memberships/partials/_add-member-bind.mdx

This is an example of a successful payload response when binding an account member. It confirms the binding with the `accountMembership` ID and its `__typename`.

```json
{
  "data": {
    "bindAccountMembership": {
      "__typename": "BindAccountMembershipSuccessPayload",
      "accountMembership": {
        "id": "$YOUR_MEMBERSHIP_ID"
      }
    }
  }
}
```

--------------------------------

### Example Invoice Payload

Source: https://github.com/swan-io/docs/blob/main/docs/topics/accounts/billing/guide-get-list.mdx

This is an example of the JSON payload returned when querying for invoices. It includes invoice details, pagination information, and the total count of invoices.

```json
{
  "data": {
    "account": {
      "invoices": {
        "edges": [
          {
            "node": {
              "closingDate": "2023-02-28T22:59:59.999Z",
              "createdAt": "2023-02-16T16:04:51.331Z",
              "expiresAt": "2023-02-17T16:08:32.832Z",
              "name": "INVOICE-20230228",
              "id": "dc43f0f6-7bae-4f05-8b35-82363a1a17cf",
              "openingDate": "2023-01-31T23:00:00.000Z",
              "status": "Paid",
              "updatedAt": "2023-02-16T16:04:52.582Z",
              "url": "$INVOICE_URL",
              "type":"Invoice"
            }
          },
          {
            "node": {
              "closingDate": "2023-02-28T22:59:59.999Z",
              "createdAt": "2023-02-16T16:02:55.416Z",
              "expiresAt": "2023-02-17T16:08:32.832Z",
              "name": "INVOICE-20230228",
              "id": "b9ccad06-417a-48e0-8a08-37fee4ea39a3",
              "openingDate": "2023-01-31T23:00:00.000Z",
              "status": "Voided",
              "updatedAt": "2023-02-16T16:04:50.888Z",
              "url": null,
              "type":"Invoice"
            }
          }
        ],
        "pageInfo": {
          "hasNextPage": false,
          "hasPreviousPage": true
        },
        "totalCount": 2
      }
    }
  }
}
```

--------------------------------

### Create Company Onboarding Mutation

Source: https://github.com/swan-io/docs/blob/main/docs/topics/onboarding/company/guide-create.mdx

Use this GraphQL mutation to initiate the onboarding process for a new company account holder.

```graphql
mutation CreateCompanyOnboarding {
  createCompanyAccountHolderOnboarding(
    input: {
      accountInfo: {
        country: ESP
      }
      accountAdmin: {
        email: "alberto.moreno@mimarca.io"
        preferredLanguage: es
        typeOfRepresentation: LegalRepresentative
      }
      company: {
        name: "MiMarca"
        businessActivity: Construction
        businessActivityDescription: "Historical restoration"
        registrationNumber: "123456789"
        monthlyPaymentVolume: Between10000And50000
        address: {
          addressLine1: "21 Barrio de San Roque"
          city: "Barcelona"
          country: "ESP"
          postalCode: "08005"
        }
        taxIdentificationNumber: "Y1234567Z"
        relatedIndividuals: {
          type: LegalRepresentativeAndUltimateBeneficialOwner
          firstName: "Sofia"
          lastName: "Ramos"
          sex: Female
          birthInfo: {
            birthDate: "1990-03-03"
            country: "ESP"
            city: "Madrid"
          }
          address: {
            addressLine1: "1 Camino del Oceano"
            city: "Barcelona"
            country: "ESP"
            postalCode: "08005"
          }
          ultimateBeneficialOwner: {
            qualificationType: Ownership
            ownership: {
              type: Direct
              totalPercentage: 100
            }
          }
        }
      }
    }
  ) {
    ... on CreateCompanyAccountHolderOnboardingSuccessPayload {
      __typename
      onboarding {
        id
        statusInfo {
          status
        }
      }
    }
  }
}
```

--------------------------------

### GraphQL Mutation to Create Company Onboarding and List Documents

Source: https://github.com/swan-io/docs/blob/main/docs/topics/onboarding/overview/guide-get-list.mdx

Use this mutation to create a company account holder onboarding link and include fields for supporting document collection. It shows how to request required document purposes and their acceptable types.

```graphql
mutation ListRequiredDocuments {
  createCompanyAccountHolderOnboarding {
  {...}
    ... on CreateCompanyAccountHolderOnboardingSuccessPayload {
      __typename
      onboarding {
        id
        statusInfo {
          status
        }
        supportingDocumentCollection {
          requiredSupportingDocumentPurposes {
            acceptableSupportingDocumentTypes
            name
          }
          statusInfo {
            status
          }
        }
      }
    }
  {...}
  }
}

```

--------------------------------

### mutation createCompanyAccountHolderOnboarding

Source: https://github.com/swan-io/docs/blob/main/docs/topics/onboarding/company/guide-create.mdx

Initiates the onboarding process for a company account holder. This mutation requires detailed information about the company, its legal representative, and its ultimate beneficial owners.

```APIDOC
## GraphQL Mutation: createCompanyAccountHolderOnboarding

### Description
Initiates the onboarding process for a company account holder. This mutation accepts an input object containing account information, administrator details, and company registration data.

### Operation
mutation createCompanyAccountHolderOnboarding(input: CreateCompanyAccountHolderOnboardingInput!)

### Request Body
- **input** (CreateCompanyAccountHolderOnboardingInput) - Required
  - **accountInfo** (AccountInfoInput) - Required
  - **accountAdmin** (AccountAdminInput) - Required
  - **company** (CompanyInput) - Required

### Response
#### Success Response
- **onboarding** (Onboarding) - The created onboarding object containing the ID and status.

### Response Example
{
  "data": {
    "createCompanyAccountHolderOnboarding": {
      "__typename": "CreateCompanyAccountHolderOnboardingSuccessPayload",
      "onboarding": {
        "id": "eda0ceec-0e20-4d1b-bbee-b3e3a4227c99",
        "statusInfo": {
          "status": "Valid"
        }
      }
    }
  }
}
```

--------------------------------

### Invalid IBAN Response Payload Examples

Source: https://github.com/swan-io/docs/blob/main/docs/topics/accounts/ibans/guide-validate.mdx

These are example responses for invalid IBANs. The first shows an 'InvalidLength' error, and the second indicates that the 'InvalidBank' referenced in the IBAN could not be found.

```json
# Response 1 for IBAN FR76182060016265
{
  "data": {
    "ibanValidation": {
      "__typename": "InvalidIban",
      "message": "IBAN is invalid",
      "code": "InvalidLength"
    }
  }
}
```

```json
# Response 2 for IBAN FR7817569000305414384277J07
{
  "data": {
    "ibanValidation": {
      "__typename": "InvalidIban",
      "message": "Bank referenced in IBAN could not be found",
      "code": "InvalidBank"
    }
  }
}
```

--------------------------------

### Deploy to GitHub Pages

Source: https://github.com/swan-io/docs/blob/main/README.md

Builds the website and deploys it to the 'gh-pages' branch, suitable for GitHub Pages hosting. Ensure your GitHub username is set.

```console
GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
```

--------------------------------

### GraphQL Payload Example for Transactions

Source: https://github.com/swan-io/docs/blob/main/docs/topics/payments/overview/guide-get-transaction-id.mdx

This is an example of the JSON payload returned when querying for transaction IDs. It includes a list of transaction edges, each containing a node with the `id`, `createdAt`, and `label` of the transaction, as well as the `totalCount`.

```json
{
  "data": {
    "transactions": {
      "edges": [
        {
          "node": {
            "id": "bosco_05582b065b10c5ca8aa03342bb1cf389",
            "createdAt": "2023-05-15T11:34:10.101Z",
            "label": "Transfer to Matilde Rana"
          }
        },
        {
          "node": {
            "id": "bosci_00d62797731fb95ee2f91ca32f4165e9",
            "createdAt": "2023-03-30T13:24:39.477Z",
            "label": "Transfer from Sasha Oliveira"
          }
        },
      ],
      "totalCount": 2
    }
  }
}
```

--------------------------------

### Example JSON Payload for International Credit Transfer

Source: https://github.com/swan-io/docs/blob/main/docs/topics/payments/credit-transfers/international/guide-get-info.mdx

This is an example of the JSON payload you can expect when querying for an International Credit Transfer. It includes details such as the credited amount, counterparty, exchange rate, debtor information, and fees.

```json
{
  "data": {
    "transaction": {
      "amount": {
        "currency": "EUR",
        "value": "850.00"
      },
      "counterparty": "Debtor",
      "currencyExchange": {
        "exchangeRate": "1.05263"
      },
      "debtor": {
        "currency": "GBP",
        "details": [
          {
            "key": "legalType",
            "value": "BUSINESS"
          },
          {
            "key": "Iban",
            "value": "GB12345678901234567890"
          }
        ],
        "name": "My debtor",
        "route": "SwiftCode",
        "instructedAmount": {
            "currency": "GBP",
            "value": "1000.00"
            },
            "intermediaryBankFees": [
                {
                    "value": "50.00",
                    "currency": "GBP"
                },
                {
                    "value": "100.00",
                    "currency": "EUR"
                },
				{
                    "value": "50.00",
                    "currency": "EUR"
                    }
                ],
            "side": "credit"
      }
    }
  }
}
```

--------------------------------

### GraphQL Query for Onboarding Document Info

Source: https://github.com/swan-io/docs/blob/main/docs/topics/accounts/documents/guide-get-info.mdx

Use this GraphQL query to fetch details about a specific onboarding document collection. It supports both individual and company account holders and retrieves information on required purposes and document statuses.

```graphql
query getOnboardingCollectionInfo {
  accountHolderOnboarding(id: "$ONBOARDING_ID") {
    ... on IndividualAccountHolderOnboarding {
      supportingDocumentCollection {
        id
        requiredSupportingDocumentPurposes {
          name
          purposeDetails
        }
        supportingDocuments {
          supportingDocumentPurpose
          supportingDocumentType
          updatedAt
          statusInfo {
            status
            ... on SupportingDocumentRefusedStatusInfo {
              __typename
              filename
              reason
              reasonCode
              refusedAt
              status
            }
          }
        }
      }
    }
    ... on CompanyAccountHolderOnboarding {
      supportingDocumentCollection {
        id
        requiredSupportingDocumentPurposes {
          name
          purposeDetails
        }
        supportingDocuments {
          supportingDocumentPurpose
          supportingDocumentType
          updatedAt
          statusInfo {
            status
            ... on SupportingDocumentRefusedStatusInfo {
              __typename
              filename
              reason
              reasonCode
              refusedAt
              status
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### Transaction Document Collection Info API Payload Example

Source: https://github.com/swan-io/docs/blob/main/docs/topics/accounts/documents/guide-get-info.mdx

Example JSON payload showing the response for a transaction document collection query. Highlights the document status, required purposes, and details of individual documents.

```json
{
  "data": {
    "transaction": {
      "id": "$TRANSACTION_ID",
      "supportingDocumentCollections": {
        "edges": [
          {
            "node": {
              "statusInfo": {
                "status": "WaitingForDocument"
              },
              "id": "$COLLECTION_ID",
              "requiredSupportingDocumentPurposes": [
                {
                  "name": "ProofOfOriginOfFunds",
                  "purposeDetails": null
                }
              ],
              "supportingDocuments": [
                {
                  "statusInfo": {
                    "status": "WaitingForUpload"
                  }
                }
              ]
            }
          }
        ]
      }
    }
  }
}
```

--------------------------------

### Build Static Content

Source: https://github.com/swan-io/docs/blob/main/README.md

Generates static website content into the 'build' directory for hosting.

```console
yarn build
```

--------------------------------

### Sample Onboarding Payload

Source: https://github.com/swan-io/docs/blob/main/docs/topics/onboarding/overview/guide-get-info.mdx

This JSON payload shows two onboarding entries: one with an 'Invalid' status and detailed errors, and another with a 'Valid' status. It includes details like onboarding ID, creation date, URL, status information, account admin email, and company name.

```json
{
  "data": {
    "accountHolderOnboardings": {
      "edges": [
        {
          "node": {
            "id": "$ONBOARDING_ID",
            "createdAt": "2023-06-20T14:10:39.286Z",
            "onboardingUrl": "https://api.banking.swan.io/projects/$PROJECT_ID/onboardings/$ONBOARDING_ID?lang=es",
            "statusInfo": {
              "status": "Invalid",
              "__typename": "OnboardingInvalidStatusInfo",
              "errors": [
                {
                  "field": "company.relatedIndividuals[0].birthInfo.birthDate",
                  "errors": [
                    "Missing"
                  ]
                }
              ]
            },
            "accountAdmin": {
              "email": "alberto.moreno@mimarca.io"
            },
            "company": {
              "name": "MiMarca"
            }
          }
        },
        {
          "node": {
            "id": "$ONBOARDING_ID",
            "createdAt": "2023-06-20T14:00:20.207Z",
            "onboardingUrl": "https://api.banking.swan.io/projects/$PROJECT_ID/onboardings/$ONBOARDING_ID?lang=en",
            "statusInfo": {
              "status": "Valid"
            },
            "accountAdmin": {
              "email": "sofia.ramos@mybrand.io"
            }
          }
        }
      ],
      "totalCount": 2
    }
  }
}
```

--------------------------------

### Install Stripe Terminal SDK for iOS via CocoaPods

Source: https://github.com/swan-io/docs/blob/main/docs/topics/merchants/in-person/cards/guide-setup.mdx

Add the StripeTerminal dependency to your Podfile.

```ruby
pod 'StripeTerminal', '~> 4.0'
```

--------------------------------

### Create individual onboarding mutation

Source: https://github.com/swan-io/docs/blob/main/docs/topics/onboarding/individual/guide-create.mdx

Use this GraphQL mutation to initiate an individual account holder onboarding process. Ensure all required fields for the specific account country are provided.

```graphql
mutation CreateIndividualOnboarding {
  createIndividualAccountHolderOnboarding(
    input: {
      accountInfo: {
        country: FRA
      }
      accountAdmin: {
        email: "malika.ngomao@mybrand.io"
        employmentStatus: Employee
        preferredLanguage: fr
        monthlyIncome: Between3000And4500
        address: {
          addressLine1: "123 avenue de Paris"
          city: "Paris"
          country: "FRA"
          postalCode: "75000"
        }
        unitedStatesTaxInfo: {
          isUnitedStatesPerson: false
        }
      }
    }
  ) {
    ... on CreateIndividualAccountHolderOnboardingSuccessPayload {
      __typename
      onboarding {
        id
        statusInfo {
          status
          ... on OnboardingInvalidStatusInfo {
            errors {
              field
              errors
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### Get Onboarding Collection Info

Source: https://github.com/swan-io/docs/blob/main/docs/topics/accounts/documents/guide-get-info.mdx

Fetches the onboarding collection details for a given onboarding ID. This includes the required document purposes and the status of each uploaded supporting document, with specific details for refused documents.

```APIDOC
## GET /onboarding/collection/{id}

### Description
Retrieves the details of an onboarding collection, including required document purposes and the status of supporting documents. This endpoint supports both individual and company account holders.

### Method
GET

### Endpoint
/onboarding/collection/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the onboarding collection.

### Response
#### Success Response (200)
- **data** (object) - The response payload containing onboarding information.
  - **accountHolderOnboarding** (object) - Information about the account holder's onboarding.
    - **supportingDocumentCollection** (object) - Details about the collection of supporting documents.
      - **id** (string) - The ID of the supporting document collection.
      - **requiredSupportingDocumentPurposes** (array) - A list of purposes for which supporting documents are required.
        - **name** (string) - The name of the required document purpose.
        - **purposeDetails** (string) - Detailed explanation of the document purpose.
      - **supportingDocuments** (array) - A list of supporting documents uploaded for the onboarding.
        - **supportingDocumentPurpose** (string) - The purpose of the supporting document.
        - **supportingDocumentType** (string) - The type of the supporting document (nullable).
        - **updatedAt** (string) - The timestamp when the document was last updated.
        - **statusInfo** (object) - Information about the status of the supporting document.
          - **status** (string) - The current status of the document (e.g., 'Validated', 'Refused').
          - **__typename** (string) - The GraphQL type name (used for specific status handling).
          - **filename** (string) - The name of the file if the status is 'Refused'.
          - **reason** (string) - The reason for refusal if the status is 'Refused'.
          - **reasonCode** (string) - The code associated with the refusal reason if the status is 'Refused'.
          - **refusedAt** (string) - The timestamp when the document was refused if the status is 'Refused'.

### Response Example
```json
{
  "data": {
    "accountHolderOnboarding": {
      "supportingDocumentCollection": {
        "id": "$COLLECTION_ID",
        "requiredSupportingDocumentPurposes": [
          {
            "name": "Other",
            "purposeDetails": "Most recent business income tax return (aangifte inkomstenbelasting)"
          }
        ],
        "supportingDocuments": [
          {
            "supportingDocumentPurpose": "Other",
            "supportingDocumentType": null,
            "updatedAt": "2026-04-16T08:37:47.625Z",
            "statusInfo": {
              "status": "Validated"
            }
          }
        ]
      }
    }
  }
}
```
```

--------------------------------

### Webhook Notification Payload

Source: https://github.com/swan-io/docs/blob/main/docs/developers/using-api/webhooks.mdx

Example of the JSON structure received in a POST request for a webhook notification.

```json
{
  "eventType": "Transaction.Booked",
  "eventId": "$YOUR_EVENT_ID",
  "eventDate": "2021-08-18T09:35:46.673Z",
  "projectId": "$YOUR_PROJECT_ID",
  "resourceId": "$YOUR_RESOURCE_ID"
}
```

--------------------------------

### Initiate a SEPA transfer and save beneficiary using GraphQL mutation

Source: https://github.com/swan-io/docs/blob/main/docs/topics/payments/credit-transfers/sepa/guide-add-beneficiary.mdx

Use the `initiateCreditTransfers` mutation to start a SEPA transfer and optionally save the beneficiary for future use by setting `save: true`. This requires specifying the amount, currency, beneficiary details (IBAN, name), account ID, and a consent redirect URL.

```graphql
mutation SaveBeneficiary {
  initiateCreditTransfers(
    input: {
      creditTransfers: {
        amount: { value: "200", currency: "EUR" }
        sepaBeneficiary: {
          iban: "$TRUSTED_BENEFICIARY_IBAN"
          name: "$TRUSTED_BENEFICIARY_NAME"
          isMyOwnIban: false
          save: true
        }
      }
      consentRedirectUrl: "$REDIRECT_URL"
      accountId: "$ACCOUNT_ID"
    }
  ) {
    ... on InitiateCreditTransfersSuccessPayload {
      __typename
      payment {
        id
      }
    }
  }
}
```

--------------------------------

### Get the reason of a merchant profile rejection

Source: https://github.com/swan-io/docs/blob/main/docs/topics/merchants/profiles/guide-get-info.mdx

Retrieves the rejection reason for a merchant profile if its status is 'Rejected'.

```APIDOC
## Get the reason of a merchant profile rejection

### Description
Retrieves the rejection reason for a merchant profile if its status is 'Rejected'.

### Query
```graphql
query merchantProfileInfo {
  merchantProfile(id: "$MERCHANT_PROFILE_ID") {
    id
    statusInfo {
      status
      ... on RejectedMerchantProfileStatusInfo {
        rejectionReason
      }
    }
  }
}
```

### Payload
```json
{
  "data": {
    "merchantProfile": {
      "id": "$MERCHANT_PROFILE_ID",
      "statusInfo": {
        "status": "Rejected",
        "rejectionReason": "$REJECTION_REASON"
      }
    }
  }
}
```
```

--------------------------------

### Close account API response payload

Source: https://github.com/swan-io/docs/blob/main/docs/topics/accounts/closure/guide-close-api.mdx

Example of the successful response containing the consent URL for the legal representative.

```json
{
  "data": {
    "closeAccount": {
      "__typename": "CloseAccountSuccessPayload",
      "consent": {
        "consentUrl": "https://identity.swan.io/consent?consentId=$YOUR_CONSENT_ID&env=Sandbox"
      }
    }
  }
}
```

--------------------------------

### Get Account Information

Source: https://github.com/swan-io/docs/blob/main/docs/topics/accounts/index.mdx

Retrieve details about a specific account using the `account` query. This is useful for fetching account-specific data.

```graphql
query Account($accountId: String!) {
  account(id: $accountId) {
    ...Account
  }
}
```

--------------------------------

### Physical Card Renewal Payload

Source: https://github.com/swan-io/docs/blob/main/docs/topics/cards/physical/guide-renew.mdx

Example JSON payload confirming a physical card's expiry date and renewal status.

```json
{
  "data": {
    "confirmPhysicalCardRenewal": {
      "__typename": "ConfirmPhysicalCardRenewalSuccessPayload",
      "physicalCard": {
        "expiryDate": "09/21",
        "statusInfo": {
          "status": "ToRenew"
        }
      }
    }
  }
}
```

--------------------------------

### Initiate Instant SEPA Credit Transfer with Fallback

Source: https://github.com/swan-io/docs/blob/main/changelog/2023/2023-03-29.mdx

Use the `initiateCreditTransfer` mutation to enable a fallback to standard transfer if instant transfer is unavailable. It is recommended to set `includeRejectedWithFallback` to `false` by default.

```graphql
mutation InitiateCreditTransfer($input: InitiateCreditTransferInput!) {
  initiateCreditTransfer(input: $input) {
    id
    status
  }
}
```

--------------------------------

### Capital Deposit Case Success Payload

Source: https://github.com/swan-io/docs/blob/main/docs/topics/capital-deposits/france/guide-create-case.mdx

Example of the JSON response returned upon successfully creating a capital deposit case.

```json
{
  "data": {
    "createCapitalDepositCase": {
      "__typename": "CreateCapitalDepositCaseSuccessPayload",
      "capitalDepositCase": {
        "id": "$CAPITAL_DEPOSIT_CASE_ID",
        "companyOnboarding": {
          "id": "$COMPANY_ONBOARDING_ID"
        },
        "statusInfo": {
          "status": "WaitingForInitialRequirements",
          "__typename": "CapitalDepositCaseWaitingForInitialRequirementsStatusInfo"
        },
        "totalCapitalDepositAmount": {
          "currency": "EUR",
          "value": "1000"
        }
      }
    }
  }
}
```

--------------------------------

### Verification Process Sequence Diagram

Source: https://github.com/swan-io/docs/blob/main/docs/topics/onboarding/account-holders/index.mdx

A Mermaid sequence diagram illustrating the onboarding flow, including alternate scenarios for first transfers and document collection.

```mermaid
sequenceDiagram autoNumber
participant P as Partner
participant U as User
participant S as Swan
    P ->> S: Creates onboarding link
    S ->> P: Returns onboarding object
    P ->> U: Sends onboarding link
    U -->> S: Completes onboarding
    S ->> U: Sends text message inviting the account<br/>holder to complete identification
    U ->> S: Provides identification provider<br/>with required elements
    S ->> S: Verifies identification

    note over P,S: If a first transfer is required, the process splits into one of two scenarios:
    alt SCENARIO A: Partner notifies user about first transfer
        S ->> P: Sends email notifying about required first transfer
        P ->> U: Requests first transfer
        U ->> S: Sends first transfer
    else SCENARIO B: Swan requests first transfer from user
        S ->> U: Sends email requesting first transfer
        U ->> S: Sends first transfer
    end
    S ->> S: Swan reviews first transfer

    note over P,S: If supporting documents are required, the process splits into one of two scenarios:
    alt SCENARIO A: Partner provides documents
        S ->> P: Sends webhook about missing supporting documents
        P ->> U: Requests documents
        U ->> P: Provides documents
        P ->>S: Uploads documents with the API
    else SCENARIO B: Account holder provides documents
        S ->> U: Sends email requesting supporting documents
        U ->> S: Uploads documents to banking interface
    end
    S ->> S: Swan reviews identity<br/>verification and documents
```

--------------------------------

### Payload for Project Additional Information Requirements

Source: https://github.com/swan-io/docs/blob/main/docs/topics/merchants/guide-missing-information.mdx

Example JSON payload indicating the additional merchant profile information expected for the project.

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

--------------------------------

### Success Payload Example for Cancel Consent

Source: https://github.com/swan-io/docs/blob/main/docs/developers/using-api/errors-rejections.mdx

Shows the expected JSON response when the `cancelConsent` mutation is successful and returns the consent ID.

```json
{
  "data": {
    "cancelConsent": {
      "consent": {
        "id" : "$YOUR_CONSENT_ID"
        }
      }
    }
  }
}
```

--------------------------------

### Add Swan GraphQL MCP Server using Claude Code CLI

Source: https://github.com/swan-io/docs/blob/main/docs/developers/tools/mcp-servers.mdx

Use the Claude Code CLI to add the Swan GraphQL MCP server. This command registers the server for use within Claude Code.

```bash
claude mcp add --transport http swan-graphql https://mcp.swan.io/graphql/mcp
```

--------------------------------

### Mutation Payload Example

Source: https://github.com/swan-io/docs/blob/main/docs/developers/graphql.mdx

This JSON shows the expected payload structure after a successful `updateAccount` mutation, including the `__typename` and the updated account details.

```json
{
  "data": {
    "updateAccount": {
      "__typename": "UpdateAccountSuccessPayload",
      "account": {
        "language": "en"
      }
    }
  }
}
```

--------------------------------

### Activate Physical Card (API Explorer)

Source: https://github.com/swan-io/docs/blob/main/docs/topics/cards/physical/sandbox.mdx

Use this mutation to activate a physical card in the sandbox. You must provide the physical card identifier obtained from the reception simulation and a consent redirect URL. The response includes card details upon success or specific rejection reasons.

```graphql
mutation MyMutation {
  activatePhysicalCard(
    input: {
      identifier: "$PHYSICAL_CARD_IDENTIFIER"
      consentRedirectUrl: "$CONSENT_REDIRECT_URL"
    }
  ) {
    ... on ActivatePhysicalCardSuccessPayload {
      __typename
      physicalCard {
        expiryDate
        identifier
        statusInfo {
          status
        }
      }
      consent {
        consentUrl
      }
    }
    ... on BadAccountStatusRejection {
      id
      message
    }
    ... on PhysicalCardNotFoundRejection {
      __typename
      message
      identifier
    }
    ... on ForbiddenRejection {
      __typename
      message
    }
    ... on CardNotFoundRejection {
      id
      message
    }
    ... on ValidationRejection {
      __typename
      message
      fields {
        code
        message
        path
      }
    }
    ... on UserNotCardHolderRejection {
      __typename
      message
    }
    ... on PhysicalCardWrongStatusRejection {
      __typename
      message
      currentStatus
      expectedStatus
      identifier
    }
    ... on CannotActivatePhysicalCardRejection {
      __typename
      message
      identifier
    }
  }
}
```

--------------------------------

### Swan Sign-up Flow Diagram

Source: https://github.com/swan-io/docs/blob/main/docs/topics/users/index.mdx

Illustrates the step-by-step process for user sign-up on Swan, including mobile and computer initiated flows, verification steps, and information collection.

```mermaid
%%{ init: { 'flowchart': { 'curve': 'linear' } } }%%
flowchart TB
    MobileEntry([User sign-up started on mobile with<br/>an OAuth 2.0 link]) -.-> EntersMobileNumber([Enters mobile number])
    ComputerEntry([User sign-up started on computer with<br/>an OAuth 2.0 link]) -.-> EntersMobileNumber

    EntersMobileNumber -- User on mobile --> ConfirmsMobileNumberMobile([Confirms mobile number])
    EntersMobileNumber -- User on computer --> ReceivesOTP([Receives verification code in text message])

    ConfirmsMobileNumberMobile --> ReceivesCode([Receives verification code in text message])
    ReceivesCode --> EntersCode([Enters verification code])
    EntersCode --> QueryParams{Are query parameters filled?}
    
    ReceivesOTP --> EntersOTP([Enters verification code on computer])
    EntersOTP --> QueryParams

    QueryParams -- No --> EntersPI([Enters personal information])
    QueryParams -- Yes --> UserStartedComputer{User started sign-up on computer?}

    EntersPI --> UserStartedComputer
    UserStartedComputer -- Yes --> ConfirmsNumber([Confirms number on computer])
    ConfirmsNumber --> ChoosesPasscode([Chooses 6-digit passcode])
    UserStartedComputer -- No --> ChoosesPasscode

    ChoosesPasscode --> ConfirmsPasscode([Confirms 6-digit passcode])

    ConfirmsPasscode --> EmailVerificationIncluded{Email verification included in OAuth URL?}
    EmailVerificationIncluded -- Yes --> EmailVerificationFlow([Email verification flow])
    EmailVerificationIncluded -- No --> EntersBirthInfo

    EmailVerificationFlow --> EntersBirthInfo([Enters birth information])
    EntersBirthInfo --> EntersResidencyInfo([Enters residency information])
    EntersResidencyInfo --> ConfirmsInfo([Confirms personal, birth,<br/>and residency information])

    ConfirmsInfo --> O

    subgraph O[Optional or performed later]
        direction LR
        IV([Completes identification]) ~~~ B([Configures biometrics])
    end

    O --> S[Can access Swan]

    style S fill:#fffdf4,stroke:#cca922,stroke-width:3px
    style O fill:#E6F3F8,stroke:#4D8296,stroke-dasharray: 5 5
    style IV fill:#E6E6FA,stroke:#6A5ACD
    style B fill:#E6E6FA,stroke:#6A5ACD
    style EntersMobileNumber fill:#D4D3D5,stroke:#514F59
    style ConfirmsMobileNumberMobile fill:#D4D3D5,stroke:#514F59
    style ReceivesCode fill:#D4D3D5,stroke:#514F59
    style EntersCode fill:#D4D3D5,stroke:#514F59
    style ReceivesOTP fill:#D4D3D5,stroke:#514F59
    style EntersOTP fill:#D4D3D5,stroke:#514F59
    style ConfirmsNumber fill:#D4D3D5,stroke:#514F59
    style EntersPI fill:#D4D3D5,stroke:#514F59
    style ChoosesPasscode fill:#D4D3D5,stroke:#514F59
    style ConfirmsPasscode fill:#D4D3D5,stroke:#514F59
    style EmailVerificationFlow fill:#D4D3D5,stroke:#514F59
    style EntersBirthInfo fill:#D4D3D5,stroke:#514F59
    style EntersResidencyInfo fill:#D4D3D5,stroke:#514F59
    style ConfirmsInfo fill:#D4D3D5,stroke:#514F59
    style UserStartedComputer fill:#E6E6FA,stroke:#6A5ACD
    style QueryParams fill:#E6E6FA,stroke:#6A5ACD
```

--------------------------------

### Android: Implement Connection Token Provider

Source: https://github.com/swan-io/docs/blob/main/docs/topics/merchants/in-person/cards/guide-initialize.mdx

Implement the `ConnectionTokenProvider` interface to fetch connection tokens. Handle success and failure callbacks appropriately.

```kotlin
class SampleTokenProvider : ConnectionTokenProvider {
  override fun fetchConnectionToken(callback: ConnectionTokenCallback) {
    try {
      val connectionToken = "$YOUR_CONNECTION_TOKEN" // fetch from Swan's API
      callback.onSuccess(connectionToken)
    } catch (e: Exception) {
      callback.onFailure(
        ConnectionTokenException("Failed to fetch connection token", e)
      )
    }
  }
}
```
Tokens:
Raw