Issue Card

curl --request POST \
  --url https://access.utgl.io/v1/cards \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "physical",
  "cardAccountId": "c8e2752d-6bd7-4244-a9f6-580f5640eaeb",
  "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "embossedName": "CHAN TAI MAN",
  "cardSuffix": "8888",
  "cardholderInfo": {
    "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"
      }
    ]
  },
  "xid": "<string>",
  "xmetadata": {
    "key1": "value1",
    "key2": [
      "value2.1",
      "value2.2"
    ]
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "cardAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "xid": "<string>",
  "xmetadata": {
    "key1": "value1",
    "key2": [
      "value2.1",
      "value2.2"
    ]
  },
  "status": "active",
  "embossedName": "<string>",
  "network": "mastercard",
  "product": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "imageUrl": "<string>",
    "cardType": "<string>",
    "cardImageDetails": {
      "cardOrientation": "LANDSCAPE",
      "cardWidth": "<string>",
      "cardHeight": "<string>",
      "cardNameFontSize": "<string>",
      "cardNameFontWeight": "<string>",
      "cardNameLineHeight": "<string>",
      "cardNameLetterSpacing": "<string>",
      "cardNamePosition": "<string>",
      "cardNameCoordinates": [
        123
      ],
      "cardNameColor": "<string>"
    }
  },
  "expiryMonth": 9,
  "expiryYear": 2030,
  "last4": "<string>",
  "replacedBy": "<string>",
  "cardLimit": 123,
  "dailyAtmLimit": 123,
  "dailyPurchaseLimit": 123,
  "dailyLimit": 123,
  "singleTransactionLimit": 123,
  "availableLimit": 123,
  "cardPresentLimit": 123,
  "cardNotPresentLimit": 123,
  "mobile": "<string>",
  "cardEmail": "[email protected]"
}

Issue Card

Issue a card under the respective card account.

This can be either a physical, which is a traditional tangible card made of plastic, or a virtual card, which is a digital version of a physical card that can be used for online transactions or transactions made through a mobile device.

When issuing a card, the productId must be specified and determines the card product to issue. The card product determines the card type, card face, card features, benefits, interest rates, capabilties, etc. The list of available productIds is static will be provided by your solution manager based on your pre-determined card product offering(s). The card will be chosen from the available inventory and given out in numerical order according to its card number.

If you wish to issue a specific card, you may specify the card number suffix (up to the full card numberA) using the cardSuffix field. If the card number is not part of the productId or already issued, the request will fail.

Multiple cards can be issued under the a single card account.

Once the request has been processed:

The card will be created in the system under the respective card account.
The card can then be activated and used for making purchases.

POST

cards

Issue Card

curl --request POST \
  --url https://access.utgl.io/v1/cards \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "physical",
  "cardAccountId": "c8e2752d-6bd7-4244-a9f6-580f5640eaeb",
  "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "embossedName": "CHAN TAI MAN",
  "cardSuffix": "8888",
  "cardholderInfo": {
    "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"
      }
    ]
  },
  "xid": "<string>",
  "xmetadata": {
    "key1": "value1",
    "key2": [
      "value2.1",
      "value2.2"
    ]
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "cardAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "xid": "<string>",
  "xmetadata": {
    "key1": "value1",
    "key2": [
      "value2.1",
      "value2.2"
    ]
  },
  "status": "active",
  "embossedName": "<string>",
  "network": "mastercard",
  "product": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "imageUrl": "<string>",
    "cardType": "<string>",
    "cardImageDetails": {
      "cardOrientation": "LANDSCAPE",
      "cardWidth": "<string>",
      "cardHeight": "<string>",
      "cardNameFontSize": "<string>",
      "cardNameFontWeight": "<string>",
      "cardNameLineHeight": "<string>",
      "cardNameLetterSpacing": "<string>",
      "cardNamePosition": "<string>",
      "cardNameCoordinates": [
        123
      ],
      "cardNameColor": "<string>"
    }
  },
  "expiryMonth": 9,
  "expiryYear": 2030,
  "last4": "<string>",
  "replacedBy": "<string>",
  "cardLimit": 123,
  "dailyAtmLimit": 123,
  "dailyPurchaseLimit": 123,
  "dailyLimit": 123,
  "singleTransactionLimit": 123,
  "availableLimit": 123,
  "cardPresentLimit": 123,
  "cardNotPresentLimit": 123,
  "mobile": "<string>",
  "cardEmail": "[email protected]"
}

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

type

enum<string>

required

The type field determines the type of card to issue. It can be either a physical card or a virtual card.

A physical card is a traditional, tangible card that is made of plastic or other materials and can be used for both online and in-person transactions at retail card terminals.

A virtual card is a digital / online only version of a payment card, which can be used for online transactions or for transactions made through a mobile device when binding to wallets or payment apps.

Available options:

physical,

virtual

cardAccountId

string

required

The cardAccountId field specifies the card account under which the card will be issued. This field is used to issue and link the newly issued card to a particular card account, which must have already been created prior to issuing the card.

The card account is an account that holds the funds, balances, and transactions that are used to make purchases with the card. Multiple cards issued under the same card account share the same balance and limit.

Example:

"c8e2752d-6bd7-4244-a9f6-580f5640eaeb"

productId

string<uuid>

required

Product ID of the card product to be issued

embossedName

string

required

The embossedName field specifies the name that is embossed or printed on a physical card. This is the name that appears on the front of the card.

Allowed characters: basic latin letters (A-Z, a-z), hyphens("-"), whitespace(" "), periods("."), and commas(","). Accented letters, apostrophes, and numeric characters are not permitted.

Examples of valid names:

"CHAN TAI MAN"
"John Smith"
"Mary-Jane"
"John, Jr."
"Mary A."

Examples of invalid names:

"11" (contains numeric characters)
"John123" (contains numeric characters)
"José María" (contains accented letters)
"O'Connor-Smith" (contains apostrophe)
"a" (too short after processing)
"John@Doe" (contains invalid characters)

Maximum string length: 22

Example:

"CHAN TAI MAN"

cardSuffix

string

Specify a card suffix to issue a specific card. This field can be used to have fine control over card selection during issuing process. The specified card must be available in the inventory and not already issued.

Example:

"8888"

cardholderInfo

object

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

Show child attributes

xid

string

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

xmetadata

object

External metadata

Show child attributes

Example:

{
  "key1": "value1",
  "key2": ["value2.1", "value2.2"]
}

Response

200 - application/json

Card Issue Successful

string<uuid>

Card ID of issued card. All card related endpoints require this ID for operation.

cardAccountId

string<uuid>

Card account ID of the card

xid

string

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

xmetadata

object

External metadata

Show child attributes

Example:

{
  "key1": "value1",
  "key2": ["value2.1", "value2.2"]
}

status

enum<string>

Available options:

active,

pending-issue,

pending-activation,

locked,

suspended,

cancelled

embossedName

string

Embossed name on the card

network

enum<string>

Card network

Available options:

mastercard

product

object

Card product

Show child attributes

expiryMonth

string

Card expiry month

Example:

9

expiryYear

string

Card expiry month

Example:

2030

last4

string

Last 4 digits of the card number

replacedBy

string

Card id of the card that replaced this card

cardLimit

number

Card limit

dailyAtmLimit

number

Daily ATM limit

dailyPurchaseLimit

number

Daily Purchase limit

dailyLimit

number

Daily limit

singleTransactionLimit

number

Single transaction limit

availableLimit

number

Available limit chargeable on the card, taking into account all limits.

cardPresentLimit

number

Card present limit.

cardNotPresentLimit

number

Card not present limit.

mobile

string

Card cell phone number

cardEmail

string<email>

Email address associated with the card

Example:

"[email protected]"

⌘I

Introduction

Authentication & Security

API Fundamentals

Issue Card

Authorizations

Body

Response