Prepare Client Operation

Simulates and validates a financial operation without executing it.

Returns detailed preview including calculated amounts, commissions, and validation results. Necessary for showing users the exact outcome before confirming the operation.

Endpoint

POST/v2/billing/operation/prepare

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	"cust_12345"
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	"acc_12345"
→ 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	"acc_67890"
→ beneficiar	string	Beneficiary Account ID (for withdrawals).	Conditional	"benef_abc123"
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.	No	"INV20240521"
documents	array	Associated documents (see below).	No	-

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"

Example Request Body (Transfer preview):

{
  "customerId": "cust_12345",
  "paymentType": "EMPTY",
  "type": "TRANSFER",
  "sourceRequisit": {
    "account": "acc_12345"
  },
  "destinationRequisit": {
    "account": "acc_67890"
  },
  "amount": {
    "units": "1000",
    "nanos": 0
  },
  "comment": "Internal transfer preview",
  "reference": "PREVIEW001"
}

Example Request Body (Withdrawal preview):

{
  "customerId": "cust_12345",
  "paymentType": "SWIFT",
  "type": "WITHDRAW",
  "sourceRequisit": {
    "account": "acc_12345"
  },
  "destinationRequisit": {
    "beneficiar": "benef_abc123"
  },
  "amount": {
    "units": "5000",
    "nanos": 0
  },
  "comment": "SWIFT withdrawal preview",
  "reference": "SWIFT_PREVIEW001"
}

Example Request Body (Exchange preview):

{
  "customerId": "cust_12345",
  "paymentType": "EMPTY",
  "type": "EXCHANGE",
  "sourceRequisit": {
    "account": "acc_usd123"
  },
  "destinationRequisit": {
    "account": "acc_eur456"
  },
  "amount": {
    "units": "1000",
    "nanos": 0
  },
  "comment": "USD to EUR exchange preview"
}

---

Response (200 OK)

Returns a preview of the operation with calculated amounts, commissions, and validation results. No actual transaction is executed.

Response Fields

Field	Type	Description	Example
opid	string	Preview operation ID (for reference only).	"preview_op_abc123"
isVisible	boolean	Visibility status.	true
status	string	Preview status: NEW.	"NEW"
type	string	Operation type from request.	"TRANSFER"
paymentType	string	Payment method from request.	"SWIFT"
createdAt	string	Preview timestamp (ISO 8601).	"2024-05-21T10:30:00Z"
updatedAt	string	Preview 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	Calculated destination amount (includes exchange rates).	-
commissionAmount	object	Calculated commission.	-
currentBalanceAmount	object	Projected balance after operation.	-
comment	string	Comment from request.	"Supplier payment"
isParent	boolean	Parent operation flag.	true
reference	string	Reference from request.	"SWIFT_PREVIEW001"
customer	object	Customer details.	-
documents	array	Associated documents.	-

Example Response (Transfer Preview):

{
  "item": {
    "opid": "preview_op_abc123",
    "isVisible": true,
    "status": "NEW",
    "type": "TRANSFER",
    "paymentType": "EMPTY",
    "createdAt": "2024-05-21T10:30:00Z",
    "updatedAt": "2024-05-21T10:30:00Z",
    "source": {
      "account": {
        "id": "acc_12345",
        "name": "Business USD Account",
        "number": "ACC001",
        "customer": {
          "cuid": "cust_12345",
          "name": "Acme Inc."
        }
      }
    },
    "destination": {
      "account": {
        "id": "acc_67890",
        "name": "Savings Account",
        "number": "ACC002",
        "customer": {
          "cuid": "cust_12345",
          "name": "Acme Inc."
        }
      }
    },
    "sourceAmount": {
      "sum": {
        "currencyCode": "USD",
        "units": "1000",
        "nanos": 0
      }
    },
    "destinationAmount": {
      "sum": {
        "currencyCode": "USD",
        "units": "1000",
        "nanos": 0
      }
    },
    "commissionAmount": {
      "sum": {
        "currencyCode": "USD",
        "units": "5",
        "nanos": 0
      }
    },
    "currentBalanceAmount": {
      "sum": {
        "currencyCode": "USD",
        "units": "15000",
        "nanos": 0
      }
    },
    "comment": "Internal transfer preview",
    "isParent": true,
    "reference": "PREVIEW001",
    "customer": {
      "cuid": "cust_12345",
      "name": "Acme Inc."
    },
    "documents": []
  }
}

Example Response (Exchange Preview):

{
  "item": {
    "opid": "preview_op_exchange123",
    "isVisible": true,
    "status": "NEW",
    "type": "EXCHANGE",
    "paymentType": "EMPTY",
    "createdAt": "2024-05-21T10:30:00Z",
    "updatedAt": "2024-05-21T10:30:00Z",
    "source": {
      "account": {
        "id": "acc_usd123",
        "name": "USD Account",
        "number": "USD001",
        "customer": {
          "cuid": "cust_12345",
          "name": "Acme Inc."
        }
      }
    },
    "destination": {
      "account": {
        "id": "acc_eur456",
        "name": "EUR Account",
        "number": "EUR001",
        "customer": {
          "cuid": "cust_12345",
          "name": "Acme Inc."
        }
      }
    },
    "sourceAmount": {
      "sum": {
        "currencyCode": "USD",
        "units": "1000",
        "nanos": 0
      }
    },
    "destinationAmount": {
      "sum": {
        "currencyCode": "EUR",
        "units": "920",
        "nanos": 500000000
      }
    },
    "commissionAmount": {
      "sum": {
        "currencyCode": "USD",
        "units": "10",
        "nanos": 0
      }
    },
    "currentBalanceAmount": {
      "sum": {
        "currencyCode": "USD",
        "units": "9000",
        "nanos": 0
      }
    },
    "comment": "USD to EUR exchange preview",
    "isParent": true,
    "reference": "",
    "customer": {
      "cuid": "cust_12345",
      "name": "Acme Inc."
    },
    "documents": []
  }
}

---

Examples

Request

curl -X POST 'https://stagep.tst-apidmndelss.com/v2/billing/operation/prepare' \
  -H 'Authorization: Bearer eyJhbGci...wNLGA' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId": "cust_12345",
    "paymentType": "SWIFT",
    "type": "WITHDRAW",
    "sourceRequisit": {
      "account": "acc_12345"
    },
    "destinationRequisit": {
      "beneficiar": "benef_abc123"
    },
    "amount": {
      "units": "5000",
      "nanos": 0
    },
    "comment": "International payment preview",
    "reference": "PREVIEW001"
  }'

---

Error Responses

1. Invalid Account:

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

2. Insufficient Funds:

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

3. Limit Exceeded:

   { "error": "Amount exceeds maximum limit of 10000.00" }

4. Invalid Configuration:

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

---

Notes

• Simulation Only: No funds are moved, no database records are created
• Real-time Rates: Uses current exchange rates for currency conversions
• Commission Calculation: Includes all applicable fees and commissions
• Validation: Performs full validation including limits, permissions, and account status
• Use Case: Ideal for showing users exact costs before confirming transactions

Typical Workflow:

1. User fills operation details in UI
2. Call prepare endpoint to get preview
3. Show user calculated amounts and commissions
4. User confirms and calls create endpoint

Real request

"{ ""customerId"": ""D7k3xbc-ERrj-lde9k1t3XuaE"", ""type"": ""WITHDRAW"", ""amount"": { ""units"": 10, ""nanos"": 0 }, ""paymentType"": ""SWIFT"", ""sourceRequisit"": { ""account"": ""UjmLCEcZCXzb"" }, ""destinationRequisit"": { ""beneficiar"": ""UuLoWhjZEtJQ"" }, ""comment"": ""Test"", ""reference"": ""Test"", ""documents"": [ { ""id"": ""string"", ""name"": ""string"" }, { ""id"": ""string"", ""name"": ""string"" } ] }" Real response

"{ ""item"": { ""operationId"": ""944723c9-5510-4d40-8093-14e83986c1fc"", ""isVisible"": true, ""status"": ""NEW"", ""type"": ""WITHDRAW"", ""paymentType"": ""SWIFT"", ""createdAt"": ""0001-01-01T00:00:00Z"", ""updatedAt"": ""0001-01-01T00:00:00Z"", ""source"": { ""account"": { ""id"": ""UjmLCEcZCXzb"", ""name"": """", ""number"": """", ""customer"": null } }, ""destination"": { ""counterpartyAccount"": { ""id"": ""UuLoWhjZEtJQ"", ""name"": """", ""number"": """", ""counterparty"": null, ""customer"": null } }, ""sourceAmount"": { ""sum"": { ""currencyCode"": ""USD"", ""units"": ""10"", ""nanos"": 0 }, ""default"": { ""currencyCode"": ""USD"", ""units"": ""10"", ""nanos"": 0 } }, ""destinationAmount"": { ""sum"": { ""currencyCode"": ""USD"", ""units"": ""10"", ""nanos"": 0 }, ""default"": { ""currencyCode"": ""USD"", ""units"": ""10"", ""nanos"": 0 } }, ""commissionAmount"": { ""sum"": { ""currencyCode"": ""USD"", ""units"": ""30"", ""nanos"": 10000000 }, ""default"": { ""currencyCode"": ""USD"", ""units"": ""30"", ""nanos"": 10000000 } }, ""currentBalanceAmount"": { ""sum"": { ""currencyCode"": ""USD"", ""units"": ""695"", ""nanos"": 790000002 }, ""default"": { ""currencyCode"": ""USD"", ""units"": ""695"", ""nanos"": 790000002 } }, ""comment"": ""Test"", ""isParent"": false, ""reference"": ""Test"", ""customer"": { ""id"": ""D7k3xbc-ERrj-lde9k1t3XuaE"", ""name"": """" }, ""documents"": [] } }"