Card Issuance (European Programs)

Overview

This guide describes the order card flow for partners whose programs issue European-issued cards (for example consumer EUR products with your configured card vendor). The request body shape, especially instructions.dob and instructions.citizenship, is tailored to that regulatory and issuer context.

Programs in other regions, or other card products, may require different fields, vendors, or validation rules. Confirm the correct payload with Custodia for your specific program before going live.

Why European Issuance Differs

European card programs often require explicit date of birth and citizenship in the order payload so the issuer can complete KYC-aligned checks. Those values travel inside the instructions object alongside any shipping or expedite options your product supports.

If you are not on a European-issued product line, refer to your program documentation or the general Users guide for the broader order-card contract.

User Phone and Address (Mandatory)

The target user must already have a phone number on the user object in the field mobile, and a physical address in the field address (single-line string: street, city, postal code, country as your program requires). Both are mandatory for card issuance: create users with POST /md/api/User including these fields, or set them with PATCH /md/api/User/{userId} before order-card. See the Create User and Update User sections for field details.

Authentication and OAuth Scopes

Obtain an access token using the same client-credentials flow as in the Authentication guide. For order-card, the token request must ask for both of the following scopes in the scope array (order does not matter):

• DEFAULT for standard application access.
• f:Card/OrderCards so the issued token is allowed to order cards.

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "scope": ["DEFAULT", "f:Card/OrderCards"],
  "grant_type": "client_credentials"
}

If f:Card/OrderCards is missing from the token, order-card calls may fail with an authorization error even when DEFAULT is present. Confirm the exact scope list for your program with Custodia if you use additional feature scopes.

Endpoint and Headers

Replace {userId} with the Custodia user id for whom the card is being ordered.

Request Body (European Example)

Example Request

Below is a fully dummy request. Do not send real personal data in support tickets or documentation samples.

Using cURL:

curl -X POST https://sandbox.custodia-tech.com/md/api/User/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/order-card \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "cardProductId": "11111111-2222-3333-4444-555555555555",
  "instructions": {
    "dob": {
      "year": 1990,
      "month": 1,
      "day": 15
    },
    "citizenship": "US"
  }
}'

Using JavaScript (fetch):

const userId = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee';

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/User/${userId}/order-card`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    cardProductId: '11111111-2222-3333-4444-555555555555',
    instructions: {
      dob: { year: 1990, month: 1, day: 15 },
      citizenship: 'US'
    }
  })
});

const card = await response.json();

Example Response

Shape and field names vary slightly by vendor and product. This sample matches a European virtual Mastercard-style product and uses only placeholder values.

{
  "id": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
  "cardNo": "XXXX-XXXX-XXXX-4242",
  "state": "ACTIVE",
  "expiration": "2029-04",
  "createdOn": "2026-05-13T15:22:53.217Z",
  "updatedOn": "2026-05-13T15:22:53.217Z",
  "vendor": "example-eu-cons-eur",
  "vendorRecordId": "00000000",
  "companyId": "cccccccc-dddd-eeee-ffff-000000000000",
  "ownerId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "cardType": "example/program/virtual/eur",
  "cardHolderName": "Example Cardholder",
  "cardProductId": "11111111-2222-3333-4444-555555555555",
  "paymentNetwork": "mastercard",
  "boundToActivitiesOnly": false,
  "cardIssuerId": "example-eu-cons-eur",
  "isVirtual": true,
  "isDefault": false,
  "partialAuth": false,
  "keywords": null,
  "restrictByKeywords": false,
  "accountId": null,
  "accountType": null,
  "paymentAccountManager": null
}

Next Steps

Request a token with DEFAULT and f:Card/OrderCards as described above. Ensure the user has mobile and address set, then follow Authentication for headers. Confirm the user exists under Users, then call order-card with the payload your program requires. For errors and state codes, rely on the API error body and Custodia support for your program id.