Skip to main content
POST
/
cardaccounts
Create Card Account
curl --request POST \
  --url https://access.utgl.io/v1/cardaccounts \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "phoneNumber": "+85255551234",
  "identityType": "individual",
  "accountType": "asset-link",
  "currency": "HKD",
  "xid": "<string>",
  "xmetadata": {
    "key1": "value1",
    "key2": [
      "value2.1",
      "value2.2"
    ]
  },
  "individual": {
    "dateOfBirth": "1985-07-20",
    "firstName": "John Anthony",
    "lastName": "CHAN",
    "email": "[email protected]",
    "annualIncome": "100000",
    "occupation": "accountant",
    "position": "senior management",
    "document": {
      "type": "passport",
      "front": "data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDQo8P3hwYW5lbCBiYXNlPSIwIiBuYW1lPSJMYXllciAxIiBjb2xvcj0iIzAwMDAwMCI+CjwvYnVmZmVyPgo8L3BhcmVudD4KPC9",
      "number": "A12345678",
      "country": "HK",
      "back": "data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDQo8P3hwYW5lbCBiYXNlPSIwIiBuYW1lPSJMYXllciAxIiBjb2xvcj0iIzAwMDAwMCI+CjwvYnVmZmVyPgo8L3BhcmVudD4KPC9",
      "expiryDate": "2025-12-31"
    },
    "address": "123 Main Street, Anytown, USA",
    "firstNameLocal": "John Anthony",
    "lastNameLocal": "CHAN",
    "mobile": "+85255551234",
    "gender": "MALE",
    "nationality": "HK",
    "supportingDocuments": [
      {
        "documentType": "WORK_VISA",
        "file": "data:application/pdf;base64,JVBERi0xLjQKJcOkw7zDQo8P3hwYW5lbCBiYXNlPSIwIiBuYW1lPSJMYXllciAxIiBjb2xvcj0iIzAwMDAwMCI+CjwvYnVmZmVyPgo8L3BhcmVudD4KPC9"
      }
    ]
  },
  "assetLink": {
    "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "creditAccount": [
    "90dde354-826a-4a0a-b1cb-7f2fc361ad5b"
  ],
  "limit": "10000",
  "settlementAccount": "de22c824-b8bd-4825-8db5-e5bdd2371dfb"
}
'
{
  "balance": 10000.25,
  "outstanding": 7500.5,
  "available": 825.3,
  "limit": 10000.25,
  "currency": "HKD",
  "accountType": "asset-link",
  "identityType": "individual",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "xid": "<string>",
  "xmetadata": {
    "key1": "value1",
    "key2": [
      "value2.1",
      "value2.2"
    ]
  },
  "name": "JOHN CHAN",
  "accountNumber": "002-010-1234567-0001",
  "balanceUsdEquivalent": 10000.25,
  "balanceHkdEquivalent": 10000.25,
  "assetLink": {
    "accountId": "<string>"
  },
  "phoneNumber": "+85212345678",
  "walletId": "0ebd3c68-af60-4a6e-aaa9-040d8e64aa8e",
  "status": "active",
  "settlementAccountId": "abcb107d-d98d-49ee-8456-73fa693dbb55",
  "settlementAccountName": "JOHN CHAN",
  "settlementAccountNumber": "002-010-1234567-0001"
}

Authorizations

​
Authorization
string
header
required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Body

application/json
​
name
string
required

Name of card account, this is a human-friendly non unique name for a card account and can be changed later. The card account name is used to identify the card account in reports and in the user interface

​
phoneNumber
string
required

Phone number of card holder This phone number should be pre verified by the partner.

Example:

"+85255551234"

​
identityType
enum<string>
required

Type of identity of card holder. Currently only individual is supported.

Available options:
individual,
corporate
​
accountType
enum<string>
required

The accountType field specifies the type of card account to create. This field is used to distinguish between two types of card accounts: asset-link and prepaid.

An asset-link card account is backed by combined asset value from a an associated account, which determines the available credit limit of the card account. Repayment on this type of account is settled through the backing account automatically through asset repayments.

A prepaid card account, on the other hand, is pre-funded directly by a top-up action. This operates as a prepaid or pre-funded card model.

A fixed-limit card account has a predetermined credit limit that remains unchanged and is not affected by the value of any associated assets. Repayments on this type of account are settled through alternative methods rather than asset repayments.

Please note that the accountType field cannot be changed after the card account has been created.

Available options:
asset-link,
prepaid,
fixed-limit
​
currency
enum<string>
required

Currency of card account. Must be a valid ISO 4217 currency code. Please consult your solution manager to ensure the correct account currency for your offered card products

Available options:
HKD,
USD
Required string length: 3
​
xid
string

External identifier, unique across all resources created under this account.

​
xmetadata
object

External metadata

Example:
{
  "key1": "value1",
  "key2": ["value2.1", "value2.2"]
}
​
individual
object

Individual card holder identity information. This is required when account type is individual.

​
assetLink
object

Asset link configuration of card account, applicable only when accountType is asset-link

If assetLink is not provided, an account will be created and linked to this card account for both asset backing and repayment.

​
creditAccount
string<uuid>[]

This is array of accountIds where the fixed-limit credit come from, the total limit of all the card accounts (under the same credit account) add up cannot exceed the credit account asset balance. When accountType is set to fixed-limit, this additional parameter needs to be passed in.

Example:
["90dde354-826a-4a0a-b1cb-7f2fc361ad5b"]
​
limit
number

This is the predetermined credit limit for fixed-limit card account. When accountType is set to fixed-limit, this additional parameter needs to be passed in.

Example:

"10000"

​
settlementAccount
string<uuid>

This is the settlement account for fixed-limit card account. When accountType is set to fixed-limit, this additional parameter needs to be passed in.

Example:

"de22c824-b8bd-4825-8db5-e5bdd2371dfb"

Response

200 - application/json

OK

​
balance
number
required

The current real-time balance of the card account in the account currency. All transactions in the account are added up to calculate this balance. Purchases and cash withdrawals increase it, while payments and credits decrease it.

For prepaid accounts, the balance will always be negative to indicate a debit balance.

Example:

10000.25

​
outstanding
number
required

The outstanding balance in the card account currency that needs to be repaid. appliable to asset-link mode only.

Example:

7500.5

​
available
number
required

The available spendable amount on the card account. It is calculated by subtracting the balance from the assigned credit limit. This value represents the total available spendable limit in the account and applies to all account types.

A positive value indicates that the card account has available spendable limit. For pre-paid mode accounts, this is the only value that should be used to determine the account's current available balance.

Example:

825.3

​
limit
number
required

In Asset-link mode, this is the credit limit assigned to the card account. For prepaid accounts, the limit is always zero.

Example:

10000.25

​
currency
string
required

Currency of the card account.

Example:

"HKD"

​
accountType
enum<string>
required
Available options:
asset-link,
prepaid,
fixed-limit
​
identityType
enum<string>
required

The type of identity associated with the card holder. Must be either "individual" or "corporate".

Available options:
individual,
corporate
​
id
string<uuid>

ID of resource

​
xid
string

External identifier, unique across all resources created under this account.

​
xmetadata
object

External metadata

Example:
{
  "key1": "value1",
  "key2": ["value2.1", "value2.2"]
}
​
name
string

Name of card account

Example:

"JOHN CHAN"

​
accountNumber
string

Account number of card account

Example:

"002-010-1234567-0001"

​
balanceUsdEquivalent
number

The equivalent balance of the card account in USD.

Example:

10000.25

​
balanceHkdEquivalent
number

The equivalent balance of the card account in HKD.

Example:

10000.25

​
assetLink
object

Asset link configuration

​
phoneNumber
string

Contact phone number of card holder, also used to receive 3DS one time passcodes. Phone number of card holder, also used to receive 3DS one time passcodes. Partner must ensure that this phone number has been verified.

Example:

"+85212345678"

​
walletId
string

The walletId is one of the Waillets bound to a card account.

Example:

"0ebd3c68-af60-4a6e-aaa9-040d8e64aa8e"

​
status
enum<string>

The status of card account.

Available options:
active,
frozen
Example:

"active"

​
settlementAccountId
string<uuid>

Settlement account id for the fixed limit card account

Example:

"abcb107d-d98d-49ee-8456-73fa693dbb55"

​
settlementAccountName
string

Settlement account name for the fixed limit card account

Example:

"JOHN CHAN"

​
settlementAccountNumber
string

Settlement account number for the fixed limit card account

Example:

"002-010-1234567-0001"