Convert to Physical Card

Upgrades an existing virtual card into a physical card. The same 16-digit PAN is preserved, so the cardholder’s stored online credentials continue to work seamlessly.

POST/v1/cards/{id}/convert_to_physical

🪪

The user must have completed full KYC (kyc.level = full) before you can convert to a physical card. Shipping is currently available within the UAE only.

Path parameters

Field	Type	Description
`id`required	string	Virtual card ID, e.g. `card_01HX7...`

Body parameters

Field	Type	Description
`shipping_address`required	object	Where the physical card should be delivered.
`recipient_name`	string	Name printed on the shipping label. Defaults to the user's legal name.
`embossed_name`	string	Name printed on the card face. Max 21 characters A–Z and spaces.
`design`	string default: default	Card design code (contact your onboarding manager).
`delivery_speed`	enum default: standard	standard \| express

`shipping_address` sub-fields

Field	Type	Description
`line1`required	string	Street line 1.
`line2`	string	Apt / suite / building.
`city`required	string	e.g. Dubai.
`country`required	ISO 3166-1 alpha-2	Must be `AE` at this time.
`postal_code`	string	If applicable.
`phone`required	string	E.164 phone for the courier.

Request

curl -X POST https://api.vaultspay.ae/v1/cards/card_01HX7.../convert_to_physical \
  -H "Authorization: Bearer sk_test_yourApiKeyHere" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: c1f5a6d8-7b11-4c9b-a0d2-5ae7b0d4f3c2" \
  -d '{
    "embossed_name": "ALI HASSAN",
    "delivery_speed": "express",
    "shipping_address": {
      "line1": "Sheikh Zayed Road",
      "line2": "Tower 3, Apt 1205",
      "city": "Dubai",
      "country": "AE",
      "phone": "+971501234567"
    }
  }'

const physical = await vp.cards.convertToPhysical('card_01HX7...', {
  embossed_name: 'ALI HASSAN',
  delivery_speed: 'express',
  shipping_address: {
    line1: 'Sheikh Zayed Road',
    line2: 'Tower 3, Apt 1205',
    city: 'Dubai',
    country: 'AE',
    phone: '+971501234567'
  }
})

physical = vaultspay.Card.convert_to_physical(
  'card_01HX7...',
  embossed_name='ALI HASSAN',
  delivery_speed='express',
  shipping_address={
      'line1': 'Sheikh Zayed Road',
      'line2': 'Tower 3, Apt 1205',
      'city': 'Dubai',
      'country': 'AE',
      'phone': '+971501234567'
  }
)

Response

202 Accepted

{
  "id": "card_01HX71YM6FJ3A8W7T5K6NRB2DN",
  "object": "card",
  "type": "physical",
  "status": "shipping",
  "shipping": {
    "courier": "Aramex",
    "tracking_number": "AWB123456789",
    "estimated_delivery": "2026-04-29",
    "address": {
      "line1": "Sheikh Zayed Road",
      "line2": "Tower 3, Apt 1205",
      "city": "Dubai",
      "country": "AE"
    }
  },
  "last4": "4321",
  "expiry_month": 11,
  "expiry_year": 2030
}

Once the physical card is delivered and the user activates it, you’ll receive the webhook card.activated.

Next steps

Activate Card → — call this once the user confirms receipt.
Set / Reset PIN → — required for ATM withdrawals and contactless > AED 300.

Errors

HTTP	Code	Description
409	`already_physical`	Card is already a physical card.
409	`kyc_level_insufficient`	User must complete `full` KYC before physical issuance.
400	`shipping_country_not_supported`	Delivery only available in supported countries.
422	`embossed_name_invalid`	Embossed name must be ≤ 21 chars, A–Z and spaces only.

Create Virtual Card Activate Card