Activate physical cards

Activate a physical card with the API after the cardholder receives it.

Methods

Physical cards can be activated in two ways:

1. First transaction: The cardholder enters their PIN during an in-person chip and PIN payment.
2. API: Call the activatePhysicalCard mutation (explained in this guide).

Activation reminder notifications

Swan can send reminder emails when users don't activate their physical card after delivery.

• Reminder notifications are sent at configured intervals (for example, 5, 10, and 15 days after estimated delivery).
• Notifications stop automatically when the user activates their card or when all reminders have been sent.
• Partners can enable or disable this feature from Dashboard > Settings > Notifications.

Review the email notifications table on the Projects page for more information.

Guide

Prerequisites

• Physical card status: ToActivate.
• You have the identifier printed on the back of the physical card.
• You're authenticated with a user access token for the cardholder.

1. Call the activatePhysicalCard mutation.
2. Add the identifier from the back of the physical card (line 4).
3. Add your consentRedirectUrl (line 5).
4. Add the success payload, including the consentUrl (line 17).
5. Add rejections (not shown).

Mutation

🔎 Open the mutation in API Explorer

Mutation

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

Payload

The cardholder must consent to activate the physical card. Open the consentUrl returned in the payload to complete Strong Customer Authentication (SCA) with Swan. After consent, the physical card status changes to Activated.

Payload

{
  "data": {
    "activatePhysicalCard": {
      "__typename": "ActivatePhysicalCardSuccessPayload",
      "physicalCard": {
        "expiryDate": "12/28",
        "identifier": "$YOUR_PHYSICAL_CARD_IDENTIFIER",
        "statusInfo": {
          "status": "ToActivate"
        }
      },
      "consent": {
        "consentUrl": "https://identity.swan.io/consent?consentId=$YOUR_CONSENT_ID&env=Sandbox"
      }
    }
  }
}