NAV Navbar
cURL

Introduction

Base URL
https://api.payaut.com/
https://sandbox.payaut.com/

The purpose of this documentation is to describe Payaut API. Our platform functionalities are exposed through the hereby described REST APIs.

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.

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.

Authentication

Authenticated request
curl -H "Accept-Charset: utf-8"
-H "Content-Type: application/json;charset=UTF-8"
-H "Authorization: Bearer YWxhZGRpbjpvcGVuc2VzYW1l"
https://sandbox.payaut.com/api/v1/accountholders

Payaut uses API keys to allow access to the API. You can ask for an API key by contacting info@payaut.com.

We expect the API key to be included in all API requests in the http Authorization header.

Errors

HTTP status codes
200 - OK Everything worked as expected.
400 - Bad Request The server cannot or will not process the request due to something that is perceived to be a client error. Only returned when the error doesn’t fit any of the specific 4xx errors bellow.
401 - Unauthorized No valid API key provided.
402 - Request Failed The parameters were valid but the request failed.
403 - Forbidden The API key doesn’t have permissions to perform the request.
404 - Not Found The requested resource doesn’t exist.
409 - Conflict The request conflicts with another request (perhaps due to using the same idempotent key).
422 - Unprocessable Entity The request was unacceptable, often due to missing a required parameter. The client should not repeat this request without modification.
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors Something went wrong on Payaut’s end. (These are rare.)

Payout uses conventional HTTP response codes to indicate the success or failure of an API request.

In general: codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, split total amount does not match with the sum of the items, etc.). Codes in the 5xx range indicate an error with Payout’‘s servers (these are rare).

Some 4xx errors that could be handled programmatically (e.g., a card is declined) include an error code that briefly explains the error reported.

Attributes

PathTypeDescription
codeStringThe Payaut status code, e.g. “422.000.000”.
messageStringA description of the cause of the error.
parameterizedObjectAn object containing a template message and params so you can build a custom message, if needed.
parameterized.templateStringA variable template message with placeholders. Example: “The total amount declared was {totalAmount} but the amount sum of the items is {sumOfElementsAmount}. They must be equal.”
parameterized.paramsObjectA dynamic object with fields that can replace the placeholders of the template message. Example: {“totalAmount”: “69600”,“sumOfElementsAmount”: “69700”}.
details[]ArrayOnly applicable for 4xx errors.
details[].fieldStringThe name of the problematic field.
details[].codeStringA more detailed Payaut status code with sub-codes defined. This code is usually related to a specific faulty business process. Example: “422.030.101”.
details[].messageStringAn error message that represents the processing of the template message with its correspondent parameters gathered from details[].parameterized. Example: “The total amount declared was 69600 but the amount sum of the items is 69700. They must be equal.”
details[].parameterizedObjectSame object as the one defined above.
details[].attemptedValueVariesThe sent value that caused the problem, if applicable.

Account holders

endPoints
POST    /api/v1/accountholders          HTTP/1.1
PATCH   /api/v1/accountholders/{code}   HTTP/1.1
GET     /api/v1/accountholders          HTTP/1.1
GET     /api/v1/accountholders/{code}   HTTP/1.1

All fund recipients on your platform can be onboarded via the Payaut API. We call this entity an “Account holder”. It represents a seller, or anyone who needs to have a virtual account on your platform.

The account holder funds are stored by a Payaut virtual account and can only be paid out to an IBAN bank account when the account holder is verified by our verification procedure. We call this procedure KYC (Know Your Customer). The KYC procedure is started when all required metadata and documents are provided during the creation or update of an account holder.

Then, once the account holder is verified, you can payout funds to an external account. As noticed, the external account represents, in this case, an IBAN bank account.

Accountholder

image representing the account holder structure

The account holder object

Attributes

The account holder object
{
  "extRef" : "abc123",
  "code" : "FD5CMJEU5Lkf1ERopxZrF4cZLpY1PmYGcNC",
  "displayName" : "J. Doe",
  "description" : "A brief description of the account holder",
  "legalEntity" : {
    "legalForm" : "individual",
    "legalName" : "J. Doe",
    "taxNumber" : "345422343AE",
    "address" : {
      "street" : "Backershagen",
      "houseNumber" : "99A",
      "addition" : "N/A",
      "city" : "Amsterdam",
      "zipcode" : "1082 GT",
      "country" : "NLD",
      "state" : "Noord Holland"
    },
    "email" : "contact@payaut.com",
    "phone" : "+31623465334",
    "kycStatus" : {
      "status" : "REJECTED",
      "details" : [ {
        "messageType" : "ERROR",
        "messageCode" : "00000000",
        "message" : "Address is a PO box"
      } ]
    },
    "firstName" : "John",
    "lastName" : "Doe",
    "socialSecurityNumber" : "999999990",
    "gender" : "MALE",
    "dateOfBirth" : "1980-12-24",
    "placeOfBirth" : {
      "city" : "Amsterdam",
      "state" : "NH",
      "country" : "NLD"
    },
    "nationality" : "NLD",
    "documents" : [ {
      "type" : "ID",
      "number" : "ID1111111",
      "issuedAt" : "2016-07-28",
      "expireAt" : "2023-07-28",
      "issuerCountry" : "NLD",
      "photos" : [ {
        "code" : "FD5CMJEU5Lkf1ERorRrjTegKMdB5mFFRkW4",
        "extRef" : "ER ID1111111 BACK STRAIGHT",
        "page" : "BACK",
        "style" : "STRAIGHT",
        "format" : "PNG",
        "data" : "ZW1wdHk="
      }, {
        "code" : "FD5CMJEU5Lkf1ERor4Y1f1CpbjV6CHH4jwe",
        "extRef" : "ER ID1111111 FRONT STRAIGHT",
        "page" : "FRONT",
        "style" : "STRAIGHT",
        "format" : "JPG",
        "data" : "ZW1wdHk="
      } ],
      "code" : "FD5CMJEU5Lkf1ERoroBTGJ3J82H126XfMuz",
      "extRef" : "ER ID1111111"
    } ]
  },
  "externalAccounts" : [ {
    "accountType" : "IBAN",
    "accountNumber" : "NL91ABNA0417164300",
    "code" : "FD5CMJEU5Lkf1ERoqhDHrMnaqb68na3z2oA",
    "extRef" : "ER J. Doe IBAN",
    "displayName" : "NL91 ABNA 0417 1643 00",
    "description" : "J. Doe ABN account",
    "currency" : "EUR",
    "statement" : {
      "issuedAt" : "2018-07-28",
      "data" : "ZW1wdHk="
    },
    "kycStatus" : {
      "status" : "FAILED",
      "details" : [ {
        "messageType" : "ERROR",
        "messageCode" : "00000000",
        "message" : "Invalid bank identifier"
      } ]
    }
  } ],
  "accounts" : [ {
    "code" : "FD5CMJEU5Lkf1ERoqKta3iNM5ShB9KGSyv8",
    "extRef" : "ER AH Default Account",
    "accountType" : "DEFAULT",
    "displayName" : "Account holder default account"
  } ],
  "status" : {
    "code" : "NOPAYOUT",
    "reason" : "KYC processing has failed",
    "processedAmount" : {
      "amount" : 0,
      "currency" : "EUR"
    }
  }
}
PathTypeDescriptionConstraints
extRefStringPlatform external reference of the account holder.
codeStringPayaut unique reference of the account holder. This field is part of the response payload, so should never be sent in the request.
displayNameStringDisplay name of the account holder that can be displayed in reports or internal systems.
descriptionStringA description of the account holder, like the full name or company name.
legalEntityObjectThe account holder legal entity representation. Please check the `Legal entities` section of this documentation for more details.
externalAccounts[]ArrayThe external accounts of the account holder. Please check the `External accounts` section of this documentation for more details.
accounts[]ArrayThe virtual accounts of the account holder. Please check the `Accounts` section of this documentation for more details.
statusObjectThe KYC status of the account holder.
status.codeStringThe status code of the account holder. Possible values: ACTIVE, NOPAYOUT, SUSPENDED, CLOSED.
status.reasonStringA descriptive message about the current status code.
status.processedAmountObjectThe total amount processed so far for the account holder.
status.processedAmount.amountNumberThe positive integer amount.
status.processedAmount.currencyStringThe amount’s currency.

Create an account holder

POST /api/v1/accountholders
$ curl 'https://sandbox.payaut.com/api/v1/accountholders?readyForKyc=true' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi' \
    -d '{
  "extRef" : "abc123",
  "displayName" : "J. Doe",
  "description" : "A brief description of the account holder",
  "legalEntity" : {
    "legalForm" : "individual",
    "legalName" : "J. Doe",
    "taxNumber" : "345422343AE",
    "address" : {
      "street" : "Backershagen",
      "houseNumber" : "99A",
      "addition" : "N/A",
      "city" : "Amsterdam",
      "zipcode" : "1082 GT",
      "country" : "NLD",
      "state" : "Noord Holland"
    },
    "email" : "contact@payaut.com",
    "phone" : "+31623465334",
    "firstName" : "John",
    "lastName" : "Doe",
    "socialSecurityNumber" : "999999990",
    "gender" : "MALE",
    "dateOfBirth" : "1980-12-24",
    "placeOfBirth" : {
      "city" : "Amsterdam",
      "state" : "NH",
      "country" : "NLD"
    },
    "nationality" : "NLD",
    "documents" : [ {
      "type" : "ID",
      "number" : "ID1111111",
      "issuedAt" : "2016-07-28",
      "expireAt" : "2023-07-28",
      "issuerCountry" : "NLD",
      "photos" : [ {
        "extRef" : "ER ID1111111 BACK STRAIGHT",
        "page" : "BACK",
        "style" : "STRAIGHT",
        "format" : "PNG",
        "data" : "ZW1wdHk="
      }, {
        "extRef" : "ER ID1111111 FRONT STRAIGHT",
        "page" : "FRONT",
        "style" : "STRAIGHT",
        "format" : "JPG",
        "data" : "ZW1wdHk="
      } ],
      "extRef" : "ER ID1111111"
    } ]
  },
  "accounts" : [ {
    "extRef" : "ER AH Default Account",
    "accountType" : "DEFAULT",
    "displayName" : "Account holder default account"
  } ]
}'
Response
{
  "extRef" : "abc123",
  "code" : "FD5CMJEU5Lqg6CrVqPK7q5kn9xiPWJorrSC",
  "displayName" : "J. Doe",
  "description" : "A brief description of the account holder",
  "legalEntity" : {
    "legalForm" : "individual",
    "legalName" : "J. Doe",
    "taxNumber" : "345422343AE",
    "address" : {
      "street" : "Backershagen",
      "houseNumber" : "99A",
      "addition" : "N/A",
      "city" : "Amsterdam",
      "zipcode" : "1082 GT",
      "country" : "NLD",
      "state" : "Noord Holland"
    },
    "email" : "contact@payaut.com",
    "phone" : "+31623465334",
    "kycStatus" : {
      "status" : "REJECTED",
      "details" : [ {
        "messageType" : "ERROR",
        "messageCode" : "00000000",
        "message" : "Address is a PO box"
      } ]
    },
    "firstName" : "John",
    "lastName" : "Doe",
    "socialSecurityNumber" : "999999990",
    "gender" : "MALE",
    "dateOfBirth" : "1980-12-24",
    "placeOfBirth" : {
      "city" : "Amsterdam",
      "state" : "NH",
      "country" : "NLD"
    },
    "nationality" : "NLD",
    "documents" : [ {
      "type" : "ID",
      "number" : "ID1111111",
      "issuedAt" : "2016-07-28",
      "expireAt" : "2023-07-28",
      "issuerCountry" : "NLD",
      "photos" : [ {
        "code" : "FD5CMJEU5Lqg6CrVrVHHF2M3QsfUcWaHGqN",
        "extRef" : "ER ID1111111 BACK STRAIGHT",
        "page" : "BACK",
        "style" : "STRAIGHT",
        "format" : "PNG",
        "data" : "ZW1wdHk="
      }, {
        "code" : "FD5CMJEU5Lqg6CrVr7xZSNsYeyyV5KsGWhe",
        "extRef" : "ER ID1111111 FRONT STRAIGHT",
        "page" : "FRONT",
        "style" : "STRAIGHT",
        "format" : "JPG",
        "data" : "ZW1wdHk="
      } ],
      "code" : "FD5CMJEU5LqiVjX3pvC7X4eMUQvLWQCZu9J",
      "extRef" : "ER ID1111111"
    } ]
  },
  "accounts" : [ {
    "code" : "FD5CMJEU5Lqg6CrVqkdqdjWZtasZZNr69JG",
    "extRef" : "ER AH Default Account",
    "accountType" : "DEFAULT",
    "displayName" : "Account holder default account"
  } ],
  "status" : {
    "code" : "NOPAYOUT",
    "reason" : "KYC processing has failed",
    "processedAmount" : {
      "amount" : 0,
      "currency" : "EUR"
    }
  }
}

Creates an account holder. You can either choose to create a fat account holder with all KYC required data in one go, or create a simple account holder and update it in a later stage.

Attributes

PathTypeDescriptionConstraints
extRefStringPlatform external reference of the account holder.Optional
displayNameStringA display name for the account holder.Mandatory
descriptionStringA description of the account holder.Optional
legalEntityObjectThe account holder legal entity representation. Please check the `Legal entities` section of this documentation for more details.Optional
accounts[]ArrayThe virtual accounts of the account holder. Please check the `Accounts` section of this documentation for more details.Mandatory

Update an account holder

PATCH /api/v1/accountholders/{code}
$ curl 'https://sandbox.payaut.com/api/v1/accountholders/FD5CMJEU5LwjKPtxzd7jchNKqqNSHDpLcYg?readyForKyc=true' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi' \
    -d '{
  "externalAccounts" : [ {
    "accountType" : "IBAN",
    "accountNumber" : "NL91ABNA0417164300",
    "extRef" : "ER J. Doe IBAN",
    "displayName" : "NL91 ABNA 0417 1643 00",
    "description" : "J. Doe ABN account",
    "currency" : "EUR",
    "statement" : {
      "issuedAt" : "2018-07-28",
      "data" : "ZW1wdHk="
    }
  } ]
}'
Response
{
  "extRef" : "abc123",
  "code" : "FD5CMJEU5LwjKPtxzd7jchNKqqNSHDpLcYg",
  "displayName" : "J. Doe",
  "description" : "A brief description of the account holder",
  "externalAccounts" : [ {
    "accountType" : "IBAN",
    "accountNumber" : "NL91ABNA0417164300",
    "code" : "FD5CMJEU5LwjKPty1MmBDzYMLbvZsxk5AaL",
    "extRef" : "ER J. Doe IBAN",
    "displayName" : "NL91 ABNA 0417 1643 00",
    "description" : "J. Doe ABN account",
    "currency" : "EUR",
    "statement" : {
      "issuedAt" : "2018-07-28",
      "data" : "ZW1wdHk="
    },
    "kycStatus" : {
      "status" : "FAILED",
      "details" : [ {
        "messageType" : "ERROR",
        "messageCode" : "00000000",
        "message" : "Invalid bank identifier"
      } ]
    }
  } ],
  "accounts" : [ {
    "code" : "FD5CMJEU5LwjKPtxzzSTRM87aTXcB8JMPFn",
    "extRef" : "ER AH Default Account",
    "accountType" : "DEFAULT",
    "displayName" : "Account holder default account"
  } ],
  "status" : {
    "code" : "NOPAYOUT",
    "reason" : "KYC has not been performed yet",
    "processedAmount" : {
      "amount" : 0,
      "currency" : "EUR"
    }
  }
}

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

This operation is useful while providing late KYC required data.

Path Parameters

ParameterDescription
codeThe account holder code generated when the entity was created.

Attributes

PathTypeDescriptionConstraints
legalEntityObjectThe account holder legal entity representation. Please check the `Legal entities` section of this documentation for more details.Optional
externalAccounts[]ArrayThe external accounts of the account holder. Please check the `External accounts` section of this documentation for more details.Optional

Retrieve an account holder

GET /api/v1/accountholders/{code}
$ curl 'https://sandbox.payaut.com/api/v1/accountholders/FD5CMJEU5M3QtpxUSCfBjp8PbmZzezY5G9e?_fragments=extacc,kycstatus,accounts' -i -X GET \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "extRef" : "abc123",
  "code" : "FD5CMJEU5M3QtpxUSCfBjp8PbmZzezY5G9e",
  "displayName" : "J. Doe",
  "description" : "A brief description of the account holder",
  "externalAccounts" : [ {
    "accountType" : "IBAN",
    "accountNumber" : "NL91ABNA0417164300",
    "code" : "FD5CMJEU5M3QtpxUSwJdM7JR6Y88YhMqyr8",
    "extRef" : "ER J. Doe IBAN",
    "displayName" : "NL91 ABNA 0417 1643 00",
    "description" : "J. Doe ABN account",
    "currency" : "EUR",
    "statement" : {
      "issuedAt" : "2018-07-28",
      "data" : "ZW1wdHk="
    },
    "kycStatus" : {
      "status" : "FAILED",
      "details" : [ {
        "messageType" : "ERROR",
        "messageCode" : "00000000",
        "message" : "Invalid bank identifier"
      } ]
    }
  } ],
  "accounts" : [ {
    "code" : "FD5CMJEU5M3QtpxUSZyuYTtBLPjAtanAn7z",
    "extRef" : "ER AH Default Account",
    "accountType" : "DEFAULT",
    "displayName" : "Account holder default account"
  } ],
  "status" : {
    "code" : "NOPAYOUT",
    "reason" : "KYC has not been performed yet",
    "processedAmount" : {
      "amount" : 0,
      "currency" : "EUR"
    }
  }
}

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

ParameterDescription
codeThe account holder code generated when the entity was created.

Request Parameters

ParameterDescription
_fragmentsBy default, a thin account holder object is returned unless a fragment is specified to be returned.

Possible values:

ubo - ultimate beneficial owner of a legal entity or company,
extacc - external account (e.g. IBAN),
kycstatus - status and details of the KYC verification,
docs, docfiles - documents,
accounts - list of accounts. &tl;dr

List all account holders

GET /api/v1/accountholders
$ curl 'https://sandbox.payaut.com/api/v1/accountholders?_fragments=extacc,kycstatus,accounts' -i -X GET \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "pageSize" : 1,
  "pageNumber" : 1,
  "elements" : [ {
    "extRef" : "abc123",
    "code" : "FD5CMJEU5LfDryMcBkZ4xKUVMjG7ijmg88Q",
    "displayName" : "J. Doe",
    "description" : "A brief description of the account holder",
    "externalAccounts" : [ {
      "accountType" : "IBAN",
      "accountNumber" : "NL91ABNA0417164300",
      "code" : "FD5CMJEU5LfDryMcCVCWZceWrVpFKVJpy8c",
      "extRef" : "ER J. Doe IBAN",
      "displayName" : "NL91 ABNA 0417 1643 00",
      "description" : "J. Doe ABN account",
      "currency" : "EUR",
      "statement" : {
        "issuedAt" : "2018-07-28",
        "data" : "ZW1wdHk="
      },
      "kycStatus" : {
        "status" : "FAILED",
        "details" : [ {
          "messageType" : "ERROR",
          "messageCode" : "00000000",
          "message" : "Invalid bank identifier"
        } ]
      }
    } ],
    "accounts" : [ {
      "code" : "FD5CMJEU5LfDryMcC7snkyEH6MRHhrHXkMW",
      "extRef" : "ER AH Default Account",
      "accountType" : "DEFAULT",
      "displayName" : "Account holder default account"
    } ],
    "status" : {
      "code" : "NOPAYOUT",
      "reason" : "KYC has not been performed yet",
      "processedAmount" : {
        "amount" : 0,
        "currency" : "EUR"
      }
    }
  } ],
  "totalElementCount" : 1
}

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

Request Parameters

ParameterDescription
_fragmentsBy default, a thin account holder object is returned unless a fragment is specified to be returned. Possible values: ubo, extacc, kycstatus, docs, docfiles, accounts.
_pageNumberThe number of this page.
_pageSizeNumber of elements returned in this page.
_sortThe request sorting of the page elements. Possible values: asc, desc.

Legal entities

An account holder is represented by a legal entity. A legal entity can be either an individual or an organization.

The legal entity has all the personal/business related metadata and documents required to verify the account holder.

The individual legal entity object
{
  "legalForm" : "individual",
  "legalName" : "J. Doe",
  "taxNumber" : "345422343AE",
  "address" : {
    "street" : "Backershagen",
    "houseNumber" : "99A",
    "addition" : "N/A",
    "city" : "Amsterdam",
    "zipcode" : "1082 GT",
    "country" : "NLD",
    "state" : "Noord Holland"
  },
  "email" : "contact@payaut.com",
  "phone" : "+31623465334",
  "kycStatus" : {
    "status" : "REJECTED",
    "details" : [ {
      "messageType" : "ERROR",
      "messageCode" : "00000000",
      "message" : "Address is a PO box"
    } ]
  },
  "firstName" : "John",
  "lastName" : "Doe",
  "socialSecurityNumber" : "999999990",
  "gender" : "MALE",
  "dateOfBirth" : "1980-12-24",
  "placeOfBirth" : {
    "city" : "Amsterdam",
    "state" : "NH",
    "country" : "NLD"
  },
  "nationality" : "NLD",
  "documents" : [ {
    "type" : "ID",
    "number" : "ID1111111",
    "issuedAt" : "2016-07-28",
    "expireAt" : "2023-07-28",
    "issuerCountry" : "NLD",
    "photos" : [ {
      "code" : "FD5CMJEU5LA75pkhdDiZxmcEcboFNbnVELp",
      "extRef" : "ER ID1111111 BACK STRAIGHT",
      "page" : "BACK",
      "style" : "STRAIGHT",
      "format" : "PNG",
      "data" : "ZW1wdHk="
    }, {
      "code" : "FD5CMJEU5LA4gJ69enojgjCQZZxJxXDnxoJ",
      "extRef" : "ER ID1111111 FRONT STRAIGHT",
      "page" : "FRONT",
      "style" : "STRAIGHT",
      "format" : "JPG",
      "data" : "ZW1wdHk="
    } ],
    "code" : "FD5CMJEU5LA75pkhdb3HmQyDNzuAZCYuwNx",
    "extRef" : "ER ID1111111"
  } ]
}

Attributes

PathTypeDescriptionConstraints
legalFormStringThe legal entity form that indicates if the entity is an individual or an organization. In this case, an individual.
legalNameStringThe individual legal name.
firstNameStringThe individual first name.
lastNameStringThe individual last name.
taxNumberStringThe individual tax number.
socialSecurityNumberStringThe individual social security number.
genderStringThe individual gender. Possible values: FEMALE, MALE
dateOfBirthStringDate of birth in ‘YYYY-MM-DD’ format.
placeOfBirthObjectThe individual place of birth.
placeOfBirth.cityStringThe individual city of birth (minimum 2 and maximum 4 characters).
placeOfBirth.stateStringThe individual state of birth (minimum 2 and maximum 4 characters).
placeOfBirth.countryStringThe individual country of birth (3 characters only).
nationalityStringNationality (3 character country code).
addressObjectThe individual address.
address.streetStringThe individual street address name.
address.houseNumberStringThe individual house number with optional prefix and suffix. For example: 10-11/D.
address.additionStringThe individual address addition, like unit, floor, door, etc.
address.zipcodeStringThe individual address zip code.
address.cityStringThe individual city name.
address.stateStringThe individual state code.
address.countryStringThe individual country code (3 characters only).
emailStringThe individual email.
phoneStringThe individual phone number.
kycStatusObjectThe individual kyc status filled after the creation of the legal entity.
kycStatus.statusStringThe individual kyc status code. Possible values: WAITING_DATA, MISSING_DATA, DATA_RECEIVED, IN_PROGRESS, PASSED, REJECTED, FORGED, FAILED.
kycStatus.details[]ArrayA list containing details about the KYC process.
kycStatus.details[].codeStringPayaut unique reference of the kyc status detail. This field is part of the response payload, so should never be sent in the request.
kycStatus.details[].typeStringThe type of the kyc detail. Possible values: ERROR, ADVICE.
kycStatus.details[].messageCodeStringAn identifier code of the descriptive message bellow.
kycStatus.details[].messageTemplateStringA descriptive message of the error or advice.
documents[]ArrayThe personal documents of the legal entity.
documents[].typeStringThe personal document type. Possible values: ID, PASSPORT, DRIVING_LICENSE, VISA.
documents[].numberStringThe personal document number.
documents[].issuedAtStringThe issuance date of the personal document.
documents[].expireAtStringThe expiration date of the personal document.
documents[].issuerCountryStringThe issuer country of the personal document.
documents[].extRefStringPlatform external reference of the document.
documents[].photos[]ArrayPhotos of the documents used in the KYC process.
documents[].photos[].codeStringPayaut unique reference of the photo. This field is part of the response payload, so should never be sent in the request.
documents[].photos[].extRefStringPlatform external reference of the photo.
documents[].photos[].pageStringIndicates the side of the document that was photographed. Possible values: FRONT, BACK.
documents[].photos[].styleStringIndicates the angle in which the document was photographed. Possible values: STRAIGHT, TILTED.
documents[].photos[].formatStringThe format of the photo. Possible values: PNG, JPG.
documents[].photos[].dataStringThe Base64 encoded string of the photo.
The organization legal entity object
{
  "legalForm" : "organization",
  "type" : "PRIVATE_COMPANY",
  "registrationNumber" : "346242542",
  "ultimateBeneficialOwners" : [ {
    "code" : "FD5CMJEU5M7thvjzspm1BhRqYZWJp6Vm6nU",
    "extRef" : "ER UBO 123",
    "type" : "CEO",
    "legalName" : "J. Doe",
    "taxNumber" : "345422343AE",
    "address" : {
      "street" : "Backershagen",
      "houseNumber" : "99A",
      "addition" : "N/A",
      "city" : "Amsterdam",
      "zipcode" : "1082 GT",
      "country" : "NLD",
      "state" : "Noord Holland"
    },
    "email" : "contact@payaut.com",
    "phone" : "+31623465334",
    "kycStatus" : {
      "status" : "REJECTED",
      "details" : [ {
        "messageType" : "ERROR",
        "messageCode" : "00000000",
        "message" : "Address is a PO box"
      } ]
    },
    "firstName" : "John",
    "lastName" : "Doe",
    "socialSecurityNumber" : "",
    "gender" : "MALE",
    "dateOfBirth" : "1980-12-24",
    "placeOfBirth" : {
      "city" : "Amsterdam",
      "state" : "NH",
      "country" : "NLD"
    },
    "nationality" : "NLD",
    "documents" : [ {
      "type" : "ID",
      "number" : "ID1111111",
      "issuedAt" : "2016-07-28",
      "expireAt" : "2023-07-28",
      "issuerCountry" : "NLD",
      "photos" : [ {
        "code" : "FD5CMJEU5M7thvjzs67ZaQK53YFDWJjsWor",
        "extRef" : "ER ID1111111 BACK STRAIGHT",
        "page" : "BACK",
        "style" : "STRAIGHT",
        "format" : "PNG",
        "data" : "ZW1wdHk="
      }, {
        "code" : "FD5CMJEU5M7thvjzrinqmkqaHeZE13gWn5E",
        "extRef" : "ER ID1111111 FRONT STRAIGHT",
        "page" : "FRONT",
        "style" : "STRAIGHT",
        "format" : "JPG",
        "data" : "ZW1wdHk="
      } ],
      "code" : "FD5CMJEU5M7thvjzsTSHP3g3owM8kcjSRE8",
      "extRef" : "ER ID1111111"
    } ]
  } ],
  "documents" : [ {
    "title" : "KVK",
    "issuer" : "COMPANY_REGISTER",
    "issuedAt" : "2019-07-28",
    "issuerCountry" : "NLD",
    "data" : "ZW1wdHk=",
    "code" : "FD5CMJEU5M7rJQ5SsvZHh4tzUyjFZuSLPXN",
    "extRef" : "ER for Payaut B.V KVK"
  } ],
  "legalName" : "Payaut B.V.",
  "taxNumber" : "345422343AE",
  "address" : {
    "street" : "Backershagen",
    "houseNumber" : "99A",
    "addition" : "N/A",
    "city" : "Amsterdam",
    "zipcode" : "1082 GT",
    "country" : "NLD",
    "state" : "Noord Holland"
  },
  "email" : "contact@payaut.com",
  "phone" : "+31623465334",
  "kycStatus" : {
    "status" : "REJECTED",
    "details" : [ {
      "messageType" : "ERROR",
      "messageCode" : "00000000",
      "message" : "Address is a PO box"
    } ]
  }
}

Attributes

PathTypeDescriptionConstraints
typeStringThe type of organization. Possible values: PRIVATE_COMPANY, PUBLIC_COMPANY, NON_PROFIT.
registrationNumberStringThe registration number of the company in the Chamber of Commerce.
ultimateBeneficialOwners[]ArrayThe list of the UBOs associated with the company. This object is an extension of the individual legal entity.
ultimateBeneficialOwners[].typeStringThe UBO type. Possible values: SHARE_HOLDER, CEO, CFO, COO.
documents[]ArrayThe organization documents.
documents[].titleStringA description of the document.
documents[].issuerStringThe issuer of the document. Possible values: COMPANY_REGISTER, TAX_AUTHORITY.
documents[].issuedAtStringThe issuance date of the document.
documents[].issuerCountryStringThe issuer country of the document.
documents[].dataStringThe Base64 encoded string of the document.
documents[].extRefStringPlatform external reference of the document.
legalFormStringThe legal entity form that indicates if the entity is an individual or an organization. In this case, an organization.
legalNameStringThe organization legal name.
taxNumberStringThe organization tax number.
addressObjectThe organization address.
address.streetStringThe organization street address name.
address.houseNumberStringThe organization house number with optional prefix and suffix. For example: 10-11/D.
address.additionStringThe organization address addition, like unit, floor, door, etc.
address.zipcodeStringThe organization address zip code.
address.cityStringThe organization city name.
address.stateStringThe organization state code.
address.countryStringThe organization country code (3 characters only).
emailStringThe organization email.
phoneStringThe organization phone number.
kycStatusObjectThe organization kyc status filled after the creation of the legal entity.
kycStatus.statusStringThe individual kyc status code. Possible values: WAITING_DATA, MISSING_DATA, DATA_RECEIVED, IN_PROGRESS, PASSED, REJECTED, FORGED, FAILED.
kycStatus.details[]ArrayA list containing details about the KYC process.
kycStatus.details[].codeStringPayaut unique reference of the kyc status detail. This field is part of the response payload, so should never be sent in the request.
kycStatus.details[].typeStringThe type of the kyc detail. Possible values: ERROR, ADVICE.
kycStatus.details[].messageCodeStringAn identifier code of the descriptive message bellow.
kycStatus.details[].messageTemplateStringA descriptive message of the error or advice.

Documents

endPoints
POST    /api/v1/accountholders/{code}/individual/documents    HTTP/1.1
POST    /api/v1/accountholders/{code}/organization/documents  HTTP/1.1

This set of endpoints allow the late creation of documents for individual and business legal entities.

The personal document object

The personal document object
{
  "type" : "PASSPORT",
  "number" : "12345",
  "issuedAt" : "2014-01-01",
  "expireAt" : "2024-01-01",
  "photos" : [ {
    "code" : "FD5CMFx3bZiVwsRBTKycuXq33FX7q6FBaNC",
    "page" : "FRONT",
    "style" : "TILTED",
    "format" : "JPG",
    "data" : "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAA1BMVEX/TQBcNTh/AAAAAXRSTlPM0jRW/QAAAApJREFUeJxjYgAAAAYAAzY3fKgAAAAASUVORK5CYII="
  }, {
    "code" : "FD5CMFx3bZiXfADk1TGrsMqJt66XryNvu4k",
    "page" : "FRONT",
    "style" : "STRAIGHT",
    "format" : "JPG",
    "data" : "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAA1BMVEX/TQBcNTh/AAAAAXRSTlPM0jRW/QAAAApJREFUeJxjYgAAAAYAAzY3fKgAAAAASUVORK5CYII="
  } ],
  "code" : "FD5CMFx3bZiW9y2fwGsCh9MZDiSiDoVxVoE"
}
PathTypeDescriptionConstraints
typeStringOne of PASSPORT or ID
expiresAtStringThe Date of expiration of the document being uploaded in the format YYYY-MM-ddMust be a future date
issuedAtStringThe Date the document being uploaded was issued in the format YYYY-MM-ddMust be a past date
numberStringThe number of the document being uploaded. It’s a string, so any alphanumeric value can be used.Must not be blank
photosArrayAn array of objects describing photos for this documentMust not be empty
photos[].pageStringOne of FRONT or BACK
photos[].styleStringOne of STRAIGHT or TILTED
photos[].formatStringOne of JPG or PNG
photos[].dataStringA base 64 string representing the bytes of the photo being uploaded

Create a personal document

POST /api/v1/accountholders/{code}/individual/documents
$ curl 'https://sandbox.payaut.com/api/v1/accountholders/FD5CMFreWNDY8EK7ze9gZfYZLv6crfrVWP2/individual/documents' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi' \
    -d '{
  "type" : "PASSPORT",
  "number" : "12345",
  "issuedAt" : "2014-01-01",
  "expireAt" : "2024-01-01",
  "photos" : [ {
    "page" : "FRONT",
    "style" : "TILTED",
    "format" : "JPG",
    "data" : "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAA1BMVEX/TQBcNTh/AAAAAXRSTlPM0jRW/QAAAApJREFUeJxjYgAAAAYAAzY3fKgAAAAASUVORK5CYII="
  }, {
    "page" : "FRONT",
    "style" : "STRAIGHT",
    "format" : "JPG",
    "data" : "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAA1BMVEX/TQBcNTh/AAAAAXRSTlPM0jRW/QAAAApJREFUeJxjYgAAAAYAAzY3fKgAAAAASUVORK5CYII="
  } ]
}'
Response
{
  "type" : "PASSPORT",
  "number" : "12345",
  "issuedAt" : "2014-01-01",
  "expireAt" : "2024-01-01",
  "photos" : [ {
    "code" : "FD5CMFx3bZiVwsRBTKycuXq33FX7q6FBaNC",
    "page" : "FRONT",
    "style" : "TILTED",
    "format" : "JPG",
    "data" : "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAA1BMVEX/TQBcNTh/AAAAAXRSTlPM0jRW/QAAAApJREFUeJxjYgAAAAYAAzY3fKgAAAAASUVORK5CYII="
  }, {
    "code" : "FD5CMFx3bZiXfADk1TGrsMqJt66XryNvu4k",
    "page" : "FRONT",
    "style" : "STRAIGHT",
    "format" : "JPG",
    "data" : "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAA1BMVEX/TQBcNTh/AAAAAXRSTlPM0jRW/QAAAApJREFUeJxjYgAAAAYAAzY3fKgAAAAASUVORK5CYII="
  } ],
  "code" : "FD5CMFx3bZiW9y2fwGsCh9MZDiSiDoVxVoE"
}

Creates a personal document that will be associated with an individual legal entity.

Path Parameters

ParameterDescription
codeThe account holder code.

Attributes

PathTypeDescriptionConstraints
typeStringOne of PASSPORT or ID
expiresAtStringThe Date of expiration of the document being uploaded in the format YYYY-MM-ddMust be a future date
issuedAtStringThe Date the document being uploaded was issued in the format YYYY-MM-ddMust be a past date
numberStringThe number of the document being uploaded. It’s a string, so any alphanumeric value can be used.Must not be blank
photosArrayAn array of objects describing photos for this documentMust not be empty
photos[].pageStringOne of FRONT or BACK
photos[].styleStringOne of STRAIGHT or TILTED
photos[].formatStringOne of JPG or PNG
photos[].dataStringA base 64 string representing the bytes of the photo being uploaded

The organization document object

The organization document object
{
  "title" : "KVK",
  "issuer" : "COMPANY_REGISTER",
  "issuedAt" : "2018-06-05",
  "issuerCountry" : "NLD",
  "data" : "ZW1wdHk=",
  "code" : "FD5CMJETHRgDazm82Xo3S8K2YVCJk8e2vZv"
}
PathTypeDescriptionConstraints
titleStringA title for this document
issuerStringOne of COMPANY_REGISTER or TAX_AUTHORITY
issuedAtStringThe Date the document being uploaded was issued in the format YYYY-MM-ddMust be a past date
issuerCountryString3-digit country code identifier from the country where the document was issued
dataStringA base 64 string representing the bytes of the document being uploaded

Create an organization document

POST /api/v1/accountholders/{code}/organization/documents
$ curl 'https://sandbox.payaut.com/api/v1/accountholders/FD5CMFreWNDY8EK7ze9gZfYZLv6crfrVWP2/organization/documents' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi' \
    -d '{
  "title" : "KVK",
  "issuer" : "COMPANY_REGISTER",
  "issuedAt" : "2018-06-05",
  "issuerCountry" : "NLD",
  "data" : "ZW1wdHk="
}'
Response
{
  "title" : "KVK",
  "issuer" : "COMPANY_REGISTER",
  "issuedAt" : "2018-06-05",
  "issuerCountry" : "NLD",
  "data" : "ZW1wdHk=",
  "code" : "FD5CMJETHRgDazm82Xo3S8K2YVCJk8e2vZv"
}

Creates an organization document that will be associated with a business legal entity.

Path Parameters

ParameterDescription
codeThe account holder code.

Attributes

PathTypeDescriptionConstraints
titleStringA title for this document
issuerStringOne of COMPANY_REGISTER or TAX_AUTHORITY
issuedAtStringThe Date the document being uploaded was issued in the format YYYY-MM-ddMust be a past date
issuerCountryString3-digit country code identifier from the country where the document was issued
dataStringA base 64 string representing the bytes of the document being uploaded

Accounts

endpoints
POST    /api/v1/accountholders/{accountHolderCode}/accounts                 HTTP/1.1
PATCH   /api/v1/accountholders/{accountHolderCode}/accounts/{accountCode}   HTTP/1.1
GET     /api/v1/accountholders/{accountHolderCode}/accounts/{accountCode}   HTTP/1.1
GET     /api/v1/accountholders/{accountHolderCode}/accounts                 HTTP/1.1

An account is a virtual location where funds can be placed. Splits and payouts use these accounts. An account is always linked to an account owner: an Accountholder, a Merchant or a MerchantDivision. The account api allows you to manage these accounts.

The account object

The account request object
{
  "code" : "FD5CMFusPZUBepKsUaPuof6WYteFa2Ju8E4",
  "extRef" : "My Unique Internal Virtual Account Reference",
  "accountType" : "DEFAULT",
  "displayName" : "My Unique Payaut Virtual Account Display Name"
}
PathTypeDescriptionConstraints
displayNameStringA unique label to make a distinction between different virtual accountsmin = 4, max = 48
extRefStringan external reference to which you like to refer to this accountmin 4, max 32 characters

Create an account

POST /api/v1/accountholders/{accountHolderCode}/accounts
$ curl 'https://sandbox.payaut.com/api/v1/accountholders/FD5CMFreWNDY8EK7ze9gZfYZLv6crfrVWP2/accounts' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi' \
    -d '{
  "extRef" : "My Unique Internal Virtual Account Reference",
  "displayName" : "My Unique Payaut Virtual Account Display Name"
}'
Response
{
  "code" : "FD5CMFusPZUBepKsUaPuof6WYteFa2Ju8E4",
  "extRef" : "My Unique Internal Virtual Account Reference",
  "accountType" : "DEFAULT",
  "displayName" : "My Unique Payaut Virtual Account Display Name"
}

Creates an account that can be used in split payments and payouts.

Path Parameters

ParameterDescription
codeThe account holder code.

Attributes

PathTypeDescriptionConstraints
displayNameStringA unique label to make a distinction between different virtual accountsmin = 4, max = 48
extRefStringan external reference to which you like to refer to this accountmin 4, max 32 characters

Retrieve an account

/api/v1/accountholders/{accountHolderCode}/accounts/{accountCode}
$ curl 'https://sandbox.payaut.com/api/v1/accountholders/FD5CMFreWNDY8EK7ze9gZfYZLv6crfrVWP2/accounts/FD5CMFusPZUBepKsUaPuof6WYteFa2Ju8E4' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "code" : "FD5CMFusPZUBepKsUaPuof6WYteFa2Ju8E4",
  "extRef" : "My Unique Internal Virtual Account Reference",
  "accountType" : "DEFAULT",
  "displayName" : "My Unique Payaut Virtual Account Display Name"
}

Path Parameters

ParameterDescription
codeThe account holder code.
accountCodeThe code of the account

List all accounts

GET /api/v1/accountholders/{accountHolderCode}/accounts
$ curl 'https://sandbox.payaut.com/api/v1/accountholders/FD5CMFreWNDY8EK7ze9gZfYZLv6crfrVWP2/accounts?_pageNumber=1&_pageSize=25&_sort=asc' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "pageSize" : 2,
  "pageNumber" : 0,
  "elements" : [ {
    "code" : "FD5CMFusSGCBWmo6hWQJtFP1Ftd3Qv1CWiC",
    "extRef" : null,
    "accountType" : "DEFAULT",
    "displayName" : "Default-2bec89b5-7d84-4fab-82cc-1e2825f9ddde"
  }, {
    "code" : "FD5CMFuWkR1fMhK8urR8G3tEHyh2oTDFX84",
    "extRef" : null,
    "accountType" : "DEFAULT",
    "displayName" : "Default-2f56474d-58d2-4d96-a453-d92f009f836d"
  } ],
  "totalElementCount" : 2
}

To get a list of all previous created accounts, you can use paging.

ParameterDescription
codeThe account holder code.

Path Parameters

ParameterDescription
codeThe account holder code.

Attributes

ParameterDescription
_pageSizeNumber of elements to be returned in the page result
_pageNumberThe number of requested page
_sortthe request sorting of the page elements

Update an account

PATCH /api/v1/accountholders/{accountHolderCode}/accounts/{accountCode}
$ curl 'https://sandbox.payaut.com/api/v1/accountholders/FD5CMFreWNDY8EK7ze9gZfYZLv6crfrVWP2/accounts/FD5CMFusPZUBepKsUaPuof6WYteFa2Ju8E4' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi' \
    -d '{
  "code" : "FD5CMFusPZUBepKsUaPuof6WYteFa2Ju8E4",
  "extRef" : "My Unique Internal Virtual Account Reference",
  "displayName" : "My Unique Payaut Virtual Account Display Name"
}'
Response
{
  "code" : "FD5CMFusPZUBepKsUaPuof6WYteFa2Ju8E4",
  "extRef" : "My Unique Internal Virtual Account Reference",
  "accountType" : "DEFAULT",
  "displayName" : "My Unique Payaut Virtual Account Display Name"
}

Updating is limited, so not to break splits and payouts that are in progress. You can update the displayName and the extRef

Path Parameters

ParameterDescription
codeThe account holder code.
accountCodeThe code of the account

Attributes

PathTypeDescriptionConstraints
codeStringUnique reference to the virtual accountauto generated
displayNameStringA unique label to make a distinction between different virtual accountsmin = 4, max = 48
extRefStringan external reference to which you like to refer to this accountmin 4, max 32 characters

External accounts

endpoints
POST  /api/v1/accountholders/{accountHolderCode}/externalaccounts    HTTP/1.1
GET  /api/v1/accountholders/{accountHolderCode}/externalaccounts/{externalAccountCode}    HTTP/1.1
GET  /api/v1/accountholders/{accountHolderCode}/externalaccounts    HTTP/1.1

An external account represents an (external) entity with banking capabilities such as a bank account or a PayPal wallet.

It is required while creating a payout request so funds can be withdrawn from Payaut’s platform. Thus, account holders must always be associated with at least one external account.

The external account object

The external account object
{
  "accountType" : "IBAN",
  "accountNumber" : "NLING0562312322",
  "code" : "FD5CMFupEH62gdyC7fznfUMpQuXRnbxbt7z",
  "extRef" : "external_reference",
  "displayName" : "A small description to identify this",
  "description" : "A human readable description for this IBAN",
  "currency" : "EUR",
  "statement" : {
    "issuedAt" : "2020-01-29",
    "data" : "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAA1BMVEX/TQBcNTh/AAAAAXRSTlPM0jRW/QAAAApJREFUeJxjYgAAAAYAAzY3fKgAAAAASUVORK5CYII="
  },
  "kycStatus" : {
    "status" : "WAITING_DATA"
  }
}

Attributes

PathTypeDescription
codeStringUnique identifier to the created external account.
accountNumberStringThe account number such as an IBAN or BBAN.
accountTypeStringThe type of the external account.
extRefStringA unique, platform-provided reference to this external account.
displayNameStringA unique label to make a distinction between different external accounts.
descriptionStringHuman readable description for this external account.
currencyStringThe currency for this external account.
statementObjectAn object containing bank statement data for KYC purposes.
statement.dataStringThe Base64 encoded string of the bank statement.
statement.issuedAtStringThe date when the bank statement was issued.
kycStatusObjectAn object representing the status of this external account KYC check.
kycStatus.statusStringThe KYC status of the account holder. Possible values: WAITING_DATA, MISSING_DATA, DATA_RECEIVED, IN_PROGRESS, PASSED, REJECTED, FORGED, FAILED.

Create an external account

POST /api/v1/accountholders/{accountHolderCode}/externalaccounts
$ curl 'https://sandbox.payaut.com/api/v1/accountholders/FD5CMFreWNDY8EK7ze9gZfYZLv6crfrVWP2/externalaccounts' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi' \
    -d '{
  "accountType" : "IBAN",
  "accountNumber" : "NLING0562312322",
  "extRef" : "CustomerProvidedRefToThisIBAN",
  "displayName" : "A Label to uniquely identify this IBAN",
  "description" : "A human readable description for this IBAN",
  "currency" : "EUR",
  "statement" : {
    "issuedAt" : "2020-01-29",
    "data" : "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAA1BMVEX/TQBcNTh/AAAAAXRSTlPM0jRW/QAAAApJREFUeJxjYgAAAAYAAzY3fKgAAAAASUVORK5CYII="
  }
}'
Response
{
  "accountType" : "IBAN",
  "accountNumber" : "NLING0562312322",
  "code" : "FD5CMFupEH62gdyC7fznfUMpQuXRnbxbt7z",
  "extRef" : "external_reference",
  "displayName" : "A small description to identify this",
  "description" : "A human readable description for this IBAN",
  "currency" : "EUR",
  "statement" : {
    "issuedAt" : "2020-01-29",
    "data" : "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAA1BMVEX/TQBcNTh/AAAAAXRSTlPM0jRW/QAAAApJREFUeJxjYgAAAAYAAzY3fKgAAAAASUVORK5CYII="
  },
  "kycStatus" : {
    "status" : "WAITING_DATA"
  }
}

Creates an external account that can be used in payouts.

Path Parameters

ParameterDescription
accountHolderCodeThe code of the merchant(division) or seller holding this account

Attributes

PathTypeDescriptionConstraints
displayNameStringA unique label to make a distinction between different IBANs
extRefStringA client provided reference to this IBAN
descriptionStringHuman readable description for this IBAN
currencyStringStandard three letter currency codeMandatory.
accountTypeStringFixed value of ‘IBAN’ for this call
accountNumberStringThe actual IBAN numberMandatory
statementObjectAn object containing bank statement data for KYC purposesOptional
statement.dataStringBase64 of the bytes of a .pdf bank statement exportMandatory
statement.issuedAtStringThe date when the .pdf bank statement was issuedformat: YYYY-MM-dd

Retrieve an external account

/api/v1/accountholders/{accountHolderCode}/externalaccounts/{externalAccountCode}
$ curl 'https://sandbox.payaut.com/api/v1/accountholders/FD5CMFreWNDY8EK7ze9gZfYZLv6crfrVWP2/externalaccounts/FD5CMFupEH62gdyC7fznfUMpQuXRnbxbt7z' -i -X GET \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "accountType" : "IBAN",
  "accountNumber" : "NLING0562312322",
  "code" : "FD5CMFupEH62gdyC7fznfUMpQuXRnbxbt7z",
  "extRef" : "external_reference",
  "displayName" : "A small description to identify this",
  "description" : "A human readable description for this IBAN",
  "currency" : "EUR",
  "statement" : {
    "issuedAt" : "2020-01-29",
    "data" : "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAA1BMVEX/TQBcNTh/AAAAAXRSTlPM0jRW/QAAAApJREFUeJxjYgAAAAYAAzY3fKgAAAAASUVORK5CYII="
  },
  "kycStatus" : {
    "status" : "WAITING_DATA"
  }
}

Path Parameters

ParameterDescription
accountHolderCodeThe code of the merchant(division) or seller holding this account
externalAccountCodeThe code of the external account

List all accounts

GET /api/v1/accountholders/{accountHolderCode}/externalaccounts
$ curl 'https://sandbox.payaut.com/api/v1/accountholders/FD5CMFreWNDY8EK7ze9gZfYZLv6crfrVWP2/externalaccounts?_pageNumber=0&_pageSize=25' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "pageSize" : 25,
  "pageNumber" : 0,
  "elements" : [ {
    "accountType" : "IBAN",
    "accountNumber" : "NLING0562312322",
    "code" : "FD5CMFuWkRMrZmCcwDRFEnGBuSR9ybLHWqW",
    "extRef" : "external_reference",
    "displayName" : "A Label for this IBAN account",
    "description" : "A human readable description for this IBAN",
    "currency" : "EUR",
    "statement" : {
      "issuedAt" : "2020-01-29",
      "data" : null
    }
  } ],
  "totalElementCount" : 1
}

To get a list of all previous created external accounts, you can use paging.

ParameterDescription
accountHolderCodeThe code of the merchant(division) or seller holding this account

Path Parameters

ParameterDescription
accountHolderCodeThe code of the merchant(division) or seller holding this account

Attributes

ParameterDescription
_pageSizeNumber of elements returned in this page
_pageNumberThe number of this page

Account Balance

endpoints
GET /api/v1/fund/balance/{code} HTTP/1.1

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 less the pending charges.


Retrieve payout balance

GET /api/v1/fund/balance/{code}
$ curl 'https://sandbox.payaut.com/api/v1/fund/balance/FD5CMJETHJ8RmZ7kZdMjE5SXbgoDRC9hfqi' -i -X GET \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "code" : "FD5CMJETHJ8RmZ7kZdMjE5SXbgoDRC9hfqi",
  "amount" : 2424
}

Retrieves the balance for given account, you need to provide the code that was generated and returned during the creation of this particular account.

Path Parameters

ParameterDescription
codeThe account code for which to request the payout balance


Payment splits

endpoints
POST /api/v1/fund/split-payments        HTTP/1.1
GET  /api/v1/fund/split-payments        HTTP/1.1
GET  /api/v1/fund/split-payments/{code} HTTP/1.1

A payment split request specifies how funds should be split between merchants and account holders.

Split instructions are defined inside the items object, which contains information on how to split the funds. This field can be represented as a tree although for simple cases it’s not required.

More details on split items

In more complex scenarios, like a split with multiple fees attached, a split can be represented as a tree that contains groups and items.

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. Then, the balances should be fixed manually by the merchant through balance transfers.

In more complex scenarios, with nested sub-items, if a virtual account is defined in a parent item and not defined in the sub-item itself, the virtual account defined in the parent will be used.

In summary, the rule of thumb to identify virtual accounts inside a split is the follow: try to get the virtual account defined in the split item; if it fails, try to get the virtual account from the parent split item; finally, if the past step also fails, use the merchant liable virtual account.

A note about the label field

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.

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.

The payment split object

The payment object
{
  "code" : "FD5CMJETHPFXZeBdMatMsGxgcsTPC4EBDUt",
  "extRef" : "platformOrderId#123",
  "totalAmount" : 70700,
  "description" : "Your Platform Order Description",
  "items" : [ {
    "code" : "FD5CMJETHPFXZeBdMxD5fvVSNWSQji8uwn8",
    "type" : "ITEM",
    "label" : "SHIPPING",
    "extRef" : "platformOrderId#123#shipping",
    "amount" : 700,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "$7.00 shipping fee charged by the platform"
  }, {
    "code" : "FD5CMJETHPFXZeBdNKXoUZxw8Q8QNC8rQzc",
    "type" : "GROUP",
    "extRef" : "platformOrderId#123#accountHolder#123",
    "amount" : 70000,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "This groups the split items for account holder A",
    "items" : [ {
      "code" : "FD5CMFuEWXbdJHC32FfXFA8wPTZfWuierzU",
      "type" : "GROUP",
      "extRef" : "platformOrderId#123#accountHolder#123#productXXX",
      "amount" : 40000,
      "description" : "This groups the split items for product item XXX",
      "items" : [ {
        "code" : "FD5CMFuEWXbf5qtTeuT1BUe5hUFPah1775J",
        "type" : "ITEM",
        "label" : "PRODUCT_ITEM",
        "extRef" : "platformOrderId#123#accountHolder#123#productXXX#item",
        "amount" : 40000,
        "description" : "Product item XXX"
      }, {
        "code" : "FD5CMFuEWXbfxNUCATc6aXUXKrie8ukMuEp",
        "type" : "ITEM",
        "label" : "DISCOUNT",
        "extRef" : "platformOrderId#123#accountHolder#123#productXXX#discount",
        "amount" : 2000,
        "description" : "Discount applied on product XXX"
      }, {
        "code" : "FD5CMFuEWXbftWy5Nw528oszxd1VFbTFtUg",
        "type" : "ITEM",
        "label" : "COMMISSION",
        "extRef" : "platformOrderId#123#accountHolder#123#productXXX#commission",
        "amount" : 2000,
        "description" : "Commission for product item YYY"
      } ]
    }, {
      "code" : "FD5CMFuEWXbfNLq1uSQKLPo8qvQ3mvsZLqv",
      "type" : "GROUP",
      "extRef" : "platformOrderId#123#accountHolder#123#productYYY",
      "amount" : 30000,
      "description" : "This groups the split items for product item YYY",
      "items" : [ {
        "code" : "FD5CMFuEWXbgztzADRRDxwMX8o9sjr64Fmi",
        "type" : "ITEM",
        "label" : "PRODUCT_ITEM",
        "extRef" : "platformOrderId#123#accountHolder#123#productYYY#item",
        "amount" : 30000,
        "description" : "Product item YYY"
      }, {
        "code" : "FD5CMFuEWXbheakYF4wXUZPesioMRjBbYVW",
        "type" : "ITEM",
        "label" : "COMMISSION",
        "extRef" : "platformOrderId#123#accountHolder#123#productYYY#commission",
        "amount" : 1500,
        "description" : "Commission for product item YYY"
      } ]
    }, {
      "code" : "FD5CMFuEWXbh82iGtp7NEyhpgbWqshB8rDn",
      "type" : "ITEM",
      "label" : "HANDLING_FEE",
      "extRef" : "platformOrderId#123#accountHolder#123#handlingFee",
      "amount" : 7000,
      "description" : "handling fee: 70.00"
    } ]
  } ],
  "extProcessedAt" : "2020-09-03T08:15:30Z",
  "pspExtRef" : "tr_IJdHG8fjgl",
  "pspResponse" : {
    "type" : "PAYMENT",
    "data" : "eyJkYXRhIjoiTW9sbGllIHBzcCByZXNwb25zZSBkYXRhIn0"
  },
  "currency" : "EUR",
  "paymentProcessor" : "MOLLIE",
  "paymentMethod" : "iDEAL"
}
PathTypeDescriptionConstraints
codeStringUnique identifier returned when the payment split is created.
extRefStringUnique reference generated by the platform.
totalAmountNumberGross amount of the payment in cents.
currencyStringThe currency in which the amount is described.
pspExtRefStringThe psp/acquirer reference that uniquely identifies the payment.
paymentProcessorStringThe payment processor identifier.
paymentMethodStringThe method of payment, such as VISA, MasterCard, iDEAL, PAYPAL, etc.
pspResponseObjectThe response object received from the payment processor.
pspResponse.typeStringThe type of the payment processor response.
pspResponse.dataStringThe whole response string encoded in Base64 format.
descriptionStringHuman-readable description of the payment split.
extProcessedAtStringThe time when the payment was processed either on the platform or PSP side. In most of the cases, this is not the time when this API is called rather the time when the PSP is called.
items[]ArraySplit items.
items[].typeStringType of the item.
items[].labelStringLabel of the item.
items[].codeStringSplit item unique identifier.
items[].extRefStringUnique reference generated by the platform for this split item.
items[].amountNumberThe gross amount of the specific split item in cents.
items[].accountCodeStringThe account code of the target account owner.
items[].descriptionStringHuman-readable description of the payment split item.
items[].itemsArrayThe split sub-items tree up to two levels depth.

Create a payment split

POST /api/v1/fund/split-payments
$ curl 'https://sandbox.payaut.com/api/v1/fund/split-payments' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi' \
    -d '{
  "extRef" : "platformOrderId#123",
  "totalAmount" : 7000,
  "description" : "Your Platform Order Description",
  "items" : [ {
    "type" : "ITEM",
    "label" : "COMMISSION",
    "extRef" : "platformOrderId#123#commission",
    "amount" : 2000,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "Human readable description of this split payment item"
  }, {
    "type" : "ITEM",
    "label" : "PRODUCT_ITEM",
    "extRef" : "platformOrderId#123#item#1",
    "amount" : 5000,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "Human readable description of this split payment item"
  } ],
  "extProcessedAt" : "2020-09-03T08:15:30Z",
  "pspExtRef" : "8464849469846894",
  "currency" : "EUR",
  "paymentProcessor" : "ADYEN",
  "paymentMethod" : "VISA"
}'
Response
{
  "code" : "FD5CMJETHNySAWHnGGnaN2E99JQTE51MQyv",
  "extRef" : "platformOrderId#123",
  "totalAmount" : 7000,
  "description" : "Your Platform Order Description",
  "items" : [ {
    "code" : "FD5CMJETHNySAWHnGe7JAfkttwPUzP4rta4",
    "type" : "ITEM",
    "label" : "COMMISSION",
    "extRef" : "platformOrderId#123#commission",
    "amount" : 2000,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "Human readable description of this split payment item"
  }, {
    "code" : "FD5CMJETHNySAWHnH1S1yKEPeq5UYoeRgGG",
    "type" : "ITEM",
    "label" : "PRODUCT_ITEM",
    "extRef" : "platformOrderId#123#item#1",
    "amount" : 5000,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "Human readable description of this split payment item"
  } ],
  "extProcessedAt" : "2020-09-03T08:15:30Z",
  "pspExtRef" : "8464849469846894",
  "currency" : "EUR",
  "paymentProcessor" : "ADYEN",
  "paymentMethod" : "VISA"
}

Creates a payment split request that will further be processed and paid out according to the instructions provided.

Attributes

PathTypeDescriptionConstraints
extRefStringUnique reference generated by the platform. This reference must be sent to the PSP (e.g. Adyen calls this field “Merchant Reference”) so it will show up in the PSP settlement report. If the PSP does not support a merchant reference or some kind of a metadata field, use the PSP payment reference in that case. However, we strongly suggest to use a platform-wide unique value. Example: platform order id.Mandatory. Regex: ^[a-z|A-Z|0-9|#|@|:||-|_]{4,64}$
totalAmountNumberGross amount of the payment as a positive integer (cents in euro, penny for pounds, etc).Mandatory
currencyStringISO 4217 currency code, composed exactly by 3 letters.Mandatory
pspExtRefStringThe psp/acquirer reference that uniquely identifies the payment. If the extRef attribute is not reflected in the payment processor settlement report, this field must be set.Optional
paymentProcessorStringThe payment processor identifier.Mandatory. Possible values: ADYEN, MOLLIE
paymentMethodStringThe method of payment, such as VISA, MasterCard, iDEAL, PAYPAL, etc.Mandatory
pspResponseObjectThe response object received from the payment processor before the payment split request is sent.Optional
pspResponse.typeStringThe unique identifier of the payment processor response type.Mandatory
pspResponse.dataStringThe whole response string encoded with Base64 format.Mandatory
descriptionStringHuman-readable description of the payment split.Optional
extProcessedAtStringThe time at which the payment was processed on the platform or PSP side in the ISO-8601 calendar system, such as `2020-09-03T10:15:30+02:00`.Mandatory
items[]ArraySplit items represented as a tree containing groups and sub-items.Mandatory
items[].typeStringType of the item. The `GROUP` type can be the root or an internal node of the tree while the `ITEM` type represents a leaf node.Mandatory. Possible values: ITEM, GROUP
items[].labelStringLabel of the item. This field is used as a subtype of the split item and helps to identify the correct fund movements that should be done while processing the payment split.Mandatory when items[].type is equals `ITEM`. Possible values: COMMISSION, DISCOUNT, DEFICIENCY, HANDLING_FEE, PAYMENT_FEE, PLATFORM_DISCOUNT, PRODUCT_ITEM, RMA_FEE, SHIPPING
items[].extRefStringUnique reference generated by the platform for this split item. It has to be unique for that specific payment, but we strongly suggest to use a platform-wide unique value to ensure the required uniqueness. Example: a combination of platform order id (merchant reference) and product reference.Mandatory. Regex: ^[a-z|A-Z|0-9|#|@|:||-|_]{4,64}$
items[].amountNumberPositive integer that represents the gross amount of the split item (cents in euro, pennies in pounds, etc).Mandatory
items[].accountCodeStringThe account code of the target account owner. This code can be retrieved through the Accounts endpoints. If not defined, some assumptions will be made based on items[].label.Optional
items[].descriptionStringHuman-readable description of the payment split item.Optional
items[].itemsArrayThe split sub-items tree up to two levels depth. Usually defined when items[].type is equals `GROUP`.Optional

Retrieve a payment split

GET /api/v1/fund/split-payments/{code}
$ curl 'https://sandbox.payaut.com/api/v1/fund/split-payments/FD5CMJETHP5SzAfhSM2vGJUsGMqb6VPRxiU' -i -X GET \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "code" : "FD5CMJETHP5SzAfhSM2vGJUsGMqb6VPRxiU",
  "extRef" : "platformOrderId#123",
  "totalAmount" : 7000,
  "description" : "Your Platform Order Description",
  "items" : [ {
    "code" : "FD5CMJETHP5SzAfhSiMe4x1d1zpcgR5tj3n",
    "type" : "ITEM",
    "label" : "COMMISSION",
    "extRef" : "platformOrderId#123#commission",
    "amount" : 2000,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "Human readable description of this split payment item"
  }, {
    "code" : "FD5CMJETHP5SzAfhT5gMsbV7mtWc9aKf5Z2",
    "type" : "ITEM",
    "label" : "PRODUCT_ITEM",
    "extRef" : "platformOrderId#123#item#1",
    "amount" : 5000,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "Human readable description of this split payment item"
  } ],
  "extProcessedAt" : "2020-09-03T08:15:30Z",
  "pspExtRef" : "8464849469846894",
  "currency" : "EUR",
  "paymentProcessor" : "ADYEN",
  "paymentMethod" : "VISA"
}

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

Path Parameters

ParameterDescription
codeThe split code generated when a payment split is created.

List all payment splits

GET /api/v1/fund/split-payments
$ curl 'https://sandbox.payaut.com/api/v1/fund/split-payments?_from=2020-05-22T08:00:00Z&_to=2020-05-25T18:00:00Z&_pageNumber=1&_pageSize=25&_asc=false' -i -X GET \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "pageSize" : 1,
  "pageNumber" : 1,
  "elements" : [ {
    "code" : "FD5CMJETHPALrZ6jWkQFQuScQd7AsJmX8zC",
    "extRef" : "platformOrderId#123",
    "totalAmount" : 7000,
    "description" : "Your Platform Order Description",
    "items" : [ {
      "code" : "FD5CMJETHPALrZ6jX7iyDYyNAG6CVFHRhiQ",
      "type" : "ITEM",
      "label" : "COMMISSION",
      "extRef" : "platformOrderId#123#commission",
      "amount" : 2000,
      "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
      "description" : "Human readable description of this split payment item"
    }, {
      "code" : "FD5CMJETHPALrZ6jXV3h2CSrv9nC3Sn7aXr",
      "type" : "ITEM",
      "label" : "PRODUCT_ITEM",
      "extRef" : "platformOrderId#123#item#1",
      "amount" : 5000,
      "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
      "description" : "Human readable description of this split payment item"
    } ],
    "extProcessedAt" : "2020-09-03T08:15:30Z",
    "pspExtRef" : "8464849469846894",
    "currency" : "EUR",
    "paymentProcessor" : "ADYEN",
    "paymentMethod" : "VISA"
  } ],
  "totalElementCount" : 1
}

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

Request Parameters

ParameterDescription
_fromThe initial date used to query. Format: `yyyy-MM-dd’T'HH:mm:ss.SSSXXX`.
_toThe final date used to query. Format: `yyyy-MM-dd’T'HH:mm:ss.SSSXXX`.
_pageNumberpageNumber.
_pageSizeresultsPerPage.
_ascasc.

Refund splits

endpoints
POST /api/v1/fund/split-refunds        HTTP/1.1
GET  /api/v1/fund/split-refunds        HTTP/1.1
GET  /api/v1/fund/split-refunds/{code} HTTP/1.1

A refund split request can be sent to our platform as a full or a partial refund. Refunds are usually processed after the associated payment has already been processed or settled. Thus, it needs some information from the payment to be processed, like providing the same extRef value used in the payment.

Matching refunds from a PSP/Acquirer report

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.

The refund split object

The refund object
{
  "code" : "FD5CMJETHLQEymTJT1djmFznbYhL6PXuPQt",
  "extRef" : "platformOrderId#123",
  "totalAmount" : 40000,
  "description" : "Your Platform Refund Description",
  "items" : [ {
    "code" : "FD5CMJETHLQEymTJTNxTZuFFNTDB4mpomZr",
    "type" : "GROUP",
    "extRef" : "refund#123#accountHolder#123",
    "originalExtRef" : "platformOrderId#123#accountHolder#123",
    "amount" : 40000,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "This groups the refunded items for account holder A",
    "items" : [ {
      "code" : "FD5CMFuZdxSphnjTNdpJdRRnKS25ussyo2p",
      "type" : "GROUP",
      "extRef" : "refund#123#accountHolder#123#productXXX",
      "originalExtRef" : "platformOrderId#123#accountHolder#123#productXXX",
      "amount" : 40000,
      "description" : "This groups the refunded items for product item XXX",
      "items" : [ {
        "code" : "FD5CMFuZdxSpPX96uCNJAZLQCi3dJRmihqS",
        "type" : "ITEM",
        "label" : "PRODUCT_ITEM",
        "extRef" : "refund#123#accountHolder#123#productXXX#item",
        "originalExtRef" : "platformOrderId#123#accountHolder#123#productXXX#item",
        "amount" : 40000,
        "description" : "Refunded product item XXX"
      }, {
        "code" : "FD5CMFuZdxSpBaXj8mYEHSrU3tcde3X594t",
        "type" : "ITEM",
        "label" : "DISCOUNT",
        "extRef" : "refund#123#accountHolder#123#productXXX#discount",
        "originalExtRef" : "platformOrderId#123#accountHolder#123#productXXX#discount",
        "amount" : 2000,
        "description" : "Refunded discount"
      } ]
    }, {
      "code" : "FD5CMFuZdxSq3hjng5xpdRoSX3GtAN8BiLG",
      "type" : "ITEM",
      "label" : "HANDLING_FEE",
      "extRef" : "refund#123#accountHolder#123#handlingFee",
      "originalExtRef" : "platformOrderId#123#accountHolder#123#handlingFee",
      "amount" : 4000,
      "description" : "Refunded handling fee: 40.00"
    } ]
  } ],
  "extProcessedAt" : "2020-09-03T08:15:30Z",
  "pspMutationExtRef" : "8565315484610879"
}
PathTypeDescriptionConstraints
codeStringUnique identifier returned when the refund split is created.
extRefStringSame unique reference as the one created for the associated payment split.
pspMutationExtRefStringPsp/acquirer mutation reference.
totalAmountNumberGross amount of the refund in cents.
descriptionStringHuman-readable description of the refund split.
extProcessedAtStringThe time when the refund was processed either on the platform or PSP side. In most of the cases, this is not the time when this API is called rather the time when the PSP is called.
items[]ArraySplit items.
items[].typeStringType of the item.
items[].labelStringLabel of the item.
items[].codeStringSplit item unique identifier.
items[].extRefStringUnique reference generated by the platform for this split item.
items[].originalExtRefStringThe original split item extRef value from the associated payment split.
items[].amountNumberThe gross amount of the specific split item in cents.
items[].accountCodeStringThe account code of the target account owner.
items[].descriptionStringHuman-readable description of the refund split item.
items[].itemsArrayThe split sub-items tree up to two levels depth.

Create a full refund split

POST /api/v1/fund/split-refunds
$ curl 'https://sandbox.payaut.com/api/v1/fund/split-refunds' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi' \
    -d '{
  "extRef" : "platformOrderId#123",
  "description" : "Human-readable description of the full refund",
  "extProcessedAt" : "2020-09-03T08:15:30Z",
  "pspMutationExtRef" : "RUJSSC"
}'
Response
{
  "extRef" : "platformOrderId#123",
  "description" : "Human-readable description of the full refund",
  "extProcessedAt" : "2020-09-03T08:15:30Z",
  "pspMutationExtRef" : "RUJSSC"
}

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.

Attributes

PathTypeDescriptionConstraints
extRefStringUnique reference generated by the platform. This reference must be sent to the PSP (e.g. Adyen calls this field “Merchant Reference”) so it will show up in the PSP settlement report. If the PSP does not support a merchant reference or a some kind of a metadata field, use the PSP payment reference in that case. However, we strongly suggest to use a platform-wide unique value. Example: platform order id.Mandatory. Regex: ^[a-z|A-Z|0-9|#|@|:||-|_]{4,64}$
pspMutationExtRefStringUnique 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.Mandatory
descriptionStringHuman-readable description of the refund split.Optional

Create a partial refund split

POST /api/v1/fund/split-refunds
$ curl 'https://sandbox.payaut.com/api/v1/fund/split-refunds' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi' \
    -d '{
  "extRef" : "platformOrderId#123",
  "totalAmount" : 2500,
  "description" : "Your Platform Refund Description",
  "items" : [ {
    "type" : "ITEM",
    "label" : "COMMISSION",
    "extRef" : "refund#123#commission",
    "originalExtRef" : "platformOrderId#123#commission",
    "amount" : 500,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "Refunded commission"
  }, {
    "type" : "ITEM",
    "label" : "PRODUCT_ITEM",
    "extRef" : "refund#123#item#1",
    "originalExtRef" : "platformOrderId#123#item#1",
    "amount" : 2000,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "Refunded product item"
  } ],
  "extProcessedAt" : "2020-09-03T08:15:30Z",
  "pspMutationExtRef" : "8565315484610879"
}'
Response
{
  "code" : "FD5CMJETHKzE6ecBjtCe3ULhg8BjyifYdzp",
  "extRef" : "platformOrderId#123",
  "totalAmount" : 2500,
  "description" : "Your Platform Refund Description",
  "items" : [ {
    "code" : "FD5CMJETHKzE6ecBkFXMr7bAT2hamWZrRV2",
    "type" : "ITEM",
    "label" : "COMMISSION",
    "extRef" : "refund#123#commission",
    "originalExtRef" : "platformOrderId#123#commission",
    "amount" : 500,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "Refunded commission"
  }, {
    "code" : "FD5CMJETHKzE6ecBkcr5em4fCvPaBMwENU8",
    "type" : "ITEM",
    "label" : "PRODUCT_ITEM",
    "extRef" : "refund#123#item#1",
    "originalExtRef" : "platformOrderId#123#item#1",
    "amount" : 2000,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "Refunded product item"
  } ],
  "extProcessedAt" : "2020-09-03T08:15:30Z"
}

Creates a partial refund split request for a given payment. If amount, accountCode or label are not provided, the correspondent values of the payment split will be used.

Attributes

PathTypeDescriptionConstraints
extRefStringSame unique reference as the one created for the associated payment split.Mandatory. Regex: ^[a-z|A-Z|0-9|#|@|:||-|_]{4,64}$
pspMutationExtRefStringUnique 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.Mandatory
totalAmountNumberGross amount of the payment as a positive integer (cents in euro, penny for pounds, etc).Mandatory
descriptionStringHuman-readable description of the refund split.Optional
extProcessedAtStringThe 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`.Mandatory
items[]ArraySplit items represented as a tree containing groups and sub-items.Mandatory
items[].typeStringType of the item. The `GROUP` type can be the root or an internal node of the tree while the `ITEM` type represents a leaf node.Mandatory. Possible values: ITEM, GROUP
items[].labelStringLabel of the item. This field is used as a subtype of the split item and helps to identify the correct fund movements that should be done while processing the payment split.Mandatory when items[].type is equals `ITEM`. Possible values: COMMISSION, DISCOUNT, DEFICIENCY, HANDLING_FEE, PAYMENT_FEE, PLATFORM_DISCOUNT, PRODUCT_ITEM, RMA_FEE, REFUND_FEE, REFUND_VAT, SHIPPING
items[].extRefStringUnique reference generated by the platform for this split item. It has to be unique for that specific payment, but we strongly suggest to use a platform-wide unique value to ensure the required uniqueness. Example: a combination of platform order id (merchant reference) and product reference.Mandatory. Regex: ^[a-z|A-Z|0-9|#|@|:||-|_]{4,64}$
items[].originalExtRefStringThe original split item extRef value from the associated payment split.Mandatory. Regex: ^[a-z|A-Z|0-9|#|@|:||-|_]{4,64}$
items[].amountNumberPositive integer that represents the gross amount of the split item (cents in euro, pennies in pounds, etc).Mandatory
items[].accountCodeStringThe account code of the target account owner. This code can be retrieved through the Accounts endpoints. If not defined, some assumptions will be made based on items[].label.Optional
items[].descriptionStringHuman-readable description of the refund split item.Optional

Retrieve a refund split

GET /api/v1/fund/split-refunds/{code}
$ curl 'https://sandbox.payaut.com/api/v1/fund/split-refunds/FD5CMJETHLJrF33emsD4wuo3ubaPj2bateC' -i -X GET \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "code" : "FD5CMJETHLJrF33emsD4wuo3ubaPj2bateC",
  "extRef" : "platformOrderId#123",
  "totalAmount" : 2500,
  "description" : "Your Platform Refund Description",
  "items" : [ {
    "code" : "FD5CMJETHLJrF33enEXnkZ3WgW6EPew3VUc",
    "type" : "ITEM",
    "label" : "COMMISSION",
    "extRef" : "refund#123#commission",
    "originalExtRef" : "platformOrderId#123#commission",
    "amount" : 500,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "Refunded commission"
  }, {
    "code" : "FD5CMJETHLJrF33enbrWZCX1SPnE7FjfD9r",
    "type" : "ITEM",
    "label" : "PRODUCT_ITEM",
    "extRef" : "refund#123#item#1",
    "originalExtRef" : "platformOrderId#123#item#1",
    "amount" : 2000,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "Refunded product item"
  } ],
  "extProcessedAt" : "2020-09-03T08:15:30Z",
  "pspMutationExtRef" : "8565315484610879"
}

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

ParameterDescription
codeThe split code generated when a refund split is created.

List all refund splits

GET /api/v1/fund/split-refunds
$ curl 'https://sandbox.payaut.com/api/v1/fund/split-refunds?_from=2020-05-22T08:00:00Z&_to=2020-05-25T18:00:00Z&_pageNumber=1&_pageSize=25&_asc=false' -i -X GET \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "pageSize" : 1,
  "pageNumber" : 1,
  "elements" : [ {
    "code" : "FD5CMJETHLDFUfKFGQqqmauejwgijaadacY",
    "extRef" : "platformOrderId#123",
    "totalAmount" : 2500,
    "description" : "Your Platform Refund Description",
    "items" : [ {
      "code" : "FD5CMJETHLDFUfKFGnAZaEA7WrCZtZqXVjW",
      "type" : "ITEM",
      "label" : "COMMISSION",
      "extRef" : "refund#123#commission",
      "originalExtRef" : "platformOrderId#123#commission",
      "amount" : 500,
      "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
      "description" : "Refunded commission"
    }, {
      "code" : "FD5CMJETHLDFUfKFH9VHNsdcGjtZSqt9rQx",
      "type" : "ITEM",
      "label" : "PRODUCT_ITEM",
      "extRef" : "refund#123#item#1",
      "originalExtRef" : "platformOrderId#123#item#1",
      "amount" : 2000,
      "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
      "description" : "Refunded product item"
    } ],
    "extProcessedAt" : "2020-09-03T08:15:30Z"
  } ],
  "totalElementCount" : 1
}

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

Request Parameters

ParameterDescription
_fromThe initial date used to query. Format: yyyy-MM-dd’T'HH:mm:ss.SSSXXX
_toThe final date used to query. Format: yyyy-MM-dd’T'HH:mm:ss.SSSXXX
_pageNumberpageNumber
_pageSizeresultsPerPage
_ascasc

Payouts

endpoints
POST /api/v1/fund/payout-requests HTTP/1.1
DELETE /api/v1/fund/payout-requests/{code} HTTP/1.1
GET /api/v1/fund/payout-requests/{code} HTTP/1.1
GET /api/v1/fund/payout-requests HTTP/1.1

A payout request is similar to a withdrawal request that may or may not be fulfilled. Once requested, it will be saved in the waiting status, queued and processed asynchronously when the time arrives.

The platform must implement a polling mechanism to keep track of status changes about a particular payout request. Thus, a unique code is returned every time a new request is created for further tracking.

There are some requirements for the payout request to be successful:

  1. The account holder owning the specified virtual account must already be KYC verified.
  2. The external account must already be KYC verified.
  3. The balance in the account must be sufficient.

In case any of the previous requirements are not filled, the payout request will be denied.


The payout request object

The payout request object
{
  "code" : "FD5CMGdfTBW1pWh8AZnci7eHuu93JLxM3zY",
  "createdAt" : "2021-07-28T15:15:43.707199+02:00",
  "processAt" : "2021-07-29T15:15:43.707223+02:00",
  "useBalanceAt" : "2021-07-29T15:15:43.707223+02:00",
  "accountCode" : "FD5CMGdfT7g7VxgUvVKSJT3tc6YKgan7GWt",
  "externalAccountCode" : "FD5CMGdfT7g56S1vx4Qc1vDEmN52G8NrWFi",
  "amount" : 1000,
  "description" : "This is a test",
  "status" : "WAITING"
}
PathTypeDescriptionConstraints
codeStringUnique identifier returned when the payout request is created.
createdAtStringThe date and time at which the payout request was created, in the ISO-8601 calendar system, such as `2020-09-03T10:15:30+02:00`.
processAtStringThe date and time, in the ISO-8601 calendar system, at which this money transfer will be due. If not specified, will be immediate.
useBalanceAtStringThe date and time, in the ISO-8601 calendar system, at which the balance will be checked against for this request. If specified, the amount attribute must be omitted. Make sure to keep a margin for subsequent refunds and fees.
accountCodeStringThe account code of the account owner holding the balance
externalAccountCodeStringThe account code of the account owner for which the payout should be transferred to.
amountNumberThe amount to payout, in cents. If you provide this attribute, you must omit the useBalanceAt attribute. If neither amount nor useBalanceAt is specified, all funds will be withdrawn.
descriptionStringThe description that will show up in the destination account bank statement.
statusStringThe current status of the payout request. Possible values: WAITING, ACCEPTED, REJECTED, FAILED, PROCESSED.

Create a payout request

POST /api/v1/fund/payout-requests
$ curl 'https://sandbox.payaut.com/api/v1/fund/payout-requests' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi' \
    -d '{
  "processAt" : "2021-07-29T15:15:43.707223+02:00",
  "useBalanceAt" : "2021-07-29T15:15:43.707223+02:00",
  "accountCode" : "FD5CMGdfT7g7VxgUvVKSJT3tc6YKgan7GWt",
  "externalAccountCode" : "FD5CMGdfT7g56S1vx4Qc1vDEmN52G8NrWFi",
  "amount" : 1000,
  "description" : "This is a test"
}'
Response
{
  "code" : "FD5CMGdfTBW1pWh8AZnci7eHuu93JLxM3zY",
  "createdAt" : "2021-07-28T15:15:43.707199+02:00",
  "processAt" : "2021-07-29T15:15:43.707223+02:00",
  "useBalanceAt" : "2021-07-29T15:15:43.707223+02:00",
  "accountCode" : "FD5CMGdfT7g7VxgUvVKSJT3tc6YKgan7GWt",
  "externalAccountCode" : "FD5CMGdfT7g56S1vx4Qc1vDEmN52G8NrWFi",
  "amount" : 1000,
  "description" : "This is a test",
  "status" : "WAITING"
}

Creates a payout request that will further be paid out according to the instructions provided.

Attributes

PathTypeDescriptionConstraints
processAtStringThe date and time, in the ISO-8601 calendar system, at which this money transfer will be due. If not specified, will be immediate.Optional
useBalanceAtStringThe date and time, in the ISO-8601 calendar system, at which the balance will be checked against for this request. If specified, the amount attribute must be omitted. Make sure to keep a margin for subsequent refunds and fees.Optional
accountCodeStringThe account code of the account owner holding the balanceMandatory
externalAccountCodeStringThe account code of the account owner for which the payout should be transferred to.Mandatory
amountNumberThe amount to payout, in cents. If you provide this attribute, you must omit the useBalanceAt attribute. If neither amount nor useBalanceAt is specified, all funds will be withdrawn.Optional
descriptionStringThe description that will show up in the destination account bank statement.Optional

Retrieve a payout request

GET /api/v1/fund/payout-requests/{code}
$ curl 'https://sandbox.payaut.com/api/v1/fund/payout-requests/FD5CMGdfTBW1pWh8AZnci7eHuu93JLxM3zY' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "code" : "FD5CMGdfTBW1pWh8AZnci7eHuu93JLxM3zY",
  "createdAt" : "2021-07-28T15:15:43.707199+02:00",
  "processAt" : "2021-07-29T15:15:43.707223+02:00",
  "useBalanceAt" : "2021-07-29T15:15:43.707223+02:00",
  "accountCode" : "FD5CMGdfT7g7VxgUvVKSJT3tc6YKgan7GWt",
  "externalAccountCode" : "FD5CMGdfT7g56S1vx4Qc1vDEmN52G8NrWFi",
  "amount" : 1000,
  "description" : "This is a test",
  "status" : "WAITING"
}

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

ParameterDescription
codethe code of the payout request to retrieve

Delete a payout request

DELETE /api/v1/fund/payout-requests/{code}
$ curl 'https://sandbox.payaut.com/api/v1/fund/payout-requests/FD5CMGdfTBW1pWh8AZnci7eHuu93JLxM3zY' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "code" : "FD5CMGdfTBW1pWh8AZnci7eHuu93JLxM3zY",
  "createdAt" : "2021-07-28T15:15:43.707199+02:00",
  "processAt" : "2021-07-29T15:15:43.707223+02:00",
  "useBalanceAt" : "2021-07-29T15:15:43.707223+02:00",
  "accountCode" : "FD5CMGdfT7g7VxgUvVKSJT3tc6YKgan7GWt",
  "externalAccountCode" : "FD5CMGdfT7g56S1vx4Qc1vDEmN52G8NrWFi",
  "amount" : 1000,
  "description" : "This is a test",
  "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.

ParameterDescription
codethe code of the payout request to delete

List all payout requests

GET /api/v1/fund/payout-requests
$ curl 'https://sandbox.payaut.com/api/v1/fund/payout-requests' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "pageSize" : 1,
  "pageNumber" : 1,
  "elements" : [ {
    "code" : "FD5CMGdfTBW1pWh8AZnci7eHuu93JLxM3zY",
    "createdAt" : "2021-07-28T15:15:43.707199+02:00",
    "processAt" : "2021-07-29T15:15:43.707223+02:00",
    "useBalanceAt" : "2021-07-29T15:15:43.707223+02:00",
    "accountCode" : "FD5CMGdfT7g7VxgUvVKSJT3tc6YKgan7GWt",
    "externalAccountCode" : "FD5CMGdfT7g56S1vx4Qc1vDEmN52G8NrWFi",
    "amount" : 1000,
    "description" : "This is a test",
    "status" : "WAITING"
  } ],
  "totalElementCount" : 1
}

To get a list of all previous payout request, you can use different filters and paging.

Request parameters

ParameterDescription
_fromThe created at date of where the list should begin, in the ISO8601 format of ‘yyyy-MM-dd hh:mm:ss.SSSSSSX’
_toThe created at date of where the list should end. in the ISO8601 format of ‘yyyy-MM-dd hh:mm:ss.SSSSSSX’
_pageNumberThe page number of the paged result set requested
_pageSizenumber of result per page requested
_orderBythe Payout request field the list should be ordered by, see the create() fields. Defaults to createdAt
_ascshould the ordering be ascending or not