Managing cards

This page explains how to manage cards by API and has the following sections:

• Creating a new card
• Blocking or cancelling cards
• One-time top ups
• Auto top ups

How to get and display cards will be described in the next sections.

Cards can also be managed manually from the cards section of our web app.

Creating a new card

To create a new card, you first need to create the user and get the account details

Once you have done this, you can create a new card like this:

curl {baseURL}/cards  
-H "Authorization:your-api-key"  
-H "Content-type: application/json"  
-X POST  
-d '{  
  "userId": "user-id",
  "accountId": "yordex-pay-account-id",
  "currency": "GBP",
  "virtual": false,
  "multipleOrders": true,
  "createExpense": true,
  "shippingAddress": {
  	"address1": "addressLine1",
 	  "address2": "addressLine2",
	  "postalCode": "postalCode",
	  "city": "city",
	  "countryCode": "GB"
  } 
}'

The currency has to be the same as the account currency.

virtual indicates if you want to create a physical card (false) or a virtual card (true).

The multipleOrders field indicates that this card will be used for more than one transaction. This should always be true unless a card is being used for a single-use only. Learn more about single-use cards here.

createExpenses is used to determine if a card should create orders with the transactions made. By default, you should set this to true, there is no detriment to this and allows you to make the most of our orders APIs. If you would like to set this to false please let our implementation team know so we can adjust the account config to accommodate this.

The cardProgram is an optional field and will default to the default card program set by your banking API provider.

The shippingAddress is where cards will be sent to. If the shippingAddress is not provided, a physical card will be shipped to the trading address set on your profile page. This field is not required for virtual cards.

The response looks like this:

{
  "id": ":id",
  "scheme": "VISA",
  "lastDigits": "0763",
  "expiryDate": "2022-04-30",
  "nameOnCard": "FIRST LAST",
  "balanceInCents": 10000,
  "currency": "GBP",
  "name": "MASTERCARD x0763",
  "status": "ACTIVATED",
  "virtual": true,
  "userId": ":userId",
  "multipleOrders": true,
  "createExpense": true
}

For security reasons this API does not return the full card details (16-digit number and CV2 code). How to get these is described in the displaying cards section.

Blocking or cancelling cards

You can block and unblock cards as many times as you like but cancelling is irreversible.

To block a card you can call this API:

curl {baseURL}/cards/:card-id/block  
-H "Content-type: application/json"  
-X POST

Unblocking and cancelling works the same way:

• /cards/:card-id/unblock
• /cards/:card-id/cancel

One-time top ups

Cards can be topped up like this

curl {baseURL}/cards/:card-id/topup  
-H "Authorization:your-api-key"  
-H "Content-type: application/json"  
-X POST 
-d '{ 
{ 
  "topUpAmountInCents": 1000,
  "customerTransactionId": "123456" // Optional
}'

card-id is the id of the card you are topping up. The topUpAmountInCents is the amount you want to top up the card by in the currency of the card. As the name suggests, that amount is in cents so if this is a GBP card, we are topping up by £10 in this example.

customerTransactionId is an optional field that will store a transaction ID of your choosing against a top-up transaction. When retrieving your transactions later, this ID will be returned to you.

Auto top ups

Auto top ups can be triggered at a specified frequency or when the card is below a certain balance. You can auto top up by or to a specified amount.

Auto top ups can be enabled like this:

curl {baseURL}/cards/:card-id/balances  
-H "Authorization:your-api-key"  
-H "Content-type: application/json"  
-X PATCH 
-d '{ 
  "targetBalanceInCents": 20000,
  "autoTopUpFrequency": null,
  "minimumBalanceInCents": 10000
  "autoTopUpType": "AMOUNT",
}'

The targetBalanceInCents is the amount to top up. autoTopUpType defines it you to up by or to that amount

• AMOUNT: the targetBalanceInCents is the amount to top up by. In this example, we top up the card by £20, so if the balance was £10 than after the auto top up it will be £30
• TARGET: the targetBalanceInCents is the amount to top up to. If that had been set, we would top up the card to £20, so if the balance was £10 than after the auto top up it would be £20

autoTopUpFrequency and minimumBalanceInCents define when to auto top up:

To disable auto top ups, just set all fields to null

Viewing auto top up schedules

The next scheduled date and amount of an upcoming auto top ups on a card can be viewed by sending a GET cards request:

curl {baseURL}/cards/:card_id
-H "Authorization:your-api-key"  
-X GET

The response for a card with an auto top up configured will look like this:

"content": [
  {
    "id": ":card_id",
    "scheme": "VISA",
    "lastDigits": "0763",
    "expiryDate": "2022-04-30",
    "nameOnCard": "Maya Angelou",
    "balanceInCents": 10000,
    "currency": "GBP",
    "name": "MASTERCARD x0763",
    "status": "ACTIVATED",
    "virtual": true,
    "userId": ":userId",
    "targetBalanceInCents": 100000,
    "nextTopUpDate": "2023-08-22"
  }
}

The key fields to consider here are targetBalanceInCents and nextTopUpDate. More information on the card object fields can be found here.