### Refund Settlement Example

Source: https://docs.noname.cards/docs

An example JSON payload illustrating a card transaction refund settlement. It contains similar fields to a successful settlement but indicates a 'REFUND' transaction type and `is_credit` as true.

```json
{
  "id": "f4c8g389-geab-5891-cc43-efg75f6b5f3g",
  "event_category": "ISSUING",
  "event_type": "CARD_TRANSACTION",
  "event_action": "CLEARING",
  "data": {
    "card_id": "27769b6f-4f4b-4cb7-84ca-fd982ee7fee0",
    "vendor_card_id": "216fb474-fc98-4cdd-adc3-578c8a7c2851",
    "vendor_transaction_id": "refund-tx-uuid",
    "timestamp": "2026-01-18",
    "transaction_amount": 6.96,
    "billing_amount": 6.96,
    "transaction_currency": "USD",
    "billing_currency": "USD",
    "merchant_name": "SAN PAOLO GELATERIA",
    "status": "APPROVED",
    "transaction_type": "REFUND",
    "is_credit": true
  },
  "reference_id": "ref-uuid",
  "created_at": "2026-01-18T10:00:01.000+00"
}
```

--------------------------------

### 3DS OTP Webhook Data Example

Source: https://docs.noname.cards/docs

Example JSON data for a 3D Secure OTP webhook, triggered when one-time password verification is required. It includes transaction details along with OTP-specific fields like the OTP code, TTL, and expiry.

```json
{
  "card_id": "uuid",
  "vendor_card_id": "uuid",
  "vendor_transaction_id": "uuid",
  "timestamp": "2026-02-04T14:00:00.000Z",
  "transaction_amount": 100.00,
  "billing_amount": 100.00,
  "transaction_currency": "USD",
  "billing_currency": "USD",
  "otp": "123456",
  "merchant_name": "Some Merchant",
  "merchant_country": "US",
  "last4": "1234",
  "ttl": 180,
  "expiry_time": "2026-02-04T14:03:00.000Z",
  "start_time": "2026-02-04T14:00:00.000Z",
  "delivery_method": "sms"
}
```

--------------------------------

### GET /api/access/info

Source: https://docs.noname.cards/docs

Verifies the provided API key and returns information about the associated wallet, user role, and permissions.

```APIDOC
## GET /api/access/info

### Description
Verifies the provided API key and retrieves metadata regarding the authenticated session, including wallet ID and assigned roles.

### Method
GET

### Endpoint
https://api.example.com/api/access/info

### Parameters
#### Query Parameters
- **x-api-key** (header) - Required - The API key for authentication.

### Request Example
curl -X GET "https://api.example.com/api/access/info" \
  -H "x-api-key: YOUR_API_KEY"

### Response
#### Success Response (200)
- **data** (object) - Contains role, wallet_id, and permissions.

#### Response Example
{
  "success": true,
  "data": {
    "role": "DEVELOPER",
    "wallet_id": "wlt_12345",
    "permissions": ["read", "write"]
  }
}
```

--------------------------------

### Successful Settlement Example

Source: https://docs.noname.cards/docs

An example JSON payload representing a successful card transaction settlement. This includes details like card identifiers, transaction amounts, currencies, merchant information, and status.

```json
{
  "id": "bbe62b23-a1dc-4062-a0df-1454f127b52f",
  "event_category": "ISSUING",
  "event_type": "CARD_TRANSACTION",
  "event_action": "CLEARING",
  "data": {
    "card_id": "18a9bc54-9525-4a24-9a42-f78c487ab205",
    "vendor_card_id": "2008606935051538434",
    "vendor_transaction_id": "F2019372997228761089",
    "timestamp": "2026-02-05",
    "transaction_amount": 40,
    "billing_amount": 48.24,
    "transaction_currency": "EUR",
    "billing_currency": "USD",
    "merchant_name": "AZ FZ TRANSPORTS",
    "status": "APPROVED",
    "transaction_type": "CLEARING",
    "is_credit": false
  },
  "reference_id": "ref-uuid",
  "created_at": "2026-02-05T11:30:17.278+00"
}
```

--------------------------------

### Refund Authorization Example

Source: https://docs.noname.cards/docs

This JSON object represents a refund authorization. The 'transaction_type' is 'REFUND', and 'is_credit' is true, indicating that funds are being returned to the cardholder. The status is 'PENDING'.

```json
{
  "id": "def67890-330f-5390-0240-ghi86e8d4898",
  "event_category": "ISSUING",
  "event_type": "CARD_TRANSACTION",
  "event_action": "AUTHORIZATION",
  "data": {
    "card_id": "a7d3739c-8656-45ee-9e65-f6ad1ed6b55a",
    "vendor_card_id": "1893332533816848385",
    "vendor_transaction_id": "refund-auth-uuid",
    "timestamp": "2026-01-18T09:55:00.000Z",
    "transaction_amount": 50.00,
    "billing_amount": 50.00,
    "transaction_currency": "USD",
    "billing_currency": "USD",
    "merchant_name": "AMAZON REFUND",
    "status": "PENDING",
    "transaction_type": "REFUND",
    "is_credit": true,
    "failure_reason": null
  },
  "reference_id": "ref-uuid",
  "created_at": "2026-01-18T09:55:01.000+00"
}
```

--------------------------------

### GET /api/orders/list

Source: https://docs.noname.cards/docs

Retrieves a paginated list of orders associated with the wallet linked to the provided API key.

```APIDOC
## GET /api/orders/list

### Description
Retrieves a paginated list of orders for the wallet bound to the API key. Supports sorting, filtering, and date range constraints.

### Method
GET

### Endpoint
/api/orders/list

### Parameters
#### Query Parameters
- **offset** (integer) - Optional - Pagination offset (default: 0)
- **limit** (integer) - Optional - Number of items to return (default: 10)
- **sort_by** (string) - Optional - Field to sort by (default: created_at)
- **sort_order** (string) - Optional - Sort direction: asc or desc (default: desc)
- **filters** (string) - Optional - JSON-encoded filter criteria
- **date_from** (string) - Optional - Start date (RFC 3339)
- **date_to** (string) - Optional - End date (RFC 3339)

### Request Example
```
curl https://production.noname.rest/api/orders/list \
  --header 'x-api-key: YOUR_SECRET_TOKEN'
```

### Response
#### Success Response (200)
- **data** (array) - List of order objects
- **pagination** (object) - Pagination metadata

#### Response Example
{
  "success": true,
  "data": [{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "NEW",
    "created_at": "2026-03-15T21:00:48.040Z"
  }],
  "pagination": {
    "offset": 1,
    "limit": 1,
    "total": 1,
    "has_more": true
  }
}
```

--------------------------------

### GET /api/orders/estimate_gas

Source: https://docs.noname.cards/docs

Estimates gas fees for a crypto transfer.

```APIDOC
## GET /api/orders/estimate_gas

### Description
Estimates gas fees for a crypto transfer.

### Method
GET

### Endpoint
/api/orders/estimate_gas

### Parameters
#### Query Parameters
- **from_currency_id** (string) - Required - UUID of source currency
- **amount** (number) - Required - Amount for transfer

### Request Example
```
curl 'https://production.noname.rest/api/orders/estimate_gas?from_currency_id=&amount=1' \
  --header 'x-api-key: YOUR_SECRET_TOKEN'
```

### Response
#### Success Response (200)
- **data** (object) - Estimated gas fee details

#### Response Example
{
  "success": true,
  "data": {
    "estimated_fee": 1,
    "fee_currency": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

--------------------------------

### GET /api/orders/calc

Source: https://docs.noname.cards/docs

Pre-calculates order amounts, fees, and exchange rates without creating an order.

```APIDOC
## GET /api/orders/calc

### Description
Pre-calculates order amounts, fees and exchange rates without creating an order.

### Method
GET

### Endpoint
/api/orders/calc

### Parameters
#### Query Parameters
- **order_type** (string) - Required - Type of order
- **amount** (number) - Required - Amount to calculate
- **from_currency_id** (string) - Required - UUID of source currency
- **to_currency_id** (string) - Required - UUID of target currency

### Request Example
```
curl 'https://production.noname.rest/api/orders/calc?order_type=&amount=1&from_currency_id=' \
  --header 'x-api-key: YOUR_SECRET_TOKEN'
```

### Response
#### Success Response (200)
- **data** (object) - Calculated order details

#### Response Example
{
  "success": true,
  "data": {
    "from_amount": 1,
    "to_amount": 1,
    "rate": 1,
    "fee": 1,
    "fee_currency": "123e4567-e89b-12d3-a456-426614174000",
    "total_amount": 1
  }
}
```

--------------------------------

### GET /api/wallets/balance

Source: https://docs.noname.cards/docs

Retrieves the current balance of the wallet associated with the provided API key.

```APIDOC
## GET /api/wallets/balance

### Description
Returns the current balance of all assets held within the wallet linked to the API key.

### Method
GET

### Endpoint
https://api.example.com/api/wallets/balance

### Parameters
#### Query Parameters
- **x-api-key** (header) - Required - The API key for authentication.

### Request Example
curl -X GET "https://api.example.com/api/wallets/balance" \
  -H "x-api-key: YOUR_API_KEY"

### Response
#### Success Response (200)
- **data** (object) - Dictionary of currency codes and their respective balances.

#### Response Example
{
  "success": true,
  "data": {
    "USD": 1500.00,
    "ETH": 0.5
  }
}
```

--------------------------------

### GET /api/orders/rates

Source: https://docs.noname.cards/docs

Retrieves individual exchange rates for the wallet bound to the API key.

```APIDOC
## GET /api/orders/rates

### Description
Retrieves individual exchange rates for the wallet bound to the API key.

### Method
GET

### Endpoint
/api/orders/rates

### Parameters
#### Query Parameters
- **order_type** (string) - Optional - Filter by order type

### Request Example
```
curl https://production.noname.rest/api/orders/rates \
  --header 'x-api-key: YOUR_SECRET_TOKEN'
```

### Response
#### Success Response (200)
- **data** (object) - Individual rates information

#### Response Example
{
  "success": true,
  "data": {
    "rate": 1,
    "from_currency": "123e4567-e89b-12d3-a456-426614174000",
    "to_currency": "123e4567-e89b-12d3-a456-426614174000",
    "amount_from": 1,
    "amount_to": 1,
    "fee": 1,
    "fee_currency": "123e4567-e89b-12d3-a456-426614174000",
    "valid_until": "2026-03-15T21:00:48.040Z"
  }
}
```

--------------------------------

### Get Orders List using cURL

Source: https://docs.noname.cards/docs

Retrieves a paginated list of orders for the wallet bound to the API key. Requires an 'x-api-key' header for authentication. Supports query parameters for pagination, sorting, and filtering by date.

```shell
curl https://production.noname.rest/api/orders/list \
  --header 'x-api-key: YOUR_SECRET_TOKEN'
```

--------------------------------

### Authorization Reversal Example

Source: https://docs.noname.cards/docs

This JSON object represents an authorization reversal, where a previously authorized transaction is canceled or undone. The 'transaction_type' is set to 'REVERSAL' and 'is_credit' is true.

```json
{
  "id": "abc12345-220e-4289-9139-fec4777d3797",
  "event_category": "ISSUING",
  "event_type": "CARD_TRANSACTION",
  "event_action": "AUTHORIZATION",
  "data": {
    "card_id": "a7d3739c-8656-45ee-9e65-f6ad1ed6b55a",
    "vendor_card_id": "1893332533816848385",
    "vendor_transaction_id": "A2012189003898834947",
    "timestamp": "2026-01-16T23:50:00.000Z",
    "transaction_amount": 108.81,
    "billing_amount": 30.73,
    "transaction_currency": "PLN",
    "billing_currency": "USD",
    "merchant_name": "SPIZARNIA Warszawa POL",
    "status": "REVERSED",
    "transaction_type": "REVERSAL",
    "is_credit": true,
    "failure_reason": null
  },
  "reference_id": "ref-uuid",
  "created_at": "2026-01-16T15:50:01.000+00"
}
```

--------------------------------

### Declined Authorization Example

Source: https://docs.noname.cards/docs

This JSON object illustrates a declined card authorization. It includes the reason for the decline, such as 'card spending limit exceeded', along with transaction and merchant details.

```json
{
  "id": "78f21507-6138-4205-8a61-7d78a34316f2",
  "event_category": "ISSUING",
  "event_type": "CARD_TRANSACTION",
  "event_action": "AUTHORIZATION",
  "data": {
    "card_id": "b351bd15-ee75-4f51-9cff-f1685a7de30f",
    "vendor_card_id": "e2694910-c461-44a5-8cc4-23918b9aba9a",
    "vendor_transaction_id": "87acc14a-bc4e-4f2b-a298-3fa0caab8a3e",
    "timestamp": "2026-02-05T11:28:18Z",
    "transaction_amount": 38,
    "billing_amount": 44.99,
    "transaction_currency": "EUR",
    "billing_currency": "USD",
    "merchant_name": "XCORP.PAIDFEATURES",
    "merchant_city": "+14156978699",
    "merchant_country": "USA",
    "merchant_category_code": "5817",
    "status": "DECLINED",
    "transaction_type": "AUTHORIZATION",
    "is_credit": false,
    "failure_reason": "card spending limit exceeded"
  },
  "reference_id": "ref-uuid",
  "created_at": "2026-02-05T11:28:25.397+00"
}
```

--------------------------------

### Handle Webhook Events in Node.js/Express

Source: https://docs.noname.cards/docs

An example implementation of a webhook handler that performs idempotency checks using X-Event-Id and routes events based on action types. It demonstrates how to process authorization, clearing, and deposit events while distinguishing between credit and debit transactions.

```javascript
app.post('/webhooks/cards', async (req, res) => {
  const eventId = req.headers['x-event-id'];
  const eventAction = req.headers['x-event-action'];
  
  // Deduplicate by event_id
  if (await isEventProcessed(eventId)) {
    return res.status(200).json({ message: 'Already processed' });
  }
  
  const { event_action, data } = req.body;
  
  switch (event_action) {
    case 'AUTHORIZATION':
      // Use transaction_type and is_credit for proper handling
      if (data.is_credit) {
        // Refund or Reversal - money returning to customer
        await handleCreditAuthorization(data);
      } else {
        await handleDebitAuthorization(data);
      }
      break;
    case 'CLEARING':
      if (data.is_credit) {
        await handleCreditClearing(data);
      } else {
        await handleDebitClearing(data);
      }
      break;
    case 'OTP':
      await handleOtp(data);
      break;
    case 'DEPOSIT':
      await handleDeposit(data);
      break;
  }
  
  await markEventProcessed(eventId);
  res.status(200).json({ message: 'Webhook received' });
});
```

--------------------------------

### Successful Authorization (Hold) Example

Source: https://docs.noname.cards/docs

This JSON object represents a successful card authorization, often referred to as a 'hold'. It includes details about the transaction amount, currency, merchant, and status set to 'PENDING'.

```json
{
  "id": "168785e7-c592-4214-854c-0ef8011930bd",
  "event_category": "ISSUING",
  "event_type": "CARD_TRANSACTION",
  "event_action": "AUTHORIZATION",
  "data": {
    "card_id": "0eabac17-4150-479d-8907-cc5d809bd21e",
    "vendor_card_id": "4b619760-1337-4811-b323-480ddf3cc807",
    "vendor_transaction_id": "7781c26b-aaf3-47ef-a249-e20b7cc6f0c7",
    "timestamp": "2026-02-05T11:29:35.665Z",
    "transaction_amount": 18.53,
    "billing_amount": 18.53,
    "local_amount": 15.5,
    "transaction_currency": "USD",
    "billing_currency": "USD",
    "local_currency": "EUR",
    "merchant_name": "UAB DU MEDU BUKISKIS",
    "merchant_city": "VILNIAUS R.",
    "merchant_country": "LT",
    "merchant_category_code": "5812",
    "status": "PENDING",
    "transaction_type": "AUTHORIZATION",
    "is_credit": false,
    "failure_reason": null
  },
  "reference_id": "ref-uuid",
  "created_at": "2026-02-05T11:29:37.591+00"
}
```

--------------------------------

### GET /api/issuing/cards

Source: https://docs.noname.cards/docs

Retrieve a list of all issued virtual and physical cards associated with the account.

```APIDOC
## GET /api/issuing/cards

### Description
Fetch a paginated list of all cards issued under the account program.

### Method
GET

### Endpoint
/api/issuing/cards

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number for pagination
- **limit** (integer) - Optional - Number of records per page

### Response
#### Success Response (200)
- **cards** (array) - List of card objects

#### Response Example
{
  "cards": [
    {
      "card_id": "uuid",
      "status": "active",
      "user_id": "uuid"
    }
  ]
}
```

--------------------------------

### Card Transaction Authorization Events

Source: https://docs.noname.cards/docs

This section provides examples of different card transaction authorization events, including successful holds, declined transactions, reversals, and refunds.

```APIDOC
## Card Transaction Authorization Events

### Description
This section provides examples of different card transaction authorization events, including successful holds, declined transactions, reversals, and refunds.

### Method
POST (Implicit, as these are webhook events)

### Endpoint
`/websites/noname_cards` (Assumed webhook endpoint)

### Request Body Examples

#### Successful Authorization (Hold)
```json
{
  "id": "168785e7-c592-4214-854c-0ef8011930bd",
  "event_category": "ISSUING",
  "event_type": "CARD_TRANSACTION",
  "event_action": "AUTHORIZATION",
  "data": {
    "card_id": "0eabac17-4150-479d-8907-cc5d809bd21e",
    "vendor_card_id": "4b619760-1337-4811-b323-480ddf3cc807",
    "vendor_transaction_id": "7781c26b-aaf3-47ef-a249-e20b7cc6f0c7",
    "timestamp": "2026-02-05T11:29:35.665Z",
    "transaction_amount": 18.53,
    "billing_amount": 18.53,
    "local_amount": 15.5,
    "transaction_currency": "USD",
    "billing_currency": "USD",
    "local_currency": "EUR",
    "merchant_name": "UAB DU MEDU BUKISKIS",
    "merchant_city": "VILNIAUS R.",
    "merchant_country": "LT",
    "merchant_category_code": "5812",
    "status": "PENDING",
    "transaction_type": "AUTHORIZATION",
    "is_credit": false,
    "failure_reason": null
  },
  "reference_id": "ref-uuid",
  "created_at": "2026-02-05T11:29:37.591+00"
}
```

#### Declined Authorization
```json
{
  "id": "78f21507-6138-4205-8a61-7d78a34316f2",
  "event_category": "ISSUING",
  "event_type": "CARD_TRANSACTION",
  "event_action": "AUTHORIZATION",
  "data": {
    "card_id": "b351bd15-ee75-4f51-9cff-f1685a7de30f",
    "vendor_card_id": "e2694910-c461-44a5-8cc4-23918b9aba9a",
    "vendor_transaction_id": "87acc14a-bc4e-4f2b-a298-3fa0caab8a3e",
    "timestamp": "2026-02-05T11:28:18Z",
    "transaction_amount": 38,
    "billing_amount": 44.99,
    "transaction_currency": "EUR",
    "billing_currency": "USD",
    "merchant_name": "XCORP.PAIDFEATURES",
    "merchant_city": "+14156978699",
    "merchant_country": "USA",
    "merchant_category_code": "5817",
    "status": "DECLINED",
    "transaction_type": "AUTHORIZATION",
    "is_credit": false,
    "failure_reason": "card spending limit exceeded"
  },
  "reference_id": "ref-uuid",
  "created_at": "2026-02-05T11:28:25.397+00"
}
```

#### Authorization Reversal
```json
{
  "id": "abc12345-220e-4289-9139-fec4777d3797",
  "event_category": "ISSUING",
  "event_type": "CARD_TRANSACTION",
  "event_action": "AUTHORIZATION",
  "data": {
    "card_id": "a7d3739c-8656-45ee-9e65-f6ad1ed6b55a",
    "vendor_card_id": "1893332533816848385",
    "vendor_transaction_id": "A2012189003898834947",
    "timestamp": "2026-01-16T23:50:00.000Z",
    "transaction_amount": 108.81,
    "billing_amount": 30.73,
    "transaction_currency": "PLN",
    "billing_currency": "USD",
    "merchant_name": "SPIZARNIA Warszawa POL",
    "status": "REVERSED",
    "transaction_type": "REVERSAL",
    "is_credit": true,
    "failure_reason": null
  },
  "reference_id": "ref-uuid",
  "created_at": "2026-01-16T15:50:01.000+00"
}
```

#### Refund Authorization
```json
{
  "id": "def67890-330f-5390-0240-ghi86e8d4898",
  "event_category": "ISSUING",
  "event_type": "CARD_TRANSACTION",
  "event_action": "AUTHORIZATION",
  "data": {
    "card_id": "a7d3739c-8656-45ee-9e65-f6ad1ed6b55a",
    "vendor_card_id": "1893332533816848385",
    "vendor_transaction_id": "refund-auth-uuid",
    "timestamp": "2026-01-18T09:55:00.000Z",
    "transaction_amount": 50.00,
    "billing_amount": 50.00,
    "transaction_currency": "USD",
    "billing_currency": "USD",
    "merchant_name": "AMAZON REFUND",
    "status": "PENDING",
    "transaction_type": "REFUND",
    "is_credit": true,
    "failure_reason": null
  },
  "reference_id": "ref-uuid",
  "created_at": "2026-01-18T09:55:01.000+00"
}
```

### Response
(No specific success/error responses are detailed for these webhook events, as they are typically acknowledged by the receiving system.)
```

--------------------------------

### Get Order by ID using cURL

Source: https://docs.noname.cards/docs

Retrieves a specific order by its numeric ID. Requires an 'x-api-key' header for authentication and the 'order_id' as a path parameter. Returns order details or a 404 if the order is not found.

```shell
curl https://production.noname.rest/api/orders/id/1 \
  --header 'x-api-key: YOUR_SECRET_TOKEN'
```

--------------------------------

### GET /api/orders/id/{order_id}

Source: https://docs.noname.cards/docs

Retrieves the full details of a specific order using its unique numeric identifier.

```APIDOC
## GET /api/orders/id/{order_id}

### Description
Retrieves a specific order by its numeric ID. Requires a valid API key in the header.

### Method
GET

### Endpoint
/api/orders/id/{order_id}

### Parameters
#### Path Parameters
- **order_id** (integer) - Required - The unique numeric ID of the order

### Request Example
```
curl https://production.noname.rest/api/orders/id/1 \
  --header 'x-api-key: YOUR_SECRET_TOKEN'
```

### Response
#### Success Response (200)
- **data** (object) - The order details

#### Error Response (404)
- Order not found

#### Response Example
{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "NEW"
  }
}
```

--------------------------------

### Handle API Error Responses

Source: https://docs.noname.cards/docs

Provides examples of JSON error structures returned by the API, specifically for unauthorized access and forbidden permissions. These structures include a success flag, error code, and descriptive message.

```json
{
  "success": false,
  "error": { "code": "UNAUTHORIZED", "message": "Invalid API key" }
}
```

```json
{
  "success": false,
  "error": { "code": "FORBIDDEN", "message": "Insufficient permissions for this operation" }
}
```

--------------------------------

### Sub-Account Deposit Webhook Payload

Source: https://docs.noname.cards/docs

JSON payload example for a cryptocurrency deposit event. This event is associated with a sub-account and provides blockchain transaction details including the wallet address and transaction hash.

```json
{
  "id": "deposit-event-uuid",
  "event_category": "ISSUING",
  "event_type": "SUB_ACCOUNT_DEPOSIT",
  "event_action": "DEPOSIT",
  "data": {
    "sub_account_id": "sa-uuid",
    "vendor_sub_account_id": "vendor-sa-uuid",
    "vendor_transaction_id": "vendor-tx-uuid",
    "timestamp": "2026-01-08T13:58:16.020Z",
    "transaction_amount": 200000.00,
    "transaction_currency": "SBC",
    "chain_id": 137,
    "wallet_address": "0xaF1e4e06554972956ddE4FBC883297421dAC6294",
    "tx_id": "0x9e1aaede64ccf002f78bd1d1a462d5996cec0e308e6ce4a8a626b2070a16ceec",
    "company_id": "fb1e3990-6239-4fca-b96b-24fb46b71f66",
    "status": "completed"
  },
  "reference_id": "ref-uuid",
  "created_at": "2026-01-08T13:58:17.000+00"
}
```

--------------------------------

### Card Transaction OTP Webhook Payload

Source: https://docs.noname.cards/docs

JSON payload example for a card transaction OTP event. It contains transaction details such as amount, currency, merchant information, and the OTP code for verification.

```json
{
  "id": "7f680c5c-a134-4ae3-9fdd-dc867cfba5f7",
  "event_category": "ISSUING",
  "event_type": "CARD_TRANSACTION",
  "event_action": "OTP",
  "data": {
    "card_id": "fb47ca31-9031-4bd2-817b-75b54c9dc3a1",
    "vendor_card_id": "65abc17b-5ee8-4eb6-9177-f6fc944c3c35",
    "vendor_transaction_id": "786f84af-d572-45f0-8380-46b54c6406fc",
    "timestamp": "2026-01-16T15:43:44.525Z",
    "transaction_amount": 1.99,
    "billing_amount": 1.99,
    "transaction_currency": "EUR",
    "billing_currency": "EUR",
    "otp": "206248",
    "merchant_name": "CapCut",
    "merchant_country": "CHN",
    "last4": "7688",
    "ttl": 300,
    "expiry_time": "2026-01-16T15:48:42Z",
    "start_time": "2026-01-16T15:43:42Z",
    "delivery_method": "EMAIL"
  },
  "reference_id": "ref-uuid",
  "created_at": "2026-01-16T15:43:44.57+00"
}
```

--------------------------------

### Verify API Key and Wallet Access

Source: https://docs.noname.cards/docs

Retrieves information about the current API key, including the associated role and wallet ID. This is the recommended first step for developers to ensure proper configuration.

```shell
curl -X GET "https://api.example.com/api/access/info" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Retrieve Wallet Balance

Source: https://docs.noname.cards/docs

Fetches the current balance and supported currencies for the wallet associated with the provided API key.

```shell
curl -X GET "https://api.example.com/api/wallets/balance" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Create Crypto Transfer Order

Source: https://docs.noname.cards/docs

Initiates a new crypto transfer by sending funds from a wallet to a destination address. Requires a JSON body containing amount, currency IDs, and destination details.

```shell
curl https://production.noname.rest/api/orders/OMNIBUS_CRYPTO_TRANSFER \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "amount": 1,
  "from_currency_id": "",
  "to_currency_id": "",
  "counterparty_destination_id": "",
  "wallet_account_id": "",
  "request_id": "",
  "reference": "",
  "note": ""
}'
```

--------------------------------

### Authenticate API Requests

Source: https://docs.noname.cards/docs

Demonstrates how to authenticate requests to the NoN Issuing API using the x-api-key header. All endpoints require this header to verify the caller's identity and permissions.

```shell
curl -X GET "https://api.example.com/api/issuing/cards" \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json"
```

--------------------------------

### Calculate order details

Source: https://docs.noname.cards/docs

Pre-calculates order amounts, fees, and exchange rates without creating a transaction. Requires order type, amount, and currency UUIDs as query parameters.

```shell
curl 'https://production.noname.rest/api/orders/calc?order_type=&amount=1&from_currency_id=' \
  --header 'x-api-key: YOUR_SECRET_TOKEN'
```

--------------------------------

### Create Sub-Account

Source: https://docs.noname.cards/docs

Creates a sub-account linked to a specific card program to manage funds. Requires a valid program ID obtained from the configuration endpoint.

```curl
curl -X POST "https://api.example.com/api/issuing/sub-accounts" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "program_id": "PROGRAM_ID_FROM_STEP_4A",
    "nick_name": "Travel Card Fund"
  }'
```

--------------------------------

### Retrieve individual exchange rates

Source: https://docs.noname.cards/docs

Retrieves current exchange rates for the wallet associated with the provided API key. Requires the x-api-key header for authentication.

```shell
curl https://production.noname.rest/api/orders/rates \
  --header 'x-api-key: YOUR_SECRET_TOKEN'
```

--------------------------------

### Retrieve Available Card Programs

Source: https://docs.noname.cards/docs

Fetches a list of available card programs. The returned program ID is a mandatory prerequisite for creating sub-accounts and issuing cards.

```curl
curl -X GET "https://api.example.com/api/issuing/config/programs" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Webhook Event Handling

Source: https://docs.noname.cards/docs

Guidelines for receiving and processing card-level and sub-account level webhooks.

```APIDOC
## POST /webhooks/receive

### Description
Endpoint to receive asynchronous event notifications for card authorizations, clearing, and deposits.

### Method
POST

### Endpoint
/webhooks/receive

### Request Body
- **event_action** (string) - The type of event (AUTHORIZATION, CLEARING, OTP, DEPOSIT)
- **data** (object) - Payload containing transaction details
- **is_credit** (boolean) - Flag indicating if the transaction is a credit/refund

### Response
#### Success Response (200)
- **message** (string) - Confirmation of receipt

### Best Practices
- **Idempotency**: Use the `X-Event-Id` header to ignore duplicate deliveries.
- **Timeout**: Respond within 10 seconds to avoid delivery failure.
- **Status**: Always return a 2xx status code to acknowledge receipt.
```

--------------------------------

### Webhook Response Format

Source: https://docs.noname.cards/docs

All webhooks are wrapped in an event_store format, providing structured event data.

```APIDOC
## Webhook Response Format

All webhooks are wrapped in an event_store format:

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event_category": "ISSUING",
  "event_type": "CARD_TRANSACTION",
  "event_action": "AUTHORIZATION",
  "data": { ... },
  "reference_id": "550e8400-e29b-41d4-a716-446655440001",
  "created_at": "2026-01-16T15:44:17.095+00"
}
```

### Field Reference

Field | Type | Description
---|---|---
`id` | UUID | Unique event identifier
`event_category` | string | Always `ISSUING` for card events
`event_type` | string | `CARD_TRANSACTION` or `SUB_ACCOUNT_DEPOSIT`
`event_action` | string | `AUTHORIZATION`, `CLEARING`, `OTP`, or `DEPOSIT`
`data` | object | Transaction data (format depends on `event_action`)
`reference_id` | UUID | Correlation identifier
`created_at` | ISO 8601 | Event creation timestamp
```

--------------------------------

### Approve Crypto Order

Source: https://docs.noname.cards/docs

Transitions an order from PENDING to PROCESSING status to initiate the execution pipeline. Requires the order UUID as a path parameter.

```shell
curl https://production.noname.rest/api/orders/123e4567-e89b-12d3-a456-426614174000/approve \
  --request POST \
  --header 'x-api-key: YOUR_SECRET_TOKEN'
```

--------------------------------

### POST /webhooks/deposit

Source: https://docs.noname.cards/docs

Webhook endpoint triggered when collateral is deposited via cryptocurrency into a sub-account.

```APIDOC
## POST /webhooks/deposit

### Description
This webhook is sent when collateral is deposited via cryptocurrency. It is associated with a specific sub-account rather than a card.

### Method
POST

### Endpoint
/webhooks/deposit

### Parameters
#### Request Body
- **sub_account_id** (UUID) - Required - Internal sub-account identifier
- **vendor_sub_account_id** (string) - Required - Sub-account identifier at the vendor
- **vendor_transaction_id** (string) - Required - Transaction identifier at the vendor
- **timestamp** (ISO 8601) - Required - Deposit timestamp
- **transaction_amount** (number) - Required - Deposit amount
- **transaction_currency** (string) - Required - Currency/token (e.g., SBC, USDT)
- **chain_id** (number) - Required - Blockchain ID (e.g., 137 for Polygon)
- **wallet_address** (string) - Required - Wallet address
- **tx_id** (string) - Required - Blockchain transaction hash
- **company_id** (string) - Required - Company identifier at the vendor
- **status** (string) - Required - Always 'completed'

### Request Example
{
  "id": "deposit-event-uuid",
  "event_category": "ISSUING",
  "event_type": "SUB_ACCOUNT_DEPOSIT",
  "event_action": "DEPOSIT",
  "data": {
    "sub_account_id": "sa-uuid",
    "vendor_sub_account_id": "vendor-sa-uuid",
    "vendor_transaction_id": "vendor-tx-uuid",
    "timestamp": "2026-01-08T13:58:16.020Z",
    "transaction_amount": 200000.00,
    "transaction_currency": "SBC",
    "chain_id": 137,
    "wallet_address": "0xaF1e4e06554972956ddE4FBC883297421dAC6294",
    "tx_id": "0x9e1aaede64ccf002f78bd1d1a462d5996cec0e308e6ce4a8a626b2070a16ceec",
    "company_id": "fb1e3990-6239-4fca-b96b-24fb46b71f66",
    "status": "completed"
  },
  "reference_id": "ref-uuid",
  "created_at": "2026-01-08T13:58:17.000+00"
}
```

--------------------------------

### Estimate gas fees

Source: https://docs.noname.cards/docs

Calculates the estimated gas fees for a specific crypto transfer based on the source currency and amount. Requires authentication via x-api-key header.

```shell
curl 'https://production.noname.rest/api/orders/estimate_gas?from_currency_id=&amount=1' \
  --header 'x-api-key: YOUR_SECRET_TOKEN'
```

--------------------------------

### POST /api/orders/{order_id}/approve

Source: https://docs.noname.cards/docs

Transitions an order from PENDING to PROCESSING status to trigger the execution pipeline.

```APIDOC
## POST /api/orders/{order_id}/approve

### Description
Transitions the order from PENDING to PROCESSING and triggers the order execution pipeline. Only orders with status PENDING can be approved.

### Method
POST

### Endpoint
/api/orders/{order_id}/approve

### Parameters
#### Path Parameters
- **order_id** (string/uuid) - Required - Order ID to approve

### Request Example
{
  "order_id": "123e4567-e89b-12d3-a456-426614174000"
}

### Response
#### Success Response (200)
- **data** (object) - Updated order details

#### Response Example
{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "PROCESSING"
  },
  "message": "Order approved and processing started"
}
```

--------------------------------

### Manage Crypto Deposit Addresses

Source: https://docs.noname.cards/docs

Operations for interacting with blockchain deposits, including listing supported chains and generating new deposit addresses for specific networks.

```shell
# List available chains
curl -X GET "https://api.example.com/api/reference/chains" \
  -H "x-api-key: YOUR_API_KEY"

# Create an address (e.g., Ethereum)
curl -X POST "https://api.example.com/api/wallets/crypto_addresses/1" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

--------------------------------

### Webhook Event Store Format

Source: https://docs.noname.cards/docs

This is the standard format for all webhooks originating from the event store. It includes a unique event identifier, category, type, action, associated data, a reference ID for correlation, and a creation timestamp.

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event_category": "ISSUING",
  "event_type": "CARD_TRANSACTION",
  "event_action": "AUTHORIZATION",
  "data": { ... },
  "reference_id": "550e8400-e29b-41d4-a716-446655440001",
  "created_at": "2026-01-16T15:44:17.095+00"
}
```

--------------------------------

### Create Cardholder

Source: https://docs.noname.cards/docs

Registers a new cardholder in the system. Returns a unique cardholder ID required for subsequent card issuance.

```curl
curl -X POST "https://api.example.com/api/issuing/cardholders" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "phone": "+1234567890",
    "date_of_birth": "1990-01-15",
    "address": {
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    }
  }'
```

--------------------------------

### POST /api/wallets/crypto_addresses/{chain_id}

Source: https://docs.noname.cards/docs

Generates a new deposit address for a specific blockchain network.

```APIDOC
## POST /api/wallets/crypto_addresses/{chain_id}

### Description
Generates a permanent deposit address for the specified blockchain chain ID to receive crypto assets.

### Method
POST

### Endpoint
https://api.example.com/api/wallets/crypto_addresses/{chain_id}

### Parameters
#### Path Parameters
- **chain_id** (integer) - Required - The ID of the blockchain network (e.g., 1 for Ethereum).

### Request Example
curl -X POST "https://api.example.com/api/wallets/crypto_addresses/1" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

### Response
#### Success Response (200)
- **address** (string) - The newly generated deposit address.

#### Response Example
{
  "success": true,
  "data": {
    "address": "0xabc123...",
    "chain_id": 1
  }
}
```

--------------------------------

### Cancel Order using cURL

Source: https://docs.noname.cards/docs

This snippet demonstrates how to cancel an order using a cURL command. It requires the order ID and optionally accepts a cancellation reason in the JSON request body. The endpoint supports POST requests and requires an 'x-api-key' header for authentication.

```shell
curl https://production.noname.rest/api/orders/123e4567-e89b-12d3-a456-426614174000/cancel \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_SECRET_TOKEN' \
  --data '{ \
  "reason": "Customer requested cancellation" \
}'
```

--------------------------------

### Transaction Flow Logic

Source: https://docs.noname.cards/docs

Logical representation of various transaction scenarios including successful purchases, declines, voids, and refunds.

```text
Successful Purchase:
1. authorization: transaction_type=AUTHORIZATION, status=PENDING, is_credit=false
2. clearing: transaction_type=CLEARING, status=APPROVED, is_credit=false

Declined Purchase:
1. authorization: transaction_type=AUTHORIZATION, status=DECLINED, is_credit=false, failure_reason="..."

Voided Authorization:
1. authorization: transaction_type=AUTHORIZATION, status=PENDING, is_credit=false
2. authorization: transaction_type=REVERSAL, status=REVERSED, is_credit=true

Refund:
1. authorization: transaction_type=REFUND, status=PENDING, is_credit=true
2. clearing: transaction_type=REFUND, status=APPROVED, is_credit=true
```