spec release

This commit is contained in:
Adyen Automation
2023-09-27 20:30:00 +02:00
parent d980b01e92
commit 10b4758e3d
10 changed files with 995 additions and 377 deletions

View File

@@ -9,7 +9,7 @@
"version" : "3",
"x-publicVersion" : true,
"title" : "Transfers API",
"description" : "This API provides endpoints that you can use to transfer funds, whether when [paying out to a transfer instrument](https://docs.adyen.com/marketplaces-and-platforms/payout-to-users/on-demand-payouts), [sending funds to third parties](https://docs.adyen.com/marketplaces-and-platforms/business-accounts/send-receive-funds) for users with business bank accounts, or to [request a payout for a grant offer](https://docs.adyen.com/marketplaces-and-platforms/capital). The API also supports use cases for [getting transactions for business bank accounts](https://docs.adyen.com/marketplaces-and-platforms/business-accounts/transactions-api) and getting [grants and its outstanding balances](https://docs.adyen.com/marketplaces-and-platforms/capital#get-balances). .\n\n## Authentication\nYour Adyen contact will provide your API credential and an API key. To connect to the 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: YOUR_API_KEY\" \\\n...\n```\n\nAlternatively, you can use the username and password to connect to the API using basic authentication. For example:\n\n```\ncurl\n-H \"Content-Type: application/json\" \\\n-U \"ws@BalancePlatform.YOUR_BALANCE_PLATFORM\":\"YOUR_WS_PASSWORD\" \\\n...\n```\n## Roles and permissions\nTo use the Transfers API, you need an additional role for your API credential. Transfers must also be enabled for the source balance account. Your Adyen contact will set up the roles and permissions for you.\n## Versioning\nThe Transfers API supports [versioning](https://docs.adyen.com/development-resources/versioning) using a version suffix in the endpoint URL. This suffix has the following format: \"vXX\", where XX is the version number.\n\nFor example:\n```\nhttps://balanceplatform-api-test.adyen.com/btl/v3/transfers\n```\n## Going live\nWhen going live, your Adyen contact will provide your API credential for the live environment. You can then use the username and password to send requests to `https://balanceplatform-api-live.adyen.com/btl/v3`.\n\n",
"description" : ">Versions 1 and 2 of the Transfers API are deprecated. If you are just starting your implementation, use the latest version.\n\nThis API provides endpoints that you can use to transfer funds, whether when [paying out to a transfer instrument](https://docs.adyen.com/marketplaces-and-platforms/payout-to-users/on-demand-payouts), [sending funds to third parties](https://docs.adyen.com/marketplaces-and-platforms/business-accounts/send-receive-funds) for users with business bank accounts, or to [request a payout for a grant offer](https://docs.adyen.com/marketplaces-and-platforms/capital). The API also supports use cases for [getting transactions for business bank accounts](https://docs.adyen.com/marketplaces-and-platforms/business-accounts/transactions-api) and getting [grants and its outstanding balances](https://docs.adyen.com/marketplaces-and-platforms/capital#get-balances). .\n\n## Authentication\nYour Adyen contact will provide your API credential and an API key. To connect to the 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: YOUR_API_KEY\" \\\n...\n```\n\nAlternatively, you can use the username and password to connect to the API using basic authentication. For example:\n\n```\ncurl\n-H \"Content-Type: application/json\" \\\n-U \"ws@BalancePlatform.YOUR_BALANCE_PLATFORM\":\"YOUR_WS_PASSWORD\" \\\n...\n```\n## Roles and permissions\nTo use the Transfers API, you need an additional role for your API credential. Transfers must also be enabled for the source balance account. Your Adyen contact will set up the roles and permissions for you.\n## Versioning\nThe Transfers API supports [versioning](https://docs.adyen.com/development-resources/versioning) using a version suffix in the endpoint URL. This suffix has the following format: \"vXX\", where XX is the version number.\n\nFor example:\n```\nhttps://balanceplatform-api-test.adyen.com/btl/v3/transfers\n```\n## Going live\nWhen going live, your Adyen contact will provide your API credential for the live environment. You can then use the username and password to send requests to `https://balanceplatform-api-live.adyen.com/btl/v3`.\n\n",
"termsOfService" : "https://www.adyen.com/legal/terms-and-conditions",
"contact" : {
"name" : "Adyen Developer Experience team",
@@ -366,7 +366,7 @@
"Transactions"
],
"summary" : "Get all transactions",
"description" : "Returns all transactions related to a balance account with a payment instrument of type **bankAccount**.\n\nThis endpoint supports cursor-based pagination. The response returns the first page of results, and returns links to the next page when applicable. You can use the links to page through the results. The response also returns links to the previous page when applicable.\n\nProvide either `balanceAccountId`, `accountHolderId`, or `balancePlatform` when using this endpoint.",
"description" : ">Versions 1 and 2 of the Transfers API are deprecated. If you are just starting your implementation, use the latest version.\n\nReturns all the transactions related to a balance account, account holder, or balance platform.\n\nWhen making this request, you must include at least one of the following:\n- `balanceAccountId`\n- `accountHolderId`\n- `balancePlatform`.\n\nThis endpoint supports cursor-based pagination. The response returns the first page of results, and returns links to the next and previous pages when applicable. You can use the links to page through the results.\n\n",
"x-addedInVersion" : "1",
"operationId" : "get-transactions",
"x-groupName" : "Transactions",
@@ -384,7 +384,7 @@
],
"parameters" : [
{
"description" : "Unique identifier of the [balance platform](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/balancePlatforms/{id}__queryParam_id).",
"description" : "The unique identifier of the [balance platform](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/balancePlatforms/{id}__queryParam_id).\n\nRequired if you don't provide a `balanceAccountId` or `accountHolderId`.",
"name" : "balancePlatform",
"in" : "query",
"required" : false,
@@ -393,7 +393,7 @@
}
},
{
"description" : "Unique identifier of the [payment instrument](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/paymentInstruments/_id_).",
"description" : "The unique identifier of the [payment instrument](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/paymentInstruments/_id_).\n\nTo use this parameter, you must also provide a `balanceAccountId`, `accountHolderId`, or `balancePlatform`.\n\nThe `paymentInstrumentId` must be related to the `balanceAccountId` or `accountHolderId` that you provide.",
"name" : "paymentInstrumentId",
"in" : "query",
"required" : false,
@@ -402,7 +402,7 @@
}
},
{
"description" : "Unique identifier of the [account holder](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/accountHolders/{id}__queryParam_id).",
"description" : "The unique identifier of the [account holder](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/accountHolders/{id}__queryParam_id).\n\nRequired if you don't provide a `balanceAccountId` or `balancePlatform`.\n\nIf you provide a `balanceAccountId`, the `accountHolderId` must be related to the `balanceAccountId`.",
"name" : "accountHolderId",
"in" : "query",
"required" : false,
@@ -411,7 +411,7 @@
}
},
{
"description" : "Unique identifier of the [balance account](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/balanceAccounts/{id}__queryParam_id).",
"description" : "The unique identifier of the [balance account](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/balanceAccounts/{id}__queryParam_id).\n\nRequired if you don't provide an `accountHolderId` or `balancePlatform`.\n\nIf you provide an `accountHolderId`, the `balanceAccountId` must be related to the `accountHolderId`.",
"name" : "balanceAccountId",
"in" : "query",
"required" : false,
@@ -524,7 +524,7 @@
"Transactions"
],
"summary" : "Get a transaction",
"description" : "Returns a transaction.",
"description" : ">Versions 1 and 2 of the Transfers API are deprecated. If you are just starting your implementation, use the latest version.\n\nReturns a transaction.",
"x-addedInVersion" : "1",
"operationId" : "get-transactions-id",
"x-groupName" : "Transactions",
@@ -561,7 +561,7 @@
}
},
"schema" : {
"$ref" : "#/components/schemas/Transaction"
"$ref" : "#/components/schemas/TransactionData"
}
}
},
@@ -616,7 +616,7 @@
"Transfers"
],
"summary" : "Transfer funds",
"description" : "Starts a request to transfer funds to [balance accounts](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts), [transfer instruments](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments), or third-party bank accounts. Adyen sends the outcome of the transfer request through webhooks.\n\nTo use this endpoint, you need an additional role for your API credential and transfers must be enabled for the source balance account. Your Adyen contact will set these up for you.",
"description" : ">Versions 1 and 2 of the Transfers API are deprecated. If you are just starting your implementation, use the latest version.\n\nStarts a request to transfer funds to [balance accounts](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts), [transfer instruments](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments), or third-party bank accounts. Adyen sends the outcome of the transfer request through webhooks.\n\nTo use this endpoint, you need an additional role for your API credential and transfers must be enabled for the source balance account. Your Adyen contact will set these up for you.",
"x-addedInVersion" : "2",
"operationId" : "post-transfers",
"x-groupName" : "Transfers",
@@ -658,6 +658,17 @@
}
}
},
"parameters" : [
{
"description" : "Header for authenticating through SCA",
"example" : "SCA realm=\"Transfer\" auth-param1=\"eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNl...\"",
"name" : "WWW-Authenticate",
"in" : "header",
"schema" : {
"type" : "string"
}
}
],
"responses" : {
"200" : {
"content" : {
@@ -700,11 +711,16 @@
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/RestServiceError"
"$ref" : "#/components/schemas/ServiceError"
}
}
},
"description" : "Unauthorized - authentication required."
"description" : "Unauthorized - authentication required.",
"headers" : {
"auth-param1" : {
"$ref" : "#/components/headers/auth-param1"
}
}
},
"403" : {
"content" : {
@@ -1245,15 +1261,15 @@
"additionalProperties" : false,
"properties" : {
"accountNumber" : {
"description" : "The 6- to 19-character bank account number (alphanumeric), without separators or whitespace.",
"maxLength" : 19,
"minLength" : 6,
"description" : "The 9- to 12-character bank account number (alphanumeric), without separators or whitespace. Starts with the 3-digit branch code.",
"maxLength" : 12,
"minLength" : 9,
"type" : "string"
},
"bankCode" : {
"description" : "The 6-digit bank code including the 3-digit bank code and 3-digit branch code, without separators or whitespace.",
"maxLength" : 6,
"minLength" : 6,
"clearingCode" : {
"description" : "The 3-digit clearing code, without separators or whitespace.",
"maxLength" : 3,
"minLength" : 3,
"type" : "string"
},
"type" : {
@@ -1268,7 +1284,7 @@
"required" : [
"type",
"accountNumber",
"bankCode"
"clearingCode"
],
"type" : "object"
},
@@ -1388,6 +1404,10 @@
},
"MerchantData" : {
"properties" : {
"acquirerId" : {
"description" : "The unique identifier of the merchant's acquirer.",
"type" : "string"
},
"mcc" : {
"description" : "The merchant category code.",
"type" : "string"
@@ -1435,21 +1455,9 @@
"additionalProperties" : false,
"properties" : {
"accountNumber" : {
"description" : "The 7-digit bank account number, without separators or whitespace.",
"maxLength" : 7,
"minLength" : 7,
"type" : "string"
},
"accountSuffix" : {
"description" : "The 2- to 3-digit account suffix, without separators or whitespace.",
"maxLength" : 3,
"minLength" : 2,
"type" : "string"
},
"bankCode" : {
"description" : "The 6-digit bank code including the 2-digit bank code and 4-digit branch code, without separators or whitespace.",
"maxLength" : 6,
"minLength" : 6,
"description" : "The 15-16 digit bank account number. The first 2 digits are the bank number, the next 4 digits are the branch number, the next 7 digits are the account number, and the final 2-3 digits are the suffix.",
"maxLength" : 16,
"minLength" : 15,
"type" : "string"
},
"type" : {
@@ -1463,9 +1471,7 @@
},
"required" : [
"type",
"accountNumber",
"accountSuffix",
"bankCode"
"accountNumber"
],
"type" : "object"
},
@@ -1790,6 +1796,32 @@
],
"type" : "object"
},
"ServiceError" : {
"properties" : {
"errorCode" : {
"description" : "The error code mapped to the error message.",
"type" : "string"
},
"errorType" : {
"description" : "The category of the error.",
"type" : "string"
},
"message" : {
"description" : "A short explanation of the issue.",
"type" : "string"
},
"pspReference" : {
"description" : "The PSP reference of the payment.",
"type" : "string"
},
"status" : {
"description" : "The HTTP response status.",
"format" : "int32",
"type" : "integer"
}
},
"type" : "object"
},
"ThresholdRepayment" : {
"properties" : {
"amount" : {
@@ -1802,7 +1834,7 @@
],
"type" : "object"
},
"Transaction" : {
"TransactionData" : {
"properties" : {
"accountHolderId" : {
"x-addedInVersion" : "1",
@@ -1811,7 +1843,7 @@
},
"amount" : {
"x-addedInVersion" : "1",
"description" : "The amount.",
"description" : "Contains information about the amount of the transaction.",
"$ref" : "#/components/schemas/Amount"
},
"balanceAccountId" : {
@@ -1821,12 +1853,12 @@
},
"balancePlatform" : {
"x-addedInVersion" : "1",
"description" : "Unique identifier of the balance platform.",
"description" : "The unique identifier of the balance platform.",
"type" : "string"
},
"bookingDate" : {
"x-addedInVersion" : "1",
"description" : "The date the transaction was booked to the balance account.",
"description" : "The date the transaction was booked into the balance account.",
"format" : "date-time",
"type" : "string"
},
@@ -1840,7 +1872,8 @@
"internal",
"issuedCard",
"migration",
"platformPayment"
"platformPayment",
"upgrade"
],
"type" : "string"
},
@@ -1867,12 +1900,12 @@
},
"eventId" : {
"x-addedInVersion" : "3",
"description" : "The PSP reference in the journal.",
"description" : "The PSP reference of the transaction in the journal.",
"type" : "string"
},
"id" : {
"x-addedInVersion" : "1",
"description" : "Unique identifier of the transaction.",
"description" : "The unique identifier of the transaction.",
"type" : "string"
},
"instructedAmount" : {
@@ -1882,7 +1915,7 @@
},
"paymentInstrumentId" : {
"x-addedInVersion" : "1",
"description" : "Unique identifier of the payment instrument that was used for the transaction.",
"description" : "The unique identifier of the payment instrument that was used for the transaction.",
"type" : "string"
},
"reference" : {
@@ -1916,13 +1949,19 @@
"atmWithdrawal",
"atmWithdrawalReversal",
"balanceAdjustment",
"balanceMigration",
"balanceRollover",
"bankTransfer",
"capture",
"captureReversal",
"cardTransfer",
"cashOutFee",
"cashOutFunding",
"cashOutInstruction",
"chargeback",
"chargebackCorrection",
"chargebackReversal",
"chargebackReversalCorrection",
"depositCorrection",
"fee",
"grant",
@@ -1939,7 +1978,8 @@
"refundReversal",
"repayment",
"reserveAdjustment",
"secondChargeback"
"secondChargeback",
"secondChargebackCorrection"
],
"type" : "string"
},
@@ -1974,7 +2014,7 @@
"data" : {
"description" : "Contains the transactions that match the query parameters.",
"items" : {
"$ref" : "#/components/schemas/Transaction"
"$ref" : "#/components/schemas/TransactionData"
},
"type" : "array"
}
@@ -2008,7 +2048,7 @@
},
"category" : {
"x-addedInVersion" : "3",
"description" : "The type of transfer.\n\nPossible values:\n\n - **bank**: Transfer to a [transfer instrument](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments__resParam_id) or a bank account.\n\n- **internal**: Transfer to another [balance account](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts__resParam_id) within your platform.\n\n- **issuedCard**: Transfer initiated by a Adyen-issued card.\n\n- **platformPayment**: Fund movements related to payments that are acquired for your users.",
"description" : "The category of transfer.\n\nPossible values:\n\n - **bank**: Transfer to a [transfer instrument](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments__resParam_id) or a bank account.\n\n- **internal**: Transfer to another [balance account](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts__resParam_id) within your platform.\n\n- **issuedCard**: Transfer initiated by a Adyen-issued card.\n\n- **platformPayment**: Fund movements related to payments that are acquired for your users.",
"enum" : [
"bank",
"internal",
@@ -2061,7 +2101,7 @@
},
"priority" : {
"x-addedInVersion" : "3",
"description" : "The priority for the bank transfer. This sets the speed at which the transfer is sent and the fees that you have to pay. Required for transfers with `category` **bank**.\n\nPossible values:\n\n* **regular**: For normal, low-value transactions.\n\n* **fast**: Faster way to transfer funds but has higher fees. Recommended for high-priority, low-value transactions.\n\n* **wire**: Fastest way to transfer funds but has the highest fees. Recommended for high-priority, high-value transactions.\n\n* **instant**: Instant way to transfer funds in [SEPA countries](https://www.ecb.europa.eu/paym/integration/retail/sepa/html/index.en.html).\n\n* **crossBorder**: High-value transfer to a recipient in a different country.\n\n* **internal**: Transfer to an Adyen-issued business bank account (by bank account number/IBAN).",
"description" : "The priority for the bank transfer. This sets the speed at which the transfer is sent and the fees that you have to pay. Required for transfers with `category` **bank**.\n\nPossible values:\n\n* **regular**: For normal, low-value transactions.\n\n* **fast**: Faster way to transfer funds but has higher fees. Recommended for high-priority, low-value transactions.\n\n* **wire**: Fastest way to transfer funds but has the highest fees. Recommended for high-priority, high-value transactions.\n\n* **instant**: Instant way to transfer funds in [SEPA countries](https://www.ecb.europa.eu/paym/integration/retail/sepa/html/index.en.html).\n\n* **crossBorder**: High-value transfer to a recipient in a different country.\n\n* **internal**: Transfer to an Adyen-issued business bank account (by bank account number/IBAN). This will be removed in v4 and replaced with a new field.",
"enum" : [
"crossBorder",
"directDebit",
@@ -2079,16 +2119,19 @@
"enum" : [
"amountLimitExceeded",
"approved",
"balanceAccountTemporarilyBlockedByTransactionRule",
"counterpartyAccountBlocked",
"counterpartyAccountClosed",
"counterpartyAccountNotFound",
"counterpartyAddressRequired",
"counterpartyBankTimedOut",
"counterpartyBankUnavailable",
"declinedByTransactionRule",
"error",
"notEnoughBalance",
"refusedByCounterpartyBank",
"routeNotFound",
"scaFailed",
"unknown"
],
"type" : "string"
@@ -2158,10 +2201,6 @@
"merchantPayinReversedPending",
"miscCost",
"miscCostPending",
"operationAuthorized",
"operationBooked",
"operationPending",
"operationReceived",
"paymentCost",
"paymentCostPending",
"received",
@@ -2222,10 +2261,6 @@
"description" : "Your description for the transfer. It is used by most banks as the transfer description. We recommend sending a maximum of 140 characters, otherwise the description may be truncated.\n\nSupported characters: **[a-z] [A-Z] [0-9] / - ?** **: ( ) . , ' + Space**\n\nSupported characters for **regular** and **fast** transfers to a US counterparty: **[a-z] [A-Z] [0-9] & $ % # @** **~ = + - _ ' \" ! ?**",
"type" : "string"
},
"id" : {
"description" : "The ID of the resource.",
"type" : "string"
},
"paymentInstrumentId" : {
"description" : "The unique identifier of the source [payment instrument](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/paymentInstruments__resParam_id).",
"type" : "string"
@@ -2395,6 +2430,14 @@
"type" : "http"
}
},
"headers" : {
"auth-param1" : {
"description" : "Base64-encoded blob of data. You will need auth-param1 when authenticating your user using the SDK.",
"schema" : {
"type" : "string"
}
}
},
"examples" : {
"get-transactions-id-success-200" : {
"summary" : "Response code - 200 OK",