Create cards

All cards are represented by a paymentInstrument resource. Creating a paymentInstrument resource creates a card. Card creation is referred to as issuing a card.

You can create both physical and virtual cards.

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

All other aspects of the card lifecycle such as reordering or cancelling cards are performed by updating the paymentInstrument resource.

Create a card

Create a paymentInstrument to issue a card. If you send a request to create a physical card, this will also trigger an order for a physical card that will be printed and shipped to the card holder.

{
  "type": "card",
  "balanceAccountId": "BA1234123412341234",
  "product": "{hint:Card scheme: mc or visa}mc{/hint}",
  "issuingCountryCode": "NL",
  "card": {
    "cardholderName": "Simon Hopper",
    "expiry":{
        "month":10,
        "year":2022
    },
    "formFactor": "virtual"
  },
  "reference":"{hint:Your unique identifier for this resource}myPaymentInstrument_12345{/hint}"
}

{
  "id": "PI6789678967896789",
  "balanceAccountId": "BA1234123412341234",
  "issuingCountryCode": "NL",
  "product": "mc",
  "type": "card",
  "card": {
    "brand": "mc",
    "bin": "555544",
    "cardNumber": "5555444400000001",
    "last4": "0001",
    "cardholderName": "Simon Hopper",
    "cvc": "737",
    "expiry": {
      "month": 10,
      "year": 2022
    },
    "formFactor": "virtual"
  },
  "reference": "{hint:Your unique identifier for this resource}myPaymentInstrument_12345{/hint}",
  "status": "inactive"
}

{
  "type": "card",
  "balanceAccountId": "BA1234123412341234",
  "issuingCountryCode": "NL",
  "product": "mc",
  "card": {
    "cardholderName": "Simon Hopper",
    "deliveryAddress": {
      "city": "Amsterdam",
      "country": "NL",
      "stateOrProvince": "NH",
      "street": "274 Brannan Street",
      "street2": "Suite 600",
      "postalCode": "1020CD",
      "recipientName": "Simon Hopper",
    },
    "formFactor": "physical",
    "expiry":{
        "month":10,
        "year":2022
    }
  },
  "reference":"{hint:Your unique identifier for this resource}myPaymentInstrument_12345{/hint}"
}

{
  "id": "PI6789678967896789",
  "balanceAccountId": "BA1234123412341234",
  "card": {
    "brand": "visa",
    "bin": "411111",
    "cardNumber": "****",
    "last4": "1111",
    "cardholderName": "Simon Hopper",
    "cvc": "string",
    "deliveryAddress": {
      "city": "Amsterdam",
      "country": "NL",
      "stateOrProvince": "NH",
      "street": "274 Brannan Street",
      "street2": "Suite 600",
      "postalCode": "1020CD",
      "recipientName": "Simon Hopper"
    },
    "expiry": {
      "month": 10,
      "year": 2022
    },
    "formFactor": "physical",
    "{hint:Returned only in test. This will not be returned on live.}testOnlyData{/hint}":{  
        "cardNumber":4111111111111111,
        "cvc":"737"
    },
  },
  "issuingCountryCode": "string",
  "product": "string",
  "reference": "{hint:Your unique identifier for this resource}myPaymentInstrument_12345{/hint}",
  "status": "inactive",
  "type": "card"
}

You need to activate the card before it can be used.

Activate a card

By default, newly created cards have a status of inactive.

To make a card active, update the status to active. Here is an example updating the status for paymentInstruments.id PI6789678967896789.

{
    "status":"active"
}

You can optionally create the paymentInstrument with a status of active. For physical cards, we recommend keeping cards inactive until your user has received the card and confirms it by providing you the full card number.

Multiple card holders under one balance account

Some business cases might require you to onboard a single user but still create cards for other users who will not go through a separate KYC process. For example, creating named cards for multiple employees in one company or creating additional cards for a spouse or children. These scenarios are only allowed in specific circumstances, so please confirm with your Adyen contact if this is a functionality you can use.

To create additional cards for additional card holders, make a POST /paymentInstruments request providing:

• type: Specify card.
• balanceAccountId: The ID of the balanceAccount the paymentInstrument will deduct balance from. The paymentInstrument will be owned by the balance account's accountHolder.
• card.cardHolderName: Name of the card holder. This is the name that will be shown or printed on the card.
• card.deliveryAddress.*: Required for physical cards. The address the card will be shipped to. The billing address on the accountHolder will be used for AVS.
• card.formFactor: Specify either virtual or physical.
• card.expiry.*: The expiration you want to set for the card. The expiry date should be between 2 to 4 years from when the card was created.
• reference: Your unique ID for the card.

{
  "type": "card",
  "balanceAccountId": "BA1234123412341234",
  "card": {
    "cardholderName": "Lisa Hopper",
    "deliveryAddress": {
      "city": "Amsterdam",
      "country": "NL",
      "stateOrProvince": "NH",
      "street": "274 Brannan Street",
      "street2": "Suite 600",
      "postalCode": "1020CD",
      "recipientName": "Lisa Hopper"
    },
    "formFactor": "physical",
    "expiry":{
      "month":10,
      "year":2022
    }
  },
  "reference": "{hint:Your unique identifier for this resource}myPaymentInstrument_18907{/hint}"
}

The response contains the new paymentInstrument resource.

{
  "id": "PI6789678967896789",
  "balanceAccountId": "BA1234123412341234",
  "card": {
    "brand": "visa",
    "bin": "411111",
    "cardNumber": "****",
    "last4": "1111",
    "cardholderName": "Lisa Hopper",
    "cvc": "string",
    "deliveryAddress": {
      "city": "Amsterdam",
      "country": "NL",
      "stateOrProvince": "NH",
      "street": "274 Brannan Street",
      "street2": "Suite 600",
      "postalCode": "1020CD",
      "recipientName": "Lisa Hopper"
    },
    "expiry": {
      "month": 10,
      "year": 2022
    },
    "formFactor": "physical"
  },
  "issuingCountryCode": "string",
  "product": "string",
  "reference": "{hint:Your unique identifier for this resource}myPaymentInstrument_18907{/hint}",
  "status": "inactive",
  "type": "card"
}

Manage card lifecycle

Creating and activating the payment instrument allows your user to start making purchases with the newly issued card. Next you will have to manage the card lifecycle, which includes updating card information, reordering new cards for lost or expired cards, and cancelling cards.

Card visual design

Before you can start sending live cards to your users, you will need to create a design for your cards and a design 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.