Create cards

All cards are represented by a paymentInstrument resource. Creating a paymentInstrument resource results in creating either a physical or a virtual card. This process of creating a card is referred to as issuing a card.

Cards have to be associated with a Visa or Mastercard pre-approved use case for a card. This is called a scheme program. By default, we handle this for you in the background.

After you have created a card, you can perform all the other aspects of the card lifecycle (such as reordering or cancelling a card) by updating the paymentInstrument resource.

PCI compliance

The scope for PCI compliance depends on your use case—the type of cards you'll issue and how the cards will be used. To know more if PCI compliance requirements apply to your use case, reach out to your Adyen contact.

Visual design for physical cards

Before you can start sending physical cards to your users, you will need to create a design for your cards and for the mail that the card is sent with. Each card design has to be explicitly approved by Visa or Mastercard.

Work with your Adyen contact to finalize the card design and the mailer material before you go live.

Create a card

You need to create a paymentInstrument resource to issue either a:

• Virtual card: A card that has no physical form, and can only be used online. You receive the card details in the API response.
• Physical card: A card that's printed and shipped to the cardholder. You do not receive the card details in the API response. Sending a request to create a physical card also starts an order. Before you create a physical card, you need to finalize the card design and mailer material together with your Adyen contact.

The parameters you need to include depend on whether you want to create a virtual or a physical card:

• Virtual
• Physical

To issue a virtual card, make a POST /paymentInstruments request specifying:

Parameter	Required	Description
type		Specify card.
balanceAccountId		The ID of the balanceAccount where this payment instrument will deduct balance from. The payment instrument will be owned by the balance account's account holder.
issuingCountryCode		Two-character country code defined in ISO-3166-1 alpha-2.
description		Your description for this card. We recommend to make this a clear, human-readable description to help differentiate in case the balance account has multiple cards associated with it.
status		By default, cards are created as Active. Depending on your use case, you might want to create cards as Inactive or Requested.
card.formFactor		Specify virtual.
card.cardHolderName		The name of the cardholder. This is the name that will be shown on the card.
card.brand		The card scheme. Allowed values: mc or visa.
card.brandVariant		The card variant. For example, mcdebit or mcprepaid for Mastercard.

Here is how you would create a virtual card linked to a balance account with id BA1234123412341234:

https://docs.adyen.com/issuing/create-cards#create-a-virtual-card

Create a virtual card

curl https://balanceplatform-api-test.adyen.com/bcl/v1/paymentInstruments \
-u "ws@Company.YourCompany":"YOUR_WS_PASSWORD" \
-H "content-type: application/json" \
-d '{
    "type": "card",
    "description": "{hint:Your human-readable description for this card}S.Hopper - Main card{/hint}",
    "balanceAccountId": "BA1234123412341234",
    "issuingCountryCode": "NL",
    "card": {
      "cardholderName": "Sam Hopper",
      "brand": "mc",
      "brandVariant": "mcdebit",
       "formFactor": "virtual"
    }
}'

The response contains the new paymentInstrument resource, which contains card details.

https://docs.adyen.com/issuing/create-cards#response

Response

{
    "balanceAccountId": "BA1234123412341234",
    "description": "S.Hopper - Main card",
    "issuingCountryCode": "NL",
    "status": "Active",
    "type": "card",
    "card": {
        "brand": "mc",
        "brandVariant": "mcdebit",
        "cardholderName": "Sam Hopper",
        "formFactor": "virtual",
        "bin": "555544",
        "cvc": "686",
        "expiration": {
            "month": "07",
            "year": "2023"
        },
        "lastFour": "2787",
        "number": "5555444400092787"
    },
    "id": "PI3227C223222B5BPCMFXD2XG"
}

To issue a physical card, make a POST /paymentInstruments request providing:

Parameter	Required	Description
type		Specify card.
balanceAccountId		The ID of the balanceAccount where this payment instrument will deduct balance from. The payment instrument will be owned by the balance account's account holder.
issuingCountryCode		Two-character country code defined in ISO-3166-1 alpha-2.
description		Your description for this card. We recommend to make this a clear, human-readable description to help differentiate in case the balance account has multiple cards associated with it.
status		By default, cards are created as Active. Depending on your use case, you might want to create cards as Inactive or Requested.
card.formFactor		Specify physical.
card.cardHolderName		The name of the cardholder. This is the name that will be shown on the card.
card.brand		The card scheme. Allowed values: mc or visa.
card.brandVariant		The card variant. For example, mcdebit or mcprepaid for Mastercard.
card.deliveryAddress		Object that contains the cardholder's delivery address. This is where the physical card will be shipped to.
configuration		Object that contains the configurationProfileId, which specifies the attributes (such as design and mailer material) of the physical card. You will receive this value from your Adyen contact.

Here is how you would create a physical card linked to a balance account with id BA1234123412341234. In this example, we'll create a card with an Inactive status, and we'll only activate the card once the user receives it.

https://docs.adyen.com/issuing/create-cards#create-a-physical-card

Create a physical card

curl https://balanceplatform-api-test.adyen.com/bcl/v1/paymentInstruments \
-u "ws@Company.YourCompany":"YOUR_WS_PASSWORD" \
-H "content-type: application/json" \
-d '{
  "type": "card",
  "issuingCountryCode": "NL",
  "balanceAccountId": "BA1234123412341234",
  "status": "Inactive",
  "card": {
    "formFactor": "physical"
    "brand": "mc",
    "brandVariant": "mcdebit",
    "cardholderName": "Sam Hopper",
    "deliveryAddress": {
      "city": "Amsterdam",
      "country": "NL",
      "stateOrProvince": "NH",
      "street": "274 Brannan Street",
      "street2": "Suite 600",
      "postalCode": "1020CD",
      "recipientName": "Sam Hopper"
    },
    "configuration": {
      "configurationProfileId": "YOUR_CONFIGURATION_PROFILE_ID"
    },
    "expiry":{
      "month":8,
      "year":2024
    }
  },
  "description": "{hint:Your human-readable description for this card}S.Hopper - Main card{/hint}"
}'

The response contains the new paymentInstrument resource.

https://docs.adyen.com/issuing/create-cards#response

Response

{
  "balanceAccountId": "BA1234123412341234",
  "description": "S.Hopper - Main card",
  "issuingCountryCode": "NL",
  "status": "Inactive",
  "type": "card",
  "card": {
    "brand": "mc",
    "brandVariant": "mcdebit",
    "cardholderName": "Sam Hopper",
    "configuration": {
      "configurationProfileId": "YOUR_CONFIGURATION_PROFILE_ID"
    },
    "formFactor": "physical",
    "bin":"555544",
    "expiration":{
      "month":"08",
      "year":"2023"
    },
    "lastFour":"1589"
  },
  "id": "PI3227C223222B5BPCMFXD2XG"
}

In test environment, you will not receive physical test cards.

Before you start creating live physical cards, you will need to create a visual design for your cards and the mailer the card is sent in. Reach out to your Adyen contact to specify the design and mailing collateral you want to send.

Multiple cardholders under one balance account

Some business cases might require having multiple cardholders under one balance account, but only the account holder will go through the KYC process. For example:

• Creating named cards for multiple employees in one company.
• Creating additional cards for a spouse or children.

After the main account holder completes the KYC process, you can start creating cards for additional cardholders.

To do this, make another POST /paymentInstruments request.

Here is how you would create another virtual card linked to same balance account BA1234123412341234 for a different cardholder:

{
  "type": "card",
  "description": "{hint:Your human-readable description for this card}Supplementary card{/hint}",
  "balanceAccountId": "BA1234123412341234",
  "issuingCountryCode": "NL",
  "card": {
    "cardholderName": "Jean Hopper",
    "brand": "{hint:Card scheme: mc or visa}mc{/hint}",
    "brandVariant": "mcdebit",
     "formFactor": "virtual"
  }
}

Activate a card

For physical cards, we recommend keeping cards inactive until your user has received the card, and confirmed it by providing you the full card number.

To make a card active, make a PATCH /paymentInstruments/{id} request and update the status to Active.

Here is an example updating the status for payment instrument with id PI3227C223222B5BPCMFXD2XG.

curl https://balanceplatform-api-test.adyen.com/bcl/v1/paymentInstruments/PI3227C223222B5BPCMFXD2XG \
-u "ws@Company.YourCompany":"YOUR_WS_PASSWORD" \
-H "content-type: application/json" \
-X PATCH \
-d '{
    "status":"Active"
}'