mirror of
https://github.com/gcatanese/adyen-openapi.git
synced 2026-03-10 08:01:24 +00:00
269 lines
8.7 KiB
YAML
269 lines
8.7 KiB
YAML
openapi: 3.1.0
|
|
servers:
|
|
- url: https://pal-test.adyen.com/pal/servlet/BalanceControl/v1
|
|
info:
|
|
version: '1'
|
|
x-publicVersion: true
|
|
title: Adyen Balance Control API
|
|
description: 'The Balance Control API lets you transfer funds between merchant accounts
|
|
that belong to the same legal entity and are under the same company account.
|
|
|
|
|
|
## Authentication
|
|
|
|
To connect to the Balance Control API, you must authenticate your requests with
|
|
an [API key or basic auth username and password](https://docs.adyen.com/development-resources/api-authentication).
|
|
To learn how you can generate these, see [API credentials](https://docs.adyen.com/development-resources/api-credentials).Here
|
|
is an example of authenticating a request with an API key:
|
|
|
|
|
|
```
|
|
|
|
curl
|
|
|
|
-H "X-API-Key: Your_API_key" \
|
|
|
|
-H "Content-Type: application/json" \
|
|
|
|
...
|
|
|
|
```
|
|
|
|
Note that when going live, you need to generate API credentials to access the
|
|
[live endpoints](https://docs.adyen.com/development-resources/live-endpoints).
|
|
|
|
|
|
## Versioning
|
|
|
|
The Balance Control 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://pal-test.adyen.com/pal/servlet/BalanceControl/v1/balanceTransfer
|
|
|
|
```
|
|
|
|
'
|
|
x-timestamp: '2022-11-24T10:17:10Z'
|
|
termsOfService: https://www.adyen.com/legal/terms-and-conditions
|
|
contact:
|
|
name: Adyen Developer Experience team
|
|
url: https://www.adyen.help/hc/en-us/community/topics
|
|
email: developer-experience@adyen.com
|
|
x-groups:
|
|
- General
|
|
tags:
|
|
- name: General
|
|
paths:
|
|
/balanceTransfer:
|
|
post:
|
|
tags:
|
|
- General
|
|
summary: Start a balance transfer
|
|
description: 'Starts a balance transfer request between merchant accounts. The
|
|
following conditions must be met before you can successfully transfer balances:
|
|
|
|
|
|
* The source and destination merchant accounts must be under the same company
|
|
account and legal entity.
|
|
|
|
|
|
* The source merchant account must have sufficient funds.
|
|
|
|
|
|
* The source and destination merchant accounts must have at least one common
|
|
processing currency.
|
|
|
|
|
|
When 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.
|
|
|
|
'
|
|
operationId: post-balanceTransfer
|
|
x-groupName: General
|
|
x-sortIndex: 0
|
|
x-methodName: startBalanceTransfer
|
|
security:
|
|
- BasicAuth: []
|
|
- ApiKeyAuth: []
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
examples:
|
|
post-balance-transfer:
|
|
$ref: '#/components/examples/post-balanceTransfer-post-balance-transfer'
|
|
schema:
|
|
$ref: '#/components/schemas/BalanceTransferRequest'
|
|
responses:
|
|
'200':
|
|
content:
|
|
application/json:
|
|
examples:
|
|
post-balance-transfer:
|
|
$ref: '#/components/examples/post-balanceTransfer-post-balance-transfer-200'
|
|
schema:
|
|
$ref: '#/components/schemas/BalanceTransferResponse'
|
|
description: OK - the request has succeeded.
|
|
components:
|
|
schemas:
|
|
Amount:
|
|
properties:
|
|
currency:
|
|
description: The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes).
|
|
maxLength: 3
|
|
minLength: 3
|
|
type: string
|
|
value:
|
|
description: The amount of the transaction, in [minor units](https://docs.adyen.com/development-resources/currency-codes).
|
|
format: int64
|
|
type: integer
|
|
required:
|
|
- value
|
|
- currency
|
|
BalanceTransferRequest:
|
|
properties:
|
|
amount:
|
|
description: The amount of the transfer in [minor units](https://docs.adyen.com/development-resources/currency-codes).
|
|
$ref: '#/components/schemas/Amount'
|
|
description:
|
|
description: A human-readable description for the transfer. You can use
|
|
alphanumeric characters and hyphens. We recommend sending a maximum of
|
|
140 characters, otherwise the description may be truncated.
|
|
maxLength: 140
|
|
type: string
|
|
fromMerchant:
|
|
description: The unique identifier of the source merchant account from which
|
|
funds are deducted.
|
|
type: string
|
|
reference:
|
|
description: 'A reference for the balance transfer. If you don''t provide
|
|
this in the request, Adyen generates a unique reference.
|
|
|
|
Maximum length: 80 characters.'
|
|
maxLength: 80
|
|
type: string
|
|
toMerchant:
|
|
description: The unique identifier of the destination merchant account from
|
|
which funds are transferred.
|
|
type: string
|
|
type:
|
|
description: 'The type of balance transfer. Possible values: **tax**, **fee**,
|
|
**terminalSale**, **credit**, **debit**, and **adjustment**.'
|
|
enum:
|
|
- tax
|
|
- fee
|
|
- terminalSale
|
|
- credit
|
|
- debit
|
|
- adjustment
|
|
type: string
|
|
required:
|
|
- amount
|
|
- fromMerchant
|
|
- toMerchant
|
|
- type
|
|
BalanceTransferResponse:
|
|
properties:
|
|
amount:
|
|
description: The amount of the transfer in [minor units](https://docs.adyen.com/development-resources/currency-codes).
|
|
$ref: '#/components/schemas/Amount'
|
|
createdAt:
|
|
description: The date when the balance transfer was requested.
|
|
format: date-time
|
|
type: string
|
|
description:
|
|
description: A human-readable description for the transfer. You can use
|
|
alphanumeric characters and hyphens. We recommend sending a maximum of
|
|
140 characters, otherwise the description may be truncated.
|
|
maxLength: 140
|
|
type: string
|
|
fromMerchant:
|
|
description: The unique identifier of the source merchant account from which
|
|
funds are deducted.
|
|
type: string
|
|
pspReference:
|
|
description: Adyen's 16-character string reference associated with the balance
|
|
transfer.
|
|
type: string
|
|
reference:
|
|
description: 'A reference for the balance transfer. If you don''t provide
|
|
this in the request, Adyen generates a unique reference.
|
|
|
|
Maximum length: 80 characters.'
|
|
maxLength: 80
|
|
type: string
|
|
status:
|
|
description: 'The status of the balance transfer. Possible values: **transferred**,
|
|
**failed**, **error**, and **notEnoughBalance**.'
|
|
enum:
|
|
- error
|
|
- failed
|
|
- notEnoughBalance
|
|
- transferred
|
|
type: string
|
|
toMerchant:
|
|
description: The unique identifier of the destination merchant account from
|
|
which funds are transferred.
|
|
type: string
|
|
type:
|
|
description: 'The type of balance transfer. Possible values: **tax**, **fee**,
|
|
**terminalSale**, **credit**, **debit**, and **adjustment**.'
|
|
enum:
|
|
- tax
|
|
- fee
|
|
- terminalSale
|
|
- credit
|
|
- debit
|
|
- adjustment
|
|
type: string
|
|
required:
|
|
- amount
|
|
- fromMerchant
|
|
- toMerchant
|
|
- type
|
|
- pspReference
|
|
- status
|
|
- createdAt
|
|
securitySchemes:
|
|
ApiKeyAuth:
|
|
in: header
|
|
name: X-API-Key
|
|
type: apiKey
|
|
BasicAuth:
|
|
scheme: basic
|
|
type: http
|
|
examples:
|
|
post-balanceTransfer-post-balance-transfer:
|
|
summary: Transfer balances between merchant accounts
|
|
description: Example request for transferring balance between merchant accounts
|
|
value:
|
|
amount:
|
|
value: 50000
|
|
currency: EUR
|
|
description: Your description for the transfer
|
|
fromMerchant: MerchantAccount_NL
|
|
toMerchant: MerchantAccount_DE
|
|
type: debit
|
|
post-balanceTransfer-post-balance-transfer-200:
|
|
summary: Transfer balances between merchant accounts
|
|
description: Example response for transferring balance between merchant accounts
|
|
value:
|
|
amount:
|
|
value: 50000
|
|
currency: EUR
|
|
createdAt: '2022-01-24T14:59:11+01:00'
|
|
description: Your description for the transfer
|
|
fromMerchant: MerchantAccount_NL
|
|
toMerchant: MerchantAccount_DE
|
|
type: debit
|
|
reference: Unique reference for the transfer
|
|
pspReference: '8816080397613514'
|
|
status: transferred
|