# Set Commission

This endpoint allows partners to set custom commission rates for various currency pairs, operation types, and payment methods, with optional customer-specific overrides.

**Endpoint**

`POST/v2/billing/commission`

**Link**

{% embed url="<https://stagep.tst-apidmndelss.com/openapi/v2.html#/operations/Billing_SetCommission>" %}

### **Request**

#### **Authentication**

An API key is required for authentication. Include it in the `Authorization` header.

* **Header:** `Authorization`
* **Value:** Your API key token

#### **HTTP Method & URL**

* **Method:** `POST`
* **URL:** `https://stagep.tst-apidmndelss.com/v2/billing/commission`

#### **Headers**

| Key             | Value              | Required |
| --------------- | ------------------ | -------- |
| `Authorization` | `Bearer <JWT>`     | Yes      |
| `Accept`        | `application/json` | Yes      |
| `Content-Type`  | `application/json` | Yes      |

#### **Request Body (JSON)**

**Required Parameters**

| Field                 | Type     | Description                     | Required | Example |
| --------------------- | -------- | ------------------------------- | -------- | ------- |
| **`currencyIsoFrom`** | `string` | **Source currency ISO code**.   | Yes      | `USD`   |
| **`currencyIsoTo`**   | `string` | **Target currency ISO code**.   | Yes      | `EUR`   |
| **`percent`**         | `number` | **Percentage commission rate**. | Yes      | `0.5`   |
| **`fixed`**           | `number` | **Fixed commission amount**.    | Yes      | `2.5`   |

**Optional Parameters**

| Field               | Type     | Description                            | Required | Example       |
| ------------------- | -------- | -------------------------------------- | -------- | ------------- |
| **`customerId`**    | `string` | **Customer ID for specific override**. | No       | `cust_abc123` |
| **`operationType`** | `string` | **Type of operation** (see values).    | No       | `TRANSFER`    |
| **`paymentType`**   | `string` | **Payment method type** (see values).  | No       | `SWIFT`       |

**Operation Type Values**

* `NOTSET` - Applies to all operation types
* `DEPOSIT` - Deposit operations
* `TRANSFER` - Transfer operations
* `WITHDRAW` - Withdrawal operations
* `COMMISSION` - Commission operations
* `EXCHANGE` - Currency exchange
* `CORRECTING` - Correction operations

**Payment Type Values**

* `EMPTY` - Applies to all payment types
* `ACH` - Automated Clearing House
* `FEDWIRE` - Fedwire transfers
* `SWIFT` - SWIFT transfers
* `CRYPTO` - Cryptocurrency
* `EFT` - Electronic Funds Transfer
* `SEPA_CT` - SEPA Credit Transfer
* `IMPS` - Immediate Payment Service

**Example Request Body (General Commission):**

```json
{
  "currencyIsoFrom": "USD",
  "currencyIsoTo": "EUR",
  "percent": 0.5,
  "fixed": 2.5
}
```

**Example Request Body (Customer-Specific):**

```json
{
  "customerId": "cust_abc123",
  "currencyIsoFrom": "USD",
  "currencyIsoTo": "EUR",
  "operationType": "TRANSFER",
  "paymentType": "SWIFT",
  "percent": 0.3,
  "fixed": 1.5
}
```

***

### **Response (200 OK)**

Returns the created or updated commission configuration.

#### **Response Fields**

**Commission Object (`item`)**

| Field                 | Type     | Description                        | Example                |
| --------------------- | -------- | ---------------------------------- | ---------------------- |
| **`currencyIsoFrom`** | `string` | **Source currency ISO code**.      | `USD`                  |
| **`currencyIsoTo`**   | `string` | **Target currency ISO code**.      | `EUR`                  |
| **`operationType`**   | `string` | **Operation type**.                | `TRANSFER`             |
| **`paymentType`**     | `string` | **Payment method type**.           | `SWIFT`                |
| **`createdAt`**       | `string` | **Commission creation timestamp**. | `2024-01-15T10:30:00Z` |
| **`updatedAt`**       | `string` | **Last update timestamp**.         | `2024-03-20T14:22:00Z` |
| **`customerCuid`**    | `string` | **Customer identifier**.           | `cust_abc123`          |
| **`customerName`**    | `string` | **Customer name**.                 | `Acme Corporation`     |

**Commission Structure (`commission`)**

| Field         | Type     | Description                            | Example |
| ------------- | -------- | -------------------------------------- | ------- |
| **`partner`** | `object` | **Partner-specific commission rates**. |         |
| → `percent`   | `number` | **Percentage commission rate**.        | `0.5`   |
| → `fixed`     | `number` | **Fixed commission amount**.           | `2.5`   |
| **`default`** | `object` | **Default system commission rates**.   |         |
| → `percent`   | `number` | **Percentage commission rate**.        | `1.0`   |
| → `fixed`     | `number` | **Fixed commission amount**.           | `5.0`   |

**Example Response:**

```json
{
  "item": {
    "currencyIsoFrom": "USD",
    "currencyIsoTo": "EUR",
    "operationType": "TRANSFER",
    "paymentType": "SWIFT",
    "commission": {
      "partner": {
        "percent": 0.5,
        "fixed": 2.5
      },
      "default": {
        "percent": 1.0,
        "fixed": 5.0
      }
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-03-20T14:22:00Z",
    "customerCuid": "cust_abc123",
    "customerName": "Acme Corporation"
  }
}
```

***

### **Examples**

#### **Set General Commission Rate (cURL)**

```bash
curl --request POST \
  --url https://stagep.tst-apidmndelss.com/v2/billing/commission \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer eyJhbGci...wNLGA' \
  --header 'Content-Type: application/json' \
  --data '{
    "currencyIsoFrom": "USD",
    "currencyIsoTo": "EUR",
    "percent": 0.5,
    "fixed": 2.5
  }'
```

#### **Set Customer-Specific Commission**

```bash
curl --request POST \
  --url https://stagep.tst-apidmndelss.com/v2/billing/commission \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer eyJhbGci...wNLGA' \
  --header 'Content-Type: application/json' \
  --data '{
    "customerId": "cust_abc123",
    "currencyIsoFrom": "USD",
    "currencyIsoTo": "EUR",
    "operationType": "TRANSFER",
    "paymentType": "SWIFT",
    "percent": 0.3,
    "fixed": 1.5
  }'
```

#### **Set Exchange-Specific Commission**

```bash
curl --request POST \
  --url https://stagep.tst-apidmndelss.com/v2/billing/commission \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer eyJhbGci...wNLGA' \
  --header 'Content-Type: application/json' \
  --data '{
    "currencyIsoFrom": "EUR",
    "currencyIsoTo": "GBP",
    "operationType": "EXCHANGE",
    "percent": 0.2,
    "fixed": 1.0
  }'
```

***

### **Error Responses**

1. **Missing Required Fields**:

   ```json
   { "error": "Missing required field: currencyIsoFrom" }
   ```
2. **Invalid Currency Code**:

   ```json
   { "error": "Invalid currency code: INVALID_CURRENCY" }
   ```
3. **Invalid Operation Type**:

   ```json
   { "error": "Invalid operation type: INVALID_TYPE" }
   ```
4. **Customer Not Found**:

   ```json
   { "error": "Customer not found: cust_invalid_id" }
   ```
5. **Unauthorized**:

   ```json
   { "error": "Unauthorized" }
   ```

***

### **Notes**

#### **Commission Hierarchy**

* **General rates**: Apply when no specific customer or operation type matches
* **Operation-specific**: Override general rates for specific operation types
* **Payment-specific**: Override for specific payment methods
* **Customer-specific**: Highest priority, override all other rates

#### **Rate Validation**

* Percentage rates should be between 0-100
* Fixed rates should be positive values
* Rates are validated against business rules
* Some rate combinations may require approval

#### **Best Practices**

* Use specific parameters for precise commission targeting
* Test commission calculations before setting rates
* Monitor rate changes and their impact on transactions
* Document rate changes for audit purposes

**Common Use Cases**:

* Setting competitive commission rates for specific markets
* Creating custom rates for VIP customers
* Adjusting rates for specific payment methods
* Implementing promotional pricing strategies

**Rate Calculation Example**:\
For a $1000 transfer with 0.5% + $2.50 commission:

```javascript
amount = 1000
commission = (amount * 0.005) + 2.50 = $7.50
```

**Update Behavior**:

* Creating a commission with existing parameters updates the existing rate
* Rates are effective immediately after successful API call
* Historical transactions use rates effective at transaction time


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.delos.financial/commissions/set-commission.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.