After you create an account holder and a balance account, you can start issuing cards. Cards can either be virtual or physical. Cards also have to be associated with a Visa or Mastercard pre-approved use case, called a scheme program. By default, Adyen handles the scheme program for you in the background.
To issue a card, you'll need to create a 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 whether PCI compliance requirements apply to your use case, reach out to your Adyen contact.
Visual design for physical cards
Before you can start issuing 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 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
To issue a card, create a paymentInstrument resource. When making an API request, you set the card form factor to either physical or virtual. The other parameters that you need to include depend on the card form factor.
A virtual card is a card that has no physical form, and can only be used online. You receive the card details in the API response.
To create a virtual card, make a POST /paymentInstruments request specifying:
| Parameter | Required | Description |
|---|---|---|
| type |  |
Set to card. |
| balanceAccountId | |
The balance account ID that should be associated with the card. You can still update the balance account associated with a card at later time as long as the card status is Requested or Inactive. |
| card | |
Object that contains card configuration such as:
|
| status | By default, cards are created with an Active status but depending on your use case, you might also want to set the status to Requested or Inactive. |
In your request, you can also include optional parameters such as a human-readable description to help your staff differentiate between multiple cards under one balance account.
Here is how you would create a virtual card linked to a balance account with id BA1234123412341234:
curl https://balanceplatform-api-test.adyen.com/bcl/v1/paymentInstruments \
-u "ws@BalancePlatform.YOUR_BALANCE_PLATFORM":"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 returns the paymentInstrument resource, identified by its unique id.
{
"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"
}A physical card is 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.
When creating a physical card, you'll need to include additional information such as the card manufacturing profile and the delivery details in your API request.
To create a physical card, make a POST /paymentInstruments request specifying:
| Parameter | Required | Description | |
|---|---|---|---|
| type | |
Set to card. | |
| balanceAccountId | |
The balance account ID that should be associated with the card. You can still update the balance account associated with a card at later time as long as the card status is Requested or Inactive. |
|
| card | |
Object that contains card configuration such as:
|
|
| configuration | |
Object that contains settings for the physical card, including design and the configurationProfileId. | |
| status | By default, cards are created with an Active status but depending on your use case, you might also want to set the status to Requested or Inactive if you don't want to ship an active card to your user. |
In your request, you can also include optional parameters such as a human-readable description to help your staff differentiate between multiple cards under one balance account.
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.
curl https://balanceplatform-api-test.adyen.com/bcl/v1/paymentInstruments \
-u "ws@BalancePlatform.YOUR_BALANCE_PLATFORM":"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",
"deliveryContact": {
"address": {
"city": "Amsterdam",
"country": "NL",
"stateOrProvince": "NH",
"street": "274 Brannan Street, Suite 600",
"houseNumberOrName": "50",
"postalCode": "1020CD"
},
"name": {
"firstName": "Sam",
"lastName": "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 returns the paymentInstrument resource, identified by its unique id.
{
"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
This use case is only allowed in specific circumstances. Check with your Adyen contact if this is a functionality you can use.
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. Once the card has been received, the card can be activated.
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.