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
}
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
[- {
- "name": "string",
- "code": "string",
- "balances": [
- {
- "virtualAccountType": "string",
- "virtualAccountCode": "string",
- "confirmedBalance": "string",
- "pendingBalance": "string",
- "payoutBalance": "string"
}
], - "balanceTransferEnabled": true,
- "kycTier": "LIGHT_KYC",
- "riskCategory": "LOW",
- "externalAccount": {
- "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"
}
}
]
Allows moving funds between virtual accounts on the Payaut platform. Multiple balance transfer types are supported depending on the use-case of the balance transfer.
Use of the balance transfer functionality for seller funds requires the signing of a separate contract addendum. Please contact Payaut support to enable this feature.
model
fromAccountCode required | string The (virtual) account code from which the balance transfer was sent |
toAccountCode required | string The (virtual) account code that recieved the balance transfer |
amount required | integer <int64> Amount in the currency's smallest unit (cents in euros, penny in pounds, etc). |
currency | string Default: "EUR" Enum: "USD" "AUD" "EUR" "GBP" "JPY" "SGD" "CAD" "NZD" |
idempotencyKey required | string <uuid> |
type required | string Enum: "INVOICE" "USAGE_FEE" "CORRECTION" "CHARGEBACK" "VAT" "WALLET" |
description | string Human-readable description of the balance transfer (255 symbols max) |
{- "fromAccountCode": "FD5CM7GKttVTf7Gt7KcTVKU37fx7StTxvcc",
- "toAccountCode": "FD5CMdGdJD7gUGVfTtDUU77vYtUSaa37tJ7",
- "amount": 1000,
- "currency": "EUR",
- "idempotencyKey": "f4754d35-7eaf-4338-a5ac-9d61bb1a2ff7",
- "type": "INVOICE",
- "description": "string"
}
{- "code": "FD5CKXPiCGB4aayBG1saNdtVsb3RAPiqPHz",
- "fromAccountCode": "FD5CM7GKttVTf7Gt7KcTVKU37fx7StTxvcc",
- "toAccountCode": "FD5CMdGdJD7gUGVfTtDUU77vYtUSaa37tJ7",
- "amount": 1000,
- "currency": "EUR",
- "idempotencyKey": "f4754d35-7eaf-4338-a5ac-9d61bb1a2ff7",
- "type": "INVOICE",
- "description": "string"
}
Lists all balance transfers. The returned object is a paginated list with balance transfers
_asc | boolean A boolean to indicate if the results should be ordered in an ascending order or not |
_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 |
{- "elements": [
- {
- "code": "FD5CKXPiCGB4aayBG1saNdtVsb3RAPiqPHz",
- "fromAccountCode": "FD5CM7GKttVTf7Gt7KcTVKU37fx7StTxvcc",
- "toAccountCode": "FD5CMdGdJD7gUGVfTtDUU77vYtUSaa37tJ7",
- "amount": 1000,
- "currency": "EUR",
- "idempotencyKey": "f4754d35-7eaf-4338-a5ac-9d61bb1a2ff7",
- "type": "INVOICE",
- "description": "string"
}
], - "pageNumber": 0,
- "pageSize": 20,
- "totalElementCount": 0
}
Get a single balance transfer
code required | string Example: FD5CM7GKttVTf7Gt7KcTVKU37fx7StTxvcc The code of the balance transfer to get |
{- "code": "FD5CKXPiCGB4aayBG1saNdtVsb3RAPiqPHz",
- "fromAccountCode": "FD5CM7GKttVTf7Gt7KcTVKU37fx7StTxvcc",
- "toAccountCode": "FD5CMdGdJD7gUGVfTtDUU77vYtUSaa37tJ7",
- "amount": 1000,
- "currency": "EUR",
- "idempotencyKey": "f4754d35-7eaf-4338-a5ac-9d61bb1a2ff7",
- "type": "INVOICE",
- "description": "string"
}
When an accountholder has a positive payout balance, and the accountholder is fully onboarded by Payaut (after the KYC checks), a payout can be initiated.
Payaut provides two possibilities to manage payouts: (1) Manually via the API and (2) Scheduled.
Manual payouts
Gives you the ability to manage the payout timing and the amount of the payouts yourself. It is possible to payout partial balances, at any date you would like.
Scheduled payouts
Scheduled payouts can be configured per division or seller, and will trigger the payout according to a schedule. Scheduled payouts can be configured according to the following schedule https://docs.payaut.com/docs/payouts/introduction.
Listing all payout requests. Can also be specified using filters and pagination
_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 |
_status | string Enum: "WAITING" "ACCEPTED" "RETURNED" "FAILED" "PROCESSED" "CANCELLED" Retrieve payout requests with specified status |
_to | string <date-time> The final date used to query. Format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX |
{- "elements": [
- {
- "accountCode": "FD5CMGdfT7g7VxgUvVKSJT3tc6YKgan7RWt",
- "amount": 1000,
- "code": "FD5CMGdfTBW1pWh8AZncwe2eHuu93JLxM3zY",
- "createdAt": "2022-02-03T13:12:53.10032+01:00",
- "description": "This is a test payout request",
- "externalAccountCode": "FD5CMGdfT7g56S1vx4Rq9vDEmN52G8NrWFi",
- "processAt": "2022-02-03T13:12:53.10032+01:00",
- "status": "WAITING"
}
], - "pageNumber": 0,
- "pageSize": 0,
- "totalElementCount": 0
}
To retrieve a previously created payout request you only need the code that was returned on the create post.
code required | string The code of the payout request to retrieve |
{- "accountCode": "FD5CMGdfT7g7VxgUvVKSJT3tc6YKgan7RWt",
- "amount": 1000,
- "code": "FD5CMGdfTBW1pWh8AZncwe2eHuu93JLxM3zY",
- "createdAt": "2022-02-03T13:12:53.10032+01:00",
- "description": "This is a test payout request",
- "externalAccountCode": "FD5CMGdfT7g56S1vx4Rq9vDEmN52G8NrWFi",
- "processAt": "2022-02-03T13:12:53.10032+01:00",
- "status": "WAITING"
}
Listing all payout requests. Can also be specified using filters and pagination
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 The query search parameter. This can either be a seller name, a seller id or a payout account id |
status | string Enum: "WAITING" "ACCEPTED" "RETURNED" "FAILED" "PROCESSED" "CANCELLED" Retrieve payout requests with specified status |
fromDate | string <date-time> The start of the range creationDate to show |
toDate | string <date-time> The end of the range creationDate to show |
{- "items": [
- {
- "code": "FD5CMGdfTBW1pWh8AZncwe2eHuu93JLxM3zY",
- "amount": 1000,
- "sourceCurrency": "EUR",
- "targetCurrency": "EUR",
- "seller": {
- "code": "string",
- "name": "string",
- "amount": 0
}, - "virtualAccountCode": "FD5CMGdfT7g7VxgUvVKSJT3tc6YKgan7RWt",
- "iban": 1234,
- "status": "WAITING",
- "createdAt": "2022-02-03T13:12:53.10032+01:00"
}
], - "pagination": {
- "page": 1,
- "limit": 0,
- "total": 0
}
}
The payout configuration defines how you want to payout your own commission and the accountHolders positive payout balance.
Payaut offers both manual and scheduled payouts. The default for your division and your accountHolders will be manual.
By changing the DEFAULT configuration you can enable SCHEDULED payouts for both your own commission and all your accountHolders.
Updates the default configuration. Default payout configuration is applied to every virtual account of "all accountHolders" and to your division account.
externalAccountCode | string The (external) account code of the account owner for which the payout should be transferred to. If it is not pass we will use a default one. The default external account will be the most recent one, and will be indicated as selected. |
type required | string (PayoutConfigType) Enum: "MANUAL" "SCHEDULED" Payout configuration type for the target account holder.
|
frequency | string (required for SCHEDULED type) A quartz cron expression which will dictate how often payout requests will be generated. You can use following tool: https://www.freeformatter.com/cron-expression-generator-quartz.html Hours, minutes, seconds are not taken into account so far as we do for the moment daily payouts. |
refundPeriod | integer <int32> (required for SCHEDULED type) Safety mechanism that will protect from paying out transactions (payments) that might get refunded in the coming days. Number of calendar days from the moment that payment split has been sent before paying it out. Example: Payment split received the 10/11 with a refund period of a week (7 days) -> Money kept internally in case of a refund coming in. Paid out on the 17/11. |
minimumAmount | integer <int32> Safety mechanism that will protect from paying out transactions (payments) with the balance lower than minimum amount. |
{- "type": "SCHEDULED",
- "frequency": "0 0 0 ? * WED *",
- "refundPeriod": 7
}
{- "externalAccountCode": "string",
- "type": "MANUAL",
- "frequency": "string",
- "refundPeriod": 0,
- "minimumAmount": 0
}
Updates the division configuration. Overrides the default configuration if it is set-up.
externalAccountCode | string The (external) account code of the account owner for which the payout should be transferred to. If it is not pass we will use a default one. The default external account will be the most recent one, and will be indicated as selected. |
type required | string (PayoutConfigType) Enum: "MANUAL" "SCHEDULED" Payout configuration type for the target account holder.
|
frequency | string (required for SCHEDULED type) A quartz cron expression which will dictate how often payout requests will be generated. You can use following tool: https://www.freeformatter.com/cron-expression-generator-quartz.html Hours, minutes, seconds are not taken into account so far as we do for the moment daily payouts. |
refundPeriod | integer <int32> (required for SCHEDULED type) Safety mechanism that will protect from paying out transactions (payments) that might get refunded in the coming days. Number of calendar days from the moment that payment split has been sent before paying it out. Example: Payment split received the 10/11 with a refund period of a week (7 days) -> Money kept internally in case of a refund coming in. Paid out on the 17/11. |
minimumAmount | integer <int32> Safety mechanism that will protect from paying out transactions (payments) with the balance lower than minimum amount. |
{- "type": "SCHEDULED",
- "frequency": "0 0 0 ? * WED *",
- "refundPeriod": 7
}
{- "externalAccountCode": "string",
- "type": "MANUAL",
- "frequency": "string",
- "refundPeriod": 0,
- "minimumAmount": 0
}
Updates the accountHolder configuration. Overrides the default configuration if it is set-up.
virtualAccountCode required | string Example: FD5CKXPz12SnYschrx71GmefFJSin636Sn6t System generated unique code assigned to the virtual account |
externalAccountCode | string The (external) account code of the account owner for which the payout should be transferred to. If it is not pass we will use a default one. The default external account will be the most recent one, and will be indicated as selected. |
type required | string (PayoutConfigType) Enum: "MANUAL" "SCHEDULED" Payout configuration type for the target account holder.
|
frequency | string (required for SCHEDULED type) A quartz cron expression which will dictate how often payout requests will be generated. You can use following tool: https://www.freeformatter.com/cron-expression-generator-quartz.html Hours, minutes, seconds are not taken into account so far as we do for the moment daily payouts. |
refundPeriod | integer <int32> (required for SCHEDULED type) Safety mechanism that will protect from paying out transactions (payments) that might get refunded in the coming days. Number of calendar days from the moment that payment split has been sent before paying it out. Example: Payment split received the 10/11 with a refund period of a week (7 days) -> Money kept internally in case of a refund coming in. Paid out on the 17/11. |
minimumAmount | integer <int32> Safety mechanism that will protect from paying out transactions (payments) with the balance lower than minimum amount. |
{- "type": "SCHEDULED",
- "frequency": "0 0 0 ? * WED *",
- "refundPeriod": 7
}
{- "externalAccountCode": "string",
- "type": "MANUAL",
- "frequency": "string",
- "refundPeriod": 0,
- "minimumAmount": 0
}
Retrieves the accountHolder configuration.
virtualAccountCode required | string Example: FD5CKXPz12SnYschrx71GmefFJSin636Sn6t System generated unique code assigned to the virtual account |
{- "externalAccountCode": "string",
- "type": "MANUAL",
- "frequency": "string",
- "refundPeriod": 0,
- "minimumAmount": 0
}
Deletes the accountHolder configuration. When deleting an accountHolder payout configuration, it will inherit the default configuration.
virtualAccountCode required | string Example: FD5CKXPz12SnYschrx71GmefFJSin636Sn6t System generated unique code assigned to the virtual account |
{- "externalAccountCode": "string",
- "type": "MANUAL",
- "frequency": "string",
- "refundPeriod": 0,
- "minimumAmount": 0
}
Creates a payout request dependent on the split instructions provided
payoutRequest
accountCode | string The (virtual) account code of the account owner holding the balance |
amount | integer <int64> The amount to payout, in the source 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). If amount is not specified, all funds will be withdrawn. |
sourceCurrency | string Default: "EUR" Value: "EUR" The currency in which to deduct from the seller's balance. The source currency is used to fund the payout and will be converted to the target currency in case the source and target currencies differ. |
targetCurrency | string Default: "EUR" Enum: "USD" "AUD" "EUR" "GBP" "JPY" "SGD" "CAD" "NZD" The currency which the beneficiary will receive. |
description | string The description that will show up in the destination account bank statement (255 symbols max) |
externalAccountCode | string The (external) account code of the account owner for which the payout should be transferred to. If none is given, it will use the Selected external account of the seller. |
processAt | string <date-time> The date and time, in the ISO-8601 calendar system, at which this money transfer will be due. If not specified, will be immediate |
{- "accountCode": "FD5CMGdfT7g7VxgUvVKSJT3tc6YKgan7RWt",
- "amount": 1000,
- "sourceCurrency": "EUR",
- "targetCurrency": "EUR",
- "description": "This is a test payout request",
- "externalAccountCode": "FD5CMGdfT7g56S1vx4Rq9vDEmN52G8NrWFi",
- "processAt": "2022-02-03T13:12:53.10032+01:00"
}
{- "accountCode": "FD5CMGdfT7g7VxgUvVKSJT3tc6YKgan7RWt",
- "amount": 1000,
- "code": "FD5CMGdfTBW1pWh8AZncwe2eHuu93JLxM3zY",
- "createdAt": "2022-02-03T13:12:53.10032+01:00",
- "description": "This is a test payout request",
- "externalAccountCode": "FD5CMGdfT7g56S1vx4Rq9vDEmN52G8NrWFi",
- "processAt": "2022-02-03T13:12:53.10032+01:00",
- "status": "WAITING"
}
It is only possible to delete an unprocessed payout request with status ‘WAITING’, using the code that was returned on the create post
code required | string The code of the payout request to delete |
{- "accountCode": "FD5CMGdfT7g7VxgUvVKSJT3tc6YKgan7RWt",
- "amount": 1000,
- "code": "FD5CMGdfTBW1pWh8AZncwe2eHuu93JLxM3zY",
- "createdAt": "2022-02-03T13:12:53.10032+01:00",
- "description": "This is a test payout request",
- "externalAccountCode": "FD5CMGdfT7g56S1vx4Rq9vDEmN52G8NrWFi",
- "processAt": "2022-02-03T13:12:53.10032+01:00",
- "status": "WAITING"
}
report required | string Enum: "marketplace-sellers" "marketplace-payments" "marketplace-settlement" "marketplace-incoming-settlement" "marketplace-revenue" "seller-settlement" "balance-mutation" "payout-report" The specific report type to retrieve |
page | number Default: 1 The page of reports to retreive (used for pagination of results) |
limit | number Default: 10 Enum: 10 25 50 100 The total amount of reports to retreive (used for pagination of results) |
account | string The account to retreive the report for (e.g. seller code). Used for seller settlement reports |
from | string <date> Example: from=2022-04-01 The start date to generate the report from. |
to | string <date> Example: to=2022-04-30 The end date to generate the report from. |
sort | string The fields to which sort by separated by "," |
direction | string Default: "asc" Enum: "asc" "desc" The direction in which to sort the previous fields, separated by "," |
{- "items": [
- {
- "id": "985bb876-657e-4fea-82a7-b1efc0bdc318",
- "report": "marketplace-sellers",
- "status": "SCHEDULED",
- "url": "string",
- "createdAt": "2022-04-09T09:32:48.257538",
- "account": {
- "id": "FD5CKXPze3o29SQD7MwYDDCX8oKKjN6h4eF",
- "name": "John Doe",
- "type": "seller"
}
}
], - "pagination": {
- "page": 1,
- "limit": 0,
- "total": 0
}
}
report required | string Enum: "marketplace-sellers" "marketplace-payments" "marketplace-settlement" "marketplace-incoming-settlement" "marketplace-revenue" "seller-settlement" "balance-mutation" "payout-report" The specific report type to request |
account | string The account to request the report for (e.g. seller code). Used for seller settlement reports |
from | string <date> The start date to generate the report from. |
to | string <date> The end date to generate the report from. |
{- "id": "985bb876-657e-4fea-82a7-b1efc0bdc318",
- "report": "marketplace-sellers",
- "status": "SCHEDULED",
- "url": "string",
- "createdAt": "2022-04-09T09:32:48.257538",
- "account": {
- "id": "FD5CKXPze3o29SQD7MwYDDCX8oKKjN6h4eF",
- "name": "John Doe",
- "type": "seller"
}
}
To receive notifications about updates that occur inside the processes, you have the option to use webhooks. Here you will find a list of the available updates that are sent via webhook and the corresponding bodies that will be received on the request.
All webhooks are sent as a POST request to the configured URL for that type of notification so multiple endpoints might be needed. The body of each request can also change depending on the type of the message.
Remember: The request descriptions on this section are to be implemented on your API. This is a specification on how the message is sent, and not how it is received by Payaut's API.
To configure the URL for the webhooks you will have to contact our support team so we can configure the webhook base URL that you will receive the calls on. This process is being improved, so soon you will have the ability to configure the webhooks via API call.
Each webhook is signed with the HMAC-SHA512 signature to ensure its authenticity. You can find it in Request Header under x-signature.
To verify HMAC Signature follow steps below:
data = webhookUrl + ":" + accountOwnerCode + ":" + timestamp
This webhook is sent everytime an update happens to the status of a KYC check.
model
accountOwnerCode | string |
kycMessage | string |
kycStatus | string Enum: "MISSING_DATA" "IN_PROGRESS" "ACTIVE" "FAILED" "REJECTED" |
hostedOnboardingUrl | string |
{- "accountOwnerCode": "FD5CM7GKttVTf7Gt7KcTVKU37fx7StTxvcc",
- "kycMessage": "Missing data for the following fields: address.city, phone, registrationNumber, ubos.address.country, ubos.lastName, address.houseNumber, address.street, ubos.firstName",
- "kycStatus": "MISSING_DATA",
}
This webhook is sent every time an update happens to the status of the payout.
model
accountOwnerCode | string |
payoutStatus | string Enum: "WAITING" "ACCEPTED" "PROCESSED" "RETURNED" "CANCELLED" "FAILED" |
payoutCode | string |
payoutMessage | string |
{- "accountOwnerCode": "FD5CM7GKttVTf7Gt7KcTVKU37fx7StTxvcc",
- "payoutStatus": "WAITING",
- "payoutCode": "FD5CMdGdJD7gUGVfTtDUU77vYtUSaa37tJ7",
- "payoutMessage": "Payout was requested."
}
If you want to configure a webhook URL to receive notifications, use this endpoint to create it for the first time. If you try to create again, the API will throw an error, because you can only have one URL configured per division per type. Try using the PUT endpoint to update your URL.
Information received from the Form with the Account Holders information to be saved. The isActivated
parameter in the request body is only for PUT requests.
url | string |
isActivated | boolean This is only for PUT requests. |
type | string Enum: "WEBHOOK_KYC_UPDATE" "WEBHOOK_PAYOUT_UPDATE" |
{- "isActivated": true,
- "type": "WEBHOOK_KYC_UPDATE"
}
{- "id": 839869699101327400,
- "type": "WEBHOOK_KYC_UPDATE",
- "divisionCode": "FD5CMFEqiTWQ1QxhCgDqCRqt4JKAaDamy9a",
- "isActivated": true
}
In case you need to list your configurations, this endpoint will return to you a list with all your configured URLs for each type.
[- {
- "id": 839869699101327400,
- "type": "WEBHOOK_KYC_UPDATE",
- "divisionCode": "FD5CMFEqiTWQ1QxhCgDqCRqt4JKAaDamy9a",
- "isActivated": true
}
]
If you already have a configuration created, but your URL changed for some reason, you can use this endpoint to update your URL for the configuration indicated in the endpoint.
configurationId required | integer Numeric ID of webhook configuration |
Information received from the Form with the Account Holders information to be saved.
url | string |
isActivated | boolean This is only for PUT requests. |
type | string Enum: "WEBHOOK_KYC_UPDATE" "WEBHOOK_PAYOUT_UPDATE" |
{- "isActivated": true,
- "type": "WEBHOOK_KYC_UPDATE"
}
{- "id": 839869699101327400,
- "type": "WEBHOOK_KYC_UPDATE",
- "divisionCode": "FD5CMFEqiTWQ1QxhCgDqCRqt4JKAaDamy9a",
- "isActivated": true
}
In case you need a single webhook information, you can use this endpoint. It will return to you the webhook that was defined on the endpoint.
configurationId required | integer Numeric ID of webhook configuration |
{- "id": 839869699101327400,
- "type": "WEBHOOK_KYC_UPDATE",
- "divisionCode": "FD5CMFEqiTWQ1QxhCgDqCRqt4JKAaDamy9a",
- "isActivated": true
}