Introduction

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

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

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

Account holders

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.

image representing the account holder structure

The account holder object

Attributes

{
  "extRef" : "abc123",
  "code" : "FD5CKXSk98HEkDkMLgijgXTV9LPnQX2FzD6",
  "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" : "2017-02-03",
      "expireAt" : "2024-02-03",
      "issuerCountry" : "NLD",
      "photos" : [ {
        "code" : "FD5CKXSk9htf7BUJoQqisAFnBzbBTzdexEk",
        "extRef" : "ER ID1111111 FRONT STRAIGHT",
        "page" : "FRONT",
        "style" : "STRAIGHT",
        "format" : "JPG",
        "data" : "ZW1wdHk="
      }, {
        "code" : "FD5CKXSk9ntzn6CLtq5b2383e1xKpBvM9Lc",
        "extRef" : "ER ID1111111 BACK STRAIGHT",
        "page" : "BACK",
        "style" : "STRAIGHT",
        "format" : "PNG",
        "data" : "ZW1wdHk="
      } ],
      "code" : "FD5CKXSk9sBrnJFEQPBrqT77ZxVWwQpbreU",
      "extRef" : "ER ID1111111"
    } ]
  },
  "externalAccounts" : [ {
    "accountType" : "IBAN",
    "accountNumber" : "NL91ABNA0417164300",
    "code" : "FD5CKXSk9Sse6TJCXtma1pfEMTAmZxQJMyA",
    "extRef" : "ER J. Doe IBAN",
    "displayName" : "NL91 ABNA 0417 1643 00",
    "description" : "J. Doe ABN account",
    "currency" : "EUR",
    "statement" : {
      "issuedAt" : "2019-02-03",
      "data" : "ZW1wdHk="
    },
    "kycStatus" : {
      "status" : "FAILED",
      "details" : [ {
        "messageType" : "ERROR",
        "messageCode" : "00000000",
        "message" : "Invalid bank identifier"
      } ]
    }
  } ],
  "accounts" : [ {
    "code" : "FD5CKXSk9K1Pkjsa721LX6mVnp99DFrH5r8",
    "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"
    }
  }
}

Create an account holder

$ 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" : "2017-02-03",
      "expireAt" : "2024-02-03",
      "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"
  } ]
}'

{
  "extRef" : "abc123",
  "code" : "FD5CKXT5PUmk8eUMwQvex6AUpMpbmcQ4CtY",
  "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" : "2017-02-03",
      "expireAt" : "2024-02-03",
      "issuerCountry" : "NLD",
      "photos" : [ {
        "code" : "FD5CKXT5PmDiUmzmP2aiGzzvSxauaZ1g3Za",
        "extRef" : "ER ID1111111 FRONT STRAIGHT",
        "page" : "FRONT",
        "style" : "STRAIGHT",
        "format" : "JPG",
        "data" : "ZW1wdHk="
      }, {
        "code" : "FD5CKXT5PrE49gioUSpaRssBtyx3q9eN3mi",
        "extRef" : "ER ID1111111 BACK STRAIGHT",
        "page" : "BACK",
        "style" : "STRAIGHT",
        "format" : "PNG",
        "data" : "ZW1wdHk="
      } ],
      "code" : "FD5CKXT5PvWv9tmgyzvrFHrFpvVEqZLkZTv",
      "extRef" : "ER ID1111111"
    } ]
  },
  "accounts" : [ {
    "code" : "FD5CKXT5PaVZUFsYchJ7SS5imhtoQE6HVZa",
    "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

Update an account holder

$ curl 'https://sandbox.payaut.com/api/v1/accountholders/FD5CKXPnSDQgCwJnQTiXbJx5xwvmZ5RYfbW?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" : "2019-02-03",
      "data" : "ZW1wdHk="
    }
  } ]
}'

{
  "extRef" : "abc123",
  "code" : "FD5CKXPnSDQgCwJnQTiXbJx5xwvmZ5RYfbW",
  "displayName" : "J. Doe",
  "description" : "A brief description of the account holder",
  "externalAccounts" : [ {
    "accountType" : "IBAN",
    "accountNumber" : "NL91ABNA0417164300",
    "code" : "FD5CKXPnSdittnFpGap6cJKHPncnGy1HrsA",
    "extRef" : "ER J. Doe IBAN",
    "displayName" : "NL91 ABNA 0417 1643 00",
    "description" : "J. Doe ABN account",
    "currency" : "EUR",
    "statement" : {
      "issuedAt" : "2019-02-03",
      "data" : "ZW1wdHk="
    },
    "kycStatus" : {
      "status" : "FAILED",
      "details" : [ {
        "messageType" : "ERROR",
        "messageCode" : "00000000",
        "message" : "Invalid bank identifier"
      } ]
    }
  } ],
  "accounts" : [ {
    "code" : "FD5CKXPnSURhDfUtfyngSetBmy7Q9eAyfyA",
    "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

Attributes

Retrieve an account holder

$ curl 'https://sandbox.payaut.com/api/v1/accountholders/FD5CKXQ7Y2KcBNHEMNbbJnRKMR5Yg2vzbYU?_fragments=extacc,kycstatus,accounts' -i -X GET \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'

{
  "extRef" : "abc123",
  "code" : "FD5CKXQ7Y2KcBNHEMNbbJnRKMR5Yg2vzbYU",
  "displayName" : "J. Doe",
  "description" : "A brief description of the account holder",
  "externalAccounts" : [ {
    "accountType" : "IBAN",
    "accountNumber" : "NL91ABNA0417164300",
    "code" : "FD5CKXQ7YdMysjMUyTf3MhLjh7Mk4s7J6SU",
    "extRef" : "ER J. Doe IBAN",
    "displayName" : "NL91 ABNA 0417 1643 00",
    "description" : "J. Doe ABN account",
    "currency" : "EUR",
    "statement" : {
      "issuedAt" : "2019-02-03",
      "data" : "ZW1wdHk="
    },
    "kycStatus" : {
      "status" : "FAILED",
      "details" : [ {
        "messageType" : "ERROR",
        "messageCode" : "00000000",
        "message" : "Invalid bank identifier"
      } ]
    }
  } ],
  "accounts" : [ {
    "code" : "FD5CKXQ7YFufrh73TAQZVCp47FnRCk3Lh8L",
    "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

Request Parameters

List all account holders

$ curl 'https://sandbox.payaut.com/api/v1/accountholders?_fragments=extacc,kycstatus,accounts' -i -X GET \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'

{
  "pageSize" : 1,
  "pageNumber" : 1,
  "elements" : [ {
    "extRef" : "abc123",
    "code" : "FD5CKXSM6kTH3EGKeuHKegrUTHG4SJdojUk",
    "displayName" : "J. Doe",
    "description" : "A brief description of the account holder",
    "externalAccounts" : [ {
      "accountType" : "IBAN",
      "accountNumber" : "NL91ABNA0417164300",
      "code" : "FD5CKXSM7aNEkDVEnYhRjueAHbr58r78aec",
      "extRef" : "ER J. Doe IBAN",
      "displayName" : "NL91 ABNA 0417 1643 00",
      "description" : "J. Doe ABN account",
      "currency" : "EUR",
      "statement" : {
        "issuedAt" : "2019-02-03",
        "data" : "ZW1wdHk="
      },
      "kycStatus" : {
        "status" : "FAILED",
        "details" : [ {
          "messageType" : "ERROR",
          "messageCode" : "00000000",
          "message" : "Invalid bank identifier"
        } ]
      }
    } ],
    "accounts" : [ {
      "code" : "FD5CKXSM75mA4AVKRc92WoQfRqsxaNLukyN",
      "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

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" : "2017-02-03",
    "expireAt" : "2024-02-03",
    "issuerCountry" : "NLD",
    "photos" : [ {
      "code" : "FD5CKXRoEdXXZ6LeXufZ4EhnSpXvd4WriFz",
      "extRef" : "ER ID1111111 FRONT STRAIGHT",
      "page" : "FRONT",
      "style" : "STRAIGHT",
      "format" : "JPG",
      "data" : "ZW1wdHk="
    }, {
      "code" : "FD5CKXRoEpyAEK91t75kEGWBeA3ynoBc4si",
      "extRef" : "ER ID1111111 BACK STRAIGHT",
      "page" : "BACK",
      "style" : "STRAIGHT",
      "format" : "PNG",
      "data" : "ZW1wdHk="
    } ],
    "code" : "FD5CKXRoEvgyZvYCZPTCic2cdH4vqj4Ta72",
    "extRef" : "ER ID1111111"
  } ]
}

Attributes

The organization legal entity object

{
  "legalForm" : "organization",
  "type" : "PRIVATE_COMPANY",
  "registrationNumber" : "346242542",
  "ultimateBeneficialOwners" : [ {
    "code" : "FD5CKXQTDep1TSgdsy96SYixD6pKGkbXTNg",
    "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" : "2017-02-03",
      "expireAt" : "2024-02-03",
      "issuerCountry" : "NLD",
      "photos" : [ {
        "code" : "FD5CKXQTCuuPRNBkq1KQtuuoJmWVWqLcv3r",
        "extRef" : "ER ID1111111 FRONT STRAIGHT",
        "page" : "FRONT",
        "style" : "STRAIGHT",
        "format" : "JPG",
        "data" : "ZW1wdHk="
      }, {
        "code" : "FD5CKXQTD34A6NwEg1x44B67LZbH5xHhBgc",
        "extRef" : "ER ID1111111 BACK STRAIGHT",
        "page" : "BACK",
        "style" : "STRAIGHT",
        "format" : "PNG",
        "data" : "ZW1wdHk="
      } ],
      "code" : "FD5CKXQTD9VT6h1ZwAT6syPDrGr6vYPmJdN",
      "extRef" : "ER ID1111111"
    } ]
  } ],
  "documents" : [ {
    "title" : "KVK",
    "issuer" : "COMPANY_REGISTER",
    "issuedAt" : "2020-02-03",
    "issuerCountry" : "NLD",
    "data" : "ZW1wdHk=",
    "code" : "FD5CKXQT5mrC5KP4kptD1NrxRSHbP4TdnEU",
    "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

Documents

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

{
  "type" : "PASSPORT",
  "number" : "12345",
  "issuedAt" : "2014-01-01",
  "expireAt" : "2024-01-01",
  "photos" : [ {
    "code" : "FD5CMFx3bZiXfADk1TGrsMqJt66XryNvu4k",
    "page" : "FRONT",
    "style" : "STRAIGHT",
    "format" : "JPG",
    "data" : "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAA1BMVEX/TQBcNTh/AAAAAXRSTlPM0jRW/QAAAApJREFUeJxjYgAAAAYAAzY3fKgAAAAASUVORK5CYII="
  }, {
    "code" : "FD5CMFx3bZiVwsRBTKycuXq33FX7q6FBaNC",
    "page" : "FRONT",
    "style" : "TILTED",
    "format" : "JPG",
    "data" : "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAA1BMVEX/TQBcNTh/AAAAAXRSTlPM0jRW/QAAAApJREFUeJxjYgAAAAYAAzY3fKgAAAAASUVORK5CYII="
  } ],
  "code" : "FD5CMFx3bZiW9y2fwGsCh9MZDiSiDoVxVoE"
}

Create a personal document

$ 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="
  } ]
}'

{
  "type" : "PASSPORT",
  "number" : "12345",
  "issuedAt" : "2014-01-01",
  "expireAt" : "2024-01-01",
  "photos" : [ {
    "code" : "FD5CMFx3bZiXfADk1TGrsMqJt66XryNvu4k",
    "page" : "FRONT",
    "style" : "STRAIGHT",
    "format" : "JPG",
    "data" : "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAA1BMVEX/TQBcNTh/AAAAAXRSTlPM0jRW/QAAAApJREFUeJxjYgAAAAYAAzY3fKgAAAAASUVORK5CYII="
  }, {
    "code" : "FD5CMFx3bZiVwsRBTKycuXq33FX7q6FBaNC",
    "page" : "FRONT",
    "style" : "TILTED",
    "format" : "JPG",
    "data" : "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAA1BMVEX/TQBcNTh/AAAAAXRSTlPM0jRW/QAAAApJREFUeJxjYgAAAAYAAzY3fKgAAAAASUVORK5CYII="
  } ],
  "code" : "FD5CMFx3bZiW9y2fwGsCh9MZDiSiDoVxVoE"
}

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

Path Parameters

Attributes

The organization document object

{
  "title" : "KVK",
  "issuer" : "COMPANY_REGISTER",
  "issuedAt" : "2018-06-05",
  "issuerCountry" : "NLD",
  "data" : "ZW1wdHk=",
  "code" : "FD5CKXQS1GBh3mJiN2suUYLLTc5qmgxzUGQ"
}

Create an organization document

$ 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="
}'

{
  "title" : "KVK",
  "issuer" : "COMPANY_REGISTER",
  "issuedAt" : "2018-06-05",
  "issuerCountry" : "NLD",
  "data" : "ZW1wdHk=",
  "code" : "FD5CKXQS1GBh3mJiN2suUYLLTc5qmgxzUGQ"
}

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

Path Parameters

Attributes

Accounts

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

{
  "code" : "FD5CMFusPZUBepKsUaPuof6WYteFa2Ju8E4",
  "extRef" : "My Unique Internal Virtual Account Reference",
  "accountType" : "DEFAULT",
  "displayName" : "My Unique Payaut Virtual Account Display Name"
}

Create an account

$ 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"
}'

{
  "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

Attributes

Retrieve an account

$ curl 'https://sandbox.payaut.com/api/v1/accountholders/FD5CMFreWNDY8EK7ze9gZfYZLv6crfrVWP2/accounts/FD5CMFusPZUBepKsUaPuof6WYteFa2Ju8E4' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'

{
  "code" : "FD5CMFusPZUBepKsUaPuof6WYteFa2Ju8E4",
  "extRef" : "My Unique Internal Virtual Account Reference",
  "accountType" : "DEFAULT",
  "displayName" : "My Unique Payaut Virtual Account Display Name"
}

Path Parameters

List all 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'

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

Path Parameters

Attributes

Update an account

$ 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"
}'

{
  "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

Attributes

External accounts

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

{
  "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

Create an external account

$ 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="
  }
}'

{
  "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

Attributes

Retrieve an external account

$ curl 'https://sandbox.payaut.com/api/v1/accountholders/FD5CMFreWNDY8EK7ze9gZfYZLv6crfrVWP2/externalaccounts/FD5CMFupEH62gdyC7fznfUMpQuXRnbxbt7z' -i -X GET \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'

{
  "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

List all accounts

$ 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'

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

Path Parameters

Attributes

Account Balance

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

$ curl 'https://sandbox.payaut.com/api/v1/fund/balance/FD5CKXSbJZyxvnkwKreGMRESWB6ppADpG56' -i -X GET \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'

{
  "code" : "FD5CKXSbJZyxvnkwKreGMRESWB6ppADpG56",
  "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

Payment splits

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

{
  "code" : "FD5CKXPYY8wRWY68isi7pioQx2x2oWLBofE",
  "extRef" : "platformOrderId#123",
  "totalAmount" : 70700,
  "description" : "Your Platform Order Description",
  "items" : [ {
    "code" : "FD5CKXPYYMp1XAEoEoPVfgCSCJEt7mSJSk8",
    "type" : "ITEM",
    "label" : "SHIPPING",
    "extRef" : "platformOrderId#123#shipping",
    "amount" : 700,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "$7.00 shipping fee charged by the platform"
  }, {
    "code" : "FD5CKXPYYSpMC4xqLDdMpZ4heKc2PofWqW8",
    "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"
}

Create a payment split

$ 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"
}'

{
  "code" : "FD5CKXS5DCAEkXKXWyt5cKCmgSbXSX1S2E4",
  "extRef" : "platformOrderId#123",
  "totalAmount" : 7000,
  "description" : "Your Platform Order Description",
  "items" : [ {
    "code" : "FD5CKXS5JXongBacLbt8hpJcohC7MxhBoma",
    "type" : "ITEM",
    "label" : "COMMISSION",
    "extRef" : "platformOrderId#123#commission",
    "amount" : 2000,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "Human readable description of this split payment item"
  }, {
    "code" : "FD5CKXS5Jh6zMJMXwCuYsTnyRFzXk9YJdMJ",
    "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

Retrieve a payment split

$ curl 'https://sandbox.payaut.com/api/v1/fund/split-payments/FD5CKXSVKWkknoq6Z8wfR29g8KvpbmTeL2t' -i -X GET \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'

{
  "code" : "FD5CKXSVKWkknoq6Z8wfR29g8KvpbmTeL2t",
  "extRef" : "platformOrderId#123",
  "totalAmount" : 7000,
  "description" : "Your Platform Order Description",
  "items" : [ {
    "code" : "FD5CKXSVKw4yUen8QtiWdMsbp33jaTQkRE8",
    "type" : "ITEM",
    "label" : "COMMISSION",
    "extRef" : "platformOrderId#123#commission",
    "amount" : 2000,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "Human readable description of this split payment item"
  }, {
    "code" : "FD5CKXSVL25K9ZWAWJxNnEjsG4Qsbn1DpNc",
    "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

List all payment splits

$ 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'

{
  "pageSize" : 1,
  "pageNumber" : 1,
  "elements" : [ {
    "code" : "FD5CKXSrNyesbkdnbQRiB8u3GUsFdS1Tqep",
    "extRef" : "platformOrderId#123",
    "totalAmount" : 7000,
    "description" : "Your Platform Order Description",
    "items" : [ {
      "code" : "FD5CKXSrPG6qwtAC2em3hQ9U9hMVXpV6Adn",
      "type" : "ITEM",
      "label" : "COMMISSION",
      "extRef" : "platformOrderId#123#commission",
      "amount" : 2000,
      "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
      "description" : "Human readable description of this split payment item"
    }, {
      "code" : "FD5CKXSrPM7BcntE84zurH1jbiie8wNDEEC",
      "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

Refund splits

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

{
  "code" : "FD5CKXS5P1PwtkbLGFRs6RkYyJAKjTCGYXJ",
  "extRef" : "platformOrderId#123",
  "totalAmount" : 40000,
  "description" : "Your Platform Refund Description",
  "items" : [ {
    "code" : "FD5CKXS5PDZ4Eg4rCJyebv6biEk7V9GjTkU",
    "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"
}

Create a full refund split

$ 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"
}'

{
  "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

Create a partial refund split

$ 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"
}'

{
  "code" : "FD5CKXQTYaXEhvkokkfifhsfS9dPwSiic9n",
  "extRef" : "platformOrderId#123",
  "totalAmount" : 2500,
  "description" : "Your Platform Refund Description",
  "items" : [ {
    "code" : "FD5CKXQTYp7JPFacrYUgr7m5EGgwXBbf67a",
    "type" : "ITEM",
    "label" : "COMMISSION",
    "extRef" : "refund#123#commission",
    "originalExtRef" : "platformOrderId#123#commission",
    "amount" : 500,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "Refunded commission"
  }, {
    "code" : "FD5CKXQTZ58KPykj84YqhTQt4ZQPBENEXHr",
    "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

Retrieve a refund split

$ curl 'https://sandbox.payaut.com/api/v1/fund/split-refunds/FD5CKXRjUJARec3uHScryBnsHCkEMLLPDFe' -i -X GET \
    -H 'Authorization: Bearer FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'

{
  "code" : "FD5CKXRjUJARec3uHScryBnsHCkEMLLPDFe",
  "extRef" : "platformOrderId#123",
  "totalAmount" : 2500,
  "description" : "Your Platform Refund Description",
  "items" : [ {
    "code" : "FD5CKXRjUh3h13edyU8XWbh8vzvCkRspFBE",
    "type" : "ITEM",
    "label" : "COMMISSION",
    "extRef" : "refund#123#commission",
    "originalExtRef" : "platformOrderId#123#commission",
    "amount" : 500,
    "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
    "description" : "Refunded commission"
  }, {
    "code" : "FD5CKXRjUnmWLf3pekVyzwL5ucXDhrvTfxt",
    "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

List all refund splits

$ 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'

{
  "pageSize" : 1,
  "pageNumber" : 1,
  "elements" : [ {
    "code" : "FD5CKXRNDoENe19kgbyytyZZ6heBqxwsLbJ",
    "extRef" : "platformOrderId#123",
    "totalAmount" : 2500,
    "description" : "Your Platform Refund Description",
    "items" : [ {
      "code" : "FD5CKXRNEGQVzeoNspHCTA5uv3FRiaWumP6",
      "type" : "ITEM",
      "label" : "COMMISSION",
      "extRef" : "refund#123#commission",
      "originalExtRef" : "platformOrderId#123#commission",
      "amount" : 500,
      "accountCode" : "FD5CMGbmkHqxsXgusxidGWFMxFou4X6Mccx",
      "description" : "Refunded commission"
    }, {
      "code" : "FD5CKXRNEN8KLGCZZ6eewVirterT9Kti2EL",
      "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

Payouts

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

{
  "code" : "FD5CMGdfTBW1pWh8AZnci7eHuu93JLxM3zY",
  "createdAt" : "2022-02-03T13:12:53.10032+01:00",
  "processAt" : "2022-02-04T13:12:53.100337+01:00",
  "useBalanceAt" : "2022-02-04T13:12:53.100337+01:00",
  "accountCode" : "FD5CMGdfT7g7VxgUvVKSJT3tc6YKgan7GWt",
  "externalAccountCode" : "FD5CMGdfT7g56S1vx4Qc1vDEmN52G8NrWFi",
  "amount" : 1000,
  "description" : "This is a test",
  "status" : "WAITING"
}

Create a payout request

$ curl 'https://sandbox.payaut.com/api/v1/fund/payout-requests' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi' \
    -d '{
  "processAt" : "2022-02-04T13:12:53.100337+01:00",
  "useBalanceAt" : "2022-02-04T13:12:53.100337+01:00",
  "accountCode" : "FD5CMGdfT7g7VxgUvVKSJT3tc6YKgan7GWt",
  "externalAccountCode" : "FD5CMGdfT7g56S1vx4Qc1vDEmN52G8NrWFi",
  "amount" : 1000,
  "description" : "This is a test"
}'

{
  "code" : "FD5CMGdfTBW1pWh8AZnci7eHuu93JLxM3zY",
  "createdAt" : "2022-02-03T13:12:53.10032+01:00",
  "processAt" : "2022-02-04T13:12:53.100337+01:00",
  "useBalanceAt" : "2022-02-04T13:12:53.100337+01: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

Retrieve a payout request

$ curl 'https://sandbox.payaut.com/api/v1/fund/payout-requests/FD5CMGdfTBW1pWh8AZnci7eHuu93JLxM3zY' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'

{
  "code" : "FD5CMGdfTBW1pWh8AZnci7eHuu93JLxM3zY",
  "createdAt" : "2022-02-03T13:12:53.10032+01:00",
  "processAt" : "2022-02-04T13:12:53.100337+01:00",
  "useBalanceAt" : "2022-02-04T13:12:53.100337+01: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.

Delete a payout request

$ curl 'https://sandbox.payaut.com/api/v1/fund/payout-requests/FD5CMGdfTBW1pWh8AZnci7eHuu93JLxM3zY' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'

{
  "code" : "FD5CMGdfTBW1pWh8AZnci7eHuu93JLxM3zY",
  "createdAt" : "2022-02-03T13:12:53.10032+01:00",
  "processAt" : "2022-02-04T13:12:53.100337+01:00",
  "useBalanceAt" : "2022-02-04T13:12:53.100337+01: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.

List all payout requests

$ curl 'https://sandbox.payaut.com/api/v1/fund/payout-requests' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: FD5CMFqSZ4c3U2YMjyDqb1sfHyDcMWEJN5E.FD5CMFqSZ4c47u5kym8Vt5DSMntNMi5VGPi'

{
  "pageSize" : 1,
  "pageNumber" : 1,
  "elements" : [ {
    "code" : "FD5CMGdfTBW1pWh8AZnci7eHuu93JLxM3zY",
    "createdAt" : "2022-02-03T13:12:53.10032+01:00",
    "processAt" : "2022-02-04T13:12:53.100337+01:00",
    "useBalanceAt" : "2022-02-04T13:12:53.100337+01: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