# Welcome

The CardsPro API provides a comprehensive set of endpoints for managing card operations including issuance, top-up, withdrawal, blocking, freezing, PIN management, and transaction retrieval. All endpoints are under the URL  `https://api.cardspro.com/cards/v1`

**Base URL:** `https://api.cardspro.com/cards/v1`

**Authentication:** All endpoints require user authentication via HTTP request headers.


# API Authentication

This document describes the authentication mechanism for the CardsPro API using custom HTTP headers with SHA-256-based signatures.

### Overview <a href="#overview" id="overview"></a>

The CardsPro API uses a signature-based authentication system that requires three custom HTTP headers on every request. This ensures that requests are authenticated and have not been tampered with in transit.

### Required HTTP Headers <a href="#required-http-headers" id="required-http-headers"></a>

All API requests must include the following three headers:

| Header      | Description                               |
| ----------- | ----------------------------------------- |
| `CAP-TOKEN` | Your API Key                              |
| `CAP-NONCE` | Current timestamp in milliseconds         |
| `CAP-SIGN`  | SHA-256 signature (see calculation below) |

### Authentication Process <a href="#authentication-process" id="authentication-process"></a>

#### 1. Obtain API Credentials

You need two credentials to authenticate:

* **API Key**: Your public identifier (sent as `CAP-TOKEN`)
* **Secret Key**: Your private signing key (used to generate `CAP-SIGN`, never sent directly)

#### 2. Generate the Nonce <a href="#id-2-generate-the-nonce" id="id-2-generate-the-nonce"></a>

Create a nonce using the current timestamp in milliseconds:

```javascript
const nonce = Date.now().toString();
```

#### 3. Calculate the Signature <a href="#id-3-calculate-the-signature" id="id-3-calculate-the-signature"></a>

The signature calculation differs based on the HTTP method:

**For POST Requests**

```
CAP-SIGN = sha256Hex(CAP-NONCE + request_body + query_string + secret)
```

**Components:**

* `CAP-NONCE`: The timestamp in milliseconds
* `request_body`: The JSON or form-encoded request body as a string
* `query_string`: The URL query parameters (e.g., `param1=value1&param2=value2`)
* `secret`: Your Secret Key

**For GET Requests**

```
CAP-SIGN = sha256Hex(CAP-NONCE + query_string + secret)
```

**Components:**

* `CAP-NONCE`: The timestamp in milliseconds
* `query_string`: The URL query parameters (e.g., `param1=value1&param2=value2`)
* `secret`: Your Secret Key

**Note:** If there are no query parameters, use an empty string for `query_string`.

### Complete Request Examples <a href="#complete-request-examples" id="complete-request-examples"></a>

#### POST Request with Query Parameters <a href="#post-request-with-query-parameters" id="post-request-with-query-parameters"></a>

```
POST /cards/v1/transactions?type=withdrawal HTTP/1.1
Host: api.cardspro.com
Content-Type: application/json
CAP-TOKEN: abc123def456
CAP-NONCE: 1738713600000
CAP-SIGN: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

{"amount": 100, "currency": "USD"}
```

**Signature Calculation:**

```
message = "1738713600000" + '{"amount": 100, "currency": "USD"}' + "type=withdrawal" + secret_key
CAP-SIGN = sha256Hex(message)
```

#### GET Request with Query Parameters <a href="#get-request-with-query-parameters" id="get-request-with-query-parameters"></a>

```
GET /cards/v1/list?limit=10&offset=0 HTTP/1.1
Host: api.cardspro.com
CAP-TOKEN: abc123def456
CAP-NONCE: 1738713600000
CAP-SIGN: d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592
```

**Signature Calculation:**

```
message = "1738713600000" + "limit=10&offset=0" + secret_key
CAP-SIGN = sha256Hex(message)
```


# Cards

Base URL: /cards/v1

### Endpoints Summary <a href="#endpoints-summary" id="endpoints-summary"></a>

| Method | Endpoint                                                               | Description                    |
| ------ | ---------------------------------------------------------------------- | ------------------------------ |
| GET    | [`/account/balance`](/api/cards/user-account-balance)                  | Get user account balance       |
| GET    | [`/products`](/api/cards/card-products)                                | Get available card products    |
| POST   | [`/issue`](/api/cards/issue-new-card)                                  | Issue a new card               |
| GET    | [`/{san}/details`](/api/cards/card-details)                            | Get card details               |
| GET    | [`/list`](/api/cards/get-card-list)                                    | Get list of user's cards       |
| POST   | [`/{san}/topup`](/api/cards/card-top-up)                               | Add funds to card              |
| POST   | [`/{san}/withdraw`](/api/cards/card-withdrawal)                        | Withdraw funds from card       |
| POST   | [`/{san}/block`](/api/cards/card-block)                                | Block card permanently         |
| GET    | [`/{san}/block-detailes`](/api/cards/get-blocked-card-details)         | Get blocked card details       |
| GET    | [`/request/status`](/api/cards/get-card-request-status)                | Get operation(request) status  |
| GET    | [`/{san}/requests`](/api/cards/get-card-requests-list)                 | Get list of operations by card |
| GET    | [`/requests`](/api/cards/get-user-requests-list)                       | Get list of operations         |
| POST   | [`/{san}/freeze`](/api/cards/card-freeze-unfreeze-api#freeze-card)     | Temporarily freeze card        |
| POST   | [`/{san}/unfreeze`](/api/cards/card-freeze-unfreeze-api#unfreeze-card) | Unfreeze card                  |
| POST   | [`/{san}/set-pin`](/api/cards/card-pin-management#set-pin)             | Set card PIN (first time)      |
| POST   | [`/{san}/update-pin`](/api/cards/card-pin-management#update-pin)       | Update card PIN                |
| POST   | [`/{san}/update-email`](/api/cards/card-email-update)                  | Update card email              |
| POST   | [`/{san}/update-phone`](/api/cards/card-phone-update)                  | Update card phone              |
| POST   | [`/{san}/transactions`](/api/cards/card-transactions)                  | Get card transactions          |
| GET    | [`/{san}/otp-codes`](/api/cards/otp-3ds-codes)                         | Get card OTP(3ds) codes        |


# User Account Balance

Retrieves the balance of one or more user accounts by currency or account name.

**Endpoint:** `GET /account/balance`

**Query Parameters:**

<table><thead><tr><th width="139.888916015625">Parameter</th><th width="118.111083984375">Type</th><th width="116.7777099609375">Required</th><th width="107.111083984375">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>currency</code></td><td>String</td><td>No</td><td>-</td><td>Currency code (EUR, USD, etc.)</td></tr><tr><td><code>account</code></td><td>String</td><td>No</td><td>-</td><td>Specific account name</td></tr></tbody></table>

**Note:** If both parameters are provided, `account` takes precedence over `currency`.

**Response:**

```json
[
  {
    "total": 1234.56,
    "currency": "USD"
  },
  {
    "total": 5678.90,
    "currency": "EUR"
  }
]
```

**Response for Single Account Query:**

```json
[
  {
    "total": 1234.56,
    "currency": "USD"
  }
]
```

**Response Parameters:**

The endpoint returns an **array** of account balance objects:

<table><thead><tr><th width="136.77783203125">Field</th><th width="181.666748046875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>total</code></td><td>Decimal</td><td>Total balance in the account </td></tr><tr><td><code>currency</code></td><td>String</td><td>Currency code of the account</td></tr></tbody></table>


# Card Products

Retrieves a list of available card products with pricing information.

#### Get Available Card Products <a href="#get-available-card-products" id="get-available-card-products"></a>

**Endpoint:** `GET /products`

**Response:**

```json
[
  {
    "productCode": "W0193384.3884",
    "currency": "USD",
    "issueMinAmount": 50,
    "issueMaxAmount": 5000,
    "topUpMinAmount": 10,
    "topUpMaxAmount": 5000
  },
  {
    "productCode": "D02111099",
    "kycSort": "D02",
    "currency": "USD",
    "topUpMinAmount": 20,
    "topUpMaxAmount": 1000000,
    "issueMinAmount": 20,
    "issueMaxAmount": 100000,
    "params": {
      "issueCardEmailRequired": true
    }
  }
]
```

**Response Parameters:**

<table><thead><tr><th width="226.6666259765625">Field</th><th width="126.3333740234375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>productCode</code></td><td>String</td><td>Unique identifier for the card product</td></tr><tr><td><code>currency</code></td><td>String</td><td>Supported currency (USD, EUR)</td></tr><tr><td><code>issueMinAmount</code></td><td>Decimal</td><td>Minimum amount required when issuing this card product</td></tr><tr><td><code>issueMaxAmount</code></td><td>Decimal</td><td>Maximum amount allowed when issuing this card product</td></tr><tr><td><code>topUpMinAmount</code></td><td>Decimal</td><td>Minimum amount required for topping up this card product</td></tr><tr><td><code>topUpMaxAmount</code></td><td>Decimal</td><td>Maximum amount allowed for topping up this card product</td></tr><tr><td><code>kycSort</code></td><td>String</td><td>The type of KYC that must be completed before card issuance.</td></tr><tr><td><code>params</code></td><td>Object</td><td>Optional product-specific parameters and requirements</td></tr></tbody></table>

**Product-specific parameters(params)**

<table><thead><tr><th width="315.5556640625" valign="middle">params field</th><th width="93.6666259765625">Type</th><th>Description</th></tr></thead><tbody><tr><td valign="middle"><code>params.issueCardEmailRequired</code></td><td>Boolean</td><td>Indicates if email is required when issuing this card product</td></tr><tr><td valign="middle"><code>params.cardValidityPeriodSupported</code></td><td>Boolean</td><td>Indicates if custom card validity period (1-4 years) is supported for this product.</td></tr></tbody></table>

**Notes:**

* The `topUpMinAmount` and `issueMinAmount` fields define the minimum amounts for card operations.


# Card Products rate by merchant

List of products (cards) and their corresponding rates for the specified merchant.

**Endpoint:** `GET /products/search-by-merchant?merchant=<merchant>`

**Query Parameters**

| Parameter | Type   | Required | Description   | Example        |
| --------- | ------ | -------- | ------------- | -------------- |
| merchant  | string | Yes      | Merchant name | github, google |

**Response** :

```json
[
  {
    "productCode": "S00E0000000",
    "rate": 0.68
  },
  {
    "productCode": "S00SV000003",
    "rate": 0.59
  }
]
```

**Response Parameters:**

<table><thead><tr><th>Field</th><th width="187.666748046875">Type</th><th>Description</th></tr></thead><tbody><tr><td>productCode</td><td>String</td><td>Unique product (card) code</td></tr><tr><td>rate</td><td>Decimal</td><td>Rate / price for this product</td></tr></tbody></table>


# Issue New Card

Issues a new card for the authenticated user.

**Endpoint:** `POST /issue`

**Content-Type:** `application/json`

**Request Body:**

```json
{
  "productCode": "B0067bd6bf2b2604be25e9821b0",
  "request_id": "request-id-12345",
  "amount": 25,
  "currency": "USD",
  "cardValidityYears": 3,
  "preferredAccount": "string",
  "cardName": "My New Card",
  "firstName": "Jimmy",
  "lastName": "Taylor",
  "kycUuid": "259da80d-455b-421a-9d7b-152c4937457f"
}
```

**Request Parameters:**

<table><thead><tr><th width="174.99993896484375">Field</th><th width="99.3333740234375">Type</th><th width="106.2222900390625">Required</th><th width="155.2222900390625">Constraints</th><th>Description</th></tr></thead><tbody><tr><td><code>productCode</code></td><td>String</td><td>Yes</td><td>Not blank</td><td>Product code identifying the card type</td></tr><tr><td><code>request_id</code></td><td>String</td><td>Yes</td><td>12-36 characters</td><td>Unique request identifier</td></tr><tr><td><code>amount</code></td><td>Decimal</td><td>Yes</td><td>Not null</td><td>Initial card balance</td></tr><tr><td><code>currency</code></td><td>String</td><td>Yes</td><td>USD, EUR</td><td>Currency code (must match Product currency)</td></tr><tr><td><code>cardValidityYears</code></td><td>Number</td><td>No</td><td>1-4</td><td>card validity period in years(card specific field)</td></tr><tr><td><code>preferredAccount</code></td><td>String</td><td>No</td><td>-</td><td>Preferred account to debit from</td></tr><tr><td><code>cardName</code></td><td>String</td><td>No</td><td>Max 32 characters</td><td>Custom name for the card</td></tr><tr><td><code>email</code></td><td>String</td><td>No</td><td>Valid email format</td><td>Cardholder email(card specific field)</td></tr><tr><td><code>firstName</code></td><td>String</td><td>No</td><td>-</td><td>card specific field</td></tr><tr><td><code>lastName</code></td><td>String</td><td>No</td><td>-</td><td>card specific field</td></tr><tr><td><code>kycUuid</code></td><td>String</td><td>No</td><td>-</td><td>UUID of the passed KYC</td></tr></tbody></table>

**Response:**

```json
{
  "type": "ISSUE",
  "status": "INPROCESS",
  "docid": 123456,
  "request_id": "request-id-12345"
}
```

**Response Parameters:**

<table><thead><tr><th width="195.111083984375">Field</th><th width="159">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>String</td><td>Operation type (ISSUE)</td></tr><tr><td><code>status</code></td><td>String</td><td><p>Current status of the operation </p><p>(INPROCESS, EXECUTED, DECLINED)</p></td></tr><tr><td><code>docid</code></td><td>Number</td><td>Document ID for tracking the operation</td></tr><tr><td><code>request_id</code></td><td>String</td><td>The request ID provided in the request</td></tr></tbody></table>


# Card Details

Retrieves detailed information about a specific card.

**Endpoint:** `GET /{san}/details`

**Path Parameters:**

* `san` - Secure Account Number (card identifier)

**Response:**

```json
{
  "created": "2025-07-03T09:21:55.605Z",
  "currency": "USD",
  "cvv": "054",
  "san": "21ce69Y8792043020317",
  "initialBalance": 5.0,
  "product": "S00E0000039",
  "status": "active",
  "balance": 6.95,
  "cardNumber": "5360181101056090",
  "expYear": 2027,
  "expMonth": 2,
  "cardSystem": "MC",
  "cardName": "My virtual card",
  "docid": 702727662
}
```

**Response Parameters:**

<table><thead><tr><th width="178.5555419921875">Field</th><th width="236.7777099609375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>created</code></td><td>String (ISO 8601)</td><td>Card creation timestamp in UTC</td></tr><tr><td><code>blocked</code></td><td>String (ISO 8601) or null</td><td>Card blocked timestamp in UTC, or null </td></tr><tr><td><code>san</code></td><td>String</td><td>Secure Account Number (card identifier)</td></tr><tr><td><code>productCode</code></td><td>String</td><td>Unique identifier for the card product</td></tr><tr><td><code>cardSystem</code></td><td>String</td><td>VISA, MC</td></tr><tr><td><code>expYear</code></td><td>Number</td><td>Card expiration year</td></tr><tr><td><code>expMonth</code></td><td>Number</td><td>Card expiration month (1-12)</td></tr><tr><td><code>cvv</code></td><td>String</td><td>Card verification value</td></tr><tr><td><code>currency</code></td><td>String</td><td>Card currency code (USD, EUR, etc.)</td></tr><tr><td><code>cardNumber</code></td><td>String(null for blocked)</td><td>Full card number (when available)</td></tr><tr><td><code>initialBalance</code></td><td>Decimal</td><td>Initial balance loaded on the card</td></tr><tr><td><code>balance</code></td><td>Decimal(null for blocked)</td><td>Current card balance</td></tr><tr><td><code>status</code></td><td>String</td><td>Card status (active, blocking, blocked, frozen, expired, unknown)</td></tr><tr><td><code>cardName</code></td><td>String</td><td>User-defined card name</td></tr><tr><td><code>docid</code></td><td>Number</td><td>Document ID associated with the card</td></tr></tbody></table>


# Card Top-Up

Adds funds to an existing card from user's account.

**Endpoint:** `POST /{san}/topup`

**Path Parameters:**

* `san` - Secure Account Number (card identifier)

**Content-Type:** `application/json`

**Request Body:**

```json
{
  "amount": 100.00,
  "currency": "USD",
  "request_id": "496708ff-cf9f-4667-a8ab-649fc2cd9094"
}
```

**Request Parameters:**

<table><thead><tr><th width="138.66668701171875">Field</th><th width="120.6666259765625">Type</th><th width="114.3333740234375">Required</th><th width="133">Constraints</th><th>Description</th></tr></thead><tbody><tr><td><code>amount</code></td><td>Decimal</td><td>Yes</td><td>> 1</td><td>Amount to add to the card</td></tr><tr><td><code>currency</code></td><td>String</td><td>Yes</td><td>USD, EUR</td><td>Currency code (must match card currency)</td></tr><tr><td><code>request_id</code></td><td>String</td><td>Yes</td><td>12-36 characters</td><td>Unique request identifier</td></tr></tbody></table>

**Response:**

```json
{
  "type": "TOPUP",
  "status": "INPROCESS",
  "docid": 123456,
  "request_id": "496708ff-cf9f-4667-a8ab-649fc2cd9094",
  "topup": {
    "san": "90ce74952717804177",
    "amount": 100.00,
    "currency": "USD"
  }
}
```

**Response Parameters:**

<table><thead><tr><th width="184.22216796875">Field</th><th width="143.4443359375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>String</td><td>Operation type (TOPUP)</td></tr><tr><td><code>status</code></td><td>String</td><td><p>Current status of the operation </p><p>(INPROCESS, EXECUTED, DECLINED)</p></td></tr><tr><td><code>docid</code></td><td>Number</td><td>Document ID for tracking the operation</td></tr><tr><td><code>request_id</code></td><td>String</td><td>The request ID provided in the request</td></tr><tr><td><code>topup</code></td><td>Object</td><td>Top-up operation details</td></tr><tr><td><code>topup.amount</code></td><td>Decimal</td><td>Amount added to the card</td></tr><tr><td><code>topup.currency</code></td><td>String</td><td>Currency code (USD, EUR, etc.)</td></tr></tbody></table>


# Card Withdrawal

Withdraws funds from a card back to user's account.

**Endpoint:** `POST /{san}/withdraw`

**Path Parameters:**

* `san` - Secure Account Number (card identifier)

**Content-Type:** `application/json`

**Request Body:**

```json
{
  "request_id": "request-id-12345",
  "currency": "USD",
  "amount": 3.82
}
```

**Request Parameters:**

<table><thead><tr><th width="147.111083984375">Field</th><th width="110">Type</th><th width="107.8887939453125">Required</th><th width="168.7777099609375">Constraints</th><th>Description</th></tr></thead><tbody><tr><td><code>request_id</code></td><td>String</td><td>Yes</td><td>12-36 characters</td><td>Unique request identifier</td></tr><tr><td><code>currency</code></td><td>String</td><td>Yes</td><td>USD, EUR</td><td>Currency code (must match card currency)</td></tr><tr><td><code>amount</code></td><td>Decimal</td><td>Yes</td><td>> 0.01</td><td>Amount to withdraw</td></tr></tbody></table>

**Response:**

```json
{
  "status": "INPROCESS",
  "type": "WITHDRAWAL",
  "docid": 216544,
  "request_id": "request-id-12345",
  "withdrawal": {
    "san": "90ce74932027804177",
    "amount": 3.82,
    "currency": "USD"
  },
}
```

**Response Parameters:**

<table><thead><tr><th width="203.6666259765625">Field</th><th width="180.1109619140625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>String</td><td>Operation type (WITHDRAWAL)</td></tr><tr><td><code>status</code></td><td>String</td><td><p>Current status of the operation </p><p>(INPROCESS, EXECUTED, DECLINED)</p></td></tr><tr><td><code>docid</code></td><td>Number</td><td>Document ID for tracking the operation</td></tr><tr><td><code>request_id</code></td><td>String</td><td>The request ID provided in the request</td></tr><tr><td><code>withdrawal</code></td><td>Object</td><td>Withdrawal operation details</td></tr><tr><td><code>withdrawal.san</code></td><td>String</td><td>Secure Account Number (card identifier)</td></tr><tr><td><code>withdrawal.amount</code></td><td>Decimal</td><td>Amount withdrawn from the card</td></tr><tr><td><code>withdrawal.currency</code></td><td>String</td><td>Currency code (USD, EUR, etc.)</td></tr></tbody></table>


# Card Block

Permanently blocks a card. This operation cannot be reversed.

**Endpoint:** `POST /{san}/block`

**Path Parameters:**

* `san` - Secure Account Number (card identifier)

**Content-Type:** `application/json`

**Request Body:**

```json
{
  "request_id": "request-id-12345"
}
```

**Request Parameters:**

<table><thead><tr><th width="131">Field</th><th width="95.5555419921875">Type</th><th width="109">Required</th><th width="186">Constraints</th><th>Description</th></tr></thead><tbody><tr><td><code>request_id</code></td><td>String</td><td>Yes</td><td>12-36 characters</td><td>Unique request identifier</td></tr></tbody></table>

**Response:**

```json
{
  "type": "BLOCK",
  "status": "INPROCESS",
  "docid": 123456,
  "request_id": "request-id-12345"
}
```

**Response Parameters:**

<table><thead><tr><th width="185.888916015625">Field</th><th width="152.333251953125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>String</td><td>Operation type (BLOCK)</td></tr><tr><td><code>status</code></td><td>String</td><td><p>Current status of the operation </p><p>(INPROCESS, EXECUTED, DECLINED)</p></td></tr><tr><td><code>docid</code></td><td>Number</td><td>Document ID for tracking the operation</td></tr><tr><td><code>request_id</code></td><td>String</td><td>The request ID provided in the request</td></tr></tbody></table>


# Get Blocked Card Details

Retrieves information about a blocked card including released balance.

**Endpoint:** `GET /{san}/block-detailes`

**Path Parameters:**

* `san` - Secure Account Number (card identifier)

**Response:**

```json
{
  "san": "1234567890",
  "releasedBalance": 15.75,
  "currency": "USD"
}
```

**Response Parameters:**

<table><thead><tr><th width="222.4444580078125">Field</th><th width="165.6666259765625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>san</code></td><td>String</td><td>Secure Account Number (card identifier)</td></tr><tr><td><code>releasedBalance</code></td><td>BigDecimal</td><td>Balance released back to user account after blocking</td></tr><tr><td><code>currency</code></td><td>String</td><td>Currency code (USD, EUR, etc.)</td></tr></tbody></table>


# Get Card Request Status

Retrieves the status of a card operation(ISSUE, TOPUP, WITHDRAWAL, BLOCK) request using either request ID or document ID.

**Endpoint:** `GET /request/status`

**Query Parameters:**

<table><thead><tr><th width="166.77783203125">Parameter</th><th width="139">Type</th><th width="149.22216796875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>request_id</code></td><td>String</td><td>Conditional</td><td>Unique request identifier</td></tr><tr><td><code>docid</code></td><td>Number</td><td>Conditional</td><td>Document ID</td></tr></tbody></table>

**Note:** Either `request_id` or `docid` must be provided.

**Response (Block Operation):**

```json
{
  "type": "BLOCK",
  "status": "EXECUTED",
  "docid": 123456,
  "request_id": "request-id-12345",
  "created": "2025-07-03T09:21:55.605Z",
  "block": {
    "san": "1234567890",
    "releasedBalance": 150.75,
    "currency": "USD"
  }
}
```

**Response Parameters (Block Operation):**

<table><thead><tr><th width="216.77783203125">Field</th><th width="155">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>String</td><td>Operation type (BLOCK)</td></tr><tr><td><code>status</code></td><td>String</td><td>Current status of the operation (see Status Values below)</td></tr><tr><td><code>docid</code></td><td>Number</td><td>Document ID for tracking the operation</td></tr><tr><td><code>request_id</code></td><td>String</td><td>The request ID provided in the original request</td></tr><tr><td><code>block</code></td><td>Object</td><td>Block operation details</td></tr><tr><td><code>block.san</code></td><td>String</td><td>Secure Account Number (card identifier)</td></tr><tr><td><code>block.releasedBalance</code></td><td>Decimal</td><td>Balance released back to user account after blocking</td></tr><tr><td><code>block.currency</code></td><td>String</td><td>Currency code (USD, EUR, etc.)</td></tr></tbody></table>

**Response (Top-Up Operation):**

```json
{
  "type": "TOPUP",
  "status": "EXECUTED",
  "docid": 123456,
  "request_id": "request-id-12345",
  "created": "2025-07-03T09:21:55.605Z",
  "topup": {
    "san": "1234567890",
    "amount": 100.00,
    "currency": "USD"
  }
}
```

**Response Parameters (Top-Up Operation):**

<table><thead><tr><th width="195.2222900390625">Field</th><th width="160.111083984375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>String</td><td>Operation type (TOPUP)</td></tr><tr><td><code>status</code></td><td>String</td><td>Current status of the operation (see Status Values below)</td></tr><tr><td><code>docid</code></td><td>Number</td><td>Document ID for tracking the operation</td></tr><tr><td><code>request_id</code></td><td>String</td><td>The request ID provided in the original request</td></tr><tr><td><code>topup</code></td><td>Object</td><td>Top-up operation details</td></tr><tr><td><code>topup.san</code></td><td>String</td><td>Secure Account Number (card identifier)</td></tr><tr><td><code>topup.amount</code></td><td>Decimal</td><td>Amount added to the card</td></tr><tr><td><code>topup.currency</code></td><td>String</td><td>Currency code (USD, EUR, etc.)</td></tr></tbody></table>

**Response (Issue Operation):**

```json
{
  "type": "ISSUE",
  "status": "EXECUTED",
  "docid": 123456,
  "request_id": "request-id-12345",
  "created": "2025-07-03T09:21:55.605Z",
  "issue": {
    "san": "1234567890",
    "pan": "************5678",
    "expYear": 2026,
    "expMonth": 12,
    "cvv": "123",
    "currency": "USD",
    "initialBalance": 100.00,
    "cardName": "My Card"
  }
}
```

**Response Parameters (Issue Operation):**

<table><thead><tr><th width="222.2222900390625">Field</th><th width="157.888916015625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>String</td><td>Operation type (ISSUE)</td></tr><tr><td><code>status</code></td><td>String</td><td>Current status of the operation (see Status Values below)</td></tr><tr><td><code>docid</code></td><td>Number</td><td>Document ID for tracking the operation</td></tr><tr><td><code>request_id</code></td><td>String</td><td>The request ID provided in the original request</td></tr><tr><td><code>issue</code></td><td>Object</td><td>Issue operation details</td></tr><tr><td><code>issue.san</code></td><td>String</td><td>Secure Account Number (card identifier)</td></tr><tr><td><code>issue.pan</code></td><td>String</td><td>Masked Primary Account Number</td></tr><tr><td><code>issue.expYear</code></td><td>Number</td><td>Card expiration year</td></tr><tr><td><code>issue.expMonth</code></td><td>Number</td><td>Card expiration month (1-12)</td></tr><tr><td><code>issue.cvv</code></td><td>String</td><td>Card verification value</td></tr><tr><td><code>issue.currency</code></td><td>String</td><td>Card currency code</td></tr><tr><td><code>issue.initialBalance</code></td><td>Decimal</td><td>Initial balance loaded on the card</td></tr><tr><td><code>issue.cardName</code></td><td>String</td><td>Custom name assigned to the card</td></tr></tbody></table>

**Response (Withdrawal Operation):**

```json
{
  "type": "WITHDRAWAL",
  "status": "EXECUTED",
  "docid": 123456,
  "request_id": "request-id-12345",
  "created": "2025-07-03T09:21:55.605Z",
  "withdrawal": {
    "san": "1234567890",
    "amount": 50.00,
    "currency": "USD"
  }
}
```

**Response Parameters (Withdrawal Operation):**

<table><thead><tr><th width="225.77783203125">Field</th><th width="139">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>String</td><td>Operation type (WITHDRAWAL)</td></tr><tr><td><code>status</code></td><td>String</td><td>Current status of the operation (see Status Values below)</td></tr><tr><td><code>docid</code></td><td>Integer</td><td>Document ID for tracking the operation</td></tr><tr><td><code>request_id</code></td><td>String</td><td>The request ID provided in the original request</td></tr><tr><td><code>withdrawal</code></td><td>Object</td><td>Withdrawal operation details</td></tr><tr><td><code>withdrawal.san</code></td><td>String</td><td>Secure Account Number (card identifier)</td></tr><tr><td><code>withdrawal.amount</code></td><td>Decimal</td><td>Amount withdrawn from the card</td></tr><tr><td><code>withdrawal.currency</code></td><td>String</td><td>Currency code (USD, EUR, etc.)</td></tr></tbody></table>

**Operation Types:**

* `ISSUE` - Card issuance
* `TOPUP` - Card top-up
* `WITHDRAWAL` - Card withdrawal
* `BLOCK` - Card blocking

**Status Values:**

* `INPROCESS` - Operation is being processed
* `EXECUTED` - Operation completed successfully
* `DECLINED` - Operation was declined for some reason


# Get Card Requests List

Retrieves a paginated list of operation requests (ISSUE, TOPUP, WITHDRAWAL, BLOCK) for a specific card.

**Endpoint:** `GET /{san}/requests`

**Path Parameters:**

<table><thead><tr><th width="154.22222900390625">Parameter</th><th width="126.4444580078125">Type</th><th width="115.888916015625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>san</code></td><td>String</td><td>Yes</td><td>Secure Account Number (card identifier)</td></tr></tbody></table>

**Query Parameters:**

<table><thead><tr><th width="125.5555419921875">Parameter</th><th width="115.7777099609375">Type</th><th width="115.8887939453125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>limit</code></td><td>Number</td><td>Yes</td><td>Maximum number of records to return (max 100)</td></tr><tr><td><code>offset</code></td><td>Number</td><td>Yes</td><td>Number of records to skip for pagination (0-based)</td></tr></tbody></table>

**Response:**

```json
{
  "count": 6,
  "requests": [
    {
      "status": "EXECUTED",
      "san": "222-333-44-55",
      "type": "BLOCK",
      "docid": 362822828,
      "request_id": "block-101-00465",
      "created": "2025-07-03T09:21:55.605Z"
    },
    {
      "status": "EXECUTED",
      "san": "222-333-44-55",
      "type": "WITHDRAWAL",
      "docid": 362822762,
      "request_id": "withdraw0000009",
      "created": "2025-07-03T09:20:55.605Z"
    },
    {
      "status": "EXECUTED",
      "san": "222-333-44-55",
      "type": "WITHDRAWAL",
      "docid": 362822740,
      "request_id": "withdraw0000008",
      "created": "2025-07-03T09:19:55.605Z"
    },
    {
      "status": "EXECUTED",
      "san": "222-333-44-55",
      "type": "TOPUP",
      "docid": 362822718,
      "request_id": "topup-100-06-493",
      "created": "2025-07-03T09:18:55.605Z"
    },
    {
      "status": "EXECUTED",
      "san": "222-333-44-55",
      "type": "TOPUP",
      "docid": 362822696,
      "request_id": "topup-100-05-0083",
      "created": "2025-07-03T09:17:55.605Z"
    },
    {
      "status": "EXECUTED",
      "san": "222-333-44-55",
      "type": "ISSUE",
      "docid": 362822674,
      "request_id": "issue-100-001-00",
      "created": "2025-07-03T09:15:55.605Z"
    }
  ]
}
```

**Response Parameters:**

<table><thead><tr><th width="216.77783203125">Field</th><th width="155">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>count</code></td><td>Number</td><td>Total number of matching records (for pagination)</td></tr><tr><td><code>requests</code></td><td>Array</td><td>Array of response objects</td></tr><tr><td><code>requests[].created</code></td><td>String (ISO 8601)</td><td>Request created timestamp in UTC</td></tr><tr><td><code>requests[].san</code></td><td>String</td><td>Secure Account Number (card identifier)</td></tr><tr><td><code>requests[].type</code></td><td>String</td><td>Operation type(see Operation Values below)</td></tr><tr><td><code>requests[].status</code></td><td>String</td><td>Current status of the operation (see Status Values below)</td></tr><tr><td><code>requests[].docid</code></td><td>Number</td><td>Document ID for tracking the operation</td></tr><tr><td><code>requests[].request_id</code></td><td>String</td><td>The request ID provided in the original request</td></tr></tbody></table>

**Operation Types:**

* `ISSUE` - Card issuance
* `TOPUP` - Card top-up
* `WITHDRAWAL` - Card withdrawal
* `BLOCK` - Card blocking

**Status Values:**

* `INPROCESS` - Operation is currently being processed
* `EXECUTED` - Operation completed successfully
* `DECLINED` - Operation was declined


# Get User Requests List

Retrieves a paginated list of operation requests (ISSUE, TOPUP, WITHDRAWAL, BLOCK) by user account.

**Endpoint:** `GET /requests`

**Query Parameters:**

<table><thead><tr><th width="125.5555419921875">Parameter</th><th width="115.7777099609375">Type</th><th width="115.8887939453125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>limit</code></td><td>Number</td><td>Yes</td><td>Maximum number of records to return (max 100)</td></tr><tr><td><code>offset</code></td><td>Number</td><td>Yes</td><td>Number of records to skip for pagination (0-based)</td></tr></tbody></table>

**Response:**

```json
{
  "count": 6,
  "requests": [
    {
      "status": "EXECUTED",
      "san": "222-333-44-55",
      "type": "BLOCK",
      "docid": 36282228,
      "request_id": "block-101-00465",
      "created": "2025-07-03T09:21:55.605Z"
    },
    {
      "status": "EXECUTED",
      "san": "222-333-44-56",
      "type": "WITHDRAWAL",
      "docid": 36282762,
      "request_id": "withdraw0000009",
      "created": "2025-07-03T09:20:55.605Z"
    },
    {
      "status": "EXECUTED",
      "san": "222-333-44-9999",
      "type": "WITHDRAWAL",
      "docid": 32822740,
      "request_id": "withdraw0000008",
      "created": "2025-07-03T09:19:55.605Z"
    },
    {
      "status": "EXECUTED",
      "san": "222-333-44-56657",
      "type": "TOPUP",
      "docid": 362782718,
      "request_id": "topup-100-06-493",
      "created": "2025-07-03T09:18:55.605Z"
    },
    {
      "status": "EXECUTED",
      "san": "222-333-44-55",
      "type": "ISSUE",
      "docid": 362888674,
      "request_id": "issue-100-001-00",
      "created": "2025-07-03T09:15:55.605Z"
    }
  ]
}
```

**Response Parameters:**

<table><thead><tr><th width="216.77783203125">Field</th><th width="155">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>count</code></td><td>Number</td><td>Total number of matching records (for pagination)</td></tr><tr><td><code>requests</code></td><td>Array</td><td>Array of response objects</td></tr><tr><td><code>requests[].created</code></td><td>String (ISO 8601)</td><td>Request created timestamp in UTC</td></tr><tr><td><code>requests[].type</code></td><td>String</td><td>Operation type(see Operation Values below)</td></tr><tr><td><code>requests[].san</code></td><td>String</td><td>Secure Account Number (card identifier)</td></tr><tr><td><code>requests[].status</code></td><td>String</td><td>Current status of the operation (see Status Values below)</td></tr><tr><td><code>requests[].docid</code></td><td>Number</td><td>Document ID for tracking the operation</td></tr><tr><td><code>requests[].request_id</code></td><td>String</td><td>The request ID provided in the original request</td></tr></tbody></table>

**Operation Types:**

* `ISSUE` - Card issuance
* `TOPUP` - Card top-up
* `WITHDRAWAL` - Card withdrawal
* `BLOCK` - Card blocking

**Status Values:**

* `INPROCESS` - Operation is currently being processed
* `EXECUTED` - Operation completed successfully
* `DECLINED` - Operation was declined


# Card Freeze/Unfreeze API

Temporarily freezes a card. The card can be unfrozen later.

#### Freeze Card <a href="#freeze-card" id="freeze-card"></a>

**Endpoint:** `POST /{san}/freeze`

**Path Parameters:**

* `san` - Secure Account Number (card identifier)

**Content-Type:** `application/json`

**Response:**

```json
{
  "success": true,
  "message": "Card frozen successfully"
}
```

***

#### Unfreeze Card <a href="#unfreeze-card" id="unfreeze-card"></a>

Unfreezes a previously frozen card.

**Endpoint:** `POST /{san}/unfreeze`

**Path Parameters:**

* `san` - Secure Account Number (card identifier)

**Content-Type:** `application/json`

**Response:**

```json
{
  "success": true,
  "message": "Card activated successfully"
}
```

***

**Response Parameters:**

<table><thead><tr><th width="151.22216796875">Field</th><th width="189.111083984375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>success</code></td><td>Boolean</td><td>Indicates if the operation was successful</td></tr><tr><td><code>message</code></td><td>String</td><td>Descriptive message about the operation result</td></tr></tbody></table>


# Card Email Update

Updates the email address associated with a card.

**Endpoint:** `POST /{san}/update-email`

**Path Parameters:**

* `san` - Secure Account Number (card identifier)

**Content-Type:** `application/json`

**Request Body:**

```json
{
  "email": "user@example.com"
}
```

**Request Parameters:**

| Field   | Type   | Required | Constraints        | Description       |
| ------- | ------ | -------- | ------------------ | ----------------- |
| `email` | String | Yes      | Valid email format | New email address |

**Response:**

```json
{
  "success": true,
  "message": "Email updated successfully"
}
```

**Response Parameters:**

<table><thead><tr><th width="155.666748046875">Field</th><th width="175.3333740234375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>success</code></td><td>Boolean</td><td>Indicates if the operation was successful</td></tr><tr><td><code>message</code></td><td>String</td><td>Descriptive message about the operation result</td></tr></tbody></table>


# Card Phone Update

Updates the phone number associated with the card (available for certain card products).

**Endpoint:** `POST /{san}/update-phone`

**Path Parameters:**

* `san` - Secure Account Number (card identifier)

**Content-Type:** `application/json`

**Request Body:**

```json
{
  "zoneNumber": "+48",
  "phoneNumber": "123456789"
}
```

**Request Parameters:**

| Field         | Type   | Required | Description                               |
| ------------- | ------ | -------- | ----------------------------------------- |
| `zoneNumber`  | String | Yes      | international country calling code with + |
| `phoneNumber` | String | Yes      | national significant number               |

**Response:**

```json
{
  "success": true,
  "message": "card update phone success"
}
```


# Card PIN Management

Set/Update a PIN for a card

#### Set PIN <a href="#set-pin" id="set-pin"></a>

Sets a PIN for a card (first-time setup).

**Endpoint:** `POST /{san}/set-pin`

**Path Parameters:**

* `san` - Secure Account Number (card identifier)

**Content-Type:** `application/json`

**Request Body:**

```json
{
  "pin": "1234"
}
```

**Request Parameters:**

| Field | Type   | Required | Constraints      | Description  |
| ----- | ------ | -------- | ---------------- | ------------ |
| `pin` | String | Yes      | Exactly 4 digits | New PIN code |

**Response:**

```json
{
  "success": true,
  "message": "PIN set successfully"
}
```

***

#### Update PIN <a href="#update-pin" id="update-pin"></a>

Updates an existing card PIN.

**Endpoint:** `POST /{san}/update-pin`

**Path Parameters:**

* `san` - Secure Account Number (card identifier)

**Content-Type:** `application/json`

**Request Body:**

```json
{
  "oldPin": "1234",
  "pin": "5678"
}
```

**Request Parameters:**

| Field    | Type   | Required                     | Constraints      | Description      |
| -------- | ------ | ---------------------------- | ---------------- | ---------------- |
| `oldPin` | String | Yes (for some products only) | Exactly 4 digits | Current PIN code |
| `pin`    | String | Yes                          | Exactly 4 digits | New PIN code     |

**Response:**

```json
{
  "success": true,
  "message": "PIN updated successfully"
}
```

***

**Response Parameters:**

<table><thead><tr><th width="174.5556640625">Field</th><th width="164.8887939453125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>success</code></td><td>Boolean</td><td>Indicates if the operation was successful</td></tr><tr><td><code>message</code></td><td>String</td><td>Descriptive message about the operation result</td></tr></tbody></table>


# Get Card List

Retrieves a paginated list of cards for the authenticated user.

**Endpoint:** `GET /list`

**Query Parameters:**

<table><thead><tr><th width="120.3333740234375">Parameter</th><th width="114.5555419921875">Type</th><th width="108.1112060546875">Required</th><th width="403.8890380859375">Description</th></tr></thead><tbody><tr><td><code>limit</code></td><td>Number</td><td>Yes</td><td>Maximum number of cards to return (max 100)</td></tr><tr><td><code>offset</code></td><td>Number</td><td>Yes</td><td>Number of cards to skip for pagination (0-based)</td></tr></tbody></table>

**Response:**

```json
{
  "count": 25,
  "cards": [
    {
      "created": "2026-01-15T10:30:00.000Z",
      "blocked": "2025-07-04T12:33:05.916Z",
      "san": "1234567890",
      "pan": "************7527",
      "expyear": 2026,
      "expmonth": 12,
      "currency": "USD",
      "cardsystem": "VISA",
      "cardname": "My Card"
    },
    {
      "created": "2026-01-10T08:15:30.000Z",
      "san": "0987654321",
      "pan": "************2345",
      "expyear": 2027,
      "expmonth": 6,
      "currency": "EUR",
      "cardsystem": "MC",
      "cardName": "Business Card",
    }
  ]
}
```

**Response Fields:**

<table><thead><tr><th width="203.888916015625">Field</th><th width="214.5555419921875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>count</code></td><td>Number</td><td>Total number of cards available (for pagination)</td></tr><tr><td><code>cards</code></td><td>Array</td><td>Array of card objects</td></tr><tr><td><code>cards[].san</code></td><td>String</td><td>Secure Account Number (unique card identifier)</td></tr><tr><td><code>cards[].created</code></td><td>String (ISO 8601)</td><td>Card creation timestamp in UTC</td></tr><tr><td><code>cards[].pan</code></td><td>String</td><td>Masked Card Number</td></tr><tr><td><code>cards[].expYear</code></td><td>Number</td><td>Card expiration year</td></tr><tr><td><code>cards[].expMonth</code></td><td>Number</td><td>Card expiration month (1-12)</td></tr><tr><td><code>cards[].currency</code></td><td>String</td><td>Card currency code (USD, EUR, etc.)</td></tr><tr><td><code>cards[].cardSystem</code></td><td>String</td><td>VISA, MC</td></tr><tr><td><code>cards[].cardName</code></td><td>String</td><td>User-defined card name</td></tr><tr><td><code>cards[].blocked</code></td><td>String (ISO 8601) or null</td><td>Card blocked timestamp in UTC</td></tr></tbody></table>


# Card Transactions

Retrieves paginated transaction history for a card.

**Endpoint:** `POST /{san}/transactions`

**Path Parameters:**

* `san` - Secure Account Number (card identifier)

**Content-Type:** `application/json`

**Request Body:**

```json
{
  "page": 0,
  "size": 20,
  "from": "2026-01-01T00:00:00.000Z",
  "to": "2026-02-04T23:59:59.999Z"
}
```

**Request Parameters:**

<table><thead><tr><th width="108.22216796875">Field</th><th width="112.3333740234375">Type</th><th width="105.111083984375">Required</th><th width="197.4444580078125">Constraints</th><th>Description</th></tr></thead><tbody><tr><td><code>page</code></td><td>Number</td><td>Yes</td><td>>= 0</td><td>Page number (0-based)</td></tr><tr><td><code>size</code></td><td>Number</td><td>Yes</td><td>1-100</td><td>Number of transactions per page</td></tr><tr><td><code>from</code></td><td>String</td><td>No</td><td>ISO-8601 format(UTC)</td><td>Start date for filtering</td></tr><tr><td><code>to</code></td><td>String</td><td>No</td><td>ISO-8601 format(UTC)</td><td>End date for filtering</td></tr></tbody></table>

**Response:**

```json
{
  "total": 6,
  "list": [
    {
      "id": "948b42f1-7dcf-43c0-a503-4e0287b9d9c1",
      "date": "2026-01-10T18:34:03.71Z",
      "authorizationCode": "744126",
      "transactionId": "A2024190693782999041",
      "isForcePost": false,
      "transactionSum": 5,
      "transactionCommission": 0,
      "cardCurrency": "USD",
      "originTxId": "A2024190524630913026",
      "txAmount": 5,
      "txCurrency": "USD",
      "transactionRecipient": "GGG.COM SURREY GBR",
      "merchantCategory": "5734 COMPUTER SOFTWARE STORES",
      "transactionValue": 5,
      "declineReason": null,
      "status": "expense"
    }
  ]
}
```

**Response Parameters:**

<table><thead><tr><th width="263.4444580078125">Field</th><th width="186.4444580078125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>total</code></td><td>Number</td><td>Total number of transactions matching the query</td></tr><tr><td><code>list</code></td><td>Array</td><td>Array of transaction objects</td></tr><tr><td><code>list[].date</code></td><td>String (ISO 8601)</td><td>Transaction date and time in UTC</td></tr><tr><td><code>list[].authorizationCode</code></td><td>String or null</td><td>Authorization code for the transaction (if available)</td></tr><tr><td><code>list[].transactionId</code></td><td>String</td><td>Unique transaction identifier</td></tr><tr><td><code>list[].isForcePost</code></td><td>Boolean</td><td>Indicates if the transaction was force-posted</td></tr><tr><td><code>list[].transactionSum</code></td><td>Decimal</td><td>Total transaction amount including commission</td></tr><tr><td><code>list[].transactionCommission</code></td><td>Decimal</td><td>Commission fee charged for the transaction</td></tr><tr><td><code>list[].cardCurrency</code></td><td>String</td><td>Currency code of the card (USD, EUR)</td></tr><tr><td><code>list[].originTxId</code></td><td>String or null</td><td>Original transaction identifier</td></tr><tr><td><code>list[].txAmount</code></td><td>Decimal</td><td>Transaction amount in the original transaction currency</td></tr><tr><td><code>list[].txCurrency</code></td><td>String</td><td>Currency code of the original transaction (USD, EUR, etc.)</td></tr><tr><td><code>list[].transactionRecipient</code></td><td>String</td><td>Merchant name and location information</td></tr><tr><td><code>list[].merchantCategory</code></td><td>String or null</td><td>Merchant category code (MCC) if available</td></tr><tr><td><code>list[].id</code></td><td>String (UUID)</td><td>Internal transaction record identifier</td></tr><tr><td><code>list[].transactionValue</code></td><td>Decimal</td><td>Transaction amount before commission</td></tr><tr><td><code>list[].declineReason</code></td><td>String or null</td><td>Reason for decline if transaction was declined</td></tr><tr><td><code>list[].status</code></td><td>String</td><td>Transaction status (expense, income, declined, etc.)</td></tr></tbody></table>

**Transaction Status Values:**

<table><thead><tr><th width="314.4444580078125">Status</th><th>Description</th></tr></thead><tbody><tr><td><code>authorization</code></td><td>Transaction authorization pending</td></tr><tr><td><code>authorization_decline</code></td><td>Transaction declined or cancelled</td></tr><tr><td><code>expense</code></td><td>Completed expense/purchase transaction</td></tr><tr><td><code>refund</code></td><td>Refund transaction completed</td></tr><tr><td><code>reversal</code></td><td>Transaction reversed</td></tr><tr><td><code>maintenance_fee</code></td><td>Card maintenance or service fee</td></tr></tbody></table>


# OTP(3ds) codes

Retrieves up to the last 10 OTP codes for the card.

**Endpoint:** `GET /{san}/otp-codes`

**Path Parameters:**

* `san` - Secure Account Number (card identifier)

**Response:**

```json
[
  {
    "code": "123456",
    "date": "2026-06-25T19:35:01.543000Z"
  },
  {
    "code": "654321",
    "date": "2026-06-25T19:27:43.733000Z"
  }
]
```

**Response Parameters:**

| Field  | Type   | Description                                                    |
| ------ | ------ | -------------------------------------------------------------- |
| `code` | string | One-time password returned for the card.                       |
| `date` | string | Timestamp when the OTP code was generated, in ISO 8601 format. |


# KYC

Base URL: /cardspro/cards/v1

#### Endpoints Summary

<table><thead><tr><th width="88.111083984375">Method</th><th width="384.1112060546875">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td>POST</td><td><a href="/api/kyc/initiate-new-kyc"><code>/kyc/start</code></a></td><td>Initiates a new KYC process</td></tr><tr><td>GET</td><td><a href="/api/kyc/query-kyc-status"><code>/kyc/status/{kycExternalUserId}/{sort}</code></a></td><td>Get current status of a KYC</td></tr><tr><td>GET</td><td><a href="/api/kyc/query-kyc-status"><code>/kyc/status-by-uuid/{uuid}</code></a></td><td>Get current status of a KYC</td></tr><tr><td>POST</td><td><a href="/api/kyc/fill-kyc-data"> <code>/kyc/set-data/{uuid}</code></a></td><td>Fills basic data for KYC</td></tr><tr><td>POST</td><td><a href="/api/kyc/add-kyc-picture"><code>/kyc/set-picture/{uuid}/{type}</code></a></td><td>Attaches a picture to KYC</td></tr><tr><td>POST</td><td><a href="/api/kyc/send-kyc-for-verification"><code>/kyc/confirm/{uuid}</code></a></td><td>Sends filled KYC for verification.</td></tr></tbody></table>


# Initiate new KYC

Initiates a new KYC process.

**Endpoint:** `POST /kyc/start`

{% hint style="warning" %}
**Starting a new KYC for the same kycExternalUserId will make the current KYC obsolete.**
{% endhint %}

#### **Request Body**

```json
{
  "kycExternalUserId": "unique-string",
  "callbackUrl": "string",
  "sort": "string"
}
```

#### Request Fields <a href="#request-fields" id="request-fields"></a>

<table><thead><tr><th width="204.22222900390625">Field</th><th width="123.22216796875">Type</th><th width="110.5555419921875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>kycExternalUserId</code></td><td>String</td><td>Yes</td><td>Your unique final user ID</td></tr><tr><td><code>sort</code></td><td>String</td><td>Yes</td><td>Sort of KYC you are making KYC for</td></tr><tr><td><code>callbackUrl</code></td><td>String</td><td>No</td><td>URL to call via <code>POST</code> when KYC status changes <a href="/api/operations-callbacks#id-8-transaction-card-callback-1"><em>(see callback fields)</em></a></td></tr></tbody></table>

#### **Response**

If the request is successful, the API returns a JSON object containing the URL for manual KYC completion and the uuid for automatic KYC processing.

```json
{
  "uuid": "unique-string",
  "urlForUser": "https://somewhere.to/someuuid"
}
```

#### Response Fields <a href="#response-fields" id="response-fields"></a>

<table><thead><tr><th width="207.77783203125">Field</th><th width="170.7777099609375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>uuid</code></td><td>String</td><td>UUID of KYC for automatic KYC processing.</td></tr><tr><td><code>urlForUser</code></td><td>String</td><td>URL for manual KYC completion</td></tr></tbody></table>


# Query KYC status

Returns the current status of a KYC.

**Endpoint:** `GET /kyc/status/{kycExternalUserId}/{sort}`

Path Parameters:

* `kycExternalUserId`  - Your unique final user ID
* `sort`  - KYS sort you are making KYC for

**Endpoint:** `GET /kyc/status-by-uuid/{uuid}`&#x20;

Path Parameters:

* `uuid`  - UUID of KYC&#x20;

#### Response <a href="#response-1" id="response-1"></a>

If the request is successful, the API returns a JSON object containing the KYC status.

```json
{
  "kycExternalUserId": "your unique user id",
  "status": "DECLINED",
  "reason": "photo is dirty",
  "uuid": "uuid-of-kyc"
}
```

#### Response Fields

| Field               | Type             | Description                                   |
| ------------------- | ---------------- | --------------------------------------------- |
| `kycExternalUserId` | String           | Your unique final user id                     |
| `status`            | String           | Status of KYC(see KYC Status Reference below) |
| `reason`            | String(optional) | Explanation of Status of KYC                  |
| `uuid`              | String           | UUID of KYC                                   |

**KYC Status Reference**

| Status         | Description                    |
| -------------- | ------------------------------ |
| `NEW`          | KYC created                    |
| `COMPLETED`    | 📝 User has completed the form |
| `UNDER_REVIEW` | 🔍 KYC is under review         |
| `APPROVED`     | ✅ KYC verified — ready to use! |
| `DECLINED`     | ❌ KYC was declined             |
| `EXPIRED`      | ⏰ KYC has expired              |


# Fill KYC data

Fills basic data for KYC.

**Endpoint:** `POST /kyc/set-data/{uuid}`

{% hint style="info" %}
**Body is JSON which format depends on sort of KYC.**
{% endhint %}

**Path Parameters**

* `uuid`  - UUID of KYC

**Response**

If the request is successful, the API returns http code 200.

### &#x20;**'S00'  sort of KYC**

#### **Request Body**&#x20;

{% content-ref url="/pages/NGtxfT6nq4CEPhaDKDF5" %}
[S00](/api/kyc/fill-kyc-data/s00)
{% endcontent-ref %}

{% content-ref url="/pages/T2sivr6HrJREuOPfxOt7" %}
[W02111048, W02111030](/api/kyc/fill-kyc-data/w02111048-w02111030)
{% endcontent-ref %}


# S00

Fills basic data for KYC sort=S00.

**Request Body**&#x20;

```json
{
  "documentCode": "2",
  "documentNumber": "DD009292928",
  "documentIssuePlace": "Brandenburg",
  "fullName": "Adam Kupferblum",
  "fullNameEn": "Adam Kupferblum",
  "genderCode": "1",
  "birthDate": "1980-12-12",
  "occupationCode": "3",
  "nationality": "DE",
  "country": "DE",
  "province": " Brandenburg",
  "addressLine": "Knesebeckstrasse 78",
  "addressEn": "Knesebeckstrasse 78",
  "city": "Forst",
  "postalCode": "03141",
  "areaCode": "+49",
  "phone": "297546567",
  "email": "my@mail.com"
}
```

<table data-header-hidden><thead><tr><th width="193.333251953125">Field</th><th width="97.22222900390625">Type</th><th width="110.2222900390625">Required</th><th>Remark</th><th>Description</th></tr></thead><tbody><tr><td>documentCode</td><td>String</td><td>yes</td><td><p>1 - ID card</p><p>2 - Passport</p></td><td>Type of Identity Document</td></tr><tr><td>documentNumber</td><td>String</td><td>yes</td><td><br></td><td>Identification Number</td></tr><tr><td>documentIssuePlace</td><td>String</td><td>yes</td><td></td><td>Document Issue Place</td></tr><tr><td>fullName</td><td>String</td><td>yes</td><td><br></td><td>Full name</td></tr><tr><td>fullNameEn</td><td>String</td><td>yes</td><td><br></td><td>Full Name (in English)</td></tr><tr><td>genderCode</td><td>String</td><td>yes</td><td><p>1 - male</p><p>2 - female</p></td><td>Gender</td></tr><tr><td>birthDate</td><td>String</td><td>yes</td><td>year-month-day</td><td>Birthday</td></tr><tr><td>occupationCode</td><td>String</td><td>yes</td><td> <a href="#occupation-reference">Reference</a></td><td>Occupation</td></tr><tr><td>nationality</td><td>String</td><td>yes</td><td>ISO 3166-1 alpha-2</td><td>nationality</td></tr><tr><td>country</td><td>String</td><td>yes</td><td>ISO 3166-1 alpha-2</td><td>Country of Residence</td></tr><tr><td>province</td><td>String</td><td>yes</td><td><br></td><td>State / Province</td></tr><tr><td>addressLine</td><td>String</td><td>yes</td><td><br></td><td>Residential Address</td></tr><tr><td>addressEn</td><td>String</td><td>yes</td><td><br></td><td>Residential Address (in English)</td></tr><tr><td>city</td><td>string</td><td>yes</td><td><br></td><td>City</td></tr><tr><td>postalCode</td><td>string</td><td>yes</td><td><br></td><td>Postal Code</td></tr><tr><td>areaCode</td><td>string</td><td>yes</td><td>+44</td><td>Phone Country Calling Code</td></tr><tr><td>phone</td><td>string</td><td>yes</td><td><br></td><td>Phone number</td></tr><tr><td>email</td><td>string</td><td>yes</td><td>Maximum 29 characters limit</td><td>Email</td></tr></tbody></table>

#### **'occupation' Reference**

| Value | Description                                    |
| ----- | ---------------------------------------------- |
| 1     | Government Officials                           |
| 2     | Government Workers                             |
| 3     | State-Owned Enterprise (SOE) Executives        |
| 4     | State-Owned Enterprise (SOE) Employees         |
| 5     | Private Business Owners & Executives           |
| 6     | Private Business Employees                     |
| 7     | Non-governmental organization (NGO) Executives |
| 8     | Non-governmental organization (NGO) Employees  |
| 9     | Sole Traders                                   |
| 10    | Retirees                                       |
| 11    | Students                                       |
| 12    | Unemployed                                     |
| 13    | Freelancers                                    |


# W02111048, W02111030

Fills basic data for KYC sort=W02111048|W02111030.

### 'W02111048' or 'W02111030'  **sort of KYC**

**Request Body**&#x20;

```json
{
  "areaCode": "+48",
  "phone": "882613981",
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "birthDate": "1990-05-15",
  "nationality": "PL",
  "country": "PL",
  "addressLine": "123 Main Street Apt 4B",
  "postalCode": "10001",
  "gender": "M",
  "documentType": "PASSPORT",
  "documentNumber": "A12345678",
  "documentIssueDate": "2025-03-20",
  "idNoExpiryDate": "2035-03-19"
}
```

<table data-header-hidden><thead><tr><th width="186.66650390625">Field</th><th width="97.22222900390625">Type</th><th width="108.0001220703125">Required</th><th width="172.77783203125">Remark</th><th>Description</th></tr></thead><tbody><tr><td>areaCode</td><td>string</td><td>yes</td><td>+44</td><td>Phone Country Calling Code. length[2...5]</td></tr><tr><td>phone</td><td>string</td><td>yes</td><td>length[5...20]</td><td>Mobile phone number</td></tr><tr><td>firstName</td><td>String</td><td>yes</td><td>length[2...32]<br></td><td>Only English characters are supported. </td></tr><tr><td>lastName</td><td>String</td><td>yes</td><td>length[2...32]</td><td>Only English characters are supported. </td></tr><tr><td>gender</td><td>String</td><td>yes</td><td><code>M</code>: male  <code>F</code>: female</td><td>Gender</td></tr><tr><td>birthDate</td><td>String</td><td>yes</td><td>yyyy-MM-dd</td><td>Birthday</td></tr><tr><td>nationality</td><td>String</td><td>yes</td><td>ISO 3166-1 alpha-2</td><td>nationality</td></tr><tr><td>country</td><td>String</td><td>yes</td><td>ISO 3166-1 alpha-2</td><td>Country of Residence</td></tr><tr><td>addressLine</td><td>String</td><td>yes</td><td>length[2...40].
<br>Can only contain letters, numbers, hyphens and spaces.
<br>regex: ^[A-Za-z0-9- ]+$</td><td>Residential Address.</td></tr><tr><td>city</td><td>string</td><td>yes</td><td><br></td><td>City</td></tr><tr><td>postalCode</td><td>string</td><td>yes</td><td>length[4...10].
<br>regex: ^[a-zA-Z0-9]{1,15}$</td><td>Postal Code.</td></tr><tr><td>email</td><td>string</td><td>yes</td><td> length[5...50]</td><td>Email. <strong>Receive verification code</strong>.</td></tr><tr><td>documentType</td><td>string</td><td>yes</td><td><code>PASSPORT</code>: Passport  <code>DLN</code>: Driver's license <code>GOVERNMENT_ISSUED_ID_CARD</code>: ID Card</td><td>Id type.</td></tr><tr><td>documentNumber</td><td>string</td><td>yes</td><td>length[2...50]</td><td>Id number</td></tr><tr><td>documentIssueDate</td><td>string</td><td>yes</td><td>yyyy-MM-dd</td><td>ID document issuance date.</td></tr><tr><td>idNoExpiryDate</td><td>string</td><td>yes</td><td>yyyy-MM-dd</td><td>ID document  expiration date</td></tr></tbody></table>


# Add KYC picture

Attaches a picture to KYC.

**Endpoint:** `POST /kyc/set-picture/{uuid}/{type}`

**Content-Type:** `application/octet-stream`

**Path Parameters:**

* `uuid`  - UUID of KYC
* `type`  - Type of picture. Needed types depends on sort of KYC

**Request Body:  picture (jpeg) binary.**

{% hint style="warning" %}
**Do not include the request body when generating the signature(CAP-SIGN).**
{% endhint %}

**'type' Reference**

<table><thead><tr><th width="171.88885498046875">Type Value</th><th width="257.666748046875">List of KYC</th><th>Description</th></tr></thead><tbody><tr><td>document_front</td><td><p>S00</p><p>W02111048</p><p>W02111030</p></td><td>Front side of the identity document</td></tr><tr><td>document_back</td><td><p>S00(optional)</p><p>W02111048(optional)</p><p>W02111030(optional)</p></td><td>Back side of the identity document</td></tr><tr><td>selfie</td><td><p>W02111048</p><p>W02111030</p></td><td>User face photo</td></tr></tbody></table>

**Response**

If the request is successful, the API returns http code 200.


# Send KYC for verification

Sends filled KYC for verification.

**Endpoint:** `POST /kyc/confirm/{uuid}`

**Path Parameters:**

* `uuid`  - UUID of KYC

**Response**

If the request is successful, the API returns http code 200.


# Operations callbacks

Card operations callbacks

This document describes the REST callback API for Card operations. Callbacks are HTTP POST requests sent to your configured endpoint when specific card events occur. All callbacks use HTTP headers to identify the callback type and card type.

### Common Headers <a href="#common-headers" id="common-headers"></a>

All callbacks include the following HTTP headers:

<table><thead><tr><th width="222.333251953125">Header</th><th width="236.4444580078125">Description</th><th>Example Values</th></tr></thead><tbody><tr><td><code>X-CP-Callback-Type</code></td><td>Type of callback event</td><td>See individual callbacks below</td></tr></tbody></table>

### 1. Issue Card Callback <a href="#id-1-issue-card-callback" id="id-1-issue-card-callback"></a>

Called when a card issuance operation is completed, regardless of success or failure (see `status` field for outcome).

**Headers:**

```
X-CP-Callback-Type: CARD_ISSUE
```

**Callback Body:**

```json
{
  "docid": 397465223,
  "request_id": "112-2F9-333-070",
  "status": "EXECUTED",
  "san": "3abdea480025082008472",
  "params":{
    "amount":69.72,
    "currency":"USD"
  }
}
```

**Fields:**

<table><thead><tr><th width="171.6666259765625">Field</th><th width="125">Type</th><th width="107">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>docid</code></td><td>Number</td><td>Yes</td><td>Document identifier for the issued card</td></tr><tr><td><code>request_id</code></td><td>String</td><td>Yes</td><td>User request identifier</td></tr><tr><td><code>status</code></td><td>String</td><td>Yes</td><td>Operation status (EXECUTED, DECLINED)</td></tr><tr><td><code>san</code></td><td>String</td><td>Yes</td><td>Secure Account Number(card id)</td></tr><tr><td><code>params</code></td><td>Object</td><td>No</td><td>Additional parameters for the card issuance</td></tr><tr><td><code>params.amount</code></td><td>Decimal</td><td>Yes</td><td>Initial card balance amount</td></tr><tr><td><code>params.currency</code></td><td>String</td><td>Yes</td><td>Currency code (e.g., USD, EUR)</td></tr></tbody></table>

***

### 2. TopUp Card Callback <a href="#id-2-topup-card-callback" id="id-2-topup-card-callback"></a>

Called when a card topup operation is completed, regardless of success or failure (see `status` field for outcome).

**Headers:**

```
X-CP-Callback-Type: CARD_TOPUP
```

**Callback Body:**

```json
{
  "docid": 3974652656,
  "request_id": "112-2F9-333-073",
  "status": "EXECUTED",
  "san": "3abdea0c20250820015603",
  "params": {
    "amount": 405.3,
    "currency": "USD"
  }
}
```

**Fields:**

<table><thead><tr><th width="171.4444580078125">Field</th><th width="124.111083984375">Type</th><th width="109.2222900390625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>docid</code></td><td>Number</td><td>Yes</td><td>Document identifier for the topup transaction</td></tr><tr><td><code>request_id</code></td><td>String</td><td>Yes</td><td>User request identifier</td></tr><tr><td><code>status</code></td><td>String</td><td>Yes</td><td>Operation status (EXECUTED, DECLINED)</td></tr><tr><td><code>san</code></td><td>String</td><td>Yes</td><td>Secure Account Number(card id)</td></tr><tr><td><code>params</code></td><td>Object</td><td>No</td><td>Additional parameters for the topup transaction</td></tr><tr><td><code>params.amount</code></td><td>Decimal</td><td>Yes</td><td>Topup amount added to the card</td></tr><tr><td><code>params.currency</code></td><td>String</td><td>Yes</td><td>Currency code (e.g., USD, EUR)</td></tr></tbody></table>

***

### 3. Withdrawal Card Callback <a href="#id-3-block-card-callback" id="id-3-block-card-callback"></a>

Called when a card withdrawal operation is completed, regardless of success or failure (see `status` field for outcome).

**Headers:**

```
X-CP-Callback-Type: CARD_WITHDRAWAL
```

**Callback Body:**

```json
{
  "docid": 362817383,
  "request_id": "389189423091B9V8",
  "status": "EXECUTED",
  "san": "mock-skqytz",
  "params": {
    "amount": 55.42,
    "currency": "USD"
  }
}
```

**Fields:**

<table><thead><tr><th width="169.22216796875">Field</th><th width="126.3333740234375">Type</th><th width="110.333251953125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>docid</code></td><td>Number</td><td>Yes</td><td>Document identifier for the topup transaction</td></tr><tr><td><code>request_id</code></td><td>String</td><td>No</td><td>User request identifier</td></tr><tr><td><code>status</code></td><td>String</td><td>Yes</td><td>Operation status (EXECUTED, DECLINED)</td></tr><tr><td><code>san</code></td><td>String</td><td>Yes</td><td>Secure Account Number(card id)</td></tr><tr><td><code>params</code></td><td>Object</td><td>No</td><td>Additional parameters for the withdrawal transaction</td></tr><tr><td><code>params.amount</code></td><td>Decimal</td><td>Yes</td><td>Withdrawal amount</td></tr><tr><td><code>params.currency</code></td><td>String</td><td>Yes</td><td>Currency code (e.g., USD, EUR)</td></tr></tbody></table>

### 4. Block Card Callback <a href="#id-3-block-card-callback" id="id-3-block-card-callback"></a>

Called when a card block operation is completed, regardless of success or failure (see `status` field for outcome).

**Headers:**

```
X-CP-Callback-Type: CARD_BLOCK
```

**Callback Body:**

```json
{
  "docid": 3974652610,
  "request_id": "11D-2F9-333-077",
  "status": "EXECUTED",
  "san": "3abdea0c20250820018903",
  "params": {
    "amount": 55.3,
    "currency": "USD"
  }
}
```

**Fields:**

<table><thead><tr><th width="177">Field</th><th width="116.3333740234375">Type</th><th width="111.4443359375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>docid</code></td><td>Number</td><td>Yes</td><td>Document identifier for the topup transaction</td></tr><tr><td><code>request_id</code></td><td>String</td><td>No</td><td>User request identifier</td></tr><tr><td><code>status</code></td><td>String</td><td>Yes</td><td>Operation status (EXECUTED, DECLINED)</td></tr><tr><td><code>san</code></td><td>String</td><td>Yes</td><td>Secure Account Number(card id)</td></tr><tr><td><code>params</code></td><td>Object</td><td>No</td><td>Additional parameters for the topup transaction</td></tr><tr><td><code>params.amount</code></td><td>Decimal</td><td>Yes</td><td>Released balance amount from the blocked card</td></tr><tr><td><code>params.currency</code></td><td>String</td><td>Yes</td><td>Currency code (e.g., USD, EUR)</td></tr></tbody></table>

### 5. Freeze Card Callback <a href="#id-4-freeze-card-callback" id="id-4-freeze-card-callback"></a>

Called when a card is temporarily frozen. A frozen card can be unfrozen later.

**Headers:**

```
X-CP-Callback-Type: CARD_FREEZE
```

**Callback Body:**

```json
{
  "san": "3abdea0c20250820015603"
}
```

**Fields:**

<table><thead><tr><th width="164.6666259765625">Field</th><th width="121.2222900390625">Type</th><th width="120.3333740234375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>san</code></td><td>String</td><td>Yes</td><td>Secure Account Number(card id)</td></tr></tbody></table>

***

### 6. Unfreeze Card Callback <a href="#id-5-unfreeze-card-callback" id="id-5-unfreeze-card-callback"></a>

Called when a previously frozen card is unfrozen and ready for use.

**Headers:**

```
X-CP-Callback-Type: CARD_UNFREEZE
```

**Callback Body:**

```json
{
  "san": "3abdea0c20250820015603"
}
```

**Fields:**

<table><thead><tr><th width="130.3333740234375">Field</th><th width="131.666748046875">Type</th><th width="170.888916015625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>san</code></td><td>String</td><td>Yes</td><td>Secure Account Number(card id)</td></tr></tbody></table>

***

### 7. Extra-Fee Card Charge Callback <a href="#id-6-extra-fee-card-charge-callback" id="id-6-extra-fee-card-charge-callback"></a>

Called when additional fees are charged to a card for specific transaction types.

**Headers:**

```
X-CP-Callback-Type: EXTRA_FEE_CARD
```

**Callback Body:**

```json
{
  "san": "e5792c6821240906122702",
  "amount": 0.25,
  "feeType": "success",
  "txId": "original_tx_id",
  "settlementDiff": true
}
```

**Fields:**

<table><thead><tr><th width="167.111083984375">Field</th><th width="131.6666259765625">Type</th><th width="123.6666259765625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>san</code></td><td>String</td><td>Yes</td><td>Secure Account Number(card id)</td></tr><tr><td><code>amount</code></td><td>Decimal</td><td>Yes</td><td>Fee amount charged</td></tr><tr><td><code>feeType</code></td><td>String</td><td>Yes</td><td>Type of fee (see Fee Types below)</td></tr><tr><td><code>txId</code></td><td>String</td><td>Yes</td><td>Original transaction ID associated with the fee</td></tr><tr><td><code>settlementDiff</code></td><td>Boolean</td><td>Yes</td><td>Indicates if there's a settlement difference</td></tr></tbody></table>

**Fee Types:**

* `success` - Fee for successful transaction
* `expense` - Expense-related fee
* `decline` - Fee for declined transaction
* `reversal` - Fee for transaction reversal
* `force_post` - Fee for forced post transaction
* `cancellation` - Fee for transaction cancellation
* `pending` - Fee for pending transaction
* `overdraft` - Overdraft fee

***

### 8. Extra-Fee Capitalist Charge Callback <a href="#id-7-extra-fee-capitalist-charge-callback" id="id-7-extra-fee-capitalist-charge-callback"></a>

Called when additional fees are charged through the Capitalist.

**Headers:**

```
X-CP-Callback-Type: EXTRA_FEE_CAP
```

**Callback Body:**

```json
{
  "san": "e5792c6821240906122702",
  "amount": 0.30,
  "feeType": "decline",
  "txId": "original_tx_id",
  "settlementDiff": false
}
```

**Fields:**

<table><thead><tr><th width="174.4444580078125">Field</th><th width="127.888916015625">Type</th><th width="120.3333740234375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>san</code></td><td>String</td><td>Yes</td><td>Secure Account Number(card id)</td></tr><tr><td><code>amount</code></td><td>Decimal</td><td>Yes</td><td>Fee amount charged</td></tr><tr><td><code>feeType</code></td><td>String</td><td>Yes</td><td>Type of fee (see Fee Types above)</td></tr><tr><td><code>txId</code></td><td>String</td><td>Yes</td><td>Original transaction ID associated with the fee</td></tr><tr><td><code>settlementDiff</code></td><td>Boolean</td><td>Yes</td><td>Indicates if there's a settlement difference</td></tr></tbody></table>

***

### 9. Transaction Card Callback <a href="#id-8-transaction-card-callback" id="id-8-transaction-card-callback"></a>

Called when a card transaction occurs. This is the most common callback type.

**Headers:**

```
X-CP-Callback-Type: CARD_TRANSACTION
```

**Callback Body:**

```json
{
  "san": "3abdea0c20250820015603",
  "txId": "A2001264138954887169",
  "originTxnId": "ad6258fa-d554-4607-a5e8-4b8025533b92",
  "txType": "expense",
  "forcePost": false,
  "txDate": "2025-12-17T12:12:07.076Z",
  "expenseDate": "2025-12-18T12:00:43.351Z",
  "txAmount": 10000.0,
  "txCurrency": "VND",
  "billAmount": 0.39,
  "billCurrency": "USD",
  "merchantName": "Grab* A-8OASB3PWW4ITAV HA NOI VNM",
  "merchantCountry": "VNM",
  "mcc": "4121 LIMOUSINES AND TAXICABS",
  "authCode": "299164",
  "fee": 0.12
}
```

**Required Fields:**

<table><thead><tr><th width="177">Field</th><th width="136.6666259765625">Type</th><th width="117">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>san</code></td><td>String</td><td>Yes</td><td>Secure Account Number(card id)</td></tr><tr><td><code>txId</code></td><td>String</td><td>Yes</td><td>Transaction identifier</td></tr><tr><td><code>txType</code></td><td>String</td><td>Yes</td><td>Type of transaction (see Transaction Types below)</td></tr><tr><td><code>txAmount</code></td><td>Decimal</td><td>Yes</td><td>Transaction amount in original currency</td></tr><tr><td><code>txCurrency</code></td><td>String</td><td>Yes</td><td>Currency code for transaction</td></tr><tr><td><code>billAmount</code></td><td>Decimal</td><td>Yes</td><td>Billing amount (converted to card currency)</td></tr><tr><td><code>billCurrency</code></td><td>String</td><td>Yes</td><td>Currency code for billing</td></tr></tbody></table>

**Optional Fields:**

<table><thead><tr><th width="178.2222900390625">Field</th><th width="123.22216796875">Type</th><th width="112.5555419921875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>originTxnId</code></td><td>String</td><td>No</td><td><p>Original transaction ID </p><p>(for expense/reversals/refunds)</p></td></tr><tr><td><code>forcePost</code></td><td>Boolean</td><td>No</td><td>Indicates if transaction was force-posted</td></tr><tr><td><code>txDate</code></td><td>String</td><td>No</td><td>Transaction date in ISO 8601 format (UTC)</td></tr><tr><td><code>expenseDate</code></td><td>String</td><td>No</td><td>Expense posting date in ISO 8601 format (UTC)</td></tr><tr><td><code>merchantName</code></td><td>String</td><td>No</td><td>Name of the merchant</td></tr><tr><td><code>merchantCountry</code></td><td>String</td><td>No</td><td>ISO 3166-1 alpha-3 country code</td></tr><tr><td><code>mcc</code></td><td>String</td><td>No</td><td>Merchant Category Code with description</td></tr><tr><td><code>authCode</code></td><td>String</td><td>No</td><td>Authorization code from payment network</td></tr><tr><td><code>fee</code></td><td>Decimal</td><td>No</td><td>Additional fee amount (always greater than 0 when present)</td></tr></tbody></table>

**Transaction Types:**

| Type                    | Description                       |
| ----------------------- | --------------------------------- |
| `authorization`         | Pre-authorization hold on funds   |
| `authorization_decline` | Declined authorization attempt    |
| `expense`               | Completed transaction expense     |
| `reversal`              | Transaction reversal/cancellation |
| `refund`                | Refund to card                    |
| `verification`          | Card verification transaction     |
| `verification_decline`  | Declined verification attempt     |
| `verification_expense`  | Completed verification expense    |
| `maintenance_fee`       | Card maintenance or service fee   |

### 10. OTP Code Card Callback <a href="#id-8-transaction-card-callback" id="id-8-transaction-card-callback"></a>

Called when the card OTP code is received.

**Headers:**

```
X-CP-Callback-Type: OTP_CODE
```

**Callback Body:**

```json
{
  "san": "3abdea0c20250820015603",
  "otpCode": "123456"
}
```

### 11. KYC Status Change Callback <a href="#id-8-transaction-card-callback" id="id-8-transaction-card-callback"></a>

Called when the KYC status changes.

**Headers:**

```
X-CP-Callback-Type: KYC_CHANGE
```

**Callback Body:**

```json
{
  "kycExternalUserId": "your unique user id",
  "status": "DECLINED",
  "reason": "photo is dirty",
  "uuid": "uuid-of-kyc"
}
```

{% hint style="info" %}
&#x20;**Body of callback for KYC status change is the same as** [**`Query KYC status response`**](/api/kyc/query-kyc-status)&#x20;
{% endhint %}

***

### Response Format <a href="#response-format" id="response-format"></a>

Your callback endpoint should respond with an HTTP status code:

* **200 OK** - Callback processed successfully
* **4xx/5xx** - Error occurred (callback may be retried)