{ "openapi": "3.0.3", "info": { "title": "VALR Business — Web API", "version": "1.0.0", "description": "The public, frontend-facing Web API for VALR business payments — collections, funding, disbursements, scheduled withdrawals and settlements. Combined from the payments-backend and account-events specs; admin and internal endpoints are excluded. Endpoints are shown at the public /institution/payments/* paths (the gateway rewrites /institution to /v1)." }, "servers": [ { "url": "https://api-dev.valr.world/institution", "description": "Dev (public). The exchange gateway in front of payments-backend exposes these routes under /institution and rewrites the prefix to /v1 before proxying — so a public GET /institution/payments/config reaches the app's /v1/payments/config." }, { "url": "http://localhost:8080/v1", "description": "Local (direct to the app, no gateway; APP_PORT, commonly overridden to 6090). The /v1 prefix is hit directly." } ], "tags": [ { "name": "Getting paid" }, { "name": "Funding records" }, { "name": "Scheduled withdrawals" }, { "name": "Settlements" }, { "name": "Disbursements" }, { "name": "Payout History" }, { "name": "Account Balances" }, { "name": "Payment Config" }, { "name": "Entity Config" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/payments/config": { "get": { "tags": [ "Payment Config" ], "summary": "Get payment config for the calling account", "description": "Returns configuration scoped to the authenticated account (resolved from the trusted internal context, never from the client).", "responses": { "200": { "description": "Config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentConfigForDisplay" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "put": { "tags": [ "Payment Config" ], "summary": "Update payment config for the calling account", "parameters": [ { "$ref": "#/components/parameters/UserUniqueId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePaymentConfigRequest" } } } }, "responses": { "200": { "description": "Updated config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentConfigForDisplay" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/entity/config": { "get": { "tags": [ "Entity Config" ], "summary": "Get entity config for the calling entity", "description": "Scoped to the caller's primary account. 204 when no config exists.", "responses": { "200": { "description": "Entity config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityConfigForDisplay" } } } }, "204": { "description": "No config for this entity" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/account/balances/{type}": { "get": { "tags": [ "Account Balances" ], "summary": "Get subaccount balances by designation", "description": "Primary account is taken from the trusted internal header; the subaccount id is never returned. Returns one balance per currency.", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AccessType" }, "description": "Account designation (e.g. FUNDING). Case-insensitive; invalid values return 400." }, { "name": "currency", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Currency code, e.g. ZAR. Required." } ], "responses": { "200": { "description": "Balances", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountBalanceResponse" } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/payout/history": { "get": { "tags": [ "Payout History" ], "summary": "List payout-account transactions", "description": "Scoped to the caller's primary account.", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "DEBIT", "CREDIT" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "COMPLETE", "PROCESSING", "REVERSED", "FAILED" ] } }, { "name": "from", "in": "query", "schema": { "type": "integer", "format": "int64" }, "description": "Epoch millis, inclusive." }, { "name": "to", "in": "query", "schema": { "type": "integer", "format": "int64" }, "description": "Epoch millis, inclusive." }, { "name": "minAmount", "in": "query", "schema": { "type": "number" } }, { "name": "maxAmount", "in": "query", "schema": { "type": "number" } }, { "name": "exactAmount", "in": "query", "schema": { "type": "number" } }, { "name": "query", "in": "query", "schema": { "type": "string" }, "description": "Free-text on recipient reference / batch label." }, { "name": "beneficiaryId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Group one recipient's history." } ], "responses": { "200": { "description": "Paginated transactions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedPayoutTransactionForDisplay" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/payout/history/{id}": { "get": { "tags": [ "Payout History" ], "summary": "Get a payout-account transaction", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutTransactionForDisplay" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payments/bulk-withdrawals/banks": { "get": { "tags": [ "Disbursements" ], "summary": "List supported banks", "responses": { "200": { "description": "Banks", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankDefinition" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/bulk-withdrawals/batches": { "get": { "tags": [ "Disbursements" ], "summary": "List bulk withdrawal batches", "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/BatchStatus" } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "Paginated batches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedBulkWithdrawalBatchForDisplay" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Disbursements" ], "summary": "Create a bulk withdrawal batch", "parameters": [ { "$ref": "#/components/parameters/UserUniqueId" }, { "$ref": "#/components/parameters/EntityId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBulkWithdrawalBatchRequest" } } } }, "responses": { "200": { "description": "Created batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkWithdrawalBatchForDisplay" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/bulk-withdrawals/batches/{id}": { "get": { "tags": [ "Disbursements" ], "summary": "Get a bulk withdrawal batch", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkWithdrawalBatchForDisplay" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payments/bulk-withdrawals/batches/{id}/withdrawals": { "get": { "tags": [ "Disbursements" ], "summary": "List withdrawals in a batch", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/WithdrawalStatus" } }, { "name": "failureCode", "in": "query", "schema": { "$ref": "#/components/schemas/WithdrawalFailureCode" } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "Paginated withdrawals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedWithdrawalWithBatchForDisplay" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payments/bulk-withdrawals/batches/{id}/fee-quote": { "get": { "tags": [ "Disbursements" ], "summary": "Get a fee quote for a batch", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Fee quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisbursementFeeQuoteForDisplay" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payments/bulk-withdrawals/batches/{id}/label": { "put": { "tags": [ "Disbursements" ], "summary": "Update a batch label", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/UserUniqueId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBulkWithdrawalBatchLabelRequest" } } } }, "responses": { "200": { "description": "Updated batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkWithdrawalBatchForDisplay" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payments/bulk-withdrawals/batches/{id}/approve": { "post": { "tags": [ "Disbursements" ], "summary": "Approve a batch", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/UserUniqueId" } ], "responses": { "200": { "description": "Approved batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkWithdrawalBatchForDisplay" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payments/bulk-withdrawals/batches/{id}/cancel": { "post": { "tags": [ "Disbursements" ], "summary": "Cancel a batch", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/UserUniqueId" } ], "responses": { "200": { "description": "Cancelled batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkWithdrawalBatchForDisplay" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payments/bulk-withdrawals/pending-total": { "get": { "tags": [ "Disbursements" ], "summary": "Get pending disbursement totals", "responses": { "200": { "description": "Totals by currency", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PendingDisbursementTotal" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/bulk-withdrawals/summary": { "get": { "tags": [ "Disbursements" ], "summary": "Get paid disbursement summary", "description": "Entity-wide (primary account) totals for paid disbursements.", "responses": { "200": { "description": "Summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisbursementSummary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/bulk-withdrawals/withdrawals": { "get": { "tags": [ "Disbursements" ], "summary": "List account withdrawals", "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/WithdrawalStatus" } }, { "name": "failureCode", "in": "query", "schema": { "$ref": "#/components/schemas/WithdrawalFailureCode" } }, { "name": "beneficiaryId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "Paginated withdrawals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedWithdrawalWithBatchForDisplay" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/bulk-withdrawals/fee-quote": { "post": { "tags": [ "Disbursements" ], "summary": "Quote fees for a set of withdrawals", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeQuoteRequest" } } } }, "responses": { "200": { "description": "Fee quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisbursementFeeQuoteForDisplay" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/bulk-withdrawals/beneficiaries": { "get": { "tags": [ "Disbursements" ], "summary": "List beneficiaries", "description": "Scoped to the entity's PAYOUT (ZAR) subaccount. Returns an empty page when no PAYOUT subaccount exists.", "parameters": [ { "name": "type", "in": "query", "schema": { "$ref": "#/components/schemas/BeneficiaryType" }, "description": "Blank is treated as absent." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "Paginated beneficiaries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedBeneficiaryForDisplay" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Disbursements" ], "summary": "Create a beneficiary", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBeneficiaryRequest" } } } }, "responses": { "200": { "description": "Created beneficiary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryForDisplay" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/bulk-withdrawals/beneficiaries/bulk": { "post": { "tags": [ "Disbursements" ], "summary": "Create many beneficiaries", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBeneficiariesRequest" } } } }, "responses": { "200": { "description": "Created beneficiaries", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BeneficiaryForDisplay" } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/bulk-withdrawals/beneficiaries/{id}": { "get": { "tags": [ "Disbursements" ], "summary": "Get a beneficiary", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Beneficiary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryForDisplay" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Disbursements" ], "summary": "Update a beneficiary", "description": "Full replace.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/UserUniqueId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBeneficiaryRequest" } } } }, "responses": { "200": { "description": "Updated beneficiary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryForDisplay" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Disbursements" ], "summary": "Delete a beneficiary", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/UserUniqueId" } ], "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payments": { "get": { "tags": [ "Getting paid" ], "summary": "List payments", "description": "The caller's payments (collections and disbursements). Scope is resolved server-side from the authenticated headers; no account ids are accepted from the client.", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "COLLECTION", "DISBURSEMENT" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "PENDING", "SETTLED", "FAILED" ] }, "description": "Settlement status." }, { "name": "from", "in": "query", "schema": { "type": "integer", "format": "int64" }, "description": "Epoch millis." }, { "name": "to", "in": "query", "schema": { "type": "integer", "format": "int64" }, "description": "Epoch millis." }, { "name": "minAmount", "in": "query", "schema": { "type": "number" } }, { "name": "maxAmount", "in": "query", "schema": { "type": "number" } }, { "name": "currency", "in": "query", "schema": { "type": "string" } }, { "name": "reference", "in": "query", "schema": { "type": "string" }, "description": "Partial match on the sender reference (UDR code)." }, { "name": "query", "in": "query", "schema": { "type": "string" }, "description": "Free-text search box (date / amount / currency / reference)." }, { "name": "tz", "in": "query", "schema": { "type": "string" }, "description": "IANA timezone for interpreting a date in `query`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Paginated payments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePaymentForUser" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/deposit-totals": { "get": { "tags": [ "Getting paid" ], "summary": "Deposit totals by currency", "description": "Total deposits per currency over a window (defaults to the last 24h).", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "integer", "format": "int64" }, "description": "Epoch millis; defaults to 24h before `to`." }, { "name": "to", "in": "query", "schema": { "type": "integer", "format": "int64" }, "description": "Epoch millis; defaults to now." } ], "responses": { "200": { "description": "Totals per currency", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyTotal" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/{id}": { "get": { "tags": [ "Getting paid" ], "summary": "Get a payment", "description": "A single payment with its flow-of-funds timeline.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentForUser" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payments/collections/history": { "get": { "tags": [ "Getting paid" ], "summary": "Collections activity feed", "description": "One chronological feed of COLLECTION payments merged with completed settlement roll-ups.", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "PENDING", "SETTLED", "FAILED" ] } }, { "name": "from", "in": "query", "schema": { "type": "integer", "format": "int64" } }, { "name": "to", "in": "query", "schema": { "type": "integer", "format": "int64" } }, { "name": "minAmount", "in": "query", "schema": { "type": "number" } }, { "name": "maxAmount", "in": "query", "schema": { "type": "number" } }, { "name": "currency", "in": "query", "schema": { "type": "string" } }, { "name": "reference", "in": "query", "schema": { "type": "string" } }, { "name": "query", "in": "query", "schema": { "type": "string" } }, { "name": "tz", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Paginated activity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageCollectionActivityForUser" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/collections/summary": { "get": { "tags": [ "Getting paid" ], "summary": "Collections summary tile", "description": "All-time entity-wide roll-up of COLLECTION payments for the dashboard tile.", "responses": { "200": { "description": "Summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionSummary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/fees/summary": { "get": { "tags": [ "Getting paid" ], "summary": "Fees summary tile", "description": "Entity-wide roll-up of fees borne across every charge type; all-time unless a window is given.", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "integer", "format": "int64" } }, { "name": "to", "in": "query", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Fee summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeSummary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/funding/history": { "get": { "tags": [ "Funding records" ], "summary": "Funding history (deposits & conversions)", "description": "The FUNDING sub-account's stablecoin deposits and their conversion to ZAR.", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "integer", "format": "int64" } }, { "name": "to", "in": "query", "schema": { "type": "integer", "format": "int64" } }, { "name": "minReceived", "in": "query", "schema": { "type": "number" } }, { "name": "maxReceived", "in": "query", "schema": { "type": "number" } }, { "name": "minIncoming", "in": "query", "schema": { "type": "number" } }, { "name": "maxIncoming", "in": "query", "schema": { "type": "number" } }, { "name": "receivedCurrency", "in": "query", "schema": { "type": "string" } }, { "name": "incomingCurrency", "in": "query", "schema": { "type": "string" } }, { "name": "query", "in": "query", "schema": { "type": "string" } }, { "name": "tz", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Paginated conversions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageConversionForUser" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/collect/schedules": { "get": { "tags": [ "Scheduled withdrawals" ], "summary": "List withdrawal schedules", "responses": { "200": { "description": "Schedules", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WithdrawalScheduleForDisplay" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/collect/upcoming": { "get": { "tags": [ "Scheduled withdrawals" ], "summary": "Upcoming withdrawals", "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string" }, "description": "Optional payout-currency filter." } ], "responses": { "200": { "description": "Upcoming", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UpcomingWithdrawalForUser" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/collect/events": { "get": { "tags": [ "Scheduled withdrawals" ], "summary": "Upcoming scheduled-withdrawal events", "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Paginated events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageScheduledWithdrawalEventForUser" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/collect/events/{id}": { "get": { "tags": [ "Scheduled withdrawals" ], "summary": "Get a scheduled-withdrawal event", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledWithdrawalEventForUser" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payments/collect/history": { "get": { "tags": [ "Scheduled withdrawals" ], "summary": "Scheduled-withdrawal event history", "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Paginated events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageScheduledWithdrawalEventForUser" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/collect/runs/history": { "get": { "tags": [ "Scheduled withdrawals" ], "summary": "Payout run history", "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Paginated runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageWithdrawalRunForDisplay" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/collect/runs/{id}": { "get": { "tags": [ "Scheduled withdrawals" ], "summary": "Get a payout run", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalRunForDisplay" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payments/collect/runs/{id}/payments": { "get": { "tags": [ "Scheduled withdrawals" ], "summary": "Payments in a payout run", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Paginated payments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePaymentForUser" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payments/collect/settlements": { "get": { "tags": [ "Settlements" ], "summary": "List settlements", "description": "Payouts grouped by payout request id, spanning scheduled and instant payouts.", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "COLLECTION", "DISBURSEMENT" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "PENDING", "SETTLED", "FAILED", "PARTIALLY_SETTLED" ] } }, { "name": "from", "in": "query", "schema": { "type": "integer", "format": "int64" } }, { "name": "to", "in": "query", "schema": { "type": "integer", "format": "int64" } }, { "name": "minAmount", "in": "query", "schema": { "type": "number" } }, { "name": "maxAmount", "in": "query", "schema": { "type": "number" } }, { "name": "currency", "in": "query", "schema": { "type": "string" } }, { "name": "query", "in": "query", "schema": { "type": "string" } }, { "name": "tz", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Paginated settlements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageSettlementForUser" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/collect/settlements/wallet": { "get": { "tags": [ "Settlements" ], "summary": "Settlement wallet", "description": "The entity-level crypto payout destination.", "responses": { "200": { "description": "Wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementWalletForUser" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payments/collect/settlements/summary": { "get": { "tags": [ "Settlements" ], "summary": "Settlements summary tile", "description": "Total amount settled over a window (all-time when omitted).", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "integer", "format": "int64" } }, { "name": "to", "in": "query", "schema": { "type": "integer", "format": "int64" } }, { "name": "currency", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementSummary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/payments/collect/settlements/{id}/payments": { "get": { "tags": [ "Settlements" ], "summary": "Payments in a settlement", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Payout request id." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Paginated payments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePaymentForUser" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payments/collect/settlements/{id}": { "get": { "tags": [ "Settlements" ], "summary": "Get a settlement", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Payout request id." } ], "responses": { "200": { "description": "Settlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementForUser" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "schemas": { "ErrorResponse": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "ValidationError": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } }, "ValidationErrorResponse": { "type": "object", "required": [ "code", "message", "errors" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationError" } } } }, "AccessType": { "type": "string", "enum": [ "PAYOUT", "COLLECTIONS", "FUNDING", "HOLD" ] }, "AccountGrant": { "type": "object", "required": [ "accountId", "type" ], "properties": { "accountId": { "type": "integer", "format": "int64" }, "publicId": { "type": "string", "nullable": true }, "type": { "$ref": "#/components/schemas/AccessType" }, "currency": { "type": "string", "nullable": true } } }, "UserAccessDto": { "type": "object", "required": [ "accountId", "primaryAccountId", "accounts", "userUuid" ], "properties": { "accountId": { "type": "integer", "format": "int64" }, "primaryAccountId": { "type": "integer", "format": "int64" }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/AccountGrant" } }, "userUuid": { "type": "string", "format": "uuid" } } }, "UpsertUserAccessRequest": { "type": "object", "required": [ "accountId", "primaryAccountId" ], "properties": { "accountId": { "type": "integer", "format": "int64" }, "userUuid": { "type": "string", "format": "uuid", "nullable": true }, "primaryAccountId": { "type": "integer", "format": "int64" }, "grants": { "type": "array", "items": { "$ref": "#/components/schemas/AccountGrant" } } } }, "CurrencyDto": { "type": "object", "required": [ "shortName" ], "properties": { "shortName": { "type": "string", "description": "Currency code, e.g. ZAR" }, "symbol": { "type": "string", "nullable": true }, "longName": { "type": "string", "nullable": true } } }, "AccountBalanceResponse": { "type": "object", "required": [ "currency", "available", "reserved", "total" ], "properties": { "currency": { "$ref": "#/components/schemas/CurrencyDto" }, "available": { "type": "string", "description": "Decimal amount as string" }, "reserved": { "type": "string" }, "total": { "type": "string" } } }, "PaymentConfigForDisplay": { "type": "object", "required": [ "accountId", "enabled", "autoConvert", "defaultPayoutCurrency", "supportedDepositCurrencies" ], "properties": { "accountId": { "type": "integer", "format": "int64" }, "enabled": { "type": "boolean" }, "autoConvert": { "type": "boolean" }, "defaultPayoutCurrency": { "type": "string" }, "supportedDepositCurrencies": { "type": "array", "items": { "type": "string" } } } }, "UpdatePaymentConfigRequest": { "type": "object", "properties": { "autoConvert": { "type": "boolean", "nullable": true }, "defaultPayoutCurrency": { "type": "string", "nullable": true } } }, "EntityProduct": { "type": "string", "enum": [ "COLLECTIONS", "DISBURSEMENTS" ] }, "EntityConfigForDisplay": { "type": "object", "required": [ "products", "businessHomeUrl", "personalEnabled", "isLegacy" ], "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/EntityProduct" } }, "businessHomeUrl": { "type": "string" }, "personalEnabled": { "type": "boolean" }, "isLegacy": { "type": "boolean" } } }, "UpsertEntityConfigRequest": { "type": "object", "required": [ "products", "businessHomeUrl" ], "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/EntityProduct" } }, "businessHomeUrl": { "type": "string" }, "personalEnabled": { "type": "boolean", "default": false }, "isLegacy": { "type": "boolean", "default": true } } }, "SubaccountConfigForDisplay": { "type": "object", "required": [ "accountId", "currency", "type", "subaccountAccountId" ], "properties": { "accountId": { "type": "integer", "format": "int64" }, "currency": { "type": "string" }, "type": { "$ref": "#/components/schemas/AccessType" }, "subaccountAccountId": { "type": "integer", "format": "int64" }, "subaccountPublicId": { "type": "string", "nullable": true } } }, "UpsertSubaccountConfigRequest": { "type": "object", "required": [ "currency", "type", "subaccountAccountId" ], "properties": { "currency": { "type": "string" }, "type": { "$ref": "#/components/schemas/AccessType" }, "subaccountAccountId": { "type": "integer", "format": "int64" }, "subaccountPublicId": { "type": "string", "nullable": true } } }, "PayoutTransactionForDisplay": { "type": "object", "required": [ "id", "direction", "kind", "status", "amount", "currency", "date" ], "properties": { "id": { "type": "string" }, "direction": { "type": "string", "enum": [ "DEBIT", "CREDIT" ] }, "kind": { "type": "string", "enum": [ "WITHDRAWAL", "FUNDING_AES", "FUNDING_MANUAL", "REVERSAL" ] }, "status": { "type": "string", "enum": [ "COMPLETE", "PROCESSING", "REVERSED", "FAILED" ] }, "amount": { "type": "string", "description": "Gross, unsigned money string" }, "currency": { "type": "string" }, "date": { "type": "integer", "format": "int64", "description": "Epoch millis" }, "counterparty": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "batchId": { "type": "string", "nullable": true }, "batchLabel": { "type": "string", "nullable": true }, "paymentId": { "type": "string", "nullable": true } } }, "PaginatedPayoutTransactionForDisplay": { "type": "object", "required": [ "items", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutTransactionForDisplay" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "BatchStatus": { "type": "string", "enum": [ "PENDING_APPROVAL", "APPROVED", "PROCESSING", "COMPLETED", "PARTIALLY_COMPLETED", "FAILED", "CANCELLED" ] }, "WithdrawalStatus": { "type": "string", "enum": [ "PENDING", "APPROVED", "EXECUTING", "SUBMITTED", "PROCESSING", "PAID", "FAILED", "SKIPPED" ] }, "WithdrawalFailureCode": { "type": "string", "enum": [ "GENERIC", "INSUFFICIENT_FUNDS", "INVALID_DETAILS", "NO_BANK_ACCOUNT", "AMOUNT_TOO_SMALL", "ACCOUNT_UNVERIFIED", "SYSTEM_UNAVAILABLE", "DECLINED", "REVERSED" ] }, "BeneficiaryType": { "type": "string", "enum": [ "INDIVIDUAL", "BUSINESS" ] }, "CancelReason": { "type": "string", "enum": [ "REJECTED_BY_APPROVER", "APPROVAL_EXPIRED" ] }, "ResolvedUserName": { "type": "object", "required": [ "name", "surname" ], "properties": { "name": { "type": "string" }, "surname": { "type": "string" } } }, "BankDefinition": { "type": "object", "required": [ "code", "displayName", "defaultBranchCode" ], "properties": { "code": { "type": "string" }, "displayName": { "type": "string" }, "defaultBranchCode": { "type": "string" }, "rtcParticipant": { "type": "boolean", "default": false } } }, "CurrencyTotal": { "type": "object", "required": [ "currency", "total" ], "properties": { "currency": { "type": "string" }, "total": { "type": "string", "description": "Money as string" } } }, "PendingDisbursementTotal": { "type": "object", "required": [ "currency", "total" ], "properties": { "currency": { "type": "string" }, "total": { "type": "string" } } }, "DisbursementSummary": { "type": "object", "required": [ "total", "totalsByCurrency", "paidCount", "distinctRecipients" ], "properties": { "total": { "type": "string" }, "totalsByCurrency": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyTotal" } }, "paidCount": { "type": "integer" }, "distinctRecipients": { "type": "integer" } } }, "DisbursementFeeGroupForDisplay": { "type": "object", "required": [ "actionType", "withdrawalCount", "grossTotal" ], "properties": { "actionType": { "type": "string" }, "withdrawalCount": { "type": "integer" }, "grossTotal": { "type": "string" } } }, "DisbursementFeeQuoteForDisplay": { "type": "object", "required": [ "fee", "currency", "withdrawalCount", "grossTotal", "requiredTotal" ], "properties": { "fee": { "type": "string" }, "currency": { "type": "string" }, "withdrawalCount": { "type": "integer" }, "grossTotal": { "type": "string" }, "requiredTotal": { "type": "string" }, "feeGroups": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/DisbursementFeeGroupForDisplay" } } } }, "MinimalBatchForDisplay": { "type": "object", "required": [ "id", "label", "status", "uploadedBy" ], "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "status": { "$ref": "#/components/schemas/BatchStatus" }, "uploadedBy": { "type": "string" }, "uploadedByName": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ResolvedUserName" } ] }, "approvedBy": { "type": "string", "nullable": true }, "approvedByName": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ResolvedUserName" } ] } } }, "BulkWithdrawalBatchForDisplay": { "type": "object", "required": [ "id", "label", "currency", "totalAmount", "withdrawalCount", "status", "uploadedBy", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "currency": { "type": "string" }, "totalAmount": { "type": "string" }, "withdrawalCount": { "type": "integer" }, "status": { "$ref": "#/components/schemas/BatchStatus" }, "uploadedBy": { "type": "string" }, "uploadedByName": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ResolvedUserName" } ] }, "approvedBy": { "type": "string", "nullable": true }, "approvedByName": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ResolvedUserName" } ] }, "approvedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "approvalIdentifier": { "type": "string", "format": "uuid", "nullable": true }, "feeQuote": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/DisbursementFeeQuoteForDisplay" } ] } } }, "PaginatedBulkWithdrawalBatchForDisplay": { "type": "object", "required": [ "items", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BulkWithdrawalBatchForDisplay" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "WithdrawalWithBatchForDisplay": { "type": "object", "required": [ "id", "amount", "bank", "bankDisplayName", "accountType", "accountHolder", "accountNumberMasked", "accountNumber", "branchCode", "status", "createdAt", "updatedAt", "batch" ], "properties": { "id": { "type": "string", "format": "uuid" }, "amount": { "type": "string" }, "bank": { "type": "string" }, "bankDisplayName": { "type": "string" }, "accountType": { "type": "string" }, "accountHolder": { "type": "string" }, "accountNumberMasked": { "type": "string" }, "accountNumber": { "type": "string" }, "branchCode": { "type": "string" }, "reference": { "type": "string", "nullable": true }, "linkedBankAccountId": { "type": "string", "format": "uuid", "nullable": true }, "withdrawalId": { "type": "string", "nullable": true }, "status": { "$ref": "#/components/schemas/WithdrawalStatus" }, "failureReason": { "type": "string", "nullable": true }, "failureReasonCode": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "batch": { "$ref": "#/components/schemas/MinimalBatchForDisplay" } } }, "PaginatedWithdrawalWithBatchForDisplay": { "type": "object", "required": [ "items", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WithdrawalWithBatchForDisplay" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "BeneficiaryForDisplay": { "type": "object", "required": [ "id", "bank", "bankDisplayName", "accountHolder", "accountNumberMasked", "accountNumber", "branchCode", "accountType", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "bank": { "type": "string" }, "bankDisplayName": { "type": "string" }, "accountHolder": { "type": "string" }, "accountNumberMasked": { "type": "string" }, "accountNumber": { "type": "string" }, "branchCode": { "type": "string" }, "accountType": { "type": "string" }, "email": { "type": "string", "nullable": true }, "type": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/BeneficiaryType" } ] }, "tradingName": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true, "description": "ISO alpha-2" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PaginatedBeneficiaryForDisplay": { "type": "object", "required": [ "items", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BeneficiaryForDisplay" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "BulkWithdrawalItemRequest": { "type": "object", "required": [ "bank", "accountHolder", "accountNumber", "branchCode", "accountType", "amount" ], "properties": { "bank": { "type": "string" }, "accountHolder": { "type": "string", "minLength": 4, "maxLength": 30 }, "accountNumber": { "type": "string", "description": "4-18 digits" }, "branchCode": { "type": "string", "description": "Exactly 6 digits" }, "accountType": { "type": "string", "description": "One of CHEQUE, SAVINGS, BOND, TRANSMISSION (case-insensitive)" }, "amount": { "type": "number", "description": "Positive; max 18 integer / 2 fraction digits" }, "reference": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true, "description": "INDIVIDUAL or BUSINESS" }, "tradingName": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true, "description": "2-letter ISO" } } }, "CreateBulkWithdrawalBatchRequest": { "type": "object", "required": [ "withdrawals" ], "properties": { "withdrawals": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/BulkWithdrawalItemRequest" } }, "label": { "type": "string", "nullable": true, "maxLength": 64 } } }, "FeeQuoteItemRequest": { "type": "object", "required": [ "bank", "amount" ], "properties": { "bank": { "type": "string" }, "amount": { "type": "number", "description": "Positive; max 18 integer / 2 fraction digits" } } }, "FeeQuoteRequest": { "type": "object", "required": [ "withdrawals" ], "properties": { "withdrawals": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/FeeQuoteItemRequest" } } } }, "UpdateBulkWithdrawalBatchLabelRequest": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "maxLength": 64 } } }, "CreateBeneficiaryRequest": { "type": "object", "required": [ "bank", "accountHolder", "accountNumber", "branchCode", "accountType", "type" ], "properties": { "bank": { "type": "string" }, "accountHolder": { "type": "string", "minLength": 4, "maxLength": 30 }, "accountNumber": { "type": "string" }, "branchCode": { "type": "string" }, "accountType": { "type": "string" }, "email": { "type": "string", "nullable": true }, "type": { "$ref": "#/components/schemas/BeneficiaryType" }, "tradingName": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true } } }, "CreateBeneficiariesRequest": { "type": "object", "required": [ "beneficiaries" ], "properties": { "beneficiaries": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/CreateBeneficiaryRequest" } } } }, "UpdateBeneficiaryRequest": { "type": "object", "required": [ "bank", "accountHolder", "accountNumber", "branchCode", "accountType", "type" ], "properties": { "bank": { "type": "string" }, "accountHolder": { "type": "string", "minLength": 4, "maxLength": 30 }, "accountNumber": { "type": "string" }, "branchCode": { "type": "string" }, "accountType": { "type": "string" }, "type": { "$ref": "#/components/schemas/BeneficiaryType" }, "email": { "type": "string", "nullable": true }, "tradingName": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true } } }, "ApproveCallbackBody": { "type": "object", "required": [ "approvalIdentifier" ], "properties": { "approvalIdentifier": { "type": "string", "format": "uuid" }, "approvedByUserIdentifier": { "type": "string", "format": "uuid", "nullable": true } } }, "RejectCallbackBody": { "type": "object", "required": [ "approvalIdentifier" ], "properties": { "approvalIdentifier": { "type": "string", "format": "uuid" }, "rejectedByUserIdentifier": { "type": "string", "format": "uuid", "nullable": true }, "reason": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CancelReason" } ] } } }, "FlowStepForDisplay": { "type": "object", "required": [ "type", "label", "status", "at" ], "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "data": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "traceId": { "type": "string", "nullable": true }, "at": { "type": "integer", "format": "int64", "description": "Epoch millis" } } }, "PaymentForUser": { "type": "object", "required": [ "id", "status", "type", "inflowCurrency", "inflowAmount", "receivedAt", "linked" ], "properties": { "id": { "type": "string", "format": "uuid" }, "depositId": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "description": "Derived: RECEIVED, CONVERTED, SWEPT, PENDING_SETTLEMENT, COMPLETED, FAILED" }, "mode": { "type": "string", "nullable": true, "enum": [ "INSTANT", "SCHEDULED" ] }, "type": { "type": "string", "enum": [ "COLLECTION", "DISBURSEMENT" ] }, "inflowCurrency": { "type": "string" }, "inflowAmount": { "type": "string" }, "convertedCurrency": { "type": "string", "nullable": true }, "convertedAmount": { "type": "string", "nullable": true }, "outflowCurrency": { "type": "string", "nullable": true }, "outflowAmount": { "type": "string", "nullable": true }, "receivedAt": { "type": "integer", "format": "int64" }, "settlementAt": { "type": "integer", "format": "int64", "nullable": true }, "settlementStatus": { "type": "string", "nullable": true, "enum": [ "PENDING", "SETTLED", "FAILED" ] }, "settlementRef": { "type": "string", "nullable": true }, "settlementId": { "type": "string", "nullable": true, "description": "Shared payout request id; null until dispatched" }, "linked": { "type": "boolean" }, "payerName": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "timeline": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/FlowStepForDisplay" } } } }, "PagePaymentForUser": { "type": "object", "required": [ "items", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentForUser" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "ConversionForUser": { "type": "object", "required": [ "id", "date", "status", "source" ], "properties": { "id": { "type": "string" }, "date": { "type": "integer", "format": "int64" }, "status": { "type": "string", "description": "COMPLETE, FAILED or PENDING" }, "source": { "type": "string", "description": "FIAT_DEPOSIT, CRYPTO_DEPOSIT, or the raw event name" }, "incomingCurrency": { "type": "string", "nullable": true }, "incomingAmount": { "type": "string", "nullable": true }, "receivedCurrency": { "type": "string", "nullable": true }, "receivedAmount": { "type": "string", "nullable": true }, "fxPrice": { "type": "string", "nullable": true }, "fxCurrency": { "type": "string", "nullable": true }, "errorCode": { "type": "string", "nullable": true }, "traceId": { "type": "string", "nullable": true } } }, "PageConversionForUser": { "type": "object", "required": [ "items", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ConversionForUser" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "CollectionActivityForUser": { "type": "object", "required": [ "kind", "id", "date", "status", "amount" ], "properties": { "kind": { "type": "string", "enum": [ "PAYMENT", "SETTLEMENT" ] }, "id": { "type": "string" }, "date": { "type": "integer", "format": "int64" }, "status": { "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string", "nullable": true }, "convertedAmount": { "type": "string", "nullable": true }, "convertedCurrency": { "type": "string", "nullable": true }, "from": { "type": "string", "nullable": true }, "to": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "paymentId": { "type": "string", "nullable": true }, "settlementId": { "type": "string", "nullable": true } } }, "PageCollectionActivityForUser": { "type": "object", "required": [ "items", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionActivityForUser" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "CollectionSummary": { "type": "object", "required": [ "total", "totalsByCurrency", "collectionCount", "distinctPayerCount" ], "properties": { "total": { "type": "string" }, "totalsByCurrency": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyTotal" } }, "collectionCount": { "type": "integer" }, "distinctPayerCount": { "type": "integer" } } }, "FeeSummary": { "type": "object", "required": [ "totalsByCurrency", "chargeCount" ], "properties": { "totalsByCurrency": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyTotal" } }, "chargeCount": { "type": "integer" } } }, "WithdrawalScheduleForDisplay": { "type": "object", "required": [ "id", "currency", "kind", "intervalType", "timeOfDay", "zoneId", "cutoffMinutes", "paymentInstrumentId", "isActive", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "currency": { "type": "string" }, "kind": { "type": "string", "enum": [ "FIAT", "CRYPTO" ] }, "intervalType": { "type": "string", "enum": [ "DAILY", "WEEKLY" ] }, "timeOfDay": { "type": "string", "description": "Wall-clock HH:mm[:ss]" }, "zoneId": { "type": "string" }, "dayOfWeek": { "type": "integer", "nullable": true, "description": "ISO 1=Mon..7=Sun" }, "cutoffMinutes": { "type": "integer" }, "paymentInstrumentId": { "type": "string", "format": "uuid" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "integer", "format": "int64" }, "updatedAt": { "type": "integer", "format": "int64" } } }, "UpcomingWithdrawalForUser": { "type": "object", "required": [ "scheduleId", "currency", "totalAmount", "eventCount" ], "properties": { "scheduleId": { "type": "string", "format": "uuid" }, "currency": { "type": "string" }, "nextRunAt": { "type": "integer", "format": "int64", "nullable": true }, "cutoffAt": { "type": "integer", "format": "int64", "nullable": true }, "totalAmount": { "type": "string" }, "eventCount": { "type": "integer" } } }, "ScheduledWithdrawalEventForUser": { "type": "object", "required": [ "id", "withdrawalCurrency", "withdrawalAmount", "receivedAt", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "withdrawalCurrency": { "type": "string" }, "withdrawalAmount": { "type": "string" }, "receivedAt": { "type": "integer", "format": "int64" }, "status": { "type": "string", "enum": [ "QUEUED", "SCHEDULED", "PROCESSING", "COMPLETED", "FAILED" ] }, "depositCurrency": { "type": "string", "nullable": true }, "depositAmount": { "type": "string", "nullable": true }, "payerName": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "timeline": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/FlowStepForDisplay" } } } }, "PageScheduledWithdrawalEventForUser": { "type": "object", "required": [ "items", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledWithdrawalEventForUser" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "WithdrawalRunForDisplay": { "type": "object", "required": [ "id", "scheduledFor", "cutoffAt", "status", "totalAmount", "currency", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "scheduledFor": { "type": "integer", "format": "int64" }, "cutoffAt": { "type": "integer", "format": "int64" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "DONE", "FAILED", "CANCELLED" ] }, "totalAmount": { "type": "string" }, "currency": { "type": "string" }, "createdAt": { "type": "integer", "format": "int64" } } }, "PageWithdrawalRunForDisplay": { "type": "object", "required": [ "items", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WithdrawalRunForDisplay" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "SettlementForUser": { "type": "object", "required": [ "id", "totalAmount", "paymentCount", "status", "receivedAt" ], "properties": { "id": { "type": "string", "description": "Payout request id" }, "currency": { "type": "string", "nullable": true }, "totalAmount": { "type": "string" }, "paymentCount": { "type": "integer" }, "status": { "type": "string", "enum": [ "PENDING", "SETTLED", "FAILED", "PARTIALLY_SETTLED" ] }, "settledAt": { "type": "integer", "format": "int64", "nullable": true }, "receivedAt": { "type": "integer", "format": "int64" } } }, "PageSettlementForUser": { "type": "object", "required": [ "items", "total", "limit", "offset" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementForUser" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "SettlementSummary": { "type": "object", "required": [ "total", "totalsByCurrency", "settledCount" ], "properties": { "total": { "type": "string" }, "totalsByCurrency": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyTotal" } }, "settledCount": { "type": "integer" } } }, "SettlementWalletForUser": { "type": "object", "required": [ "id", "address", "currency" ], "properties": { "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "address": { "type": "string" }, "network": { "type": "string", "nullable": true }, "currency": { "type": "string" }, "beneficiaryName": { "type": "string", "nullable": true }, "serviceProviderName": { "type": "string", "nullable": true } } } }, "parameters": { "UserUniqueId": { "name": "X-USER-UNIQUE-ID", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Calling user's UUID; required on write operations." }, "EntityId": { "name": "X-VALR-Entity-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Entity UUID; required when creating a batch." }, "AccountIdPath": { "name": "accountId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Entity (primary) account id." } }, "responses": { "Unauthorized": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "Authenticated but lacking the required role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ValidationError": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT carrying role management:user. Admin/internal operations require additional roles as noted per operation." } } } }