{ "openapi" : "3.1.0", "servers" : [ { "url" : "https://balance-control-test.adyen.com/balance-control/api/v2", "description" : "Test Environment" }, { "url" : "https://balance-control-live.adyen.com/balance-control/api/v2", "description" : "Live Environment" } ], "info" : { "title" : "Balance Control API", "description" : "The Balance Control API allows you to view and manage the balances in your company and merchant accounts.\n## Authentication\nWe recommend that you use an API key to connect to the Balance Control API. You can [generate an API key](https://docs.adyen.com/development-resources/api-credentials#generate-api-key) in your Customer Area.\n### Header format\nTo connect to the Balance Control API, add an `X-API-Key` header with the API key as the value. For example:\n\n ```\ncurl\n-H 'Content-Type: application/json' \\\n-H 'X-API-Key: ADYEN_API_KEY' \\\n...\n```\n\n## Versioning\n\nThe Balance Control API handles versioning as part of the endpoint URL. For example, to send a request to version 2 of the `/balanceOverview/companies/{companyId}/balances` endpoint, use:\n\nhttps://balance-control-test.adyen.com/balance-control/api/v2/balanceOverview/companies/{companyId}/balances\n\n## Going live\nWhen going live, generate an API key in your [live Customer Area](https://ca-live.adyen.com/ca/). You can then use the API key to send requests to `https://balance-control-live.adyen.com/api/v2`.\n\n", "termsOfService" : "https://www.adyen.com/legal/terms-and-conditions", "contact" : { "name" : "Adyen Developer Experience team", "url" : "https://github.com/Adyen/adyen-openapi" }, "version" : "2" }, "tags" : [ { "name" : "Balances overview", "x-groupIndex" : 1 }, { "name" : "Balance transfers", "x-groupIndex" : 2 } ], "paths" : { "/balanceOverview/companies/{companyAccountCode}/balances" : { "get" : { "tags" : [ "Balances overview" ], "summary" : "View the available balances for all merchant accounts under your company.", "description" : "Returns an array with details about the balances available for all merchant accounts under your company account. For each merchant account, the response returns the following:\n\n\n* **Available funds**: The funds in the merchant account that have been settled and are available for use.\n\n\n* **Pending balance**: The funds in the merchant account that have not been settled yet.\n\n\n* **Next payout amount**: The amount that will be settled to your bank account with the next payout.\n\n\n* **Reserve**: The available amount to cover refunds, payouts, chargebacks, and other operational expenses that cannot be covered by your in-process funds.\n\n\n* **Deposit**: The amount withheld by Adyen to cover potential losses and liabilities due to payment processing.\n", "operationId" : "get-balanceOverview-companies-companyAccountCode-balances", "parameters" : [ { "name" : "companyAccountCode", "in" : "path", "description" : "The unique identifier of your company account.", "required" : true, "schema" : { "type" : "string" } }, { "name" : "currency", "in" : "query", "description" : "The currency for which you want a balances overview.", "required" : true, "schema" : { "minLength" : 1, "type" : "string" } } ], "responses" : { "200" : { "description" : "OK - The request has succeeded.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CompanyBalances" }, "examples" : { "Response code 200: balances overview for company account" : { "summary" : "Response code 200: balances overview for company account", "description" : "Response code 200: balance details for company account", "value" : "{\n \"merchantBalancesOverview\": [\n {\n \"merchantAccount\": \"MERCHANT_ACCOUNT_1\",\n \"availableFund\": {\n \"value\": 3191,\n \"currency\": \"EUR\"\n },\n \"pendingBalance\": {\n \"value\": -112845,\n \"currency\": \"EUR\"\n },\n \"nextPayout\": {\n \"value\": 3191,\n \"currency\": \"EUR\"\n },\n \"reserve\": {\n \"value\": 0,\n \"currency\": \"EUR\"\n }\n },\n {\n \"merchantAccount\": \"MERCHANT_ACCOUNT_2\",\n \"availableFund\": {\n \"value\": 0,\n \"currency\": \"USD\"\n },\n \"reserve\": {\n \"value\": 0,\n \"currency\": \"USD\"\n },\n \"deposit\": {\n \"value\": 50000,\n \"currency\": \"USD\"\n }\n }\n }\n}\n" } } } } }, "401" : { "description" : "Unauthorized - Authentication required.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" } } } }, "403" : { "description" : "Forbidden - insufficient permissions to process the request.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" } } } }, "422" : { "description" : "Unprocessable Content - A request validation error.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" } } } } }, "x-group-parameters" : "false", "x-methodName" : "getCompanyBalancesOverview", "x-sortIndex" : 0 } }, "/balanceOverview/merchants/{merchantAccountCode}/balances" : { "get" : { "tags" : [ "Balances overview" ], "summary" : "View all balances available for your merchant account.", "description" : "Returns an overview of the different balances available for the merchant account. This includes details about the following:\n\n\n* **Available funds**: The funds in the merchant account that have been settled and are available for use.\n\n\n* **Pending balance**: The funds in the merchant account that have not been settled yet.\n\n\n* **Next payout amount**: The amount that will be settled to your bank account with the next payout.\n\n\n* **Reserve**: The available amount to cover refunds, payouts, chargebacks, and other operational expenses that cannot be covered by your in-process funds.\n\n\n* **Deposit**: The amount withheld by Adyen to cover potential losses and liabilities due to payment processing.\n", "operationId" : "get-balanceOverview-merchants-merchantAccountCode-balances", "parameters" : [ { "name" : "merchantAccountCode", "in" : "path", "description" : "The unique identifier of your merchant account.", "required" : true, "schema" : { "type" : "string" } }, { "name" : "currency", "in" : "query", "description" : "The currency for which you want a balances overview.", "required" : true, "schema" : { "minLength" : 1, "type" : "string" } } ], "responses" : { "200" : { "description" : "OK - The request has succeeded.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/MerchantBalance" }, "examples" : { "Response code 200: balances overview for merchant account" : { "summary" : "Response code 200: balances overview for merchant account", "description" : "Response code 200: balance details for merchant account", "value" : "{\n \"merchantBalancesOverview\": [\n {\n \"merchantAccount\": \"MERCHANT_ACCOUNT_1\",\n \"availableFund\": {\n \"value\": 3191,\n \"currency\": \"EUR\"\n },\n \"pendingBalance\": {\n \"value\": -112845,\n \"currency\": \"EUR\"\n },\n \"nextPayout\": {\n \"value\": 3191,\n \"currency\": \"EUR\"\n },\n \"reserve\": {\n \"value\": 0,\n \"currency\": \"EUR\"\n }\n },\n {\n \"merchantAccount\": \"MERCHANT_ACCOUNT_2\",\n \"availableFund\": {\n \"value\": 0,\n \"currency\": \"USD\"\n },\n \"reserve\": {\n \"value\": 0,\n \"currency\": \"USD\"\n },\n \"deposit\": {\n \"value\": 50000,\n \"currency\": \"USD\"\n }\n }\n }\n}\n" } } } } }, "401" : { "description" : "Unauthorized - Authentication required.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" } } } }, "403" : { "description" : "Forbidden - insufficient permissions to process the request.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" } } } }, "422" : { "description" : "Unprocessable Content - A request validation error.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" } } } } }, "x-group-parameters" : "false", "x-methodName" : "getMerchantBalancesOverview", "x-sortIndex" : 0 } }, "/balanceTransfers" : { "post" : { "tags" : [ "Balance transfers" ], "summary" : "Performs a balance transfer", "description" : "Performs a balance transfer between merchant accounts. The following conditions must be met before you can successfully transfer balances:\n* The source and destination merchant accounts must be under the same company account and legal entity.\n* The source merchant account must have sufficient funds.\n* The source and destination merchant accounts must have at least one common processing currency.\\n\\n\nWhen sending multiple API requests with the same source and destination merchant accounts, send the requests sequentially and *not* in parallel. Some requests may not be processed if the requests are sent in parallel.\n", "operationId" : "post-balanceTransfers", "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BalanceTransferRequest" }, "examples" : { "Create balance transfer" : { "summary" : "Create balance transfer", "description" : "Create balance transfer", "value" : { "amount" : { "currency" : "EUR", "value" : 3000 }, "fromMerchant" : "SOURCE_MERCHANT_ACCOUNT", "reference" : "Your reference for the balance transfer.", "toMerchant" : "DESTINATION_MERCHANT_ACCOUNT", "type" : "adjustment" } } } } }, "required" : true }, "responses" : { "200" : { "description" : "OK - The request has succeeded.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/BalanceTransferResponse" }, "examples" : { "Response code 200: balance transfer created." : { "summary" : "Response code 200: balance transfer created.", "description" : "Response code 200: balance transfer created.", "value" : { "createdAt" : "2025-10-27T07:06:15+00:00", "pspReference" : "993617895204576J" } } } } } }, "401" : { "description" : "Unauthorized", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" } } } }, "422" : { "description" : "Unprocessable Content - A request validation error.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/DefaultErrorResponseEntity" } } } } }, "x-methodName" : "createTransferBalance", "x-sortIndex" : 0 } } }, "components" : { "schemas" : { "Amount" : { "required" : [ "currency", "value" ], "type" : "object", "properties" : { "currency" : { "type" : "string", "description" : "The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes#currency-codes) of the amount." }, "value" : { "type" : "integer", "description" : "The numeric value of the amount, in [minor units](https://docs.adyen.com/development-resources/currency-codes#minor-units).", "format" : "int64" } } }, "BalanceTransferRequest" : { "required" : [ "amount", "fromMerchant", "toMerchant", "type" ], "type" : "object", "properties" : { "amount" : { "description" : "The amount of the transfer.", "$ref" : "#/components/schemas/Amount" }, "fromMerchant" : { "minLength" : 1, "type" : "string", "description" : "The unique identifier of the source merchant account from which funds are deducted." }, "reference" : { "maxLength" : 80, "minLength" : 0, "type" : "string", "description" : "A reference for the balance transfer. Maximum length: 80 characters." }, "toMerchant" : { "minLength" : 1, "type" : "string", "description" : "The unique identifier of the destination merchant account to which funds are transferred." }, "type" : { "description" : "The type of balance transfer. Possible values: **tax**, **fee**, **terminalSale**, **credit**, **debit**, and **adjustment**.", "$ref" : "#/components/schemas/BalanceTransferType" } } }, "BalanceTransferResponse" : { "required" : [ "createdAt", "pspReference" ], "type" : "object", "properties" : { "createdAt" : { "type" : "string", "description" : "The date when the balance transfer was performed.", "format" : "date-time" }, "pspReference" : { "type" : "string", "description" : "Adyen's 16-character string reference associated with the balance transfer." } } }, "BalanceTransferType" : { "type" : "string", "enum" : [ "tax", "fee", "terminalSale", "credit", "debit", "adjustment" ] }, "CompanyBalances" : { "type" : "object", "properties" : { "merchantBalancesOverview" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/MerchantBalance" } } } }, "DefaultErrorResponseEntity" : { "type" : "object", "properties" : { "detail" : { "type" : "string", "description" : "A human-readable explanation specific to this occurrence of the problem." }, "errorCode" : { "type" : "string", "description" : "Unique business error code." }, "instance" : { "type" : "string", "description" : "A URI that identifies the specific occurrence of the problem if applicable." }, "invalidFields" : { "type" : "array", "description" : "Array of fields with validation errors when applicable.", "items" : { "$ref" : "#/components/schemas/InvalidField" } }, "requestId" : { "type" : "string", "description" : "The unique reference for the request." }, "status" : { "type" : "integer", "description" : "The HTTP status code.", "format" : "int32" }, "title" : { "type" : "string", "description" : "A short, human-readable summary of the problem type." }, "type" : { "type" : "string", "description" : "A URI that identifies the validation error type. It points to human-readable documentation for the problem type." } }, "description" : "Standardized error response following RFC-7807 format", "externalDocs" : { "url" : "https://www.rfc-editor.org/rfc/rfc7807" } }, "InvalidField" : { "required" : [ "message", "name", "value" ], "type" : "object", "properties" : { "message" : { "type" : "string", "description" : "Description of the validation error." }, "name" : { "type" : "string", "description" : "The field that has an invalid value." }, "value" : { "type" : "string", "description" : "The invalid value." } } }, "MerchantBalance" : { "type" : "object", "properties" : { "availableFund" : { "$ref" : "#/components/schemas/Amount" }, "deposit" : { "$ref" : "#/components/schemas/Amount" }, "merchantAccount" : { "type" : "string" }, "nextPayout" : { "$ref" : "#/components/schemas/Amount" }, "pendingBalance" : { "$ref" : "#/components/schemas/Amount" }, "reserve" : { "$ref" : "#/components/schemas/Amount" } } } }, "securitySchemes" : { "ApiKeyAuth" : { "type" : "apiKey", "name" : "X-API-Key", "in" : "header" }, "BasicAuth" : { "type" : "http", "scheme" : "basic" } } }, "jsonSchemaDialect" : "https://spec.openapis.org/oas/3.1/dialect/base" }