NAV Navbar
cURL

Introduction

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

This document describes the integration of the Payaut API V1.0

The Payaut API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

For some async response data, callbacks have to be configured.

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 register a new 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

Path Type Description
code String The Payaut status code, e.g. “422.000.000”.
message String A description of the cause of the error.
parameterized Object An object containing a template message and params so you can build a custom message, if needed.
parameterized.template String A 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.params Object A dynamic object with fields that can replace the placeholders of the template message. Example: {“totalAmount”: “69600”,“sumOfElementsAmount”: “69700”}.
details[] Array Only applicable for 4xx errors.
details[].field String The name of the problematic field.
details[].code String A 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[].message String An 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[].parameterized Object Same object as the one defined above.
details[].attemptedValue Varies The 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" : "FD5CMFy2tzXugdqHmCcjSxsJwqUhtdRQmVa",
  "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" : [ {
        "code" : "FD5CMFy2tzY1QkcZy1i33ddfpgkv2evtPHa",
        "type" : "ERROR",
        "messageCode" : "00000000",
        "messageTemplate" : "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" : "2015-06-08",
      "expireAt" : "2022-06-08",
      "issuerCountry" : "NLD",
      "photos" : [ {
        "code" : "FD5CMFy2tzXyg6VxeS8DmmEvrbqHs68fU1v",
        "extRef" : "ER ID1111111 FRONT STRAIGHT",
        "page" : "FRONT",
        "style" : "STRAIGHT",
        "format" : "JPG",
        "data" : "ZW1wdHk="
      }, {
        "code" : "FD5CMFy2tzXyPAShr6JRzryZPN8jMRueE64",
        "extRef" : "ER ID1111111 BACK STRAIGHT",
        "page" : "BACK",
        "style" : "STRAIGHT",
        "format" : "PNG",
        "data" : "ZW1wdHk="
      } ],
      "code" : "FD5CMFy2tzXyWfPYefnngfTPVz1m6PLj4DW",
      "extRef" : "ER ID1111111"
    } ]
  },
  "externalAccounts" : [ {
    "accountType" : "IBAN",
    "accountNumber" : "NL91ABNA0417164300",
    "code" : "FD5CMFy2tzXw8QDbWAGFWGdix3mcVzMcTxC",
    "extRef" : "ER J. Doe IBAN",
    "displayName" : "NL91 ABNA 0417 1643 00",
    "description" : "J. Doe ABN account",
    "currency" : "EUR",
    "statement" : {
      "issuedAt" : "2017-06-08",
      "data" : "ZW1wdHk="
    },
    "kycStatus" : {
      "status" : "FAILED",
      "details" : [ {
        "code" : "FD5CMFy2tzXxzvgBt4qG6aUMgqBZ3Dkxu2p",
        "type" : "ERROR",
        "messageCode" : "00000000",
        "messageTemplate" : "Invalid bank identifier"
      } ]
    }
  } ],
  "accounts" : [ {
    "code" : "FD5CMFy2tzXy6CK2v2Tp3kmx7CaWbqzMbj6",
    "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"
    }
  }
}
Path Type Description Constraints
extRef String Platform external reference of the account holder.
code String Payaut unique reference of the account holder. This field is part of the response payload, so should never be sent in the request.
displayName String Display name of the account holder that can be displayed in reports or internal systems.
description String A description of the account holder, like the full name or company name.
legalEntity Object The account holder legal entity representation. Please check the `Legal entities` section of this documentation for more details.
externalAccounts[] Array The external accounts of the account holder. Please check the `External accounts` section of this documentation for more details.
accounts[] Array The virtual accounts of the account holder. Please check the `Accounts` section of this documentation for more details.
status Object The KYC status of the account holder.
status.code String The status code of the account holder. Possible values: ACTIVE, NOPAYOUT, SUSPENDED, CLOSED.
status.reason String A descriptive message about the current status code.
status.processedAmount Object The total amount processed so far for the account holder.
status.processedAmount.amount Number The positive integer amount.
status.processedAmount.currency String The 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" : "2015-06-08",
      "expireAt" : "2022-06-08",
      "issuerCountry" : "NLD",
      "photos" : [ {
        "extRef" : "ER ID1111111 FRONT STRAIGHT",
        "page" : "FRONT",
        "style" : "STRAIGHT",
        "format" : "JPG",
        "data" : "ZW1wdHk="
      }, {
        "extRef" : "ER ID1111111 BACK STRAIGHT",
        "page" : "BACK",
        "style" : "STRAIGHT",
        "format" : "PNG",
        "data" : "ZW1wdHk="
      } ],
      "extRef" : "ER ID1111111"
    } ]
  },
  "accounts" : [ {
    "extRef" : "ER AH Default Account",
    "accountType" : "DEFAULT",
    "displayName" : "Account holder default account"
  } ]
}'
Response
{
  "extRef" : "abc123",
  "code" : "FD5CMFy2tzhVsaXU9hYgvMVDrJoLhbesmDz",
  "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" : [ {
        "code" : "FD5CMFy2tzhVVH3W6ANnacbBa9qags2MwHS",
        "type" : "ERROR",
        "messageCode" : "00000000",
        "messageTemplate" : "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" : "2015-06-08",
      "expireAt" : "2022-06-08",
      "issuerCountry" : "NLD",
      "photos" : [ {
        "code" : "FD5CMFy2tzhV4QaDi2kXTdEUsoqhukSqLe4",
        "extRef" : "ER ID1111111 FRONT STRAIGHT",
        "page" : "FRONT",
        "style" : "STRAIGHT",
        "format" : "JPG",
        "data" : "ZW1wdHk="
      }, {
        "code" : "FD5CMFy2tzhVeisspJqb58vU1cD31EiR2Bi",
        "extRef" : "ER ID1111111 BACK STRAIGHT",
        "page" : "BACK",
        "style" : "STRAIGHT",
        "format" : "PNG",
        "data" : "ZW1wdHk="
      } ],
      "code" : "FD5CMFy2tzhW8WwSndH5fyBcxeeagwpjFGc",
      "extRef" : "ER ID1111111"
    } ]
  },
  "accounts" : [ {
    "code" : "FD5CMFy2tzhWapTUbPywWacdjpA91e1nAW4",
    "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

Path Type Description Constraints
extRef String Platform external reference of the account holder. Optional
displayName String A display name for the account holder. Mandatory
description String A description of the account holder. Optional
legalEntity Object The account holder legal entity representation. Please check the `Legal entities` section of this documentation for more details. Optional
accounts[] Array The 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/FD5CMFy2tzrZkdBBAy3K1z9gVWr2XYwuEwJ?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" : "2017-06-08",
      "data" : "ZW1wdHk="
    }
  } ]
}'
Response
{
  "extRef" : "abc123",
  "code" : "FD5CMFy2tzrZkdBBAy3K1z9gVWr2XYwuEwJ",
  "displayName" : "J. Doe",
  "description" : "A brief description of the account holder",
  "externalAccounts" : [ {
    "accountType" : "IBAN",
    "accountNumber" : "NL91ABNA0417164300",
    "code" : "FD5CMFy2tzraE3jQw46Ste2bYEuJxV7mCwz",
    "extRef" : "ER J. Doe IBAN",
    "displayName" : "NL91 ABNA 0417 1643 00",
    "description" : "J. Doe ABN account",
    "currency" : "EUR",
    "statement" : {
      "issuedAt" : "2017-06-08",
      "data" : "ZW1wdHk="
    },
    "kycStatus" : {
      "status" : "FAILED",
      "details" : [ {
        "code" : "FD5CMFy2tzraQR1Hxy6qae9FnBmif9ynNec",
        "type" : "ERROR",
        "messageCode" : "00000000",
        "messageTemplate" : "Invalid bank identifier"
      } ]
    }
  } ],
  "accounts" : [ {
    "code" : "FD5CMFy2tzraygPoUULyp8ZZpuQJMoaL2et",
    "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

Parameter Description
code The account holder code generated when the entity was created.

Attributes

Path Type Description Constraints
legalEntity Object The account holder legal entity representation. Please check the `Legal entities` section of this documentation for more details. Optional
externalAccounts[] Array The 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/FD5CMFy2tzzKyqaUCV5GGcjwD7zVhFYCn6c?_fragments=extacc,kycstatus,accounts' -i -X GET \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "extRef" : "abc123",
  "code" : "FD5CMFy2tzzKyqaUCV5GGcjwD7zVhFYCn6c",
  "displayName" : "J. Doe",
  "description" : "A brief description of the account holder",
  "externalAccounts" : [ {
    "accountType" : "IBAN",
    "accountNumber" : "NL91ABNA0417164300",
    "code" : "FD5CMFy2tzzMvb3D4k4xi3hs8pZriXC373v",
    "extRef" : "ER J. Doe IBAN",
    "displayName" : "NL91 ABNA 0417 1643 00",
    "description" : "J. Doe ABN account",
    "currency" : "EUR",
    "statement" : {
      "issuedAt" : "2017-06-08",
      "data" : "ZW1wdHk="
    },
    "kycStatus" : {
      "status" : "FAILED",
      "details" : [ {
        "code" : "FD5CMFy2tzzN1atX1i72JSTmsu3EBSHb256",
        "type" : "ERROR",
        "messageCode" : "00000000",
        "messageTemplate" : "Invalid bank identifier"
      } ]
    }
  } ],
  "accounts" : [ {
    "code" : "FD5CMFy2tzzMsKbW61Ug1NLfze4XP153eMv",
    "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

Parameter Description
code The account holder code generated when the entity was created.

Request Parameters

Parameter Description
_fragments By default, a thin account holder object is returned unless a fragment is specified to be returned. Possible values: ubo, extacc, kycstatus, docs, docfiles, accounts.

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" : "FD5CMFy2tzQUBSX2EVdeNGURRcUvSWAcEKr",
    "displayName" : "J. Doe",
    "description" : "A brief description of the account holder",
    "externalAccounts" : [ {
      "accountType" : "IBAN",
      "accountNumber" : "NL91ABNA0417164300",
      "code" : "FD5CMFy2tzQXf25HuKrGPkDimSwupdqN2s2",
      "extRef" : "ER J. Doe IBAN",
      "displayName" : "NL91 ABNA 0417 1643 00",
      "description" : "J. Doe ABN account",
      "currency" : "EUR",
      "statement" : {
        "issuedAt" : "2017-06-08",
        "data" : "ZW1wdHk="
      },
      "kycStatus" : {
        "status" : "FAILED",
        "details" : [ {
          "code" : "FD5CMFy2tzQXJHyFVB3KNuTpX2Nq6Gvv6Ec",
          "type" : "ERROR",
          "messageCode" : "00000000",
          "messageTemplate" : "Invalid bank identifier"
        } ]
      }
    } ],
    "accounts" : [ {
      "code" : "FD5CMFy2tzQXb7qU4dut2U9jZwwpUA2JMGt",
      "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

Parameter Description
_fragments By default, a thin account holder object is returned unless a fragment is specified to be returned. Possible values: ubo, extacc, kycstatus, docs, docfiles, accounts.
_pageNumber The number of this page.
_pageSize Number of elements returned in this page.
_sort The 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" : [ {
      "code" : "FD5CMFy2tywTV4qyPje58erNLG5UNMuXSQQ",
      "type" : "ERROR",
      "messageCode" : "00000000",
      "messageTemplate" : "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" : "2015-06-08",
    "expireAt" : "2022-06-08",
    "issuerCountry" : "NLD",
    "photos" : [ {
      "code" : "FD5CMFy2tywQAFV23Q92DYzZcbSPvQQstTJ",
      "extRef" : "ER ID1111111 FRONT STRAIGHT",
      "page" : "FRONT",
      "style" : "STRAIGHT",
      "format" : "JPG",
      "data" : "ZW1wdHk="
    }, {
      "code" : "FD5CMFy2tywPggXuuKK7mvftQQTxqb4DEdv",
      "extRef" : "ER ID1111111 BACK STRAIGHT",
      "page" : "BACK",
      "style" : "STRAIGHT",
      "format" : "PNG",
      "data" : "ZW1wdHk="
    } ],
    "code" : "FD5CMFy2tywQgR8d6ipDyuETHRfGS5TTQpp",
    "extRef" : "ER ID1111111"
  } ]
}

Attributes

Path Type Description Constraints
legalForm String The legal entity form that indicates if the entity is an individual or an organization. In this case, an individual.
legalName String The individual legal name.
firstName String The individual first name.
lastName String The individual last name.
taxNumber String The individual tax number.
socialSecurityNumber String The individual social security number.
gender String The individual gender. Possible values: FEMALE, MALE
dateOfBirth String Date of birth in ‘YYYY-MM-DD’ format.
placeOfBirth Object The individual place of birth.
placeOfBirth.city String The individual city of birth (minimum 2 and maximum 4 characters).
placeOfBirth.state String The individual state of birth (minimum 2 and maximum 4 characters).
placeOfBirth.country String The individual country of birth (3 characters only).
nationality String Nationality (3 character country code).
address Object The individual address.
address.street String The individual street address name.
address.houseNumber String The individual house number with optional prefix and suffix. For example: 10-11/D.
address.addition String The individual address addition, like unit, floor, door, etc.
address.zipcode String The individual address zip code.
address.city String The individual city name.
address.state String The individual state code.
address.country String The individual country code (3 characters only).
email String The individual email.
phone String The individual phone number.
kycStatus Object The individual kyc status filled after the creation of the legal entity.
kycStatus.status String The individual kyc status code. Possible values: WAITING_DATA, MISSING_DATA, DATA_RECEIVED, IN_PROGRESS, PASSED, REJECTED, FORGED, FAILED.
kycStatus.details[] Array A list containing details about the KYC process.
kycStatus.details[].code String Payaut 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[].type String The type of the kyc detail. Possible values: ERROR, ADVICE.
kycStatus.details[].messageCode String An identifier code of the descriptive message bellow.
kycStatus.details[].messageTemplate String A descriptive message of the error or advice.
documents[] Array The personal documents of the legal entity.
documents[].type String The personal document type. Possible values: ID, PASSPORT, DRIVING_LICENSE, VISA.
documents[].number String The personal document number.
documents[].issuedAt String The issuance date of the personal document.
documents[].expireAt String The expiration date of the personal document.
documents[].issuerCountry String The issuer country of the personal document.
documents[].extRef String Platform external reference of the document.
documents[].photos[] Array Photos of the documents used in the KYC process.
documents[].photos[].code String Payaut unique reference of the photo. This field is part of the response payload, so should never be sent in the request.
documents[].photos[].extRef String Platform external reference of the photo.
documents[].photos[].page String Indicates the side of the document that was photographed. Possible values: FRONT, BACK.
documents[].photos[].style String Indicates the angle in which the document was photographed. Possible values: STRAIGHT, TILTED.
documents[].photos[].format String The format of the photo. Possible values: PNG, JPG.
documents[].photos[].data String The Base64 encoded string of the photo.
The organization legal entity object
{
  "legalForm" : "organization",
  "type" : "PRIVATE_COMPANY",
  "registrationNumber" : "346242542",
  "ultimateBeneficialOwners" : [ {
    "code" : "FD5CMFy2u18WiU9MJUho4XSABAgFGFcqUgp",
    "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" : [ {
        "code" : "FD5CMFy2u18XSsctu9f6qT8tGG3HDp8n7di",
        "type" : "ERROR",
        "messageCode" : "00000000",
        "messageTemplate" : "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" : "2015-06-08",
      "expireAt" : "2022-06-08",
      "issuerCountry" : "NLD",
      "photos" : [ {
        "code" : "FD5CMFy2u18TMRwGa21geYywsohyCDPy1xk",
        "extRef" : "ER ID1111111 FRONT STRAIGHT",
        "page" : "FRONT",
        "style" : "STRAIGHT",
        "format" : "JPG",
        "data" : "ZW1wdHk="
      }, {
        "code" : "FD5CMFy2u18URrvNd5cjLpQGJnZWbkWj6zc",
        "extRef" : "ER ID1111111 BACK STRAIGHT",
        "page" : "BACK",
        "style" : "STRAIGHT",
        "format" : "PNG",
        "data" : "ZW1wdHk="
      } ],
      "code" : "FD5CMFy2u18SpN4cbzVdeJfoJuQtTvsqiVe",
      "extRef" : "ER ID1111111"
    } ]
  } ],
  "documents" : [ {
    "title" : "KVK",
    "issuer" : "COMPANY_REGISTER",
    "issuedAt" : "2018-06-08",
    "issuerCountry" : "NLD",
    "data" : "ZW1wdHk=",
    "code" : "FD5CMFy2u18Qd52egtPjmNx8aDnVfwEnxYg",
    "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" : [ {
      "code" : "FD5CMFy2u18RXQ3Q1CZRfXxN8Ucnh6aJj8k",
      "type" : "ERROR",
      "messageCode" : "00000000",
      "messageTemplate" : "Address is a PO box"
    } ]
  }
}

Attributes

Path Type Description Constraints
type String The type of organization. Possible values: PRIVATE_COMPANY, PUBLIC_COMPANY, NON_PROFIT.
registrationNumber String The registration number of the company in the Chamber of Commerce.
ultimateBeneficialOwners[] Array The list of the UBOs associated with the company. This object is an extension of the individual legal entity.
ultimateBeneficialOwners[].type String The UBO type. Possible values: SHARE_HOLDER, CEO, CFO, COO.
documents[] Array The organization documents.
documents[].title String A description of the document.
documents[].issuer String The issuer of the document. Possible values: COMPANY_REGISTER, TAX_AUTHORITY.
documents[].issuedAt String The issuance date of the document.
documents[].issuerCountry String The issuer country of the document.
documents[].data String The Base64 encoded string of the document.
documents[].extRef String Platform external reference of the document.
legalForm String The legal entity form that indicates if the entity is an individual or an organization. In this case, an organization.
legalName String The organization legal name.
taxNumber String The organization tax number.
address Object The organization address.
address.street String The organization street address name.
address.houseNumber String The organization house number with optional prefix and suffix. For example: 10-11/D.
address.addition String The organization address addition, like unit, floor, door, etc.
address.zipcode String The organization address zip code.
address.city String The organization city name.
address.state String The organization state code.
address.country String The organization country code (3 characters only).
email String The organization email.
phone String The organization phone number.
kycStatus Object The organization kyc status filled after the creation of the legal entity.
kycStatus.status String The individual kyc status code. Possible values: WAITING_DATA, MISSING_DATA, DATA_RECEIVED, IN_PROGRESS, PASSED, REJECTED, FORGED, FAILED.
kycStatus.details[] Array A list containing details about the KYC process.
kycStatus.details[].code String Payaut 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[].type String The type of the kyc detail. Possible values: ERROR, ADVICE.
kycStatus.details[].messageCode String An identifier code of the descriptive message bellow.
kycStatus.details[].messageTemplate String A 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"
}
Path Type Description Constraints
type String One of PASSPORT or ID
expiresAt String The Date of expiration of the document being uploaded in the format YYYY-MM-dd Must be a future date
issuedAt String The Date the document being uploaded was issued in the format YYYY-MM-dd Must be a past date
number String The number of the document being uploaded. It’s a string, so any alphanumeric value can be used. Must not be blank
photos Array An array of objects describing photos for this document Must not be empty
photos[].page String One of FRONT or BACK
photos[].style String One of STRAIGHT or TILTED
photos[].format String One of JPG or PNG
photos[].data String A 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

Parameter Description
code The account holder code.

Attributes

Path Type Description Constraints
type String One of PASSPORT or ID
expiresAt String The Date of expiration of the document being uploaded in the format YYYY-MM-dd Must be a future date
issuedAt String The Date the document being uploaded was issued in the format YYYY-MM-dd Must be a past date
number String The number of the document being uploaded. It’s a string, so any alphanumeric value can be used. Must not be blank
photos Array An array of objects describing photos for this document Must not be empty
photos[].page String One of FRONT or BACK
photos[].style String One of STRAIGHT or TILTED
photos[].format String One of JPG or PNG
photos[].data String A 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" : "FD5CMFy2u35jNtzvoEpGKSMnhQ475axMY32"
}
Path Type Description Constraints
title String A title for this document
issuer String One of COMPANY_REGISTER or TAX_AUTHORITY
issuedAt String The Date the document being uploaded was issued in the format YYYY-MM-dd Must be a past date
issuerCountry String 3-digit country code identifier from the country where the document was issued
data String A 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" : "FD5CMFy2u35jNtzvoEpGKSMnhQ475axMY32"
}

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

Path Parameters

Parameter Description
code The account holder code.

Attributes

Path Type Description Constraints
title String A title for this document
issuer String One of COMPANY_REGISTER or TAX_AUTHORITY
issuedAt String The Date the document being uploaded was issued in the format YYYY-MM-dd Must be a past date
issuerCountry String 3-digit country code identifier from the country where the document was issued
data String A 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"
}
Path Type Description Constraints
displayName String A unique label to make a distinction between different virtual accounts min = 4, max = 48
extRef String an external reference to which you like to refer to this account min 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

Parameter Description
code The account holder code.

Attributes

Path Type Description Constraints
displayName String A unique label to make a distinction between different virtual accounts min = 4, max = 48
extRef String an external reference to which you like to refer to this account min 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

Parameter Description
code The account holder code.
accountCode The 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.

Parameter Description
code The account holder code.

Path Parameters

Parameter Description
code The account holder code.

Attributes

Parameter Description
_pageSize Number of elements to be returned in the page result
_pageNumber The number of requested page
_sort the 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

Parameter Description
code The account holder code.
accountCode The code of the account

Attributes

Path Type Description Constraints
code String Unique reference to the virtual account auto generated
displayName String A unique label to make a distinction between different virtual accounts min = 4, max = 48
extRef String an external reference to which you like to refer to this account min 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 is represents a real bank account. Its most important field is the IBAN. An external account is used with a PayoutRequest to transfer funds to the outside. An external account is always linked to an account owner: an Accountholder.

The external account object

The external account request 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

Path Type Description Constraints
displayName String A unique label to make a distinction between different IBANs min 4, max 32 characters
extRef String A client provided reference to this IBAN
description String Human readable description for this IBAN
currency String Standard three letter currency code Currently only ‘EUR’ is supported. Mandatory.
accountType String Fixed value of ‘IBAN’ for this call
accountNumber String The actual IBAN number Mandatory
statement Object An object containing bank statement data for KYC purposes Optional
statement.data String Base64 of the bytes of a .pdf bank statement export Mandatory
statement.issuedAt String The date when the .pdf bank statement was issued format: YYYY-MM-dd

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

Parameter Description
accountHolderCode The code of the merchant(division) or seller holding this account

Attributes

Path Type Description Constraints
displayName String A unique label to make a distinction between different IBANs min 4, max 32 characters
extRef String A client provided reference to this IBAN
description String Human readable description for this IBAN
currency String Standard three letter currency code Currently only ‘EUR’ is supported. Mandatory.
accountType String Fixed value of ‘IBAN’ for this call
accountNumber String The actual IBAN number Mandatory
statement Object An object containing bank statement data for KYC purposes Optional
statement.data String Base64 of the bytes of a .pdf bank statement export Mandatory
statement.issuedAt String The date when the .pdf bank statement was issued format: 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

Parameter Description
accountHolderCode The code of the merchant(division) or seller holding this account
externalAccountCode The 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=1&_pageSize=25' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "pageSize" : 500,
  "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.

Parameter Description
accountHolderCode The code of the merchant(division) or seller holding this account

Path Parameters

Parameter Description
accountHolderCode The code of the merchant(division) or seller holding this account

Attributes

Parameter Description
_pageSize Number of elements returned in this page
_pageNumber The number of this page

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.

The payment split object

The payment object
{
  "code" : "FD5CMFy2uGtTkYUisn3ryJJKu3wBZ26jHFN",
  "extRef" : "platformOrderId#123",
  "totalAmount" : 70700,
  "description" : "Your Platform Order Description",
  "items" : [ {
    "code" : "FD5CMFy2uGtSNZdTv4jXWCcfAS37iLtuDSx",
    "type" : "ITEM",
    "label" : "SHIPPING",
    "extRef" : "platformOrderId#123#shipping",
    "amount" : 700,
    "accountCode" : "YourDefaultPlatformAccountCode",
    "description" : "$7.00 shipping fee charged by the platform"
  }, {
    "code" : "FD5CMFy2uGtTc2gBUkb4WfgLSKxyXUTyUZv",
    "type" : "GROUP",
    "extRef" : "platformOrderId#123#accountHolder#123",
    "amount" : 70000,
    "accountCode" : "UniqueAccountCodeForThisAccountHolder",
    "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"
    } ]
  } ],
  "pspExtRef" : "tr_IJdHG8fjgl",
  "pspResponse" : {
    "type" : "PAYMENT",
    "data" : "eyJkYXRhIjoiTW9sbGllIHBzcCByZXNwb25zZSBkYXRhIn0"
  },
  "currency" : "EUR",
  "paymentProcessor" : "MOLLIE",
  "paymentMethod" : "iDEAL"
}
Path Type Description Constraints
code String Unique identifier returned when the payment split is created.
extRef String Unique reference generated by the platform.
totalAmount Number Gross amount of the payment in cents.
currency String The currency in which the amount is described.
pspExtRef String The psp/acquirer reference that uniquely identifies the payment.
paymentProcessor String The payment processor identifier.
paymentMethod String The method of payment, such as VISA, MasterCard, iDEAL, PAYPAL, etc.
pspResponse Object The response object received from the payment processor.
pspResponse.type String The type of the payment processor response.
pspResponse.data String The whole response string encoded in Base64 format.
description String Human-readable description of the payment split.
items[] Array Split items.
items[].type String Type of the item.
items[].label String Label of the item.
items[].code String Split item unique identifier.
items[].extRef String Unique reference generated by the platform for this split item.
items[].amount Number The gross amount of the specific split item in cents.
items[].accountCode String The account code of the target account owner.
items[].description String Human-readable description of the payment split item.
items[].items Array The 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" : "YourDefaultPlatformAccountCode",
    "description" : "Human readable description of this split payment item"
  }, {
    "type" : "ITEM",
    "label" : "PRODUCT_ITEM",
    "extRef" : "platformOrderId#123#item#1",
    "amount" : 5000,
    "accountCode" : "UniqueAccountCodeForThisAccountHolder",
    "description" : "Human readable description of this split payment item"
  } ],
  "pspExtRef" : "8464849469846894",
  "currency" : "EUR",
  "paymentProcessor" : "ADYEN",
  "paymentMethod" : "VISA"
}'
Response
{
  "code" : "FD5CMFy2uGRoipA6nc4T2EPgAkrQJ1HjmLt",
  "extRef" : "platformOrderId#123",
  "totalAmount" : 7000,
  "description" : "Your Platform Order Description",
  "items" : [ {
    "code" : "FD5CMFy2uGRpvvrL1YvaJiVqC8mvSUiPwu2",
    "type" : "ITEM",
    "label" : "COMMISSION",
    "extRef" : "platformOrderId#123#commission",
    "amount" : 2000,
    "accountCode" : "YourDefaultPlatformAccountCode",
    "description" : "Human readable description of this split payment item"
  }, {
    "code" : "FD5CMFy2uGRs1ztRUf1X73TF9kMHUyqqbcC",
    "type" : "ITEM",
    "label" : "PRODUCT_ITEM",
    "extRef" : "platformOrderId#123#item#1",
    "amount" : 5000,
    "accountCode" : "UniqueAccountCodeForThisAccountHolder",
    "description" : "Human readable description of this split payment item"
  } ],
  "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

Path Type Description Constraints
extRef String Unique 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|#|@|:||-|_]{1,64}$
totalAmount Number Gross amount of the payment as a positive integer (cents in euro, penny for pounds, etc). Mandatory
currency String ISO 4217 currency code, composed exactly by 3 letters. Mandatory
pspExtRef String The psp/acquirer reference that uniquely identifies the payment. Optional
paymentProcessor String The payment processor identifier. Mandatory. Possible values: ADYEN, MOLLIE
paymentMethod String The method of payment, such as VISA, MasterCard, iDEAL, PAYPAL, etc. Mandatory
pspResponse Object The response object received from the payment processor before the payment split request is sent. Optional
pspResponse.type String The unique identifier of the payment processor response type. Mandatory
pspResponse.data String The whole response string encoded with Base64 format. Mandatory
description String Human-readable description of the payment split. Optional
items[] Array Split items represented as a tree containing groups and sub-items. Mandatory
items[].type String Type 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[].label String Label 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[].extRef String Unique 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|#|@|:||-|_]{1,64}$
items[].amount Number Positive integer that represents the gross amount of the split item (cents in euro, pennies in pounds, etc). Mandatory
items[].accountCode String The 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[].description String Human-readable description of the payment split item. Optional
items[].items Array The 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/FD5CMFy2uGcdAvB9Q6h5yuik8EnWUnyBZ1J' -i -X GET \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "code" : "FD5CMFy2uGcdAvB9Q6h5yuik8EnWUnyBZ1J",
  "extRef" : "platformOrderId#123",
  "totalAmount" : 7000,
  "description" : "Your Platform Order Description",
  "items" : [ {
    "code" : "FD5CMFy2uGcdrttebDWKEeS1Rxv85NQ5AEU",
    "type" : "ITEM",
    "label" : "COMMISSION",
    "extRef" : "platformOrderId#123#commission",
    "amount" : 2000,
    "accountCode" : "YourDefaultPlatformAccountCode",
    "description" : "Human readable description of this split payment item"
  }, {
    "code" : "FD5CMFy2uGceVtQJ58zJ2PHvMfnj6ADbKoW",
    "type" : "ITEM",
    "label" : "PRODUCT_ITEM",
    "extRef" : "platformOrderId#123#item#1",
    "amount" : 5000,
    "accountCode" : "UniqueAccountCodeForThisAccountHolder",
    "description" : "Human readable description of this split payment item"
  } ],
  "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

Parameter Description
code The 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&pgNum=1&rPerPg=25&asc=false' -i -X GET \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "pageSize" : 1,
  "pageNumber" : 1,
  "elements" : [ {
    "code" : "FD5CMFy2uGjnVV5YtagCY1VBvpRnvNQtykU",
    "extRef" : "platformOrderId#123",
    "totalAmount" : 7000,
    "description" : "Your Platform Order Description",
    "items" : [ {
      "code" : "FD5CMFy2uGjmtgsPD6rjW751PAs9YVxtsL4",
      "type" : "ITEM",
      "label" : "COMMISSION",
      "extRef" : "platformOrderId#123#commission",
      "amount" : 2000,
      "accountCode" : "YourDefaultPlatformAccountCode",
      "description" : "Human readable description of this split payment item"
    }, {
      "code" : "FD5CMFy2uGjnrNqAf44NUvZ1FBEYvXR31fN",
      "type" : "ITEM",
      "label" : "PRODUCT_ITEM",
      "extRef" : "platformOrderId#123#item#1",
      "amount" : 5000,
      "accountCode" : "UniqueAccountCodeForThisAccountHolder",
      "description" : "Human readable description of this split payment item"
    } ],
    "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

Parameter Description
from The initial date used to query. Format: `yyyy-MM-dd’T'HH:mm:ss.SSSXXX`.
to The final date used to query. Format: `yyyy-MM-dd’T'HH:mm:ss.SSSXXX`.
pgNum pageNumber.
rPerPg resultsPerPage.
asc asc.

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" : "FD5CMFy2uK5xTFhV87KCGUNnjELPkVuKPCU",
  "extRef" : "platformOrderId#123",
  "totalAmount" : 40000,
  "description" : "Your Platform Refund Description",
  "items" : [ {
    "code" : "FD5CMFy2uK5w9N1nvuffVY7LRYpLEkky4j2",
    "type" : "GROUP",
    "extRef" : "refund#123#accountHolder#123",
    "originalExtRef" : "platformOrderId#123#accountHolder#123",
    "amount" : 40000,
    "accountCode" : "UniqueAccountCodeForThisAccountHolder",
    "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"
    } ]
  } ],
  "pspMutationExtRef" : "8565315484610879"
}
Path Type Description Constraints
code String Unique identifier returned when the refund split is created.
extRef String Same unique reference as the one created for the associated payment split.
pspMutationExtRef String Psp/acquirer mutation reference.
totalAmount Number Gross amount of the refund in cents.
description String Human-readable description of the refund split.
items[] Array Split items.
items[].type String Type of the item.
items[].label String Label of the item.
items[].code String Split item unique identifier.
items[].extRef String Unique reference generated by the platform for this split item.
items[].originalExtRef String The original split item extRef value from the associated payment split.
items[].amount Number The gross amount of the specific split item in cents.
items[].accountCode String The account code of the target account owner.
items[].description String Human-readable description of the refund split item.
items[].items Array The 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",
  "pspMutationExtRef" : "RUJSSC"
}'
Response
{
  "extRef" : "platformOrderId#123",
  "description" : "Human-readable description of the full refund",
  "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

Path Type Description Constraints
extRef String Unique 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|#|@|:||-|_]{1,64}$
pspMutationExtRef 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. Mandatory
description String Human-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" : "YourDefaultPlatformAccountCode",
    "description" : "Refunded commission"
  }, {
    "type" : "ITEM",
    "label" : "PRODUCT_ITEM",
    "extRef" : "refund#123#item#1",
    "originalExtRef" : "platformOrderId#123#item#1",
    "amount" : 2000,
    "accountCode" : "UniqueAccountCodeForThisAccountHolder",
    "description" : "Refunded product item"
  } ],
  "pspMutationExtRef" : "8565315484610879"
}'
Response
{
  "code" : "FD5CMFy2uJVcvaryBwnZgN5hzbveqkD8WSC",
  "extRef" : "platformOrderId#123",
  "totalAmount" : 2500,
  "description" : "Your Platform Refund Description",
  "items" : [ {
    "code" : "FD5CMFy2uJVb3NtvDVdmoVHgCaFyEbPuB3e",
    "type" : "ITEM",
    "label" : "COMMISSION",
    "extRef" : "refund#123#commission",
    "originalExtRef" : "platformOrderId#123#commission",
    "amount" : 500,
    "accountCode" : "YourDefaultPlatformAccountCode",
    "description" : "Refunded commission"
  }, {
    "code" : "FD5CMFy2uJVejbYaiSBS35MmBSguaDAw1Ax",
    "type" : "ITEM",
    "label" : "PRODUCT_ITEM",
    "extRef" : "refund#123#item#1",
    "originalExtRef" : "platformOrderId#123#item#1",
    "amount" : 2000,
    "accountCode" : "UniqueAccountCodeForThisAccountHolder",
    "description" : "Refunded product item"
  } ]
}

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

Path Type Description Constraints
extRef String Same unique reference as the one created for the associated payment split. Mandatory. Regex: ^[a-z|A-Z|0-9|#|@|:||-|_]{1,64}$
pspMutationExtRef 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. Mandatory
totalAmount Number Gross amount of the payment as a positive integer (cents in euro, penny for pounds, etc). Mandatory
description String Human-readable description of the refund split. Optional
items[] Array Split items represented as a tree containing groups and sub-items. Mandatory
items[].type String Type 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[].label String Label 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[].extRef String Unique 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|#|@|:||-|_]{1,64}$
items[].originalExtRef String The original split item extRef value from the associated payment split. Mandatory. Regex: ^[a-z|A-Z|0-9|#|@|:||-|_]{1,64}$
items[].amount Number Positive integer that represents the gross amount of the split item (cents in euro, pennies in pounds, etc). Mandatory
items[].accountCode String The 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[].description String Human-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/FD5CMFy2uJxfcfWsgHJDHGERWTkEFk1ewSQ' -i -X GET \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "code" : "FD5CMFy2uJxfcfWsgHJDHGERWTkEFk1ewSQ",
  "extRef" : "platformOrderId#123",
  "totalAmount" : 2500,
  "description" : "Your Platform Refund Description",
  "items" : [ {
    "code" : "FD5CMFy2uJxebp2J8CKRmnivEPfVzQrqEP2",
    "type" : "ITEM",
    "label" : "COMMISSION",
    "extRef" : "refund#123#commission",
    "originalExtRef" : "platformOrderId#123#commission",
    "amount" : 500,
    "accountCode" : "YourDefaultPlatformAccountCode",
    "description" : "Refunded commission"
  }, {
    "code" : "FD5CMFy2uJxdfKuouRQY3f6ZjEe2EA5aJSk",
    "type" : "ITEM",
    "label" : "PRODUCT_ITEM",
    "extRef" : "refund#123#item#1",
    "originalExtRef" : "platformOrderId#123#item#1",
    "amount" : 2000,
    "accountCode" : "UniqueAccountCodeForThisAccountHolder",
    "description" : "Refunded product item"
  } ],
  "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

Parameter Description
code The 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&pgNum=1&rPerPg=25&asc=false' -i -X GET \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "pageSize" : 1,
  "pageNumber" : 1,
  "elements" : [ {
    "code" : "FD5CMFy2uJqTvenaPEQzHSJFSpmAZ2tsSwa",
    "extRef" : "platformOrderId#123",
    "totalAmount" : 2500,
    "description" : "Your Platform Refund Description",
    "items" : [ {
      "code" : "FD5CMFy2uJqUKiUErghi4t9A29XbJfb1eS4",
      "type" : "ITEM",
      "label" : "COMMISSION",
      "extRef" : "refund#123#commission",
      "originalExtRef" : "platformOrderId#123#commission",
      "amount" : 500,
      "accountCode" : "YourDefaultPlatformAccountCode",
      "description" : "Refunded commission"
    }, {
      "code" : "FD5CMFy2uJqVAqi2X5sDMU4dYDhUVU9jWGQ",
      "type" : "ITEM",
      "label" : "PRODUCT_ITEM",
      "extRef" : "refund#123#item#1",
      "originalExtRef" : "platformOrderId#123#item#1",
      "amount" : 2000,
      "accountCode" : "UniqueAccountCodeForThisAccountHolder",
      "description" : "Refunded product item"
    } ]
  } ],
  "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

Parameter Description
from The initial date used to query. Format: yyyy-MM-dd’T'HH:mm:ss.SSSXXX
to The final date used to query. Format: yyyy-MM-dd’T'HH:mm:ss.SSSXXX
pgNum pageNumber
rPerPg resultsPerPage
asc asc

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 specifies when and to where funds should be payed out to merchants and account holders. The fund movements are based on Payaut virtual accounts.

Payout instructions are defined by the ‘PayoutRequest’ object, which contains information on when and to where to transfer the funds.


The payout request object

The payout request object
{
  "code" : "FD5CMFy2uAvRxtXbVgCV33iHcvFnzBKdi3A",
  "createdAt" : "2020-06-08T15:08:29.508676+02:00",
  "processAt" : "2020-06-09T15:08:29.508676+02:00",
  "useBalanceAt" : "2020-06-09T15:08:29.508676+02:00",
  "accountCode" : "FD5CMFy2uAvTH9MTDBXz66gGDsctUBY5pQY",
  "externalAccountCode" : "FD5CMFy2uAvTHSqqc7L8gkC2yvRy1N5wwRi",
  "amount" : 1,
  "description" : "This is a test",
  "status" : "ACCEPTED",
  "reconciledResultCode" : null
}
Path Type Description Constraints
code String User defined code
createdAt String The date this request was created, in the ISO8601 format of ‘yyyy-MM-dd hh:mm:ss.SSSSSSX’ user generated
processAt String The date when this money transfer will be due. If null, will be immediate. in the ISO8601 format of ‘yyyy-MM-dd hh:mm:ss.SSSSSSX’ user generated
useBalanceAt String The date of the balance date this request should be checked against, useful to keep a margin for refunds and fees. in the ISO8601 format of ‘yyyy-MM-dd hh:mm:ss.SSSSSSX’ user generated
accountCode String The account number of the account holding the balance
externalAccountCode String The account number of the account the payout should be transferred to
amount Number The amount to payout, in cents. If there’s no amount, it means it’s a max balance payout request
description String Description that will show up in the destination account bank’s statement
status String describes the current status of the payout request
reconciledResultCode String describes if the request was reconciled with the instructions sent to the banks

Create a Payout request

POST /api/v1/fund/payout-requests
$ curl 'http://localhost:8080/api/v1/fund/payout-requests' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi' \
    -d '{
  "createdAt" : "2020-06-08T15:08:27.370771+02:00",
  "processAt" : "2020-06-09T15:08:27.370771+02:00",
  "useBalanceAt" : "2020-06-09T15:08:27.370771+02:00",
  "accountCode" : "FD5CMFy2u9PmgcjSWwRNw6Ss6vpT24f5F9S",
  "externalAccountCode" : "FD5CMFy2u9Pm6gdi9KVPdDtQkVg8bEhJvZ6",
  "amount" : 1,
  "description" : "This is a test",
  "status" : "ACCEPTED"
}'
Response
{
  "code" : "FD5CMFy2uAvRxtXbVgCV33iHcvFnzBKdi3A",
  "createdAt" : "2020-06-08T15:08:29.508676+02:00",
  "processAt" : "2020-06-09T15:08:29.508676+02:00",
  "useBalanceAt" : "2020-06-09T15:08:29.508676+02:00",
  "accountCode" : "FD5CMFy2uAvTH9MTDBXz66gGDsctUBY5pQY",
  "externalAccountCode" : "FD5CMFy2uAvTHSqqc7L8gkC2yvRy1N5wwRi",
  "amount" : 1,
  "description" : "This is a test",
  "status" : "ACCEPTED",
  "reconciledResultCode" : null
}

Creates a payout request that will be paid out according to the instructions provided. This uses a payout request object

Retrieve a payout request

GET /api/v1/fund/payout-requests/{code}
$ curl 'http://localhost:8080/api/v1/fund/payout-requests/testMerchant' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "code" : "FD5CMFy2uBMUQexhnKYyuit7wHg6wz7Q6Cx",
  "createdAt" : "2020-06-08T15:08:30.111658+02:00",
  "processAt" : "2020-06-09T15:08:30.111658+02:00",
  "useBalanceAt" : "2020-06-09T15:08:30.111658+02:00",
  "accountCode" : "FD5CMFy2uBMTdwUZ9xGVWDUXYrPZPfQ3xwA",
  "externalAccountCode" : "FD5CMFy2uBMUMyV2VLygQ6pNebnqZx2rq68",
  "amount" : 1,
  "description" : "This is a test",
  "status" : "ACCEPTED",
  "reconciledResultCode" : null
}

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

Parameter Description
code the code of the payout request to retrieve

List all payout request

GET /api/v1/fund/payout-requests
$ curl 'http://localhost:8080/api/v1/fund/payout-requests' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'
Response
{
  "totalElements" : 1,
  "totalPages" : 1,
  "content" : [ {
    "code" : "FD5CMFy2uBVjRu9VHFMiQu2dmZ8RS7hyZw6",
    "createdAt" : "2020-06-08T15:08:30.311898+02:00",
    "processAt" : "2020-06-09T15:08:30.311898+02:00",
    "useBalanceAt" : "2020-06-09T15:08:30.311898+02:00",
    "accountCode" : "FD5CMFy2uBVmHgmn6ByzyRWQkSCQeeHUzq6",
    "externalAccountCode" : "FD5CMFy2uBVmcYsC7GRvJdBduXtrNUdVmaQ",
    "amount" : 1,
    "description" : "This is a test",
    "status" : "ACCEPTED",
    "reconciledResultCode" : null
  } ],
  "empty" : false,
  "first" : true,
  "last" : true,
  "number" : 1,
  "numberOfElements" : 1,
  "elements" : [ {
    "code" : "FD5CMFy2uBVjRu9VHFMiQu2dmZ8RS7hyZw6",
    "createdAt" : "2020-06-08T15:08:30.311898+02:00",
    "processAt" : "2020-06-09T15:08:30.311898+02:00",
    "useBalanceAt" : "2020-06-09T15:08:30.311898+02:00",
    "accountCode" : "FD5CMFy2uBVmHgmn6ByzyRWQkSCQeeHUzq6",
    "externalAccountCode" : "FD5CMFy2uBVmcYsC7GRvJdBduXtrNUdVmaQ",
    "amount" : 1,
    "description" : "This is a test",
    "status" : "ACCEPTED",
    "reconciledResultCode" : null
  } ],
  "pageNumber" : 1,
  "pageSize" : 1,
  "totalElementCount" : 1
}

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

Request parameters

Parameter Description
from The created at date of where the list should begin, in the ISO8601 format of ‘yyyy-MM-dd hh:mm:ss.SSSSSSX’
to The created at date of where the list should end. in the ISO8601 format of ‘yyyy-MM-dd hh:mm:ss.SSSSSSX’
pgNum The page number of the paged result set requested
rPerPg number of result per page requested
ordBy the Payout request field the list should be ordered by, see the create() fields. Defaults to createdAt
asc should the ordering be ascending or not