API docs by Redocly

Payaut API documentation (1.2)

Download OpenAPI specification:Download

Payaut API reference

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

# Authentication Payaut uses bearer token to allow access to the API. You can ask for a bearer token by contacting info@payaut.com. We expect the bearer token to be included in all API requests in the http Authorization header. # Security

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.

Account Holders

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:

  • First name
  • Last name
  • Any field of the address
  • Any of the documents

    For Businesses the fields that force a retriger of KYC are:
  • Legal name
  • Any field of the address
  • Any of the documents
  • UBOs data

List account holders

Retrieves a list of existing account holders. The result is an object containing fields used for paging along side with the account holders itself.

query Parameters
_fragments
string

Fragments are used to access detailed data about an account holder. The following fragments are supported.

  1. extacc (info about external account)
  2. docs (info about the documents)
  3. accounts (overview of all associated accounts)
  4. ubo (info about the UBO's in case its an Organization)
_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".

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "pageNumber": 1,
  • "pageSize": 100,
  • "totalElementCount": 0
}

Create accountholder

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):

  1. Individual + LIGHT KYC
  2. Individual + STANDARD KYC
  3. Individual + ADVANCED KYC
  4. Business
Request Body schema: application/json
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)

Responses

Request samples

Content type
application/json
Example
{
  • "displayName": "J. Doe",
  • "legalEntity": {
    },
  • "externalAccounts": [
    ]
}

Response samples

Content type
application/json
{
  • "code": "FD5CM3gDntAdnVGnW3xfV7n3fatgAaG7vYS",
  • "createdAt": "2022-02-03",
  • "description": "John Doe",
  • "displayName": "John Doe",
  • "extRef": "MERCHANTX_User123456",
  • "accounts": [
    ],
  • "externalAccounts": [
    ],
  • "legalEntity": {
    },
  • "status": {
    },
  • "tier": "LIGHT_KYC"
}

Get account holder

Retrieves an existing account holder. You need to provide the code that was generated and returned during the creation of this particular account holder.

path Parameters
accountHolderCode
required
string
Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48

System generated unique code used to identify and modify that account holder

query Parameters
_fragments
string

Fragments are used to access detailed data about an account holder. The following fragments are supported.

  1. extacc (info about external account)
  2. docs (info about the documents)
  3. accounts (overview of all associated accounts)
  4. ubo (info about the UBO's in case its an Organization)

Responses

Response samples

Content type
application/json
{
  • "code": "FD5CM3gDntAdnVGnW3xfV7n3fatgAaG7vYS",
  • "createdAt": "2022-02-03",
  • "description": "John Doe",
  • "displayName": "John Doe",
  • "extRef": "MERCHANTX_User123456",
  • "accounts": [
    ],
  • "externalAccounts": [
    ],
  • "legalEntity": {
    },
  • "status": {
    },
  • "tier": "LIGHT_KYC"
}

Update account holder

Updates an existing account holder. Any data not provided will be left unchanged.

path Parameters
accountHolderCode
required
string
Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48

System generated unique code used to identify and modify that account holder

Request Body schema: application/json
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)

Responses

Request samples

Content type
application/json
{
  • "description": "John Doe",
  • "displayName": "John Doe",
  • "extRef": "MERCHANTX_User123456",
  • "externalAccounts": [
    ],
  • "legalEntity": {
    }
}

Response samples

Content type
application/json
{
  • "code": "FD5CM3gDntAdnVGnW3xfV7n3fatgAaG7vYS",
  • "createdAt": "2022-02-03",
  • "description": "John Doe",
  • "displayName": "John Doe",
  • "extRef": "MERCHANTX_User123456",
  • "accounts": [
    ],
  • "externalAccounts": [
    ],
  • "legalEntity": {
    },
  • "status": {
    },
  • "tier": "LIGHT_KYC"
}

Delete account holder

Deletes the account holder

path Parameters
accountHolderCode
required
string
Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48

System generated unique code used to identify and modify that account holder

Responses

Ultimate Beneficial Owners

Get ultimate beneficial owners

Retrieves a list of existing ultimate beneficial owners

path Parameters
accountHolderCode
required
string
Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48

System generated unique code used to identify and modify that account holder

query Parameters
_fragments
string

Fragments are used to access detailed data about an UBO. The following fragments are supported.

  1. docs (info about the documents of the UBO)
pageNumber
integer <int32>

The current page number

pageSize
integer <int32>

The amount of items to be fetched

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "pageNumber": 1,
  • "pageSize": 100,
  • "totalElementCount": 0
}

Creates an ultimate beneficial owner

Creates an ultimate beneficial owner

path Parameters
accountHolderCode
required
string
Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48

System generated unique code used to identify and modify that account holder

Request Body schema: application/json
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)

Responses

Request samples

Content type
application/json
{
  • "legalName": "John Doe",
  • "firstName": "John",
  • "lastName": "Doe",
  • "dateOfBirth": "2019-08-24T14:15:22Z",
  • "nationality": "NLD",
  • "type": "CEO",
  • "extRef": "string",
  • "address": {
    },
  • "documents": [
    ]
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "documents": [
    ]
}

Get ultimate beneficial owner

Retrieves an existing ultimate beneficial owner. You need to provide the code that was generated and returned during the creation of this particular ubo.

path Parameters
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

query Parameters
_fragments
string

Fragments are used to access detailed data about an UBO. The following fragments are supported.

  1. docs (info about the documents of the UBO)

Responses

Response samples

Content type
application/json
{
  • "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": {
    },
  • "documents": [
    ]
}

Update ultimate beneficial owner

Updates an existing ultimate beneficial owner. Any data not provided will be left unchanged.

path Parameters
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

Request Body schema: application/json
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)

Responses

Request samples

Content type
application/json
{
  • "legalName": "John Doe",
  • "firstName": "John",
  • "lastName": "Doe",
  • "dateOfBirth": "2019-08-24T14:15:22Z",
  • "nationality": "NLD",
  • "type": "CEO",
  • "extRef": "string",
  • "address": {
    },
  • "documents": [
    ]
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "documents": [
    ]
}

Accounts

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 accounts

Get all the virtual accounts connected with one account holder, by providing the account holder code.

path Parameters
accountHolderCode
required
string
Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48

System generated unique code used to identify and modify that account holder

query Parameters
_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

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "pageNumber": 0,
  • "pageSize": 100,
  • "totalElementCount": 454
}

Get account

Retrieves a virtual account connected with one account holder, by providing the account holder code and virtual account code.

path Parameters
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

Responses

Response samples

Content type
application/json
{
  • "accountType": "DEFAULT",
  • "code": "FD5CMUdtxdxnaWWvGxAV7aUgx3DK6VKDddc",
  • "displayName": "Virtual account for user John Doe",
  • "extRef": "JDoe_virtual_account"
}

External accounts

List external accounts for the specific account holder.

Get list of external account

path Parameters
accountHolderCode
required
string
Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48

System generated unique code used to identify and modify that account holder

query Parameters
_fragments
string

Fragments are used to access detailed data about an account holder. The following fragments are supported.

  1. extacc (info about external account)
  2. docs (info about the documents)
  3. accounts (overview of all associated accounts)
  4. ubo (info about the UBO's in case its an Organization)
_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".

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "pageNumber": 0,
  • "pageSize": 0,
  • "totalElementCount": 0
}

Create external account

Create external account

path Parameters
accountHolderCode
required
string
Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48

System generated unique code used to identify and modify that account holder

Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "extRef": "user1234_external_account",
  • "displayName": "IBAN for user1234",
  • "currency": "EUR",
  • "statement": {
    },
  • "accountType": "IBAN",
  • "accountNumber": "NL60INGB0008551819"
}

Response samples

Content type
application/json
{
  • "code": "FD5CKXQ3r8QEVM1CWjLuv72YbwNfGaVLjJg",
  • "extRef": "user1234_external_account",
  • "displayName": "IBAN for user1234",
  • "description": "string",
  • "currency": "EUR",
  • "kycStatus": "MISSING_DATA",
  • "kycMessage": "string",
  • "selected": true,
  • "acceptOtherCurrencies": false,
  • "allowedOtherCurrencyCodes": [
    ],
  • "statement": {
    },
  • "accountNumber": "string",
  • "accountType": "IBAN"
}

Get external account

Get external account

path Parameters
accountHolderCode
required
string
Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48

System generated unique code used to identify and modify that account holder

externalAccountCode
required
string
query Parameters
_fragments
string

Fragments are used to access detailed data about an account holder. The following fragments are supported.

  1. extacc (info about external account)
  2. docs (info about the documents)
  3. accounts (overview of all associated accounts)
  4. ubo (info about the UBO's in case its an Organization)

Responses

Response samples

Content type
application/json
{
  • "code": "FD5CKXQ3r8QEVM1CWjLuv72YbwNfGaVLjJg",
  • "extRef": "user1234_external_account",
  • "displayName": "IBAN for user1234",
  • "description": "string",
  • "currency": "EUR",
  • "kycStatus": "MISSING_DATA",
  • "kycMessage": "string",
  • "selected": true,
  • "acceptOtherCurrencies": false,
  • "allowedOtherCurrencyCodes": [
    ],
  • "statement": {
    },
  • "accountNumber": "string",
  • "accountType": "IBAN"
}

Update external account

Update external account

path Parameters
accountHolderCode
required
string
Example: FD5CKXPzDbi5xmwhrx71GmefFJNsztJjC48

System generated unique code used to identify and modify that account holder

externalAccountCode
required
string
Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "extRef": "user1234_external_account",
  • "displayName": "IBAN for user1234",
  • "currency": "EUR",
  • "statement": {
    },
  • "accountType": "IBAN",
  • "accountNumber": "NL60INGB0008551819"
}

Response samples

Content type
application/json
{
  • "code": "FD5CKXQ3r8QEVM1CWjLuv72YbwNfGaVLjJg",
  • "extRef": "user1234_external_account",
  • "displayName": "IBAN for user1234",
  • "description": "string",
  • "currency": "EUR",
  • "kycStatus": "MISSING_DATA",
  • "kycMessage": "string",
  • "selected": true,
  • "acceptOtherCurrencies": false,
  • "allowedOtherCurrencyCodes": [
    ],
  • "statement": {
    },
  • "accountNumber": "string",
  • "accountType": "IBAN"
}

Selects the active external account

Selects the active external account

path Parameters
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

Responses

Hosted Onboarding

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.

Generate Hosted onboarding URL

This endpoint is used to generate a unique URL for a certain Account Holder's hosted onboarding form page.

path Parameters
accountHolderCode
required
string
query Parameters
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.

Responses

Splits

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.

List split payments

Retrieves a list of existing payment splits. The result is an object containing fields used for paging along side with the splits itself.

query Parameters
_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

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "pageNumber": 0,
  • "pageSize": 0,
  • "totalElementCount": 0
}

Create split payment

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.

Request Body schema: application/json
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 time when the payment was processed either on the platform or PSP side.

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.

Responses

Request samples

Content type
application/json
Example
{
  • "extRef": "order123",
  • "totalAmount": 7000,
  • "description": "order 123",
  • "items": [
    ],
  • "pspExtRef": "PSP reference",
  • "currency": "EUR",
  • "paymentProcessor": "ADYEN",
  • "paymentMethod": "iDEAL"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "currency": "EUR",
  • "description": "string",
  • "extProcessedAt": "2019-08-24T14:15:22Z",
  • "extRef": "string",
  • "items": [
    ],
  • "paymentMethod": "string",
  • "paymentProcessor": "ADYEN",
  • "pspExtRef": "string",
  • "totalAmount": 0
}

Get split payment

Retrieves existing payment split. The result is an object containing fields with the splits itself.

path Parameters
code
required
string
Example: FD5CM7GKttVTf7Gt7KcTVKU37fx7StTxvcc

The code of the payment to get

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "currency": "EUR",
  • "description": "string",
  • "extProcessedAt": "2019-08-24T14:15:22Z",
  • "extRef": "string",
  • "items": [
    ],
  • "paymentMethod": "string",
  • "paymentProcessor": "ADYEN",
  • "pspExtRef": "string",
  • "totalAmount": 0
}

Refunds

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.

List split refunds

Retrieves a list of existing refund splits. The result is an object containing fields used for paging along side with the refund splits itself.

query Parameters
_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

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "pageNumber": 0,
  • "pageSize": 0,
  • "totalElementCount": 0
}

Create split refund

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 Body schema: application/json

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 2020-09-03T10:15:30+02:00.

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).

Responses

Request samples

Content type
application/json
Example
{
  • "extRef": "order123",
  • "pspMutationExtRef": "RUJSSC",
  • "totalAmount": 7000,
  • "description": "Full refund of order 123"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "description": "string",
  • "extProcessedAt": "2019-08-24T14:15:22Z",
  • "extRef": "string",
  • "items": [
    ],
  • "pspMutationExtRef": "string",
  • "totalAmount": 0
}

Get split refund

Retrieves an existing refund split. You need to provide the code that was generated and returned during the creation of this particular refund split.

path Parameters
code
required
string

The split code generated when a refund split is created

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "description": "string",
  • "extProcessedAt": "2019-08-24T14:15:22Z",
  • "extRef": "string",
  • "items": [
    ],
  • "pspMutationExtRef": "string",
  • "totalAmount": 0
}

Cancel split

Allows the cancellation of splits.

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

path Parameters
code
required
string = 36 characters

Code for the split to be cancelled

Responses

Balance

Get balance

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.

path Parameters
code
required
string

The account code for which to request the payout balance

Responses

Response samples

Content type
application/json
{
  • "amounts": [
    ],
  • "code": "string"
}

List Division Information

Retrieves the list of divisions with the information like payout, confirmed, pending balances

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Balance transfer

Create balance transfer

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.

Request Body schema: application/json

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)

Responses

Request samples

Content type
application/json
{
  • "fromAccountCode": "FD5CM7GKttVTf7Gt7KcTVKU37fx7StTxvcc",
  • "toAccountCode": "FD5CMdGdJD7gUGVfTtDUU77vYtUSaa37tJ7",
  • "amount": 1000,
  • "currency": "EUR",
  • "idempotencyKey": "f4754d35-7eaf-4338-a5ac-9d61bb1a2ff7",
  • "type": "INVOICE",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "code": "FD5CKXPiCGB4aayBG1saNdtVsb3RAPiqPHz",
  • "fromAccountCode": "FD5CM7GKttVTf7Gt7KcTVKU37fx7StTxvcc",
  • "toAccountCode": "FD5CMdGdJD7gUGVfTtDUU77vYtUSaa37tJ7",
  • "amount": 1000,
  • "currency": "EUR",
  • "idempotencyKey": "f4754d35-7eaf-4338-a5ac-9d61bb1a2ff7",
  • "type": "INVOICE",
  • "description": "string"
}

List balance transfers

Lists all balance transfers. The returned object is a paginated list with balance transfers

query Parameters
_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

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "pageNumber": 0,
  • "pageSize": 20,
  • "totalElementCount": 0
}

Get balance transfer

Get a single balance transfer

path Parameters
code
required
string
Example: FD5CM7GKttVTf7Gt7KcTVKU37fx7StTxvcc

The code of the balance transfer to get

Responses

Response samples

Content type
application/json
{
  • "code": "FD5CKXPiCGB4aayBG1saNdtVsb3RAPiqPHz",
  • "fromAccountCode": "FD5CM7GKttVTf7Gt7KcTVKU37fx7StTxvcc",
  • "toAccountCode": "FD5CMdGdJD7gUGVfTtDUU77vYtUSaa37tJ7",
  • "amount": 1000,
  • "currency": "EUR",
  • "idempotencyKey": "f4754d35-7eaf-4338-a5ac-9d61bb1a2ff7",
  • "type": "INVOICE",
  • "description": "string"
}

Payouts overview

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.

List payout requests

Listing all payout requests. Can also be specified using filters and pagination

query Parameters
_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" "REJECTED" "FAILED" "PROCESSED"

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

Responses

Response samples

Content type
application/json
{
  • "elements": [
    ],
  • "pageNumber": 0,
  • "pageSize": 0,
  • "totalElementCount": 0
}

Get payout request

To retrieve a previously created payout request you only need the code that was returned on the create post.

path Parameters
code
required
string

The code of the payout request to retrieve

Responses

Response samples

Content type
application/json
{
  • "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"
}

List payout requests v2

Listing all payout requests. Can also be specified using filters and pagination

query Parameters
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:

  • asc - Ascending order, from A to Z
  • desc - Descending order, from Z to A
query
string

The query search parameter. This can either be a seller name, a seller id or a payout account id

status
string
Enum: "PENDING" "IN_PROGRESS" "PROCESSED" "FAILED"

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

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Payout config

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.

  • Do you only want to change the configuration for your commission payouts, please use the the DIVISION CONFIGURATION.
  • Do you only want to change the configuration for a specific accountHolder, please use the ACCOUNTHOLDER CONFIGURATION.

Update the default configuration

Updates the default configuration. Default payout configuration is applied to every virtual account of "all accountHolders" and to your division account.

Request Body schema: application/json
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.

  • If MANUAL payout request will be generated only using the API on demand.
  • If SCHEDULED payout request will be generated and processed by Payaut on a scheduled basis.
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.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "SCHEDULED",
  • "frequency": "0 0 0 ? * WED *",
  • "refundPeriod": 7
}

Response samples

Content type
application/json
{
  • "externalAccountCode": "string",
  • "type": "MANUAL",
  • "frequency": "string",
  • "refundPeriod": 0,
  • "minimumAmount": 0
}

Get the default payout configuration

Retrieves the default payout configuration.

Responses

Response samples

Content type
application/json
{
  • "externalAccountCode": "string",
  • "type": "MANUAL",
  • "frequency": "string",
  • "refundPeriod": 0,
  • "minimumAmount": 0
}

Update the division configuration

Updates the division configuration. Overrides the default configuration if it is set-up.

Request Body schema: application/json
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.

  • If MANUAL payout request will be generated only using the API on demand.
  • If SCHEDULED payout request will be generated and processed by Payaut on a scheduled basis.
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.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "SCHEDULED",
  • "frequency": "0 0 0 ? * WED *",
  • "refundPeriod": 7
}

Response samples

Content type
application/json
{
  • "externalAccountCode": "string",
  • "type": "MANUAL",
  • "frequency": "string",
  • "refundPeriod": 0,
  • "minimumAmount": 0
}

Get the division configuration

Retrieves the division configuration.

Responses

Response samples

Content type
application/json
{
  • "externalAccountCode": "string",
  • "type": "MANUAL",
  • "frequency": "string",
  • "refundPeriod": 0,
  • "minimumAmount": 0
}

Update the accountHolder configuration

Updates the accountHolder configuration. Overrides the default configuration if it is set-up.

path Parameters
virtualAccountCode
required
string
Example: FD5CKXPz12SnYschrx71GmefFJSin636Sn6t

System generated unique code assigned to the virtual account

Request Body schema: application/json
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.

  • If MANUAL payout request will be generated only using the API on demand.
  • If SCHEDULED payout request will be generated and processed by Payaut on a scheduled basis.
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.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "SCHEDULED",
  • "frequency": "0 0 0 ? * WED *",
  • "refundPeriod": 7
}

Response samples

Content type
application/json
{
  • "externalAccountCode": "string",
  • "type": "MANUAL",
  • "frequency": "string",
  • "refundPeriod": 0,
  • "minimumAmount": 0
}

Get the accountHolder configuration

Retrieves the accountHolder configuration.

path Parameters
virtualAccountCode
required
string
Example: FD5CKXPz12SnYschrx71GmefFJSin636Sn6t

System generated unique code assigned to the virtual account

Responses

Response samples

Content type
application/json
{
  • "externalAccountCode": "string",
  • "type": "MANUAL",
  • "frequency": "string",
  • "refundPeriod": 0,
  • "minimumAmount": 0
}

Delete the accountHolder configuration

Deletes the accountHolder configuration. When deleting an accountHolder payout configuration, it will inherit the default configuration.

path Parameters
virtualAccountCode
required
string
Example: FD5CKXPz12SnYschrx71GmefFJSin636Sn6t

System generated unique code assigned to the virtual account

Responses

Response samples

Content type
application/json
{
  • "externalAccountCode": "string",
  • "type": "MANUAL",
  • "frequency": "string",
  • "refundPeriod": 0,
  • "minimumAmount": 0
}

Manual

Create payout request

Creates a payout request dependent on the split instructions provided

Request Body schema: application/json

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

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

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

Content type
application/json
{
  • "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"
}

Delete payout request

It is only possible to delete an unprocessed payout request with status ‘WAITING’, using the code that was returned on the create post

path Parameters
code
required
string

The code of the payout request to delete

Responses

Response samples

Content type
application/json
{
  • "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"
}

Transactions

Get transactions

query Parameters
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:

  • asc - Ascending order, from A to Z
  • desc - Descending order, from Z to A
query
string

The query search parameter

transactionStatus
string
Enum: "PENDING" "RECONCILED"

The status of a transaction:

  • PENDING - Payment has not been processed yet and is still pending
  • RECONCILED - Payment has been processed
refundStatus
string
Enum: "NONE" "PARTIAL" "FULL" "PENDING"

The type of refund:

  • NONE - No refund has been issued for this transaction
  • PARTIAL - A partial refund has been issued for this transaction
  • FULL - This transaction has been fully refunded
  • PENDING - There are only PENDING refunds that belong to this transaction
from
string <date>

The from date of a transaction

to
string <date>

The to date of a transaction

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Reporting

Get list of reports

path Parameters
report
required
string
Enum: "marketplace-sellers" "marketplace-payments" "marketplace-settlement" "seller-settlement"

The specific report type to retrieve

query Parameters
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 ","

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "pagination": {
    }
}

Request reports for specific accounts with a specific timeframe.

path Parameters
report
required
string
Enum: "marketplace-sellers" "marketplace-payments" "marketplace-settlement" "seller-settlement"

The specific report type to request

Request Body schema: application/x-www-form-urlencoded
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.

Responses

Response samples

Content type
application/json
{
  • "id": "985bb876-657e-4fea-82a7-b1efc0bdc318",
  • "report": "marketplace-sellers",
  • "status": "SCHEDULED",
  • "url": "string",
  • "createdAt": "2022-04-09T09:32:48.257538",
  • "account": {
    }
}

Webhooks

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.

Hmac Signature

Each webhook is signed with the HMAC-SHA512 signature to ensure its authenticity. You can find it in Request Header under x-signature.

Contract

  1. Shared secret (Secret Key) API access token
  2. Hashing tool (Algorithm) HMAC-SHA512
  3. Data to hash: webhookUrl - URL of the web hook accountOwnerCode - from the web hook body timestamp - from Request Header under x-timestamp

Verifying Signature

To verify HMAC Signature follow steps below:

  1. Prepare data string using following pattern:
    data = webhookUrl + ":" + accountOwnerCode + ":" + timestamp
  2. Create HMAC Signature using contract described above with data in format prepared in step one.
  3. Transform computed HMAC Signature into Base64
  4. Compare received and created HMAC Signature to ensure they match.

Update of KYC status

This webhook is sent everytime an update happens to the status of a KYC check.

  • MISSING_DATA - the input was incomplete, not all required data/documents were submitted by the seller (e.g. they did not provide their full address or did not upload the bank statement)
  • IN_PROGRESS - the KYC check is currently being carried out by Payaut - this status is temporary and will result in either ACTIVE or FAILED or REJECTED as explained above.
  • ACTIVE - the seller has passed KYC check successfully and is eligible for payouts - no further action is required from the seller or from the merchant
  • FAILED - the KYC check failed due to incorrect input/data (e.g. an expired document was uploaded or a blurry picture) - the seller can make corrections (e.g. submit a valid document or a better quality picture)
  • REJECTED - the input was complete and correct but the seller has not passed the KYC check - they were declined by Payaut as a customer (e.g. due to suspicion of fraud or money laundering)

The webhook has standardized response codes for all MISSING_DATA and FAILED KYC requests. These response codes are described in our business docs at: Payaut Business Documentation - KYC
Request Body schema: application/json

model

accountOwnerCode
string
kycMessage
string
kycStatus
string
Enum: "MISSING_DATA" "IN_PROGRESS" "ACTIVE" "FAILED" "REJECTED"
hostedOnboardingUrl
string

Responses

Request samples

Content type
application/json
{
  • "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",
  • "hostedOnboardingUrl": "https://onboarding.payaut.com?token=..."
}

Update of Payout Status

This webhook is sent every time an update happens to the status of the payout.

  • REQUESTED - payout request is created
  • PAID - funds have been transferred to the external account
  • RETURNED - funds have been transferred from the external account's bank to Payaut due to the fact that the bank account has been closed
  • CANCELLED - payout request is canceled before it was paid (edited)

Request Body schema: application/json

model

accountOwnerCode
string
payoutStatus
string
Enum: "REQUESTED" "PAID" "RETURNED" "CANCELLED"
payoutCode
string
payoutMessage
string

Responses

Request samples

Content type
application/json
{
  • "accountOwnerCode": "FD5CM7GKttVTf7Gt7KcTVKU37fx7StTxvcc",
  • "payoutStatus": "REQUESTED",
  • "payoutCode": "FD5CMdGdJD7gUGVfTtDUU77vYtUSaa37tJ7",
  • "payoutMessage": "Payout was requested."
}

Create webhook configuration

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.

Request Body schema: application/json

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"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Get your webhook configurations

In case you need to list your configurations, this endpoint will return to you a list with all your configured URLs for each type.

Responses

Response samples

Content type
application/json
[]

Update webhook configuration

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.

path Parameters
configurationId
required
integer

Numeric ID of webhook configuration

Request Body schema: application/json

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"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Get single webhook information

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.

path Parameters
configurationId
required
integer

Numeric ID of webhook configuration

Responses

Response samples

Content type
application/json
{}