Add Client Operation

Creates a new financial operation for a client. Supports various operation types including transfers, deposits, withdrawals, and exchanges with flexible source/destination configurations.

Endpoint

POST/v2/billing/operation

Link

Gateway APIstagep.tst-apidmndelss.com

Request

Headers

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

Request Body (JSON)

Field	Type	Description & Requirements	Required	Example
customerId	string	Customer ID initiating the operation.	Yes	"D7k3xbc-ERrj-lde9k1t3XuaE"
paymentType	string	Payment method: - EMPTY - ACH - FEDWIRE - SWIFT - CRYPTO - UAEFTS - SEPA_CT - CHAPS - FPS	No	"SWIFT"
type	string	Operation type: - NOTSET - DEPOSIT - TRANSFER - WITHDRAW - COMMISSION - EXCHANGE	Yes	"TRANSFER"
sourceRequisit	object	Source account details (see rules below).	Yes	-
→ account	string	Deposit Account ID (for source).	Conditional	"UjmLCEcZCXzb"
→ beneficiar	string	Beneficiary Account ID (not used for source).	No	-
destinationRequisit	object	Destination account details (see rules below).	Yes	-
→ account	string	Deposit Account ID (for transfers/exchanges).	Conditional	"UjmLCEcZCXzb"
→ beneficiar	string	Beneficiary Account ID (for withdrawals).	Conditional	"UjmLCEcZCXzb"
amount	object	Transaction amount (see Money Object below).	Yes	-
→ units	string	Whole units of amount.	Yes	"1000"
→ nanos	integer	Fractional units (nanos = 10^-9).	Yes	500000000
comment	string	Operation comment/description.	No	"Supplier payment"
reference	string	Reference number for tracking.	Yes, 30 symbols max	"INV20240521"
documents	array	Associated documents (see below).	Highly recommended	-

Account Selection Rules

For Source (always):

• Must set sourceRequisit.account (Deposit Account ID)

For Destination:

• TRANSFER, EXCHANGE, DEPOSIT: Set destinationRequisit.account (Deposit Account ID)
• WITHDRAW: Set destinationRequisit.beneficiar (Beneficiary Account ID)

Money Object

Field	Type	Description	Example
units	string	Whole units (e.g., dollars).	"1000"
nanos	integer	Fractional units (10^-9).	500000000 (= $0.50)

Document Object

Field	Type	Description	Example
id	string	Document ID (if already uploaded).	"doc_123"
name	string	Document name.	"invoice.pdf"

---

Response (200 OK)

Returns the created operation with full details including calculated amounts and system-generated fields.

Response Fields

Field	Type	Description	Example
opid	string	System-generated operation ID.	"op_abc123"
isVisible	boolean	Visibility status.	true
status	string	Initial status: NEW.	"NEW"
type	string	Operation type from request.	"TRANSFER"
paymentType	string	Payment method from request.	"SWIFT"
createdAt	string	Creation timestamp (ISO 8601).	"2024-05-21T10:30:00Z"
updatedAt	string	Update timestamp (ISO 8601).	"2024-05-21T10:30:00Z"
source	object	Source account details.	-
destination	object	Destination account details.	-
sourceAmount	object	Source amount with currency.	-
destinationAmount	object	Destination amount with currency.	-
commissionAmount	object	Calculated commission.	-
currentBalanceAmount	object	Current balance after operation.	-
comment	string	Comment from request.	"Supplier payment"
isParent	boolean	Parent operation flag.	true
reference	string	Reference from request.	"SWIFT20240521001"
customer	object	Customer details.	-
documents	array	Associated documents.	-

---

Error Responses

1. Invalid Account:

   { "error": "Source account not found: UjmLCEcZCXzb" }

2. Insufficient Funds:

   { "error": "Insufficient funds in source account" }

3. Invalid Configuration:

   { "error": "Withdrawal operations require beneficiary account for destination" }

---

Notes

• Status Flow: New operations start with NEW status and progress through approval workflow
• Amount Precision: Use units + nanos for precise amounts
• Currency Conversion: For exchanges, system calculates destination amount automatically
• Commission: Calculated based on operation type and payment method
• Validation: Operations are validated against limits and account permissions
• "units" is a whole number, for example: 10 / 100 / 1000 / 0 "nanos" is a decimal number and is filled in a specific way, for example: 500000000 / 100000000 If you want to specify the amount as 10.5, you should enter it as follows: "units": 10, "nanos": 500000000

Examples

Request sample

{
  "customerId": "D7k3xbc-ERrj-lde9k1t3XuaE",
  "paymentType": "EMPTY",
  "type": "EXCHANGE",
  "sourceRequisit": {
    "account": "UjmLCEcZCXzb",
    "beneficiar": "string"
  },
  "destinationRequisit": {
    "account": "UrpI6jMzHnsP",
    "beneficiar": "string"
  },
  "amount": {
    "units": "100",
    "nanos": 0
  },
  "comment": "testapi",
  "reference": "string",
  "documents": [
    {
      "id": "string",
      "name": "string"
    }
  ]
}

Response sample

{
  "item": {
    "operationId": "8248956e-a002-4404-aafc-be8fd8dc16b6",
    "isVisible": true,
    "status": "NEW",
    "type": "EXCHANGE",
    "paymentType": "EMPTY",
    "createdAt": "2025-10-28T12:09:33Z",
    "updatedAt": "2025-10-28T12:09:33Z",
    "source": {
      "counterpartyAccount": {
        "id": "string",
        "name": "",
        "number": "",
        "counterparty": null,
        "customer": null
      }
    },
    "destination": {
      "counterpartyAccount": {
        "id": "string",
        "name": "",
        "number": "",
        "counterparty": null,
        "customer": null
      }
    },
    "sourceAmount": {
      "sum": {
        "currencyCode": "USD",
        "units": "98",
        "nanos": 0
      },
      "default": {
        "currencyCode": "USD",
        "units": "98",
        "nanos": 0
      }
    },
    "destinationAmount": {
      "sum": {
        "currencyCode": "USDT_ERC20",
        "units": "98",
        "nanos": 0
      },
      "default": {
        "currencyCode": "USD",
        "units": "98",
        "nanos": 0
      }
    },
    "commissionAmount": {
      "sum": {
        "currencyCode": "USD",
        "units": "2",
        "nanos": 0
      },
      "default": {
        "currencyCode": "USD",
        "units": "2",
        "nanos": 0
      }
    },
    "currentBalanceAmount": {
      "sum": {
        "currencyCode": "USD",
        "units": "835",
        "nanos": 800000002
      },
      "default": {
        "currencyCode": "USD",
        "units": "835",
        "nanos": 800000002
      }
    },
    "comment": "testapi",
    "isParent": false,
    "reference": "string",
    "customer": {
      "id": "D7k3xbc-ERrj-lde9k1t3XuaE",
      "name": ""
    },
    "documents": []
  }
}