Download OpenAPI specification:Download
The Payaut API is organised around REST. The APIs have predictable resource-oriented URLs,
accept form-encoded request bodies, return JSON-encoded responses, and use standard HTTP
response codes, authentication, and verbs.
You can use the Payaut API in Sandbox mode, which does not affect your Live data.
For all api call, the following base urls need to be used according to the environment.
- Sandbox: sandbox.payaut.com/api
- Live: api.payaut.com/api
In order to exchange messages securely it’s necessary to grant your servers access to our domains:
- Sandbox: sandbox.payaut.com
- Live: api.payaut.com
Every connection to the domains above should target port 443 (https). If this is not possible, please contact us, so we can provide you with a list of IPs that should be released.
In our API sellers on your platform are called ‘accountHolders’. Creating an accountHolder using our API only requires a name, additional data can be added later in the process.
Once a seller account is created and it has a virtual account, funds can be allocated to the virtual account. Only after the KYC (Know Your Customer) process has been completed successfully payouts can be initiated.
You can POST and PATCH accountHolders until all data is complete.
How to trigger the KYC check?
KYC checks get automatically triggered when all the required data are provided. To check the status of the request, check the KYC status field, which is accompanied by a message, that indicates the fields that are missing in order to trigger the KYC check.
We do have a webhook implemented to get the KYC status. You can also use a GET call in order to check if the screening (KYC) has been approved or if another PATCH is required with additional data.
Fields that retrigger KYC
When important data get updated (through a PATCH call), the KYC status of the account holder goes to IN_PROGRESS and a KYC check needs to be conducted again.
For Individuals the important fields are:
Retrieves a list of existing account holders. The result is an object containing fields used for paging along side with the account holders itself.
_fragments | string Fragments are used to access detailed data about an account holder. The following fragments are supported.
|
_pageNumber | integer <int32> The specific page number to retrieve. The first page is on _pageNumber=0 |
_pageSize | integer <int32> The number of results to retrieve in a page. Max results is 500 |
_sort | string The request sorting of the page elements. Possible values are "asc", "desc". |
{- "elements": [
- {
- "code": "FD5CM3gDntAdnVGnW3xfV7n3fatgAaG7vYS",
- "createdAt": "2022-02-03",
- "description": "John Doe",
- "displayName": "John Doe",
- "extRef": "MERCHANTX_User123456",
- "accounts": [
- {
- "accountType": "DEFAULT",
- "balances": [
- {
- "confirmed": 12000,
- "currency": "EUR",
- "payout": 18400,
- "pending": 3500
}
], - "code": "FD5CMUdtxdxnaWWvGxAV7aUgx3DK6VKDddc",
- "displayName": "Virtual account for user John Doe",
- "extRef": "JDoe_virtual_account"
}
], - "externalAccounts": [
- {
- "extRef": "user1234_external_account",
- "displayName": "IBAN for user1234",
- "currency": "EUR",
- "statement": {
- "issuedAt": "2022-05-04",
- "data": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII"
}, - "accountType": "IBAN",
- "accountNumber": "NL60INGB0008551819"
}
], - "legalEntity": {
- "address": {
- "addition": "II",
- "city": "Heusweiler",
- "country": "DEU",
- "houseNumber": "19",
- "street": "Richard-Wagner-Str.",
- "zipcode": "66265"
}, - "firstName": "John",
- "lastName": "Doe",
- "email": "john.doe@merchant.com",
- "kycStatus": "MISSING_DATA",
- "kycMessage": "Missing data for the following fields city, country",
- "legalName": "John Doe",
- "registrationNumber": 89870485,
- "phone": 31986484987,
- "taxNumber": "ESB49845783",
- "legalForm": "organization",
- "type": "PRIVATE_COMPANY",
- "indirectControlThrough": "string"
}, - "status": {
- "code": "ACTIVE",
- "reason": "string"
}, - "tier": "LIGHT_KYC"
}
], - "pageNumber": 1,
- "pageSize": 100,
- "totalElementCount": 0
}
Creates a seller (accountHolder in our APIs). You can either choose to create a advanced account holder with all KYC required data in one go, or create a simple account holder and update it in a later stage.
It will create a virtual account by default with an extRef as {accountHolderExtRef}_virtual_account
only if if you provide extRef
for accountHolder. Otherwise extRef
for virtual account will be null.
Examples (see request samples on the right):
description | string The description of the account holder |
displayName | string The display name of the account holder name |
extRef | string An external (unique) reference for the account holder |
Array of objects (RequestExternalAccount) | |
required | object (RequestLegalEntity) |
{- "displayName": "J. Doe",
- "legalEntity": {
- "legalName": "John Doe",
- "firstName": "John",
- "lastName": "Doe",
- "legalForm": "individual"
}, - "externalAccounts": [
- {
- "displayName": "IBAN for J. Doe",
- "currency": "EUR",
- "accountType": "IBAN",
- "accountNumber": "NL91ABNA0417164300"
}
]
}
{- "code": "FD5CM3gDntAdnVGnW3xfV7n3fatgAaG7vYS",
- "createdAt": "2022-02-03",
- "description": "John Doe",
- "displayName": "John Doe",
- "extRef": "MERCHANTX_User123456",
- "accounts": [
- {
- "accountType": "DEFAULT",
- "balances": [
- {
- "confirmed": 12000,
- "currency": "EUR",
- "payout": 18400,
- "pending": 3500
}
], - "code": "FD5CMUdtxdxnaWWvGxAV7aUgx3DK6VKDddc",
- "displayName": "Virtual account for user John Doe",
- "extRef": "JDoe_virtual_account"
}
], - "externalAccounts": [
- {
- "extRef": "user1234_external_account",
- "displayName": "IBAN for user1234",
- "currency": "EUR",
- "statement": {
- "issuedAt": "2022-05-04",
- "data": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII"
}, - "accountType": "IBAN",
- "accountNumber": "NL60INGB0008551819"
}
], - "legalEntity": {
- "address": {
- "addition": "II",
- "city": "Heusweiler",
- "country": "DEU",
- "houseNumber": "19",
- "street": "Richard-Wagner-Str.",
- "zipcode": "66265"
}, - "firstName": "John",
- "lastName": "Doe",
- "email": "john.doe@merchant.com",
- "kycStatus": "MISSING_DATA",
- "kycMessage": "Missing data for the following fields city, country",
- "legalName": "John Doe",
- "registrationNumber": 89870485,
- "phone": 31986484987,
- "taxNumber": "ESB49845783",
- "legalForm": "organization",
- "type": "PRIVATE_COMPANY",
- "indirectControlThrough": "string"
}, - "status": {
- "code": "ACTIVE",
- "reason": "string"
}, - "tier": "LIGHT_KYC"
}
Retrieves an existing account holder. You need to provide the code that was generated and returned during the creation of this particular account holder.
accountHolderCode required | string Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48 System generated unique code used to identify and modify that account holder |
_fragments | string Fragments are used to access detailed data about an account holder. The following fragments are supported.
|
{- "code": "FD5CM3gDntAdnVGnW3xfV7n3fatgAaG7vYS",
- "createdAt": "2022-02-03",
- "description": "John Doe",
- "displayName": "John Doe",
- "extRef": "MERCHANTX_User123456",
- "accounts": [
- {
- "accountType": "DEFAULT",
- "balances": [
- {
- "confirmed": 12000,
- "currency": "EUR",
- "payout": 18400,
- "pending": 3500
}
], - "code": "FD5CMUdtxdxnaWWvGxAV7aUgx3DK6VKDddc",
- "displayName": "Virtual account for user John Doe",
- "extRef": "JDoe_virtual_account"
}
], - "externalAccounts": [
- {
- "extRef": "user1234_external_account",
- "displayName": "IBAN for user1234",
- "currency": "EUR",
- "statement": {
- "issuedAt": "2022-05-04",
- "data": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII"
}, - "accountType": "IBAN",
- "accountNumber": "NL60INGB0008551819"
}
], - "legalEntity": {
- "address": {
- "addition": "II",
- "city": "Heusweiler",
- "country": "DEU",
- "houseNumber": "19",
- "street": "Richard-Wagner-Str.",
- "zipcode": "66265"
}, - "firstName": "John",
- "lastName": "Doe",
- "email": "john.doe@merchant.com",
- "kycStatus": "MISSING_DATA",
- "kycMessage": "Missing data for the following fields city, country",
- "legalName": "John Doe",
- "registrationNumber": 89870485,
- "phone": 31986484987,
- "taxNumber": "ESB49845783",
- "legalForm": "organization",
- "type": "PRIVATE_COMPANY",
- "indirectControlThrough": "string"
}, - "status": {
- "code": "ACTIVE",
- "reason": "string"
}, - "tier": "LIGHT_KYC"
}
Updates an existing account holder. Any data not provided will be left unchanged.
accountHolderCode required | string Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48 System generated unique code used to identify and modify that account holder |
description | string The description of the account holder |
displayName | string The display name of the account holder name |
extRef | string An external (unique) reference for the account holder |
Array of objects (RequestExternalAccount) | |
required | object (RequestLegalEntity) |
{- "description": "John Doe",
- "displayName": "John Doe",
- "extRef": "MERCHANTX_User123456",
- "externalAccounts": [
- {
- "extRef": "user1234_external_account",
- "displayName": "IBAN for user1234",
- "currency": "EUR",
- "statement": {
- "issuedAt": "2022-05-04",
- "data": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII"
}, - "accountType": "IBAN",
- "accountNumber": "NL60INGB0008551819"
}
], - "legalEntity": {
- "address": {
- "addition": "II",
- "city": "Heusweiler",
- "country": "DEU",
- "houseNumber": "19",
- "street": "Richard-Wagner-Str.",
- "zipcode": "66265"
}, - "firstName": "John",
- "lastName": "Doe",
- "email": "john.doe@merchant.com",
- "legalName": "John Doe",
- "phone": 31986484987,
- "taxNumber": "ESB49845783",
- "registrationNumber": 89870485,
- "legalForm": "individual",
- "type": "PRIVATE_COMPANY",
- "indirectControlThrough": "string",
- "documents": [
- {
- "code": "string",
- "expireAt": "2019-08-24",
- "extRef": "string",
- "issuedAt": "2019-08-24",
- "issuerCountry": "string",
- "number": "string",
- "photos": [
- {
- "code": "string",
- "data": "string",
- "extRef": "string",
- "page": "FRONT"
}
], - "type": "ID"
}
]
}
}
{- "code": "FD5CM3gDntAdnVGnW3xfV7n3fatgAaG7vYS",
- "createdAt": "2022-02-03",
- "description": "John Doe",
- "displayName": "John Doe",
- "extRef": "MERCHANTX_User123456",
- "accounts": [
- {
- "accountType": "DEFAULT",
- "balances": [
- {
- "confirmed": 12000,
- "currency": "EUR",
- "payout": 18400,
- "pending": 3500
}
], - "code": "FD5CMUdtxdxnaWWvGxAV7aUgx3DK6VKDddc",
- "displayName": "Virtual account for user John Doe",
- "extRef": "JDoe_virtual_account"
}
], - "externalAccounts": [
- {
- "extRef": "user1234_external_account",
- "displayName": "IBAN for user1234",
- "currency": "EUR",
- "statement": {
- "issuedAt": "2022-05-04",
- "data": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII"
}, - "accountType": "IBAN",
- "accountNumber": "NL60INGB0008551819"
}
], - "legalEntity": {
- "address": {
- "addition": "II",
- "city": "Heusweiler",
- "country": "DEU",
- "houseNumber": "19",
- "street": "Richard-Wagner-Str.",
- "zipcode": "66265"
}, - "firstName": "John",
- "lastName": "Doe",
- "email": "john.doe@merchant.com",
- "kycStatus": "MISSING_DATA",
- "kycMessage": "Missing data for the following fields city, country",
- "legalName": "John Doe",
- "registrationNumber": 89870485,
- "phone": 31986484987,
- "taxNumber": "ESB49845783",
- "legalForm": "organization",
- "type": "PRIVATE_COMPANY",
- "indirectControlThrough": "string"
}, - "status": {
- "code": "ACTIVE",
- "reason": "string"
}, - "tier": "LIGHT_KYC"
}
Retrieves a list of existing ultimate beneficial owners
accountHolderCode required | string Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48 System generated unique code used to identify and modify that account holder |
_fragments | string Fragments are used to access detailed data about an UBO. The following fragments are supported.
|
pageNumber | integer <int32> The current page number |
pageSize | integer <int32> The amount of items to be fetched |
{- "elements": [
- {
- "legalName": "John Doe",
- "code": "FD5CM3gDntAdnVGnW3xfV7n3fatgAaG7vYS",
- "firstName": "John",
- "lastName": "Doe",
- "dateOfBirth": "2019-08-24T14:15:22Z",
- "nationality": "NLD",
- "type": "CEO",
- "extRef": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "address": {
- "addition": "II",
- "city": "Heusweiler",
- "country": "DEU",
- "houseNumber": "19",
- "street": "Richard-Wagner-Str.",
- "zipcode": "66265"
}, - "documents": [
- {
- "code": "string",
- "expireAt": "2019-08-24",
- "extRef": "string",
- "issuedAt": "2019-08-24",
- "issuerCountry": "string",
- "number": "string",
- "photos": [
- {
- "code": "string",
- "data": "string",
- "extRef": "string",
- "page": "FRONT"
}
], - "type": "ID"
}
]
}
], - "pageNumber": 1,
- "pageSize": 100,
- "totalElementCount": 0
}
Creates an ultimate beneficial owner
accountHolderCode required | string Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48 System generated unique code used to identify and modify that account holder |
legalName | string The legal name of the ultimate beneficial owner. |
firstName | string The first name of the ultimate beneficial owner. |
lastName | string The last name of the ultimate beneficial owner. |
dateOfBirth | string <date-time> |
nationality | string County code in ALPHA-3 format |
type | string Enum: "CEO" "CFO" "COO" "SHARE_HOLDER" The type of UBO |
extRef | string An external (unique) reference |
object (RAddress) | |
Array of objects (RDocumentPersonal) |
{- "legalName": "John Doe",
- "firstName": "John",
- "lastName": "Doe",
- "dateOfBirth": "2019-08-24T14:15:22Z",
- "nationality": "NLD",
- "type": "CEO",
- "extRef": "string",
- "address": {
- "addition": "II",
- "city": "Heusweiler",
- "country": "DEU",
- "houseNumber": "19",
- "street": "Richard-Wagner-Str.",
- "zipcode": "66265"
}, - "documents": [
- {
- "code": "string",
- "expireAt": "2019-08-24",
- "extRef": "string",
- "issuedAt": "2019-08-24",
- "issuerCountry": "string",
- "number": "string",
- "photos": [
- {
- "code": "string",
- "data": "string",
- "extRef": "string",
- "page": "FRONT"
}
], - "type": "ID"
}
]
}
{- "legalName": "John Doe",
- "code": "FD5CM3gDntAdnVGnW3xfV7n3fatgAaG7vYS",
- "firstName": "John",
- "lastName": "Doe",
- "dateOfBirth": "2019-08-24T14:15:22Z",
- "nationality": "NLD",
- "type": "CEO",
- "extRef": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "address": {
- "addition": "II",
- "city": "Heusweiler",
- "country": "DEU",
- "houseNumber": "19",
- "street": "Richard-Wagner-Str.",
- "zipcode": "66265"
}, - "documents": [
- {
- "code": "string",
- "expireAt": "2019-08-24",
- "extRef": "string",
- "issuedAt": "2019-08-24",
- "issuerCountry": "string",
- "number": "string",
- "photos": [
- {
- "code": "string",
- "data": "string",
- "extRef": "string",
- "page": "FRONT"
}
], - "type": "ID"
}
]
}
Retrieves an existing ultimate beneficial owner. You need to provide the code that was generated and returned during the creation of this particular ubo.
accountHolderCode required | string Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48 System generated unique code used to identify and modify that account holder |
uboCode required | string Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48 System generated unique code used to identify and modify that ultimate beneficial owner |
_fragments | string Fragments are used to access detailed data about an UBO. The following fragments are supported.
|
{- "legalName": "John Doe",
- "code": "FD5CM3gDntAdnVGnW3xfV7n3fatgAaG7vYS",
- "firstName": "John",
- "lastName": "Doe",
- "dateOfBirth": "2019-08-24T14:15:22Z",
- "nationality": "NLD",
- "type": "CEO",
- "extRef": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "address": {
- "addition": "II",
- "city": "Heusweiler",
- "country": "DEU",
- "houseNumber": "19",
- "street": "Richard-Wagner-Str.",
- "zipcode": "66265"
}, - "documents": [
- {
- "code": "string",
- "expireAt": "2019-08-24",
- "extRef": "string",
- "issuedAt": "2019-08-24",
- "issuerCountry": "string",
- "number": "string",
- "photos": [
- {
- "code": "string",
- "data": "string",
- "extRef": "string",
- "page": "FRONT"
}
], - "type": "ID"
}
]
}
Updates an existing ultimate beneficial owner. Any data not provided will be left unchanged.
accountHolderCode required | string Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48 System generated unique code used to identify and modify that account holder |
uboCode required | string Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48 System generated unique code used to identify and modify that ultimate beneficial owner |
legalName | string The legal name of the ultimate beneficial owner. |
firstName | string The first name of the ultimate beneficial owner. |
lastName | string The last name of the ultimate beneficial owner. |
dateOfBirth | string <date-time> |
nationality | string County code in ALPHA-3 format |
type | string Enum: "CEO" "CFO" "COO" "SHARE_HOLDER" The type of UBO |
extRef | string An external (unique) reference |
object (RAddress) | |
Array of objects (RDocumentPersonal) |
{- "legalName": "John Doe",
- "firstName": "John",
- "lastName": "Doe",
- "dateOfBirth": "2019-08-24T14:15:22Z",
- "nationality": "NLD",
- "type": "CEO",
- "extRef": "string",
- "address": {
- "addition": "II",
- "city": "Heusweiler",
- "country": "DEU",
- "houseNumber": "19",
- "street": "Richard-Wagner-Str.",
- "zipcode": "66265"
}, - "documents": [
- {
- "code": "string",
- "expireAt": "2019-08-24",
- "extRef": "string",
- "issuedAt": "2019-08-24",
- "issuerCountry": "string",
- "number": "string",
- "photos": [
- {
- "code": "string",
- "data": "string",
- "extRef": "string",
- "page": "FRONT"
}
], - "type": "ID"
}
]
}
{- "legalName": "John Doe",
- "code": "FD5CM3gDntAdnVGnW3xfV7n3fatgAaG7vYS",
- "firstName": "John",
- "lastName": "Doe",
- "dateOfBirth": "2019-08-24T14:15:22Z",
- "nationality": "NLD",
- "type": "CEO",
- "extRef": "string",
- "createdAt": "2019-08-24T14:15:22Z",
- "address": {
- "addition": "II",
- "city": "Heusweiler",
- "country": "DEU",
- "houseNumber": "19",
- "street": "Richard-Wagner-Str.",
- "zipcode": "66265"
}, - "documents": [
- {
- "code": "string",
- "expireAt": "2019-08-24",
- "extRef": "string",
- "issuedAt": "2019-08-24",
- "issuerCountry": "string",
- "number": "string",
- "photos": [
- {
- "code": "string",
- "data": "string",
- "extRef": "string",
- "page": "FRONT"
}
], - "type": "ID"
}
]
}
Virtual accounts are the accounts where the funds are stored within the Payaut environment. Once an accountHolder is created, it will have a virtual account by default.
Technically it is possilbe to create multiple accounts for 1 AH, but there is often no value in doing so
Get all the virtual accounts connected with one account holder, by providing the account holder code.
accountHolderCode required | string Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48 System generated unique code used to identify and modify that account holder |
_pageNumber | integer <int32> The specific page number to retrieve. The first page is on _pageNumber=0 |
_pageSize | integer <int32> The number of results to retrieve in a page. Max results is 500 |
{- "elements": [
- {
- "accountType": "DEFAULT",
- "code": "FD5CMUdtxdxnaWWvGxAV7aUgx3DK6VKDddc",
- "displayName": "Virtual account for user John Doe",
- "extRef": "JDoe_virtual_account"
}
], - "pageNumber": 0,
- "pageSize": 100,
- "totalElementCount": 454
}
Retrieves a virtual account connected with one account holder, by providing the account holder code and virtual account code.
virtualAccountCode required | string Example: FD5CKXPz12SnYschrx71GmefFJSin636Sn6t System generated unique code assigned to the virtual account |
accountHolderCode required | string Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48 System generated unique code used to identify and modify that account holder |
{- "accountType": "DEFAULT",
- "code": "FD5CMUdtxdxnaWWvGxAV7aUgx3DK6VKDddc",
- "displayName": "Virtual account for user John Doe",
- "extRef": "JDoe_virtual_account"
}
Get list of external account
accountHolderCode required | string Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48 System generated unique code used to identify and modify that account holder |
_fragments | string Fragments are used to access detailed data about an account holder. The following fragments are supported.
|
_pageNumber | integer <int32> The specific page number to retrieve. The first page is on _pageNumber=0 |
_pageSize | integer <int32> The number of results to retrieve in a page. Max results is 500 |
_sort | string The request sorting of the page elements. Possible values are "asc", "desc". |
{- "elements": [
- {
- "code": "FD5CKXQ3r8QEVM1CWjLuv72YbwNfGaVLjJg",
- "extRef": "user1234_external_account",
- "displayName": "IBAN for user1234",
- "description": "string",
- "currency": "EUR",
- "kycStatus": "MISSING_DATA",
- "kycMessage": "string",
- "selected": true,
- "acceptOtherCurrencies": false,
- "allowedOtherCurrencyCodes": [
- "string"
], - "statement": {
- "issuedAt": "2022-05-04",
- "data": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII"
}, - "accountNumber": "string",
- "accountType": "IBAN"
}
], - "pageNumber": 0,
- "pageSize": 0,
- "totalElementCount": 0
}
Create external account
accountHolderCode required | string Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48 System generated unique code used to identify and modify that account holder |
extRef | string The (unique) external reference for the external account |
displayName | string The display name of the external account |
currency | string (Currency) Value: "EUR" |
object (RDocumentBankStatement) | |
accountType | string |
accountNumber | string |
{- "extRef": "user1234_external_account",
- "displayName": "IBAN for user1234",
- "currency": "EUR",
- "statement": {
- "issuedAt": "2022-05-04",
- "data": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII"
}, - "accountType": "IBAN",
- "accountNumber": "NL60INGB0008551819"
}
{- "code": "FD5CKXQ3r8QEVM1CWjLuv72YbwNfGaVLjJg",
- "extRef": "user1234_external_account",
- "displayName": "IBAN for user1234",
- "description": "string",
- "currency": "EUR",
- "kycStatus": "MISSING_DATA",
- "kycMessage": "string",
- "selected": true,
- "acceptOtherCurrencies": false,
- "allowedOtherCurrencyCodes": [
- "string"
], - "statement": {
- "issuedAt": "2022-05-04",
- "data": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII"
}, - "accountNumber": "string",
- "accountType": "IBAN"
}
Get external account
accountHolderCode required | string Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48 System generated unique code used to identify and modify that account holder |
externalAccountCode required | string |
_fragments | string Fragments are used to access detailed data about an account holder. The following fragments are supported.
|
{- "code": "FD5CKXQ3r8QEVM1CWjLuv72YbwNfGaVLjJg",
- "extRef": "user1234_external_account",
- "displayName": "IBAN for user1234",
- "description": "string",
- "currency": "EUR",
- "kycStatus": "MISSING_DATA",
- "kycMessage": "string",
- "selected": true,
- "acceptOtherCurrencies": false,
- "allowedOtherCurrencyCodes": [
- "string"
], - "statement": {
- "issuedAt": "2022-05-04",
- "data": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII"
}, - "accountNumber": "string",
- "accountType": "IBAN"
}
Update external account
accountHolderCode required | string Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48 System generated unique code used to identify and modify that account holder |
externalAccountCode required | string |
extRef | string The (unique) external reference for the external account |
displayName | string The display name of the external account |
currency | string (Currency) Value: "EUR" |
object (RDocumentBankStatement) | |
accountType | string |
accountNumber | string |
{- "extRef": "user1234_external_account",
- "displayName": "IBAN for user1234",
- "currency": "EUR",
- "statement": {
- "issuedAt": "2022-05-04",
- "data": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII"
}, - "accountType": "IBAN",
- "accountNumber": "NL60INGB0008551819"
}
{- "code": "FD5CKXQ3r8QEVM1CWjLuv72YbwNfGaVLjJg",
- "extRef": "user1234_external_account",
- "displayName": "IBAN for user1234",
- "description": "string",
- "currency": "EUR",
- "kycStatus": "MISSING_DATA",
- "kycMessage": "string",
- "selected": true,
- "acceptOtherCurrencies": false,
- "allowedOtherCurrencyCodes": [
- "string"
], - "statement": {
- "issuedAt": "2022-05-04",
- "data": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII"
}, - "accountNumber": "string",
- "accountType": "IBAN"
}
Selects the active external account
accountHolderCode required | string Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48 System generated unique code used to identify and modify that account holder |
externalAccountCode required | string Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48 System generated unique code assigned to the external account |
Hosted Onboarding provides the Marketplace with the ability to generate unique URL's for their Seller's to provide KYC information to Payaut.
The Marketplace will: (1) Create a new CODE for the seller using our existing API (Account Holders) and (2) use that CODE to generate a unique URL for the Seller.
Once the Unique URL is generated, the Seller will need to open it and fill in the required information for KYC to be made.
This endpoint is used to generate a unique URL for a certain Account Holder's hosted onboarding form page.
accountHolderCode required | string |
redirectUrl | string The page to be redirected to once the form is submitted |
expirationTime | integer <int32> The time before the generated URL expires. Default is 48h (2.880 min) and maximum allowed is 2 weeks (20.160 min). Time unit is in minutes. |
page | integer <int32> The current page number |
limit | integer <int32> The amount of items to be fetched |
sort | string The data type to sort the list by |
direction | string Enum: "asc" "desc" The direction to sort in:
|
query | string Free text search for transaction(s) e.g. by pspExtRef or pspMutationExtRef |
status | string Enum: "pending_split" "pending_settlement" "reconciled" "cancelled" Filter results for a specific status, leave empty to get all results |
type | string Enum: "PAYMENT" "REFUND" "CHARGEBACK" Filter results for a specific transaction type, leave empty to get all results |
from | string <date> The from date of a transaction e.g. "2024-04-03" |
to | string <date> The to date of a transaction e.g. "2024-04-15" |
{- "items": [
- {
- "code": "FD5CKXQRpnLDsfbhtFHfY7BqvTJp8aru3WQ",
- "type": "PAYMENT",
- "status": {
- "type": "PENDING_SETTLEMENT",
- "message": "string"
}, - "sellers": [
- {
- "code": "string",
- "name": "string",
- "amount": 0
}
], - "amount": 0,
- "processor": "ADYEN",
- "method": "CARD",
- "createdAt": "2019-08-24T14:15:22Z",
- "pspExtRef": "string",
- "pspMutationExtRef": "string",
- "updatedAt": "2019-08-24T14:15:22Z"
}
], - "pagination": {
- "page": 1,
- "limit": 0,
- "total": 0
}
}
For every transaction that happens on your platform, Payaut is expecting split information. In the split, you can define how you want to split the funds between the number of accounts that belong to yourself and the sellers on your platform. For instance, you can trigger 90% of the fund to your seller and 10% to you as a marketplace.
In the request you specify which amounts are going to which accounts. We distinguish the different items contained in every transaction and we label them (product, fees, VAT,..). Then we follow these labels to assign every amount to a specific account (merchant, seller,..)
Split transactions should be created at the moment of Capture of the PSP.
Defining virtual accounts on splits
As the fund movements are based on Payaut virtual accounts, we do expect to receive the associated account holders’ virtual accounts as part of the split information. In case no virtual account is provided inside an item or it doesn’t exist, the funds will be transferred to the merchant liable virtual account.
Default split request
A basic split request is a split between your commission (label - commission) and the seller's revenue (label - product item).
Labels, add additional detail when needed
As splits get more complicated, like a split with multiple account holders and sub-items, the label field defined for a split item starts to become important since some rules on how to move funds are built on it. For example, when a DISCOUNT label is applied, our platform knows that the fund movement should be a credit from the account holder virtual account to the merchant virtual account. All labels and behavior can be found here.
Idempotence
The split API uses the extRef field as the idempotency key for both split and split items, meaning these fields must be unique for every request.
In case a request is sent with the same split extRef, the existing split will be returned and the applied changes, if any, will be discarded. When the split item extRef fields are sent duplicated, a conflict error will be thrown.
Retrieves a list of existing payment splits. The result is an object containing fields used for paging along side with the splits itself.
_asc | boolean A boolean to indicate if the results should be ordered in an ascending order or not |
_from | string <date-time> The initial date used to query. Format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX |
_orderBy | string A criteria on which the results should be ordered, e.g. column 'createdAt' |
_pageNumber | integer <int32> The specific page number to retrieve. The first page is on _pageNumber=0 |
_pageSize | integer <int32> The number of results to retrieve in a page. Max results is 500 |
_to | string <date-time> The final date used to query. Format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX |
{- "elements": [
- {
- "code": "string",
- "currency": "EUR",
- "description": "string",
- "extProcessedAt": "2019-08-24T14:15:22Z",
- "extRef": "string",
- "items": [
- {
- "accountCode": "string",
- "amount": 0,
- "code": "string",
- "description": "string",
- "extRef": "string",
- "originalExtRef": "string",
- "items": [
- { }
], - "label": "COMMISSION",
- "type": "GROUP"
}
], - "paymentMethod": "string",
- "paymentProcessor": "ADYEN",
- "pspExtRef": "string",
- "totalAmount": 0
}
], - "pageNumber": 0,
- "pageSize": 0,
- "totalElementCount": 0
}
For every transaction that happens on your platform, Payaut is expecting split information. In the split instruction you can define how you want to split the funds between the number of accounts that belong to yourself and the sellers on your platform.
code | string Payaut generates a unique identifier immediately after a split instruction is created. You do not need to include this field in the create request. |
currency required | string (Currency) Value: "EUR" |
description | string Human-readable description of the payment split (255 symbols max), e.g. order number |
extProcessedAt | string <date-time> The zoned-date-time when the payment was processed either on the platform or PSP side. Example - "2024-04-16T15:23:54+02:00" |
extRef required | string Unique reference generated by the marketplace. This needs to be unique per group in every split. The extRef should be between 4 and 64 characters |
required | Array of objects (RSplitItem) Split definitions |
paymentMethod | string The method of payment, such as VISA, MasterCard, iDEAL, PAYPAL, etc. |
paymentProcessor required | string (PaymentProcessor) Enum: "ADYEN" "CHECKOUT" "CLEARHAUS" "MOLLIE" "PAYPAL" "STRIPE" |
pspExtRef required | string The payment processor's unique identifier for the payment exactly as received from the payment processor. |
totalAmount required | integer <int64> Gross amount of the split instruction in the currency's smallest unit (this means that JPY should be multiplied by 1, BHD by 1000 and all other should be multiplied by 100 in order to get smallest unit integer value). The sum of the split definition item amounts must equal this field. |
{- "extRef": "order123",
- "totalAmount": 7000,
- "description": "order 123",
- "items": [
- {
- "type": "GROUP",
- "extRef": "order123split",
- "amount": 7000,
- "accountCode": "FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48",
- "description": "order 123 group",
- "items": [
- {
- "type": "GROUP",
- "extRef": "order123splitgroup",
- "amount": 7000,
- "description": "order 123 group",
- "items": [
- {
- "type": "ITEM",
- "label": "COMMISSION",
- "extRef": "order123commission",
- "amount": 1200,
- "description": "commission"
}, - {
- "type": "ITEM",
- "label": "PRODUCT_ITEM",
- "extRef": "order123selleramount",
- "amount": 7000,
- "description": "seller amount"
}
]
}
]
}
], - "pspExtRef": "PSP reference",
- "currency": "EUR",
- "paymentProcessor": "ADYEN",
- "paymentMethod": "iDEAL"
}
{- "code": "string",
- "currency": "EUR",
- "description": "string",
- "extProcessedAt": "2019-08-24T14:15:22Z",
- "extRef": "string",
- "items": [
- {
- "accountCode": "string",
- "amount": 0,
- "code": "string",
- "description": "string",
- "extRef": "string",
- "originalExtRef": "string",
- "items": [
- { }
], - "label": "COMMISSION",
- "type": "GROUP"
}
], - "paymentMethod": "string",
- "paymentProcessor": "ADYEN",
- "pspExtRef": "string",
- "totalAmount": 0
}
Retrieves existing payment split. The result is an object containing fields with the splits itself.
code required | string Example: FD5CM7GKttVTf7Gt7KcTVKU37fx7StTxvcc The code of the payment to get |
{- "code": "string",
- "currency": "EUR",
- "description": "string",
- "extProcessedAt": "2019-08-24T14:15:22Z",
- "extRef": "string",
- "items": [
- {
- "accountCode": "string",
- "amount": 0,
- "code": "string",
- "description": "string",
- "extRef": "string",
- "originalExtRef": "string",
- "items": [
- { }
], - "label": "COMMISSION",
- "type": "GROUP"
}
], - "paymentMethod": "string",
- "paymentProcessor": "ADYEN",
- "pspExtRef": "string",
- "totalAmount": 0
}
When a refund is triggered, both the PSP and Payaut need to be informed in order to handle a refund sufficiently. The PSP will withhold the funds from the next settlement, and Payaut will allocate the missing funds according to the split data.
Refunds are usually processed after the associated payment has already been processed or settled. If the transaction is authorised, but not captured yet by the PSP, you can cancel the split instead of sending a refund request.
You can either trigger a full refund or a partial refund. For the full refund, the full amount of money paid by the buyer is refunded back to the buyer’s account. For the partial refund, depending on the split data, funds can be distributed based on the refund split (eg. you can decide to send the full amount back to the seller, or to keep the commission and settle less, depending on the business model).
For a refund to be reconciled completely, you should provide a pspMutationExtRef to a refund split. This field should be a unique reference that will be sent to the PSP/Acquirer and shown up in the underlying PSP report. More details are described above.
Retrieves a list of existing refund splits. The result is an object containing fields used for paging along side with the refund splits itself.
_asc | boolean A boolean to indicate if the results should be ordered in an ascending order or not |
_from | string <date-time> The initial date used to query. Format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX |
_orderBy | string A criteria on which the results should be ordered, e.g. column 'createdAt' |
_pageNumber | integer <int32> The specific page number to retrieve. The first page is on _pageNumber=0 |
_pageSize | integer <int32> The number of results to retrieve in a page. Max results is 500 |
_to | string <date-time> The final date used to query. Format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX |
{- "elements": [
- {
- "code": "string",
- "description": "string",
- "extProcessedAt": "2019-08-24T14:15:22Z",
- "extRef": "string",
- "items": [
- {
- "accountCode": "string",
- "amount": 0,
- "code": "string",
- "description": "string",
- "extRef": "string",
- "originalExtRef": "string",
- "items": [
- { }
], - "label": "COMMISSION",
- "type": "GROUP"
}
], - "pspMutationExtRef": "string",
- "totalAmount": 0
}
], - "pageNumber": 0,
- "pageSize": 0,
- "totalElementCount": 0
}
Creates a full refund split request that will further be processed and affect the defined virtual account balances. The split data are gathered from the associated payment.
request
code | string Payaut generates a unique identifier immediately after a split instruction is created. You do not need to include this field in the create request. |
description | string Human-readable description of the refund split. |
extProcessedAt | string <date-time> The time at which the refund was processed on the platform or PSP side in the ISO-8601 calendar system, such as |
extRef required | string Same unique reference as the one created for the associated payment split. |
Array of objects (RSplitItem) Split items represented as a tree containing groups and sub-items. | |
pspMutationExtRef required | string Unique reference generated by the platform or by the psp/acquirer. This reference can be sent to the PSP as a “Merchant Reference” or a “metadata” field. It can also happen that the PSP/acquirer already generates a unique reference per refund (e.g. Adyen generates the “Modification Reference” field). In the end, it will show up in the PSP settlement report. |
totalAmount | integer <int64> Gross amount of the payment, in the currency's smallest unit (cents in euros, penny in pounds, etc). |
{- "extRef": "order123",
- "pspMutationExtRef": "RUJSSC",
- "totalAmount": 7000,
- "description": "Full refund of order 123"
}
{- "code": "string",
- "description": "string",
- "extProcessedAt": "2019-08-24T14:15:22Z",
- "extRef": "string",
- "items": [
- {
- "accountCode": "string",
- "amount": 0,
- "code": "string",
- "description": "string",
- "extRef": "string",
- "originalExtRef": "string",
- "items": [
- { }
], - "label": "COMMISSION",
- "type": "GROUP"
}
], - "pspMutationExtRef": "string",
- "totalAmount": 0
}
Retrieves an existing refund split. You need to provide the code that was generated and returned during the creation of this particular refund split.
code required | string The split code generated when a refund split is created |
{- "code": "string",
- "description": "string",
- "extProcessedAt": "2019-08-24T14:15:22Z",
- "extRef": "string",
- "items": [
- {
- "accountCode": "string",
- "amount": 0,
- "code": "string",
- "description": "string",
- "extRef": "string",
- "originalExtRef": "string",
- "items": [
- { }
], - "label": "COMMISSION",
- "type": "GROUP"
}
], - "pspMutationExtRef": "string",
- "totalAmount": 0
}
Cancels the split defined in the path by the its code. Assumes the caller is the one with specific Merchant and Division Codes, as specified in the headers
code required | string = 36 characters Code for the split to be cancelled |
This endpoint makes it possible to request the payout balance for a given account code. The system will return the available balance for the account minus the pending charges. Retrieves the balance for a given account, you need to provide the code that was generated and returned during the creation of this particular account.
code required | string The account code for which to request the payout balance |
{- "amounts": [
- {
- "amount": "52000",
- "currency": "EUR"
}
], - "code": "string"
}
Retrieves the list of divisions with the information like payout, confirmed, pending balances