Set Commission

Creates or updates a commission configuration for specific transaction parameters.

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

Gateway APIstagep.tst-apidmndelss.com

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):

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

Example Request Body (Customer-Specific):

{
  "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:

{
  "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)

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

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

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:

   { "error": "Missing required field: currencyIsoFrom" }

2. Invalid Currency Code:

   { "error": "Invalid currency code: INVALID_CURRENCY" }

3. Invalid Operation Type:

   { "error": "Invalid operation type: INVALID_TYPE" }

4. Customer Not Found:

   { "error": "Customer not found: cust_invalid_id" }

5. Unauthorized:

   { "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:

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