Skip to main content
POST
/
cardaccounts
/
topup
Top up account
curl --request POST \
  --url https://access.utgl.io/v1/cardaccounts/topup \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "6a3176fe-7715-4fe0-a548-034912d7f800",
  "cardAccountId": "6a3176fe-7715-4fe0-a548-034912d7f800",
  "amount": 50000,
  "currency": "HKD",
  "idempotencyKey": "xeev1she5eegh9daiviethahchoo1muW",
  "xid": "<string>",
  "xmetadata": {
    "key1": "value1",
    "key2": [
      "value2.1",
      "value2.2"
    ]
  }
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "xid": "<string>",
  "xmetadata": {
    "key1": "value1",
    "key2": [
      "value2.1",
      "value2.2"
    ]
  },
  "refId": "CT34567890",
  "cardAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "cardId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "cardLast4": "<string>",
  "cardEmbossedName": "<string>",
  "createdAt": "2022-11-10T07:47:09.415Z",
  "status": "pending",
  "postedAt": "2022-11-10T07:47:09.415Z",
  "intent": "charge",
  "authorization": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "currency": "USD",
    "amount": 128.29,
    "createdAt": "2022-11-10T07:47:09.415Z",
    "type": "Payment authorization type",
    "responseCode": "<string>",
    "responseMessage": "<string>",
    "cardPresent": true
  },
  "merchant": {
    "name": "UBER * PENDING Amsterdam NLD",
    "mcc": "4121",
    "category": "Taxicabs and limousines",
    "country": "HK"
  },
  "currency": "HKD",
  "amount": 1000,
  "entryType": "CREDIT",
  "description": "UBER * PENDING Amsterdam NLD",
  "grossAmount": 1000
}

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
​
accountId
string<uuid>
required

Account ID used to fund this top up

Example:

"6a3176fe-7715-4fe0-a548-034912d7f800"

​
cardAccountId
string<uuid>
required

Card Account ID to top up. This card account must be of type prepaid. For asset-link cards, plesae use the Transfer endpoint to fund the backing account.

Example:

"6a3176fe-7715-4fe0-a548-034912d7f800"

​
amount
number
required

Amount to top up

Example:

50000

​
currency
string
required

Currency to top up, must match card account currency

Example:

"HKD"

​
idempotencyKey
string<string>

Unique idempotency key for ensuring exactly-once execution of mutating requests.

Example:

"xeev1she5eegh9daiviethahchoo1muW"

​
xid
string

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

​
xmetadata
object

External metadata

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

Response

Card Account Top-up completed

Card account transaction

​
id
string<uuid>

Card account transaction id

​
xid
string

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

​
xmetadata
object

External metadata

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

Card account transaction reference

Example:

"CT34567890"

​
cardAccountId
string<uuid>

Card account id

​
cardId
string<uuid>

Card id of the card that was used to make the transaction. This field will be null for card account transactions that are not associated with a card

​
cardLast4
string

The last 4 digits of the card number.

​
cardEmbossedName
string

The name embossed on the card.

​
createdAt
string<date-time>

Date / Time of transaction at which it was initially recorded into the account

Example:

"2022-11-10T07:47:09.415Z"

​
status
enum<string>

Status of the card account transaction

  • pending: The transaction has been initiated but has not yet been fully processed. The amount and details of the transaction may change while it is in pending status
  • posted: The transaction has been posted and is final, for card transactions this means that the transaction has been captured
  • declined: The transaction has been rejected / declined (Card Transaction Only)
  • void: The transaction has been cancelled
Available options:
pending,
posted,
declined,
void
​
postedAt
string<date-time>

Date / Time of transaction at which it was posted into the account For transactions that have not been captured, postedAt will be null, indicating that it hasn't is pending

Example:

"2022-11-10T07:47:09.415Z"

​
intent
enum<string>
Available options:
charge,
refund,
topup,
withdraw,
transfer,
repay,
cashback,
interest,
fee,
other
​
authorization
object

Authorization info, applies to charge transactions only

​
merchant
object

This field will provide information about the merchant where the transaction occurred (for "charge" transactions only).

​
currency
string

Currency of transaction in card account base currency

Example:

"HKD"

​
amount
number

Amount of the transaction in the base currency of the card account.

Example:

1000

​
entryType
enum<string>

The type of entry representing whether the transaction resulted in a credit to or debit from the card account balance. A DEBIT transaction indicates a positive value added to the account (e.g. points reward, refund), while a CREDIT transaction indicates a negative value subtracted from the account balance (e.g. purchase, interest charge).

Available options:
CREDIT,
DEBIT
​
description
string

Description of the transaction, for statement and/or account activity display

Example:

"UBER * PENDING Amsterdam NLD"

​
grossAmount
number

The total purchase amount of the transaction in the base currency of the card account.

Example:

1000