Search

Are you looking for test card numbers?

Would you like to contact support?

Issuin icon

Create cards

Learn how to create and activate 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.

You have to be fully PCI DSS Compliant to issue virtual cards.

To issue a virtual card, 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: The name of the card holder. This is the name that will be shown on the card.
  • card.formFactor: Specify virtual.
  • card.expiry.*: The expiration date you want to set for the card. Minimum of 2 years from when the card was created.
  • description: A human readable description for this card.
  • product: The card scheme. Allowed values: mc or visa.
  • issuingCountryCode: Two-character country code defined in ISO-3166-1 alpha-2.
POST /paymentInstruments request
{
  "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"
  },
  "description": "{hint:Your human readable description for this card}PaymentInstrument 1234{/hint}",
}

The response contains the new paymentInstrument resource, which contains the cardNumber.

Response
{
  "id": "PI6789678967896789",
  "balanceAccountId": "BA1234123412341234",
  "issuingCountryCode": "NL",
  "product": "mc",
  "type": "card",
  "card": {
    "brand": "mc",
    "bin": "555544",
    "cardNumber": "5555444400000001",
    "lastFour": "0001",
    "cardholderName": "Simon Hopper",
    "cvc": "737",
    "expiry": {
      "month": 10,
      "year": 2022
    },
    "formFactor": "virtual"
  },
  "description": "{hint:Your human readable description for this card}PaymentInstrument 1234{/hint}",
  "status": "inactive"
}

To issue a physical card, 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: The name of the card holder. This is the name that will be 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 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.
  • description: A human readable description for this card.
POST /paymentInstruments request
{
  "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
    }
  },
  "description": "{hint:Your human readable description for this card}PaymentInstrument 1234{/hint}",
}

The response contains the new paymentInstrument resource.

Response
{
  "id": "PI6789678967896789",
  "balanceAccountId": "BA1234123412341234",
  "card": {
    "brand": "visa",
    "bin": "411111",
    "cardNumber": "****",
    "lastFour": "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",
  "description": "{hint:Your human readable description for this card}PaymentInstrument 1234{/hint}",
  "status": "inactive",
  "type": "card"
}

By default, physical cards will have their card numbers masked with ****. If your business is fully PCI DSS compliant, you can request to receive full card numbers.

While you are testing, some responses may contain a testOnlyData object. We return this data to make your integration easier. Do not build logic against this data as it will not be returned on the live platform.

While testing, you will not receive physical test cards. Physical cards return raw card numbers in testOnlyData on test so you can make test transactions with the card.

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.

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.

PATCH /paymentInstruments/{id} request
{
    "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.
  • description: A human readable description for this card.
POST /paymentInstruments
{
  "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
    }
  },
  "description": "{hint:Your human readable description for this card}PaymentInstrument 1234{/hint}",
}

The response contains the new paymentInstrument resource.

Response
{
  "id": "PI6789678967896789",
  "balanceAccountId": "BA1234123412341234",
  "card": {
    "brand": "visa",
    "bin": "411111",
    "cardNumber": "****",
    "lastFour": "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",
  "description": "{hint:Your human readable description for this card}PaymentInstrument 1234{/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.

Next steps