VCC Cardholder API

Create and manage individual cardholders, retrieve their details and configure spending controls.

Endpoint

Sandbox base URL

https://api.futurepay-develop.com/api/v1/issuing/cardholder

Production base URL

https://api.futurepay.global/api/v1/issuing/cardholder

API Overview

Paths below are relative to the base URL.

id is the string returned by this API, for example ich_EXAMPLE. Use this ID for subsequent requests.

Common Response

Check success and code; HTTP status alone does not indicate business success.

Create a Cardholder

Endpoint

POST /create

Request Parameters

Document filenames must belong to files uploaded by the authenticated merchant. Send the filename exactly as returned by the File Upload API. Omit optional document fields when no file is supplied.

For US addresses, New York, US-NY, ny and NYzz are invalid state values. Other countries are not subject to a universal two-character state restriction.

Name Validation

Both name fields must be nonblank and match this pattern:

^[A-Za-z\u00C0-\u00FF\s/\-&:()'.]*$

The pattern permits ASCII letters, characters in U+00C0–U+00FF, whitespace and the punctuation shown. Digits, Chinese characters and characters outside this pattern are not accepted.

The combined name, formed as trimmed firstName + one space + trimmed lastName, must not exceed 24 characters, including the separator.

Email Validation

An email already used by another successfully created cardholder under the same merchant cannot be reused. An existing pending creation also reserves its email during creation. Failed creations alone do not prevent a new creation with that email.

Request Example

{
  "type": "individual",
  "individual": {
    "firstName": "Alex",
    "lastName": "Morgan",
    "birthday": "1990-01-15"
  },
  "email": "[email protected]",
  "billing": {
    "address": {
      "country": "US",
      "line1": "123 Main Street",
      "line2": "Unit 3",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001"
    }
  }
}

To provide documents, add idDocFrontPath and idDocBackPath inside individual, using the filenames returned by the File Upload API.

curl

curl --request POST \
  'https://api.futurepay-develop.com/api/v1/issuing/cardholder/create' \
  --header 'Content-Type: application/json' \
  --header 'merchantId: YOUR_MERCHANT_ID' \
  --header 'appId: YOUR_APP_ID' \
  --header 'authorization: YOUR_SIGNATURE' \
  --header 'curTime: YOUR_REQUEST_TIME' \
  --data-raw '{"individual":{"firstName":"Alex","lastName":"Morgan","birthday":"1990-01-15"},"email":"[email protected]","billing":{"address":{"country":"US","line1":"123 Main Street","city":"New York","state":"NY","postalCode":"10001"}}}'

Generate the signature using the actual request and your assigned signing credentials.

Response Example

{
  "code": "0",
  "msg": "succeeded",
  "serverTime": "1794034703869",
  "success": true,
  "data": {
    "id": "ich_EXAMPLE",
    "type": "individual",
    "individual": {
      "firstName": "Alex",
      "lastName": "Morgan",
      "birthday": "1990-01-15"
    },
    "email": "[email protected]",
    "billing": {
      "address": {
        "line1": "123 Main Street",
        "line2": "Unit 3",
        "city": "New York",
        "state": "NY",
        "country": "US",
        "postalCode": "10001"
      }
    },
    "status": "pending",
    "failureReason": null,
    "createdAt": "2026-11-07 06:58:23",
    "updatedAt": "2026-11-07 06:58:23"
  }
}

Creation is asynchronous. success: true with status: pending means the request was accepted, rather than that creation has completed. Save the returned id. Receive the final result through a notification or retrieve the cardholder to check its status. Validation failures before acceptance return an error response.

Cardholder Response Object

Creation, update, retrieval and list items use the same cardholder structure.

Retrieve a Cardholder

Endpoint

POST /{id}/detail

Request Example

{}

Response

data contains the Cardholder Response Object with the current status and failure reason. A cardholder outside the authenticated merchant is not accessible.

List Cardholders

Endpoint

POST /paging

Request Parameters

The current status filter uses the uppercase values above. Response statuses use lowercase values: PROCESSING maps to pending, and IN_ACTIVE maps to inactive. Explicit null pagination values are invalid.

Request Example

{
  "status": "ACTIVE",
  "pageNum": 1,
  "pageSize": 20
}

Response

Empty result example

{
  "code": "0",
  "msg": "succeeded",
  "serverTime": "1794034703869",
  "success": true,
  "data": {
    "pageNum": 1,
    "pageSize": 20,
    "total": 0,
    "totalPage": 0,
    "list": []
  }
}

Update a Cardholder

Endpoint

POST /{id}

Request Parameters

Update uses the same field names and nesting as creation. All business fields are optional; supplied values must satisfy the applicable creation validation rules.

Except for type, omitted or null fields preserve existing values. An empty body {} returns the current cardholder without changing it. Supplied empty strings are not a substitute for omitted required personal/address fields. The merged address must remain valid, including the US state rule.

After successful creation, first and last names cannot change. If creation failed, information can be corrected and the update retries creation. An unchanged email on an already successful cardholder does not conflict with itself. A changed email, or an update to a failed cardholder, is checked against other successfully created cardholders under the same merchant.

Updates are synchronous. An update failure returns an error and does not send an update-success notification.

Request Example

{
  "email": "[email protected]",
  "billing": {
    "address": {
      "line1": "456 Main Street",
      "city": "New York",
      "state": "NY",
      "postalCode": "10002"
    }
  }
}

Response

data contains the updated Cardholder Response Object.

Activate / Deactivate a Cardholder

Endpoints

POST /{id}/activate
POST /{id}/deactivate

Request Example

{}

Response

A successful operation returns the common success envelope without a cardholder result object. data may be null or omitted. Retrieve the cardholder to obtain the latest details.

Activating an already active cardholder returns CARDHOLDER_ALREADY_ACTIVE. Deactivating an already inactive cardholder returns CARDHOLDER_ALREADY_INACTIVE. Pending or failed creation states do not permit these operations.

Successful activation and deactivation send an UPDATE_CARDHOLDER_RESULT notification after the operation is committed, with status: "active" or status: "inactive" respectively. Failed operations do not send a success notification.

Set Spending Controls

Endpoint

POST /{id}/controls

Cardholder spending limits apply to the combined spending of the cardholder's cards. Card-level controls can impose additional restrictions.

Request Parameters

Both arrays must be supplied, even if only one part changes. This endpoint replaces the complete configuration, rather than merging it. Array items cannot be null. Currency is fixed to USD by the service; do not send a currency field.

Request Example

{
  "limits": [
    {
      "amount": 5000.00,
      "interval": "monthly"
    },
    {
      "amount": 500.00,
      "interval": "daily"
    }
  ],
  "categories": [
    {
      "rule": "deny",
      "mcc": ["0742", "7311"]
    }
  ]
}

Response Example

{
  "code": "0",
  "msg": "succeeded",
  "serverTime": "1794034703869",
  "success": true,
  "data": {
    "limits": [
      {"amount": 5000.00, "interval": "monthly", "currency": "USD"},
      {"amount": 500.00, "interval": "daily", "currency": "USD"}
    ],
    "categories": [
      {"rule": "deny", "mcc": ["0742", "7311"]}
    ]
  }
}

Clear All Controls

{
  "limits": [],
  "categories": []
}

{} is invalid for this endpoint because both fields are required.

Retrieve Spending Controls

Endpoint

POST /{id}/controls/detail

Request Example

{}

Response

data has the same structure as the Set Spending Controls response: limits and categories. Every returned limit includes currency: "USD". Empty configurations return empty arrays.

Result Notifications

Configure your merchant notification URL during integration. Result notifications are sent to that URL using the Futurepay notification signing protocol. Verify signatures according to that protocol; file-upload Bearer authentication does not apply to notifications.

Cardholder status changes also send UPDATE_CARDHOLDER_RESULT, regardless of whether the operation was performed through the API or merchant console. Use the notification's id and status to refresh your records.

Notification Parameters

Notification Example

{
  "merchantId": "1929723739654762496",
  "appId": "1929723739684102144",
  "notificationItems": [
    {
      "eventCode": "CREATE_CARDHOLDER_RESULT",
      "eventDate": 1794034703869,
      "id": "ich_EXAMPLE",
      "status": "create_failed",
      "failureReason": "Cardholder creation failed: Invalid US state or province"
    }
  ]
}

Handle notifications idempotently and retrieve current details when reconciling state. A notification may arrive before the original HTTP response. Different successful updates can have the same cardholder ID and status; that pair is not a unique update identifier. If no notification arrives, query the saved ID before attempting another creation.

Error Codes

Error Response Example

{
  "code": "CARDHOLDER_ALREADY_EXISTS",
  "msg": "A cardholder has already been successfully created with this email: [email protected]",
  "serverTime": "1794034703869",
  "success": false
}

After an accepted asynchronous creation fails, its final state is available through notifications and retrieval as status: "create_failed" with failureReason. Keep the cardholder ID to correct and retry through the update endpoint.