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

Transactions

Get transactions. This API endpoint is connected to Payaut's data warehouse and provides an overview of all payments, refunds & chargeback including their status. Data from this endpoint may be slightly delayed.

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

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
* pending_settlement - Payaut received a split but not the funds from the PSP
* pending_split - Payaut received the funds from the PSP but not yet the split
* reconciled - The transaction has been processed
* cancelled - The transaction has been cancelled

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"

Responses

Response samples

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

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

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
[
  • {