GuidesAPI ReferenceChangelog
Log In

Implement Card Switch

Suggest Edits

Using Pinwheel, you can have your user easily switch their payout card on file, helping you capture the wallet share and drive increased engagement with your products.

Step 1: Subscribe to Webhook Events

Subscribe to the following webhook events when changes to the user's payout card settings are made:

  • card_switch.added: Notifies you when a card switch is available.
  • payout_cards.added: Notifies you when changes to payout cards are made.

You can subscribe to either webhooks or both. Register a webhook endpoint using Pinwheel's Create Webhook, as the following example illustrates.

POST /v1/webhooks
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET
{
  "url": "https://your-domain.com/webhook_endpoint",
  "status": "ACTIVE",
  "enabled_events": [
    "card_switch.added"
  ]
}

Step 2: Update Link token

Card switch is offered as an additional option within the existing direct deposit switch flow. If you want the user to be given the affordance, include the target card in the card object during Link token creation. Card data is stored in a secure internal vault, and Pinwheel is PCI DSS Level 2 compliant.

To create a Link token, see Create Link Token.

To filter out platforms from the search that do not support card switch, add card_switch to your set of required jobs.

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET
{
  "org_name": "YOUR APP NAME",
  "end_user_id": "my_user_12345",
  "allocation": {
    "targets": [
      {
        "type": "checking",
        "routing_number": "07464755",
        "account_number": "193464372203"
      }
    ]
  },
  "required_jobs": [
    "direct_deposit_switch"
  ],
  "card": {
    "card_name": "My Debit Card",
    "card_number": "5102545105675100",
    "cvc": "246",
    "expiration_date": "07/24"
  }
}

Step 3: Initialize Link

Use the Link token to open the Link modal in your client application. In addition to passing in the token, you can optionally pass several callback handlers.

<!DOCTYPE html>
<html>
  <head>
    <script src="https://cdn.getpinwheel.com/pinwheel-v2.3.js"></script>
    <script>
      Pinwheel.open({
        linkToken: "INSERT LINK TOKEN",
          onSuccess: (result) => {
            console.log("Job succeeded!");
        },
      });
    </script>
  </head>
  <body></body>
</html>

The onSuccess callback handler is executed on job success and contains metadata about the direct deposit and/or card switch jobs.

Step 4: Respond to Webhook Events

A card switch is always executed after the direct deposit switch job. You receive the standard direct deposit switch webhooks, including account.added , direct_deposit_switch.added or direct_deposit_allocations.added.

Pinwheel sends analogous webhooks when information about payout cards is available or when a card switch job successfully executes.

Pinwheel firespayout_cards.added when data on the payout card on the user's account is available. 

{
  "event": "payout_cards.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "payout_cards",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success"
  }
}

Pinwheel fires card_switch.added when a card switch job executes on the user's account, for example, when the card on file is updated to the one passed in during Link token creation.

{
  "event": "card_switch.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "card_switch",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "params": {
      "card_name": "My Debit Card"
    }
  }
}

Step 5: Query for Job Results

If you are not subscribed to webhook events, or there was an issue handling thecard_switch.added or payout_cards.added events, you can fetch job results by querying the Jobs endpoint with the link_token_id pertaining to a specific user.

Request

GET /v1/jobs?link_token_id=97f420ff-5d0a-46ee-9cfc-6f17d5d31256
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET

Response

{
  "meta": {
    "count": 1
  },
  "data": [
    {
      "id": "625f0acd-4a16-4708-a075-2be67918a9ad",
      "account_id": "03bbc20e-bc39-464a-b4dc-4b63ffb7213d",
      "link_token_id": "97f420ff-5d0a-46ee-9cfc-6f17d5d31256",
      "name": "card_switch",
      "timestamp": "2021-01-12T02:36:01.287148+00:00",
      "outcome": "success",
      "params": {
        "card_name": "My Debit Card"
      }
    }
  ]
}

Please contact [email protected] for access to our Developer Dashboard.

Updated 12 days ago