Adyen Transfers API
This API provides endpoints that you can use to transfer funds, whether when paying out to a transfer instrument, sending funds to third parties for users with business bank accounts, or to request a payout for a grant offer.
OpenAPI Specification
openapi: 3.1.0
servers:
- url: https://balanceplatform-api-test.adyen.com/btl/v4
info:
version: '4'
x-publicVersion: true
title: Adyen Transfers API
description: >+
>Versions 1 and 2 of the Transfers API are deprecated. If you are just
starting your implementation, use the latest version.
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).
.
## Authentication
Your 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:
```
curl
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
...
```
Alternatively, you can use the username and password to connect to the API
using basic authentication. For example:
```
curl
-H "Content-Type: application/json" \
-U "[email protected]_BALANCE_PLATFORM":"YOUR_WS_PASSWORD" \
...
```
## Roles and permissions
To 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.
## Versioning
The 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.
For example:
```
https://balanceplatform-api-test.adyen.com/btl/v4/transfers
```
## Going live
When 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/v4`.
termsOfService: https://www.adyen.com/legal/terms-and-conditions
contact:
name: Adyen Developer Experience team
url: https://github.com/Adyen/adyen-openapi
tags:
- name: Grants
- name: Transactions
- name: Transfers
paths:
/grants:
get:
tags:
- Grants
summary: Adyen Get a Capital Account
description: Returns a list of grants with status and outstanding balances.
x-addedInVersion: '3'
operationId: get-grants
x-sortIndex: 2
x-methodName: getCapitalAccount
security:
- clientKey: []
- BasicAuth: []
- ApiKeyAuth: []
parameters:
- description: The counterparty account holder id.
name: counterpartyAccountHolderId
in: query
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CapitalGrants'
examples:
get-grants200Example:
summary: Default get-grants 200 response
x-microcks-default: true
value:
grants:
- example_value
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-grants400Example:
summary: Default get-grants 400 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-grants401Example:
summary: Default get-grants 401 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-grants403Example:
summary: Default get-grants 403 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Forbidden - insufficient permissions to process the request.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-grants404Example:
summary: Default get-grants 404 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Not Found - the payment was not found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-grants422Example:
summary: Default get-grants 422 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-grants500Example:
summary: Default get-grants 500 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
tags:
- Grants
summary: Adyen Request a Grant Payout
description: Requests the payout of the selected grant offer.
x-addedInVersion: '3'
operationId: post-grants
x-sortIndex: 1
x-methodName: requestGrantPayout
security:
- clientKey: []
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
requestGrant:
$ref: '#/components/examples/post-grants-requestGrant'
schema:
$ref: '#/components/schemas/CapitalGrantInfo'
responses:
'200':
content:
application/json:
examples:
requestGrant:
$ref: '#/components/examples/post-grants-requestGrant-200'
schema:
$ref: '#/components/schemas/CapitalGrant'
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
post-grants400Example:
summary: Default post-grants 400 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
post-grants401Example:
summary: Default post-grants 401 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
post-grants403Example:
summary: Default post-grants 403 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Forbidden - insufficient permissions to process the request.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
post-grants404Example:
summary: Default post-grants 404 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Not Found - the payment was not found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
post-grants422Example:
summary: Default post-grants 422 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
post-grants500Example:
summary: Default post-grants 500 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/grants/{id}:
get:
tags:
- Grants
summary: Adyen Get Grant Reference Details
description: Returns the details of a capital account specified in the path.
x-addedInVersion: '3'
operationId: get-grants-id
x-sortIndex: 3
x-methodName: getGrantReferenceDetails
security:
- clientKey: []
- BasicAuth: []
- ApiKeyAuth: []
parameters:
- description: The unique identifier of the grant.
name: id
in: path
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CapitalGrant'
examples:
get-grants-id200Example:
summary: Default get-grants-id 200 response
x-microcks-default: true
value:
amount: 1000
balances: example_value
counterparty: example_value
fee: example_value
grantAccountId: '500123'
grantOfferId: '500123'
id: '500123'
repayment: example_value
status: Pending
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-grants-id400Example:
summary: Default get-grants-id 400 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-grants-id401Example:
summary: Default get-grants-id 401 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-grants-id403Example:
summary: Default get-grants-id 403 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Forbidden - insufficient permissions to process the request.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-grants-id404Example:
summary: Default get-grants-id 404 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Not Found - the payment was not found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-grants-id422Example:
summary: Default get-grants-id 422 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-grants-id500Example:
summary: Default get-grants-id 500 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/transactions:
get:
tags:
- Transactions
summary: Adyen Get All Transactions
description: >+
>Versions 1 and 2 of the Transfers API are deprecated. If you are just
starting your implementation, use the latest version.
Returns all the transactions related to a balance account, account
holder, or balance platform.
When making this request, you must include at least one of the
following:
- `balanceAccountId`
- `accountHolderId`
- `balancePlatform`.
This 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.
x-addedInVersion: '1'
operationId: get-transactions
x-sortIndex: 1
x-methodName: getAllTransactions
security:
- clientKey: []
- BasicAuth: []
- ApiKeyAuth: []
parameters:
- description: >-
The unique identifier of the [balance
platform](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/balancePlatforms/{id}__queryParam_id).
Required if you don't provide a `balanceAccountId` or
`accountHolderId`.
name: balancePlatform
in: query
required: false
schema:
type: string
- description: >-
The unique identifier of the [payment
instrument](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/paymentInstruments/_id_).
To use this parameter, you must also provide a `balanceAccountId`,
`accountHolderId`, or `balancePlatform`.
The `paymentInstrumentId` must be related to the `balanceAccountId`
or `accountHolderId` that you provide.
name: paymentInstrumentId
in: query
required: false
schema:
type: string
- description: >-
The unique identifier of the [account
holder](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/accountHolders/{id}__queryParam_id).
Required if you don't provide a `balanceAccountId` or
`balancePlatform`.
If you provide a `balanceAccountId`, the `accountHolderId` must be
related to the `balanceAccountId`.
name: accountHolderId
in: query
required: false
schema:
type: string
- description: >-
The unique identifier of the [balance
account](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/balanceAccounts/{id}__queryParam_id).
Required if you don't provide an `accountHolderId` or
`balancePlatform`.
If you provide an `accountHolderId`, the `balanceAccountId` must be
related to the `accountHolderId`.
name: balanceAccountId
in: query
required: false
schema:
type: string
- description: The `cursor` returned in the links of the previous response.
name: cursor
in: query
required: false
schema:
type: string
- description: >-
Only include transactions that have been created on or after this
point in time. The value must be in ISO 8601 format. For example,
**2021-05-30T15:07:40Z**.
name: createdSince
in: query
required: true
schema:
format: date-time
type: string
- description: >-
Only include transactions that have been created on or before this
point in time. The value must be in ISO 8601 format. For example,
**2021-05-30T15:07:40Z**.
name: createdUntil
in: query
required: true
schema:
format: date-time
type: string
- description: >-
The number of items returned per page, maximum of 100 items. By
default, the response returns 10 items per page.
name: limit
in: query
required: false
schema:
format: int32
type: integer
responses:
'200':
content:
application/json:
examples:
success:
$ref: '#/components/examples/get-transactions-success-200'
schema:
$ref: '#/components/schemas/TransactionSearchResponse'
description: OK - the request has succeeded.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-transactions401Example:
summary: Default get-transactions 401 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-transactions403Example:
summary: Default get-transactions 403 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-transactions422Example:
summary: Default get-transactions 422 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-transactions500Example:
summary: Default get-transactions 500 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/transactions/{id}:
get:
tags:
- Transactions
summary: Adyen Get a Transaction
description: >-
>Versions 1 and 2 of the Transfers API are deprecated. If you are just
starting your implementation, use the latest version.
Returns a transaction.
x-addedInVersion: '1'
operationId: get-transactions-id
x-sortIndex: 2
x-methodName: getTransaction
security:
- clientKey: []
- BasicAuth: []
- ApiKeyAuth: []
parameters:
- description: The unique identifier of the transaction.
name: id
in: path
required: true
schema:
type: string
responses:
'200':
content:
application/json:
examples:
success:
$ref: '#/components/examples/get-transactions-id-success-200'
schema:
$ref: '#/components/schemas/Transaction'
description: OK - the request has succeeded.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-transactions-id401Example:
summary: Default get-transactions-id 401 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-transactions-id403Example:
summary: Default get-transactions-id 403 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-transactions-id422Example:
summary: Default get-transactions-id 422 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '500123'
response: example_value
status: 500
title: example_value
type: standard
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/RestServiceError'
examples:
get-transactions-id500Example:
summary: Default get-transactions-id 500 response
x-microcks-default: true
value:
detail: example_value
errorCode: CODE123
instance: example_value
invalidFields:
- example_value
requestId: '5
# --- truncated at 32 KB (115 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adyen/refs/heads/main/openapi/transfers-openapi-original.yml