--- title: "Create a deposit" method: POST path: "/pty/account/v1/deposits" tags: ["Ledger API - Deposits"] --- # Create a deposit `POST /pty/account/v1/deposits` ## Request - Base URL: `https://api.uat.paymentology.com` - URL: `https://api.uat.paymentology.com/pty/account/v1/deposits` - Auth: HTTP bearer ## Request body - DepositRequest: Deposit (cash-in) request. Single-currency only — `destination_amount` describes the credit applied to the internal destination account; both `amount` and `currency` are required. The `external_account_reference` identifies the external funding source. - `external_account_reference` string, nullable: External source (funding) account reference - `destination_account_id` string, required: Internal destination account identifier - `destination_amount` Money, required: A monetary amount with currency. `amount` is in minor units (positive integer string). - On a transfer request, both `source_amount` and `destination_amount` are present and each carries its `currency`. **Exactly one** must supply `amount` — the server computes the other and populates both on the stored record. - On a deposit request (`destination_amount`) and a withdrawal request (`source_amount`), both `amount` and `currency` are always required. - On every response (Create or Get), all `Money` objects are fully populated (`amount` + `currency`). - `amount` string: Amount in minor units. Must be greater than 0 (e.g., 2000 = 20.00 USD). - `currency` string, required: ISO 4217 currency code - `fee` DepositFee: Fee on a deposit. Always charged to the destination account: the destination is credited `destination_amount.amount - fee.amount`. `fee.currency` must equal `destination_amount.currency`. - `amount` string, required: Fee amount in minor units. Must be greater than 0. - `currency` string, required: ISO 4217 currency code. Must equal `destination_amount.currency`. - `type` string, required: Client-defined fee classification tag - `transaction_reference` string, required: Client-provided unique transaction reference (idempotency key). Must not contain whitespace. - `transaction_description` string: Human-readable description ## Response `201` Deposit created - Deposit: Deposit (cash-in) record. Single-currency — `destination_amount` carries both `amount` and `currency`. - `deposit_id` string, uuid, required: Unique deposit identifier. - `external_account_reference` string, nullable: External source (funding) account reference. - `destination_account_id` string, required: Internal destination account identifier. - `destination_amount` Money, required: A monetary amount with currency. `amount` is in minor units (positive integer string). - On a transfer request, both `source_amount` and `destination_amount` are present and each carries its `currency`. **Exactly one** must supply `amount` — the server computes the other and populates both on the stored record. - On a deposit request (`destination_amount`) and a withdrawal request (`source_amount`), both `amount` and `currency` are always required. - On every response (Create or Get), all `Money` objects are fully populated (`amount` + `currency`). - `amount` string: Amount in minor units. Must be greater than 0 (e.g., 2000 = 20.00 USD). - `currency` string, required: ISO 4217 currency code - `fee` DepositFee: Fee on a deposit. Always charged to the destination account: the destination is credited `destination_amount.amount - fee.amount`. `fee.currency` must equal `destination_amount.currency`. - `amount` string, required: Fee amount in minor units. Must be greater than 0. - `currency` string, required: ISO 4217 currency code. Must equal `destination_amount.currency`. - `type` string, required: Client-defined fee classification tag - `transaction_reference` string, required: Client-provided unique transaction reference. - `transaction_description` string: Human-readable description. - `status` 'IN_PROGRESS' | 'COMPLETED' | 'REJECTED' | 'FAILED', required: Transaction processing status (shared across transfers, deposits, and withdrawals). - `IN_PROGRESS` — request persisted, operation in progress (non-terminal). - `COMPLETED` — operation executed successfully (terminal). - `REJECTED` — operation refused by a business rule (terminal). The specific reason is carried in `failure_reason.code`. - `FAILED` — operation failed due to a transient error (non-terminal). The specific reason is carried in `failure_reason.code`. - `failure_reason` FailureReason: Structured rejection or failure detail. Present iff `status ∈ {REJECTED, FAILED}`; absent on `COMPLETED` and `IN_PROGRESS`. - `REJECTED` codes: `INSUFFICIENT_FUNDS`, `ACCOUNT_LIMIT_EXCEEDED`, `TRANSFER_LIMIT_EXCEEDED`. - `FAILED` codes: `DEPENDENCY_UNAVAILABLE`, `INTERNAL_ERROR`. - `code` string, required: Rejection or failure code. Codes currently emitted: - `INSUFFICIENT_FUNDS` - `ACCOUNT_LIMIT_EXCEEDED` - `TRANSFER_LIMIT_EXCEEDED` - `DEPENDENCY_UNAVAILABLE` - `INTERNAL_ERROR` Clients should handle unknown codes gracefully. - `message` string, required: Human-readable detail. - `updated_at` string, date-time, required: Timestamp of the last update. - `destination_account_balance_after` string, nullable: The destination account's net available balance, in minor units, immediately after this deposit. Present only when `status` is `COMPLETED`. ## Other responses - `400`: Request rejected before processing. `VALIDATION_ERROR` for field-level errors (listed in `details`); otherwise a business-rule code: `ACCOUNT_NOT_ACTIVE`, `CURRENCY_MISMATCH`, `INVALID_AMOUNT`, `INVALID_CURRENCY`, `FEE_EXCEEDS_AMOUNT`, `FEE_CURRENCY_MISMATCH`. - `401`: Missing or invalid access token: `UNAUTHORIZED`, `INVALID_CLIENT` or `INVALID_TENANT`. - `403`: Access token rejected by the API gateway (for example, expired). - `404`: `ACCOUNT_NOT_FOUND`: an account in the request does not exist or does not belong to the client. - `409`: `IDEMPOTENCY_CONFLICT`: the `transaction_reference` was already used for a deposit with a different request body. Resending the identical request returns the original deposit with `201`. - `424`: `DEPENDENCY_FAILURE`: the ledger could not process the deposit. It was not completed and can be retried with the same `transaction_reference`. - `500`: `INTERNAL_SERVER_ERROR`: unexpected error. - `503`: `SERVICE_UNAVAILABLE` or `INFRASTRUCTURE_ERROR`: temporary failure. The deposit was not completed and can be retried with the same `transaction_reference`. --- [API](https://skmtc.dev/paymentology/apis/ledger-api.md) - [All operations](https://skmtc.dev/paymentology/apis/ledger-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paymentology/apis/ledger-api/revisions/a5700c501bee?raw)