Quickstart Tutorial

Introduction

Visa Next platform provides a RESTful API infrastructure to create and manage virtual and physical cards, manage card controls (spend restrictions), and allow developers to subscribe to various entity state changes via webhooks. All services expose Instances and Collections interfaces with some exceptions. Instances are the instantiations of a single object or entity, and collections are multiple instances of an entity that can be returned by a REST call.

Visa Next Issuing APIs work around some base entities. Salient set of entities include a Cardholder, Card, Card Template, Authorization, and Transaction objects. The API provides various methods to manage lifecycle of these entities or objects. The following sections cover step-by-step process to get started with bare minimum requirements to get access, create base entities such as Card Template, Cardholder, Card, and a Transaction to fund the card. Advanced concepts allowing a client to participate in an auth decision are covered as well.

Getting Started

Developers can quickly get started with Visa Next API platform by getting access to the APIs in Sandbox environment. This sandbox provides API developers an ability to create objects required to issue cards, manage cards lifecycle, and simulate transactions. To get started, the sandbox requires a registration process to create base user credentials. This is available via a self-serve sign-up process to retrieve master credentials. Once master credentials are available, they can be used to create other objects. Master credentials will include an API Key, required in all calls.

Core Objects

Here is a quick overview of the core objects required to build a card issuing and management system.

Card Template

Allows creating a base object to provide default settings to issuable cards. The card template includes setting default expiry date, default address, and default set of card controls and other attributes. Using a card template, the subsequent issuing calls can be made succinct.

Cardholder

A cardholder is the consumer for whom a card is to be issued. There could be multiple cards issued for a cardholder. Wallet clients may associate one cardholder with each of their own consumers. A cardholder object contains demographic information about the consumer such as address, phone, and email etc.

Card

Card represents the 16-digit PAN number and additional attributes. A cardholder object is required for creating a card, and providing a card template reduces the need to specify several attributes. Card object also includes expiry date, CVV2 etc. Operations such as funding the card, managing its lifecycle etc. are available on it.

Transaction

A transaction object is a multi-purpose entity that represents all types of transactions made on a card object. It may include funding transactions, authorizations made while using the card, or when a refund is applied to the card.

Subscription

A subscription object can be created to listen to various objects’ state changes in Visa Next system. By creating a Subscription, the developer provides their webhook URL to be called when a certain event takes place. This allows a real-time access to Visa entity states without explicitly polling for statuses.

The following section will explain creating and working with aforementioned objects.

Create Objects (API calls)

Here is a quick overview of the core objects required to build a card issuing and management system.

Creating a Cardholder

One of the core entities in Visa Next Issuing platform is a cardholder. A cardholder represents the user for which the card is to be issued. It includes demographic information about the user. In addition to basic information, this object may also be used to contain KYC (Know Your Customer) details as required in some markets.

This POST RESTful API requires an Authorization header containing the access token retrieved in previous step (creating access token), and the API Key created for your (developer) account. The following example shows trimmed down list of request parameters for Cardholder creation, but the full schema of cardholder can be found in the API Reference section.

curl -X POST /api/v1/cardholders \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-API-KEY: ***"
-d '{
      "first_name": "Jane",
      "last_name": "Doe",
      "type": "primary",
      "address": {
      },
      "phone": "+14155551234",
      "email": "jane@example.com"
    }'
                  
201 Created
{
  "data": {
    "id": "123e4567-e89b-12d3-a456-556642440000",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+14155551234",
    "email": "jane@example.com",
    "address": {},
    "type": "primary",
    "metadata": {},
    "created": "2019-04-12T23:33:21+0000",
    "modified": "2019-04-12T23:33:21+0000"
  }
}
                  

In the response above, a cardholder ID has been generated, which will be used for the Card creation later.

Creating a Card Template

A Card Template is a base object to provide default settings to issuable cards. The card template includes setting default expiry date, default address, and default set of card controls and other attributes. Using a card template, the subsequent issuing calls can be made succinct.

Here is an example of card template creation.

  • cURL
curl -X POST /api/v1/cardtemplates \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-API-KEY: ***"
                  
Body parameter
{
  "expiry": {
    "year": "2021",
    "month": "05"
  },
  "tokenization": [
    "APPLE_PAY",
    "CHATIFY_PAY"
  ],
  "address": {},
  "type": "virtual",
  "funding_source": "a340635e-5d7b-11e9-8647-d663bd873d93",
  "number_limit": 50,
  "status": "ACTIVE"
}
                  

Response : 201 Created

{
  "id": "bc7badc4-5d7b-11e9-8647-d663bd873d93",
  "expiry": {
    "year": "2021",
    "month": "05"
  },
  "tokenization": [
    "APPLE_PAY",
    "CHATIFY_PAY"
  ],
  "address": {},
  "type": "virtual",
  "funding_source": "a340635e-5d7b-11e9-8647-d663bd873d93",
  "number_limit": 50,
  "status": "ACTIVE",
  "created": "2019-04-12T23:33:21+0000",
  "updated": "2019-04-12T23:33:21+0000"
}

Creating a Card

This step takes the cardholder and card template objects created in the previous steps, and some additional arguments for card issuance. This simple step is a realtime API that creates digital credentials using a preconfigured BIN. Card Template is a base object to provide default settings to issuable cards. The card template includes setting default expiry date, default address, and default set of card controls and other attributes. Using a card template, the subsequent issuing calls can be made succinct.

  • cURL
curl -X POST /api/v1/cards \
-H "Content-Type: application/json" \
-H "Accept: application/json"
-H "X-API-KEY: ***"
                  
Body parameter
{
  "cardholderid": "123e4567-e89b-12d3-a456-556642440000",
  "templateid": "bc7badc4-5d7b-11e9-8647-d663bd873d93",
  "display_name": "Jane Doe",
  "type": "VIRTUAL",
  "status": "ACTIVE"
}
                  

201 Created

{
  "data": {
    "id": "0cd57e6c-5d7c-11e9-8647-d663bd873d93",
    "display_name": "Jane Doe",
    "address": {},
    "last_four": "1111",
    "expiry": {
      "month": "05",
      "year": "2021"
    },
    "pan": "__________1111",
    "cvv2": "___",
    "cardholderid": {},
    "customizations": {},
    "type": "VIRTUAL",
    "metadata": {},
    "status": "ACTIVE",
    "created": "2019-04-12T23:33:21+0000",
    "updated": "2019-04-12T23:33:21+0000",
    "templateid": "bc7badc4-5d7b-11e9-8647-d663bd873d93"
  }
}

Retrieving details of a card

By default, the sensitive information such as PAN number and CVV2 of a card are not returned while creating a card, and an additional call is required to do so. In production developer may want to call this API after doing a step-up auth of their users.

  • cURL
curl -X GET /api/v1/cards/0cd57e6c-5d7c-11e9-8647-d663bd873d93 \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Show-PAN: true" \
-H "X-API-KEY: ***"
                  

Response : 200 OK

{
  "data": {
    "id": "0cd57e6c-5d7c-11e9-8647-d663bd873d93",
    "display_name": "Jane Doe",
    "address": {},
    "currency_code": "USD",
    "last_four": "1111",
    "expiry": {
      "month": 1,
      "year": 2020
    },
    "pan": "4111111111111111",
    "cvv2": "123",
    "cardholderid": "123e4567-e89b-12d3-a456-556642440000",
    "customizations": {},
    "type": "VIRTUAL",
    "metadata": {},
    "status": "ACTIVE",
    "created": "2019-04-12T23:33:21+0000",
    "updated": "2019-04-12T23:33:21+0000",
    "templateid": "bc7badc4-5d7b-11e9-8647-d663bd873d93"
  }
}

Funding a card

Once the card has been issued, it contains a zero money balance. Funding API takes in card ID and funding source ID as the base parameters along with amount details to fund the underlying account for a given card. This API creates a transaction object that contains debit/credit transactions and keeps a trail of all calls on a card.

  • cURL
curl -X POST /api/v1/cards/0cd57e6c-5d7c-11e9-8647-d663bd873d93/transactions \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-API-KEY: ***"
                  
Body parameter
{
  "amount": 10.5,
  "type": "reload",
  "funding_source": "<funding source ID>",
  "currency_code": "USD"
}
                  

Response: 201 Created

{
  "data": {
    "id": "tran_1",
    "amount": 10.5,
    "currency_code": "USD",
    "country_code": "US",
    "created": "<timestamp>",
    "entry_mode": "digitalreload",
    "status": "pending",
    "card": {
      "id": "0cd57e6c-5d7c-11e9-8647-d663bd873d93",
      "display_name": "Jane Doe",
      "address": {},
      "currency_code": "USD",
      "last_four": "1111",
      "expiry": {
        "month": 1,
        "year": 2020
      },
      "pan": "___________1111",
      "cvv2": "___",
      "metadata": {},
      "status": "ACTIVE",
      "created": "2019-04-12T23:33:21+0000",
      "updated": "2019-04-12T23:33:21+0000"
    }
  }
}

Subscriptions: Creating webhooks to listen to entity state changes

Service broker helps orchestrate communication between services, and enables invocation of webhooks setup by developers. Webhooks enable developers to subscribe to certain events associated with an entity. For instance, you can provider your callback/webhook URL to be invoked every time a card is deactivated, canceled, or a transaction settles etc. Basic API structure is as follows:

Webhooks enable developers to subscribe to certain events associated with an entity. For instance, you can provider your callback/webhook URL to be invoked every time a card is deactivated, canceled, or a transaction settles etc. Basic API structure is as follows:

In this example, everytime a new card is issued for specific API userID, developer’s URL will be invoked with a body containing the changed entity (a card in this case). Developers must provide authentication or handshake information for allowing inbound calls.

  • cURL
curl -X POST /api/v1/subscriptions \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-API-KEY: ***"
                  
Body parameter
{
  "event": "card.created",
  "forUserId": "<userId>",
  "state": "active | inactive",
  "description": "webhook to receive details of all created cards",
  "callback": {
    "url": "http://somewalletprovider.com/statusupdater",
    "symkey": "some shared secret",
    "access-token": "some access token for inbound auth",
    "retries": 5
  }
}

Response : 201 Created

{
  "subscriptionId": 1,
  "event": "card.created",
  "forUserId": "<userId>",
  "state": "active | inactive",
  "description": "webhook to receive details of all created cards",
  "callback": {
    "url": "http://somewalletprovider.com/statusupdater",
    "symkey": "some shared secret",
    "access-token": "some access token for inbound auth",
    "retries": 5
  },
  "created": "<timestamp>",
  "modified": "<timestamp>"
}

Simulating a Transaction

Developers can simulate a transaction for the newly issued card, and test triggering of card controls etc. This can be done using the following API.

  • cURL
curl -X POST /api/v1/simulations \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-API-KEY: ***"
                  
Body parameter
{
  "cardid": "abc124",
  "amount": "10.00",
  "currency_code": "USD",
  "entry_mode": "ecommerce",
  "merchantid": "merch1",
  "bypass_controls": false
}

Response : 201 Created

Retrieving Transactions

Transactions for a card (or simulations in sandbox) can be retrieved using the following simple API. It returns a list of transactions issued for the provided cardID.

  • cURL
curl -X GET /api/v1/cards/1/transactions \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-API-KEY: ***"
                  

Response

{
  "data": [
    {
      "id": "auth_1",
      "amount": 100,
      "currency_code": "USD",
      "country_code": "US",
      "created": "<timestamp>",
      "entry_mode": "contactless",
      "status": "pending",
      "card": {
        "id": "abc124",
        "display_name": "John Doe",
        "address": {},
        "currency_code": "USD",
        "last_four": "4444",
        "expiry": {
          "month": 1,
          "year": 2020
        },
        "pan": "___________4444",
        "cvv2": "___",
        "metadata": {},
        "status": "active",
        "created": "<timestamp>",
        "updated": "<timestamp>"
      },
      "merchant": {
        "id": "merch123",
        "mcc": 1,
        "address": {},
        "branch": "branch details",
        "hours": {
          "openhour": "900",
          "closehour": "2200"
        }
      }
    }
  ]
}