### Top up card balance response example

Source: https://developers.vertex-cards.com/docs/api-reference/patch-app-external-v-1-cardissue-card-card-topup

This is an example of a successful response after initiating a card top-up. It includes transaction IDs for fund transfer tracking.

```json
{
  "data": {
    "fromTransactionId": "9f283e59-21ec-4c74-ae32-156d49cd9cf2",
    "toTransactionId": "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
  }
}
```

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

### Transaction Details Response Example

Source: https://developers.vertex-cards.com/docs/api-reference/get-app-external-v-1-cardissue-transaction-transaction-getdetails

This is an example of a successful response (200 OK) when retrieving transaction details. It includes all relevant fields for a transaction.

```json
{
  "data": {
    "id": "string",
    "account": {
      "accountId": "9f283e59-21ec-4c74-ae32-156d49cd9cf2",
      "accountName": "Marketing Expenses"
    },
    "amount": "150.00",
    "currency": "USD",
    "feeAmount": "string",
    "feeCurrency": "USD",
    "settlementAmount": "string",
    "settlementCurrency": "USD",
    "description": "string",
    "status": "authorized",
    "createdAt": "2025-06-02T15:38:49+00:00",
    "updatedAt": "2025-06-02T15:38:49+00:00",
    "parentId": "63e6579c-d4e4-4ef4-b25a-332e2f2f4e5b",
    "transactionDetails": {
      "sourceAccountId": "a9c213e4-5678-90ab-cdef-1234567890ab",
      "type": "payin",
      "transactionAt": "2025-06-02T15:38:49+00:00"
    }
  }
}
```

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

### Transfer Account Balance C# Example

Source: https://developers.vertex-cards.com/docs/api-reference/post-app-external-v-1-cardissue-account-account-transferbalance

Example of how to perform a balance transfer using HttpClient in C#. Ensure you replace placeholders with actual values.

```csharp
var client = new HttpClient();  
var request = new HttpRequestMessage(HttpMethod.Post, "https://gateway.vertex-cards.com/api/v1/cards/accounts/:accountUuid/balance/transfer");  
request.Headers.Add("Api-Access-Token", "<Api-Access-Token>");  
var content = new StringContent("{\n  \"amount\": \"50.00\",\n  \"description\": \"Monthly budget allocation\",\n  \"destinationAccountUuid\": \"1ef2294f-b286-64de-b605-0242ac12000e\"\n}", null, "application/json");  
request.Content = content;  
var response = await client.SendAsync(request);  
response.EnsureSuccessStatusCode();  
Console.WriteLine(await response.Content.ReadAsStringAsync());  
```

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

### Get Transaction Details

Source: https://developers.vertex-cards.com/docs/api-reference/get-app-external-v-1-cardissue-transaction-transaction-getdetails

This example shows how to retrieve the details of a card issue transaction using the `Api-Access-Token` for authorization.

```APIDOC
## GET /api/v1/cards/companies/:companyUuid/accounts/transactions/:transactionUuid

### Description
Retrieves the details of a specific card issue transaction.

### Method
GET

### Endpoint
https://gateway.vertex-cards.com/api/v1/cards/companies/:companyUuid/accounts/transactions/:transactionUuid

### Parameters
#### Path Parameters
- **companyUuid** (string) - Required - The unique identifier for the company.
- **transactionUuid** (string) - Required - The unique identifier for the transaction.

#### Headers
- **Api-Access-Token** (string) - Required - The API access token for authentication.

### Request Example
```csharp
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://developers.vertex-cards.com/api/v1/cards/companies/:companyUuid/accounts/transactions/:transactionUuid");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Api-Access-Token", "<Api-Access-Token>");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

### Response
#### Success Response (200)
(Response details not provided in source)
```

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

### Deactivate Account using HttpClient (C#)

Source: https://developers.vertex-cards.com/docs/api-reference/post-app-external-v-1-cardissue-account-account-deactivate

This C# example demonstrates how to deactivate an account using HttpClient. It includes setting the API access token in the headers and handling the response. The request is asynchronous.

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://gateway.vertex-cards.com/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/disable");
request.Headers.Add("Api-Access-Token", "<Api-Access-Token>");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

```

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

### Get Transaction Details using HttpClient

Source: https://developers.vertex-cards.com/docs/api-reference/get-app-external-v-1-cardissue-transaction-transaction-getdetails

This C# code snippet demonstrates how to retrieve transaction details by making a GET request to the Vertex Cards API. Ensure you replace \"<Api-Access-Token>\" with your actual token and provide the correct company and transaction UUIDs.

```csharp
var client = new HttpClient();  
var request = new HttpRequestMessage(HttpMethod.Get, "https://developers.vertex-cards.com/api/v1/cards/companies/:companyUuid/accounts/transactions/:transactionUuid");  
request.Headers.Add("Accept", "application/json");  
request.Headers.Add("Api-Access-Token", "<Api-Access-Token>");  
var response = await client.SendAsync(request);  
response.EnsureSuccessStatusCode();  
Console.WriteLine(await response.Content.ReadAsStringAsync());  
```

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

### GET Request for Transaction Details

Source: https://developers.vertex-cards.com/docs/api-reference/get-app-external-v-1-cardissue-transaction-transaction-getdetails

Use this endpoint to retrieve detailed information about a specific account transaction. Ensure you replace the placeholder UUIDs with actual values.

```http
GET
## https://gateway.vertex-cards.com/api/v1/cards/companies/:companyUuid/accounts/transactions/:transactionUuid
```

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

### GET /api/v1/cards/companies/:companyUuid/card-owners

Source: https://developers.vertex-cards.com/docs/api-reference/get-app-external-v-1-cardissue-cardowner-cardowner-list

Returns a list of card owners for a specified company.

```APIDOC
## GET /api/v1/cards/companies/:companyUuid/card-owners

### Description
Returns a list of card owners for a specified company.

### Method
GET

### Endpoint
/api/v1/cards/companies/:companyUuid/card-owners

### Responses
#### Success Response (200)
List of card owners.
```

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

### Get Card Transaction Details

Source: https://developers.vertex-cards.com/docs/api-reference/get-app-external-v-1-cardissue-transaction-cardtransaction-getdetails

Retrieves detailed information about a specific card transaction within a given company.

```APIDOC
## GET /api/v1/cards/companies/:companyUuid/cards/transactions/:transactionUuid

### Description
Returns detailed information about a specific card transaction within a given company.

### Method
GET

### Endpoint
/api/v1/cards/companies/:companyUuid/cards/transactions/:transactionUuid

### Parameters
#### Path Parameters
- **companyUuid** (string) - Required - The unique identifier for the company.
- **transactionUuid** (string) - Required - The unique identifier for the transaction.

### Responses
#### Success Response (200)
- **Transaction Details** (object) - Contains the details of the card transaction.
```

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

### Withdraw Card Balance

Source: https://developers.vertex-cards.com/docs/api-reference/patch-app-external-v-1-cardissue-card-card-withdraw

Withdraws funds from the specified card's balance to the associated account balance. This operation is asynchronous. After receiving a `204` response, the withdrawal process has started, but may not be completed immediately. To confirm the updated card balance, call Retrieve Card Details and check the `availableBalance` field.

```APIDOC
## PATCH https://gateway.vertex-cards.com/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards/:cardUuid/balance/withdraw

### Description
Withdraws funds from the specified card's balance to the associated account balance.

### Method
PATCH

### Endpoint
https://gateway.vertex-cards.com/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards/:cardUuid/balance/withdraw

### Parameters
#### Path Parameters
- **companyUuid** (string) - Required - Unique identifier of the company. Value must match regular expression `[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}`
- **accountUuid** (string) - Required - Unique identifier of the account containing the card. Value must match regular expression `[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}`
- **cardUuid** (string) - Required - Unique identifier of the card to withdraw from. Value must match regular expression `[0-9a-f]{8}-[0-9a-f]{4}-[13-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}`

#### Request Body
- **amount** (string) - Required - Amount to withdraw from the card balance. Expressed as a string with a dot as the decimal separator. Example: `50.00`

### Request Example
```json
{
  "amount": "50.00"
}
```

### Responses
#### Success Response (200)
- **data** (object) - Required
  - **fromTransactionId** (string) - Required - Unique identifier of the transaction from which the funds were transferred. Example: `9f283e59-21ec-4c74-ae32-156d49cd9cf2`
  - **toTransactionId** (string) - Required - Unique identifier of the transaction to which the funds were transferred. Example: `9f283e59-21ec-4c74-ae32-156d49cd9cf2`

### Response Example
```json
{
  "data": {
    "fromTransactionId": "9f283e59-21ec-4c74-ae32-156d49cd9cf2",
    "toTransactionId": "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
  }
}
```

#### Authorization
- **Api-Access-Token** (apiKey) - Required - Located in header
```

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

### Initialize a New Top-Up

Source: https://developers.vertex-cards.com/docs/api-reference/post-app-external-v-1-cardissue-topup-topups-init

Creates a new top-up transaction for a specified company.

```APIDOC
## POST /api/v1/cards/companies/:companyUuid/top-ups

### Description
Creates a new top-up transaction for a specified company.

### Method
POST

### Endpoint
/api/v1/cards/companies/:companyUuid/top-ups

### Responses
#### Success Response (200)
Returns the top-up identifier and a payment address.
```

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

### Available Environments

Source: https://developers.vertex-cards.com/docs/api-reference/gateway

List of available environments for accessing the Gateway API.

```APIDOC
## Available environments:
  * **Production:** `https://gateway.vertex-cards.com`
  * **Demo:** `https://gateway.demo.vertex-cards.com`
```

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

### Retrieve Top-Up Details

Source: https://developers.vertex-cards.com/docs/api-reference/get-app-external-v-1-cardissue-topup-topups-details

Returns detailed information about a specific top-up.

```APIDOC
## GET /api/v1/cards/companies/:companyUuid/top-ups/:topUpUuid

### Description
Returns detailed information about a specific top-up.

### Method
GET

### Endpoint
/api/v1/cards/companies/:companyUuid/top-ups/:topUpUuid

### Responses
#### Success Response (200)
Information about the specified top-up.
```

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

### Top up card balance using HttpClient in C#

Source: https://developers.vertex-cards.com/docs/api-reference/patch-app-external-v-1-cardissue-card-card-topup

Use HttpClient in C# to send a PATCH request to top up a card's balance. Ensure to include the 'Api-Access-Token' header and set the 'Content-Type' to 'application/json'.

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Patch, "https://developers.vertex-cards.com/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards/:cardUuid/balance/top-up");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Api-Access-Token", "<Api-Access-Token>");
var content = new StringContent(string.Empty);
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

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

### Create Company Account

Source: https://developers.vertex-cards.com/docs/api-reference/post-cards-companies-accounts-create

Creates a new account for the specified company, linked to a provider account. The `id` field in the request body must be set to the identifier of the provider account. The response contains the identifier of the newly created account. This request is asynchronous. After you receive the `201` response, wait a short moment and then call Retrieve Account Details to confirm that the account has been created and its `status` is `active`.

```APIDOC
## POST /api/v1/cards/companies/:companyUuid/accounts

### Description
Creates a new account for the specified company, linked to a provider account. The `id` field in the request body must be set to the identifier of the provider account, as returned by the Retrieve Available Provider Accounts endpoint. The response contains the identifier of the newly created account.

This request is asynchronous. After you receive the `201` response, wait a short moment and then call Retrieve Account Details to confirm that the account has been created and its `status` is `active`.

### Method
POST

### Endpoint
/api/v1/cards/companies/:companyUuid/accounts

### Parameters
#### Path Parameters
- **companyUuid** (string) - Required - The unique identifier of the company.

#### Request Body
- **id** (string) - Required - The identifier of the provider account.

### Response
#### Success Response (201)
Account creation request accepted.

#### Response Example
(No example provided in source)
```

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

### Withdraw Card Balance using HttpClient in C#

Source: https://developers.vertex-cards.com/docs/api-reference/patch-app-external-v-1-cardissue-card-card-withdraw

This C# code snippet demonstrates how to initiate a card balance withdrawal using HttpClient. Ensure you include the correct API access token and replace placeholder UUIDs with actual values.

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Patch, "https://gateway.vertex-cards.com/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards/:cardUuid/balance/withdraw");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Api-Access-Token", "<Api-Access-Token>");
var content = new StringContent("{\n  \"amount\": \"50.00\"\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

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

### OpenAPI File Export

Source: https://developers.vertex-cards.com/docs/api-reference/gateway

Download the OpenAPI file for a comprehensive reference of the API structure and endpoints.

```APIDOC
## OpenAPI File Export

For your convenience, you can download the OpenAPI file of our API: [download API Reference](link_to_openapi_file)
```

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

### Retrieve Top-Ups List

Source: https://developers.vertex-cards.com/docs/api-reference/get-app-external-v-1-cardissue-topup-topups-list

Fetches a list of all top-up transactions for a given company.

```APIDOC
## GET /api/v1/cards/companies/:companyUuid/top-ups

### Description
Returns a list of top-ups associated with a specified company.

### Method
GET

### Endpoint
/api/v1/cards/companies/:companyUuid/top-ups

### Parameters
#### Path Parameters
- **companyUuid** (string) - Required - The unique identifier of the company.

### Responses
#### Success Response (200)
- **Top-ups list** (array) - A list of top-up transaction objects.
```

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

### Authentication - API Key

Source: https://developers.vertex-cards.com/docs/api-reference/gateway

Details on how to authenticate your requests using an API Key.

```APIDOC
## Authentication

*   **API Key:** ApiKey

Security Scheme Type:| apiKey  
---|---
Header parameter name:| Api-Access-Token
```

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

### Create Card Request (C#)

Source: https://developers.vertex-cards.com/docs/api-reference/post-app-external-v-1-cardissue-card-card-create

Use this snippet to create a virtual card using the Vertex Cards API. Ensure you replace placeholder values with your actual company and account UUIDs, and the API access token.

```csharp
var client = new HttpClient();  
var request = new HttpRequestMessage(HttpMethod.Post, "https://developers.vertex-cards.com/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards");  
request.Headers.Add("Accept", "application/json");  
request.Headers.Add("Api-Access-Token", "<Api-Access-Token>");  
var content = new StringContent(string.Empty);  
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");  
request.Content = content;  
var response = await client.SendAsync(request);  
response.EnsureSuccessStatusCode();  
Console.WriteLine(await response.Content.ReadAsStringAsync());  

```

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

### Top up card balance

Source: https://developers.vertex-cards.com/docs/api-reference/patch-app-external-v-1-cardissue-card-card-topup

Tops up the specified card's balance using funds from the associated account balance. This operation is asynchronous.

```APIDOC
## PATCH /api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards/:cardUuid/balance/top-up

### Description
Tops up the specified card's balance using funds from the associated account balance.

### Method
PATCH

### Endpoint
https://gateway.vertex-cards.com/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards/:cardUuid/balance/top-up

### Parameters
#### Path Parameters
- **companyUuid** (string) - Required - Unique identifier of the company.
- **accountUuid** (string) - Required - Unique identifier of the account containing the card.
- **cardUuid** (string) - Required - Unique identifier of the card to be topped up.

#### Request Body
- **amount** (string) - Required - Amount to top up the card balance. Expressed as a string with a dot as the decimal separator. Must be greater than 0.

### Request Example
```json
{
  "amount": "100.00"
}
```

### Response
#### Success Response (204)
Request to top up the card balance was accepted. This only indicates that the top-up operation has started.

#### Success Response Example (200)
```json
{
  "data": {
    "fromTransactionId": "9f283e59-21ec-4c74-ae32-156d49cd9cf2",
    "toTransactionId": "9f283e59-21ec-4c74-ae32-156d49cd9cf2"
  }
}
```

#### Authorization
- **Api-Access-Token**: apiKey in header
```

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

### Retrieve Available Provider Accounts

Source: https://developers.vertex-cards.com/docs/api-reference/get-cards-companies-accounts-providers

Fetches a list of provider accounts available for a given company. The `id` returned in the response can be used when creating a new account to associate it with the correct provider.

```APIDOC
## Retrieve Available Provider Accounts

### Description
Returns a list of available provider accounts for the specified company. Use the returned `id` when creating a new account to link it to the desired provider.

### Method
GET

### Endpoint
/api/v1/cards/companies/:companyUuid/accounts/providers

### Responses
#### Success Response (200)
List of available provider accounts.
```

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

### Top up card balance request body

Source: https://developers.vertex-cards.com/docs/api-reference/patch-app-external-v-1-cardissue-card-card-topup

Specify the amount to top up the card balance. The amount must be a string with a dot as the decimal separator and be greater than 0.

```json
{
  "amount": "100.00"
}
```

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

### Create Card

Source: https://developers.vertex-cards.com/docs/api-reference/post-app-external-v-1-cardissue-card-card-create

Creates a new card for a specified company account. Requires companyUuid and accountUuid in the path, and card details in the request body.

```APIDOC
## POST /api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards

### Description
Creates a new card for a specified company account.

### Method
POST

### Endpoint
/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards

### Parameters
#### Path Parameters
- **companyUuid** (string) - Required - The UUID of the company.
- **accountUuid** (string) - Required - The UUID of the account.

#### Request Body
- **name** (string) - Required - The name of the card.
- **cardProviderBinId** (string) - Required - The ID of the card provider BIN.
- **binCategoryId** (string) - Required - The ID of the BIN category.
- **cardOwnerId** (string) - Required - The ID of the card owner.
- **cardType** (string) - Required - The type of the card (e.g., 'virtual').
- **limits** (object) - Optional - An object containing various limits for the card.
  - **daily_limit** (string) - Optional - The daily spending limit.
  - **weekly_limit** (string) - Optional - The weekly spending limit.
  - **monthly_limit** (string) - Optional - The monthly spending limit.
  - **year_limit** (string) - Optional - The yearly spending limit.
  - **lifetime_limit** (string) - Optional - The lifetime spending limit.
  - **transaction_limit** (string) - Optional - The limit per transaction.
- **currency** (string) - Required - The currency of the card (e.g., 'USD').

### Request Example
{
  "name": "Company Expenses Card",
  "cardProviderBinId": "ff246e21-3bda-4e47-83fb-05203939fe5b",
  "binCategoryId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "cardOwnerId": "be7312c7-8f46-4519-8d90-2ca196d43ba8",
  "cardType": "virtual",
  "limits": {
    "daily_limit": "100.00",
    "weekly_limit": "200.00",
    "monthly_limit": "300.00",
    "year_limit": "1000.00",
    "lifetime_limit": "10000.00",
    "transaction_limit": "50.00"
  },
  "currency": "USD"
}

### Response
#### Success Response (200)
- **cardUuid** (string) - The UUID of the created card.
- **companyUuid** (string) - The UUID of the company.
- **accountUuid** (string) - The UUID of the account.
- **name** (string) - The name of the card.
- **cardProviderBinId** (string) - The ID of the card provider BIN.
- **binCategoryId** (string) - The ID of the BIN category.
- **cardOwnerId** (string) - The ID of the card owner.
- **cardType** (string) - The type of the card.
- **status** (string) - The status of the card.
- **createdAt** (string) - The timestamp when the card was created.
- **limits** (object) - An object containing various limits for the card.
  - **daily_limit** (string) - The daily spending limit.
  - **weekly_limit** (string) - The weekly spending limit.
  - **monthly_limit** (string) - The monthly spending limit.
  - **year_limit** (string) - The yearly spending limit.
  - **lifetime_limit** (string) - The lifetime spending limit.
  - **transaction_limit** (string) - The limit per transaction.
- **currency** (string) - The currency of the card.

#### Response Example
{
  "cardUuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "companyUuid": "00000000-0000-0000-0000-000000000000",
  "accountUuid": "11111111-1111-1111-1111-111111111111",
  "name": "Company Expenses Card",
  "cardProviderBinId": "ff246e21-3bda-4e47-83fb-05203939fe5b",
  "binCategoryId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "cardOwnerId": "be7312c7-8f46-4519-8d90-2ca196d43ba8",
  "cardType": "virtual",
  "status": "active",
  "createdAt": "2023-10-27T10:00:00Z",
  "limits": {
    "daily_limit": "100.00",
    "weekly_limit": "200.00",
    "monthly_limit": "300.00",
    "year_limit": "1000.00",
    "lifetime_limit": "10000.00",
    "transaction_limit": "50.00"
  },
  "currency": "USD"
}
```

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

### Update Card Limits (C#)

Source: https://developers.vertex-cards.com/docs/api-reference/patch-app-external-v-1-cardissue-card-card-edit

This C# code snippet demonstrates how to update card limits using HttpClient. Ensure you have the correct API-Access-Token and replace placeholder UUIDs with actual values. The request body includes optional fields for card name and various spending limits.

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Patch, "https://gateway.vertex-cards.com/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards/:cardUuid");
request.Headers.Add("Api-Access-Token", "<Api-Access-Token>");
var content = new StringContent("{\n  \"name\": \"Business Travel Card\",\n  \"limits\": {\n    \"daily_limit\": \"100.00\",\n    \"weekly_limit\": \"200.00\",\n    \"monthly_limit\": \"300.00\",\n    \"year_limit\": \"1000.00\",\n    \"lifetime_limit\": \"10000.00\",\n    \"transaction_limit\": \"50.00\"\n  }\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

```

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

### Retrieve Available BINs

Source: https://developers.vertex-cards.com/docs/api-reference/get-app-external-v-1-cardissue-cardbin-cardbin-listwithbins

Retrieves a list of BIN categories with detailed information about available BINs for card issuance within the specified company.

```APIDOC
## POST /api/v1/cards/companies/:companyUuid/bins

### Description
Retrieves a list of BIN categories with detailed information about available BINs for card issuance within the specified company.

### Method
POST

### Endpoint
/api/v1/cards/companies/:companyUuid/bins

### Responses
#### Success Response (200)
List of BIN categories with detailed BIN information.
```

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

### Activate Account

Source: https://developers.vertex-cards.com/docs/api-reference/post-app-external-v-1-cardissue-account-account-activate

Reactivates the specified account belonging to a company, allowing the account to be used again. Sets the `status` field to `active` in Retrieve Account Details. The request is asynchronous. Call the Retrieve Account Details endpoint after a short delay to confirm that the activation has completed successfully.

```APIDOC
## POST /api/v1/cards/companies/:companyUuid/accounts/:accountUuid/enable

### Description
Reactivates the specified account belonging to a company, allowing the account to be used again. Sets `status` field is `active` in Retrieve Account Details.

The request is asynchronous. Call the Retrieve Account Details endpoint after a short delay to confirm that the deactivation has completed successfully.

### Method
POST

### Endpoint
https://gateway.vertex-cards.com/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/enable

### Parameters
#### Path Parameters
- **companyUuid** (string) - Required - Unique identifier of the company. Example: `123e4567-e89b-12d3-a456-426614174000`
- **accountUuid** (string) - Required - Unique identifier of the account. Example: `9f283e59-21ec-4c74-ae32-156d49cd9cf2`

### Responses
#### Success Response (204)
Account activation request accepted.

#### Authorization
- **name**: Api-Access-Token
- **type**: apiKey
- **in**: header
```

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

### Issue a New Card

Source: https://developers.vertex-cards.com/docs/api-reference/post-app-external-v-1-cardissue-card-card-create

Creates a new card under the specified account within a given company. This is an asynchronous operation.

```APIDOC
## POST https://gateway.vertex-cards.com/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards

### Description
Creates (issues) a new card under the specified account within a given company.

This is an asynchronous operation. After you initiate the card issuance, the card's status might initially be `creating`. You should call Retrieve Card Details and check the `status` field to confirm when the card becomes `active` (or if the creation fails with `creating_failed`).

### Method
POST

### Endpoint
https://gateway.vertex-cards.com/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards

### Parameters
#### Path Parameters
- **accountUuid** (string) - Required - Unique identifier of the account where the card will be issued. Example: `9f283e59-21ec-4c74-ae32-156d49cd9cf2`
- **companyUuid** (string) - Required - Unique identifier of the company. Example: `123e4567-e89b-12d3-a456-426614174000`

#### Request Body
- **name** (string) - Required - Card name or label as defined by the user. Example: `Company Expenses Card`
- **cardProviderBinId** (string) - Nullable - Identifier of the BIN used to issue the card. Example: `ff246e21-3bda-4e47-83fb-05203939fe5b`
- **binCategoryId** (string) - Nullable - Identifier of the BIN category from which a BIN will be selected for card issuance. Example: `7c9e6679-7425-40de-944b-e07fc1f90ae7`
- **cardOwnerId** (string) - Required - Identifier of the card owner. Example: `be7312c7-8f46-4519-8d90-2ca196d43ba8`
- **cardType** (string) - Required - Type of the card to be issued. Possible values: `virtual`, `physical`
- **limits** (object) - Required - An object to configure spending limits for the card.
  - **daily_limit** (string) - Nullable - The maximum amount allowed per day. Example: `100.00`
  - **weekly_limit** (string) - Nullable - The maximum amount allowed per week. Example: `200.00`
  - **monthly_limit** (string) - Nullable - The maximum amount allowed per month. Example: `300.00`
  - **year_limit** (string) - Nullable - The maximum amount allowed per year. Example: `1000.00`
  - **lifetime_limit** (string) - Nullable - The maximum total amount allowed over the entire card lifetime. Example: `10000.00`
  - **transaction_limit** (string) - Nullable - The maximum amount allowed for a single transaction. Example: `50.00`
  - **currency** (string) - Nullable - ISO 4217 currency code. Example: `USD`

### Response
#### Success Response (201)
- **data** (object) - Response body containing the identifier of the newly issued card.
  - **id** (string) - Unique identifier of the issued card. Example: `fb7f9a93-9ef3-4da6-8e22-45a1cd042f4d`

### Response Example
```json
{
  "data": {
    "id": "fb7f9a93-9ef3-4da6-8e22-45a1cd042f4d"
  }
}
```
```

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

### Activate Account Request

Source: https://developers.vertex-cards.com/docs/api-reference/post-app-external-v-1-cardissue-account-account-activate

This snippet shows how to activate a company account using the Vertex Cards API. Ensure you replace placeholder UUIDs with actual values. The request is asynchronous; verify activation status using the Retrieve Account Details endpoint.

```http
POST https://gateway.vertex-cards.com/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/enable
Authorization: Api-Access-Token <Api-Access-Token>
```

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://gateway.vertex-cards.com/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/enable");
request.Headers.Add("Api-Access-Token", "<Api-Access-Token>");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

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

### Retrieve All Accounts for a Company

Source: https://developers.vertex-cards.com/docs/api-reference/get-app-external-v-1-cardissue-account-account-getcompanyaccountsbyid

Returns a list of all accounts associated with a specified company.

```APIDOC
## GET /api/v1/cards/companies/:companyUuid/accounts

### Description
Returns a list of all accounts associated with a specified company.

### Method
GET

### Endpoint
/api/v1/cards/companies/:companyUuid/accounts

### Parameters
#### Path Parameters
- **companyUuid** (string) - Required - The unique identifier of the company.

### Responses
#### Success Response (200)
- **Account data** (object) - Account data.
```

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

### Transfer Account Balance Request

Source: https://developers.vertex-cards.com/docs/api-reference/post-app-external-v-1-cardissue-account-account-transferbalance

Use this endpoint to initiate a balance transfer between accounts. The request is asynchronous and requires account identifiers and the transfer amount.

```http
POST 
## https://gateway.vertex-cards.com/api/v1/cards/accounts/:accountUuid/balance/transfer
```

```http
Authorization: Api-Access-Token
```

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

### Account Top-Up Event Notification

Source: https://developers.vertex-cards.com/docs/api-reference/account-top-up-event-callback

This webhook notifies your system whenever an account top-up event occurs, such as receiving a top-up, confirmation, or status change. The payload mirrors the Retrieve Top-Up Details endpoint response. POST requests are sent to your configured endpoint with a control signature in the `api-notification-sign` header (SHA512).

```APIDOC
## Account Top-Up Event Callback

### Description
Notifies your system whenever any of the following events occur for an account top-up: Top-up received, Top-up confirmation, Top-up status change.

### Method
POST

### Endpoint
Your configured callback endpoint

### Headers
- **api-notification-sign** (string) - SHA512 signature for security and authenticity.

### Request Body
The payload structure is identical to the response of the Retrieve Top-Up Details endpoint.

### Response
#### Success Response (200)
Indicates that the callback was received successfully.

#### Error Response
Appropriate HTTP status codes for errors (e.g., 400, 500).
```

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

### Retrieve Accounts Available for Transfer

Source: https://developers.vertex-cards.com/docs/api-reference/get-app-external-v-1-cardissue-account-account-listavailablefortransfer

Returns a paginated list of accounts that are available as destinations for a balance transfer from the specified account.

```APIDOC
## GET /api/v1/cards/accounts/:accountUuid/accounts-available-for-transfer

### Description
Returns a paginated list of accounts that are available as destinations for a balance transfer from the specified account.

### Method
GET

### Endpoint
/api/v1/cards/accounts/:accountUuid/accounts-available-for-transfer

### Responses
#### Success Response (200)
List of accounts available for transfer.
```

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

### Close Card Request (C#)

Source: https://developers.vertex-cards.com/docs/api-reference/post-app-external-v-1-cardissue-card-card-close

Use this C# code to send a POST request to close a card. Ensure you replace placeholder UUIDs and the Api-Access-Token. The response indicates if the request was accepted, not if the card is fully closed.

```csharp
var client = new HttpClient();  
var request = new HttpRequestMessage(HttpMethod.Post, "https://gateway.vertex-cards.com/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards/:cardUuid/close");  
request.Headers.Add("Api-Access-Token", "<Api-Access-Token>");  
var response = await client.SendAsync(request);  
response.EnsureSuccessStatusCode();  
Console.WriteLine(await response.Content.ReadAsStringAsync());  
```

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

### Retrieve Card Creation Restrictions

Source: https://developers.vertex-cards.com/docs/api-reference/get-app-external-v-1-cardissue-account-account-availablecardlimits

Retrieves information about the restrictions and limits related to creating new cards for a specified account within a given company.

```APIDOC
## Retrieve Card Creation Restrictions

### Description
Retrieves information about the restrictions and limits related to creating new cards for a specified account within a given company.

### Method
GET

### Endpoint
/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/restrictions

### Responses
#### Success Response (200)
Available restrictions and limits for card creation.
```

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

### Retrieve Account Details

Source: https://developers.vertex-cards.com/docs/api-reference/get-app-external-v-1-cardissue-account-account-details

Fetches detailed information about a specific account belonging to a company, identified by their IDs.

```APIDOC
## GET /api/v1/cards/companies/:companyUuid/accounts/:accountUuid

### Description
Retrieves detailed information about a specific account belonging to a company, identified by their ids.

### Method
GET

### Endpoint
/api/v1/cards/companies/:companyUuid/accounts/:accountUuid

### Parameters
#### Path Parameters
- **companyUuid** (string) - Required - The unique identifier for the company.
- **accountUuid** (string) - Required - The unique identifier for the account.

### Responses
#### Success Response (200)
Account data.
```

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

### Card State Event Webhook

Source: https://developers.vertex-cards.com/docs/api-reference/card-state-event-callback

This webhook notifies your system whenever a card is created or its `status` changes. The payload structure is identical to the response of the Retrieve Card Details endpoint. POST requests with card data are sent to your configured endpoint. A control signature is included in the headers as `api-notification-sign` (SHA512) to ensure security and authenticity.

```APIDOC
## Card State Event Webhook

### Description
Notifies your system whenever a card is created or its `status` changes. The payload structure is identical to the response of the Retrieve Card Details endpoint. POST requests with card data are sent to your configured endpoint.

### Security
A control signature is included in the headers as `api-notification-sign` (SHA512) to ensure security and authenticity.

### Method
POST

### Endpoint
Your configured callback endpoint

### Request Body
The payload structure is identical to the response of the Retrieve Card Details endpoint.

### Headers
- **api-notification-sign** (string) - Required - SHA512 signature for security and authenticity.
```

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

### Account Transaction Event Callback

Source: https://developers.vertex-cards.com/docs/api-reference/account-transaction-event-callback

This webhook notifies your system of various events related to account transactions, including creation, confirmation, clearing, and status changes. It sends POST requests with transaction data to your configured endpoint. A control signature is included in the headers as `api-notification-sign` (SHA512) for security.

```APIDOC
## Account Transaction Event Callback

### Description
Notifies your system whenever any of the following events occur for an account transaction: Transaction creation, Transaction confirmation, Transaction clearing, Transaction status change.

### Method
POST

### Endpoint
`[Your Configured Endpoint]`

### Headers
- **api-notification-sign** (string) - SHA512 hash for security and authenticity.

### Request Body
The payload structure is identical to the response of the Retrieve Account Transactions endpoint.

### Response
(Details of the response body are identical to the Retrieve Account Transactions endpoint response.)
```

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

### Retrieve Card Details

Source: https://developers.vertex-cards.com/docs/api-reference/get-app-external-v-1-cardissue-card-card-getbyid

Fetches detailed information about a specific card belonging to an account within a given company.

```APIDOC
## GET /api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards/:cardUuid

### Description
Returns detailed information about a specific card belonging to an account within a given company.

### Method
GET

### Endpoint
/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards/:cardUuid

### Parameters
#### Path Parameters
- **companyUuid** (string) - Required - The unique identifier for the company.
- **accountUuid** (string) - Required - The unique identifier for the account.
- **cardUuid** (string) - Required - The unique identifier for the card.

### Responses
#### Success Response (200)
Card data.

#### Response Example
{
  "example": "response body"
}
```

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

### Create Card Owner

Source: https://developers.vertex-cards.com/docs/api-reference/post-app-external-v-1-cardissue-cardowner-cardowner-create

Creates a new card owner within the specified company. The same `cardOwnerId` can be reused to create multiple cards.

```APIDOC
## POST /api/v1/cards/companies/:companyUuid/card-owners

### Description
Creates a new card owner within the specified company. The same `cardOwnerId` can be reused to create multiple cards.

This request is asynchronous. After you receive the `201` response, wait a short moment and then call Retrieve Card Owner Data to confirm the owner has been created successfully.

### Method
POST

### Endpoint
/api/v1/cards/companies/:companyUuid/card-owners

### Responses
#### Success Response (201)

Card owner creation request accepted.
```

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

### Create Card Request Body

Source: https://developers.vertex-cards.com/docs/api-reference/post-app-external-v-1-cardissue-card-card-create

This is the JSON payload required to create a card. It includes details such as card name, limits, currency, and owner information.

```json
{
  "name": "Company Expenses Card",
  "cardProviderBinId": "ff246e21-3bda-4e47-83fb-05203939fe5b",
  "binCategoryId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "cardOwnerId": "be7312c7-8f46-4519-8d90-2ca196d43ba8",
  "cardType": "virtual",
  "limits": {
    "daily_limit": "100.00",
    "weekly_limit": "200.00",
    "monthly_limit": "300.00",
    "year_limit": "1000.00",
    "lifetime_limit": "10000.00",
    "transaction_limit": "50.00"
  },
  "currency": "USD"
}

```

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

### Close Card Endpoint

Source: https://developers.vertex-cards.com/docs/api-reference/post-app-external-v-1-cardissue-card-card-close

This snippet shows the POST endpoint for closing a card. It requires company, account, and card UUIDs in the path. The action is irreversible.

```http
POST 
## https://gateway.vertex-cards.com/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards/:cardUuid/close
```

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

### Activate Card

Source: https://developers.vertex-cards.com/docs/api-reference/post-app-external-v-1-cardissue-card-card-activate

Reactivates (unfreezes) a card that is currently in the `frozen` state, allowing transactions to resume. This endpoint is only valid if the card is currently `frozen`. When successfully reactivated, the card's `status` becomes `active`. This request is asynchronous: to confirm the card has been activated, call Retrieve Card Details and check the `status`.

```APIDOC
## POST /api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards/:cardUuid/activate

### Description
Reactivates (unfreezes) a card that is currently in the `frozen` state, allowing transactions to resume. This endpoint is only valid if the card is currently `frozen`. When successfully reactivated, the card's `status` becomes `active`.

This request is asynchronous: to confirm the card has been activated, call Retrieve Card Details and check the `status`.

### Method
POST

### Endpoint
/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards/:cardUuid/activate

### Responses
#### Success Response (204)
Request to activate (unfreeze) the card was accepted. This indicates the activation operation has started, but to confirm the status is now `active`, you must call Retrieve Card Details and check the `status`.
```

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

### Transfer Account Balance

Source: https://developers.vertex-cards.com/docs/api-reference/post-app-external-v-1-cardissue-account-account-transferbalance

Transfers a specified amount from the source account to a destination account. This request is asynchronous.

```APIDOC
## POST https://gateway.vertex-cards.com/api/v1/cards/accounts/:accountUuid/balance/transfer

### Description
Transfers a specified amount from the source account to a destination account. This request is asynchronous.

### Method
POST

### Endpoint
https://gateway.vertex-cards.com/api/v1/cards/accounts/:accountUuid/balance/transfer

### Parameters
#### Path Parameters
- **accountUuid** (string) - Required - Unique identifier of the source account. Example: `9f283e59-21ec-4c74-ae32-156d49cd9cf2`

#### Request Body
- **amount** (string) - Required - Amount to transfer. Expressed as a string with a dot as the decimal separator. Possible values: `> 0`. Example: `50.00`
- **description** (string) - Optional - Purpose or reason for the transfer. Example: `Monthly budget allocation`
- **destinationAccountUuid** (string) - Required - Unique identifier of the destination account. Example: `1ef2294f-b286-64de-b605-0242ac12000e`

### Request Example
```json
{
  "amount": "50.00",
  "description": "Monthly budget allocation",
  "destinationAccountUuid": "1ef2294f-b286-64de-b605-0242ac12000e"
}
```

### Response
#### Success Response (204)
Balance transfer request accepted.

#### Authorization
Api-Access-Token: [Your API Key]
```

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

### Retrieve Account Transactions

Source: https://developers.vertex-cards.com/docs/api-reference/get-app-external-v-1-cardissue-transaction-transaction-list

Fetches a list of transactions for all accounts within a specified company.

```APIDOC
## GET /api/v1/cards/companies/:companyUuid/accounts/transactions

### Description
Returns a list of transactions related to all accounts under a specified company.

### Method
GET

### Endpoint
/api/v1/cards/companies/:companyUuid/accounts/transactions

### Parameters
#### Path Parameters
- **companyUuid** (string) - Required - The unique identifier of the company.

### Responses
#### Success Response (200)
- **transactions** (array) - A list of transactions.
```

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

### Retrieve Cards for an Account

Source: https://developers.vertex-cards.com/docs/api-reference/get-app-external-v-1-cardissue-card-card-list

Retrieves a list of cards associated with a specified account belonging to a given company.

```APIDOC
## GET /api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards

### Description
Retrieves a list of cards associated with a specified account belonging to a given company.

### Method
GET

### Endpoint
/api/v1/cards/companies/:companyUuid/accounts/:accountUuid/cards

### Parameters
#### Path Parameters
- **companyUuid** (string) - Required - The unique identifier for the company.
- **accountUuid** (string) - Required - The unique identifier for the account.

### Responses
#### Success Response (200)
- **cards** (array) - A list of card objects associated with the account.
```