Share a merchant's details when they choose to apply, and send them to a registration that starts already filled in.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Call this endpoint at the point of handoffEach request prepopulates one registration. Call it when the merchant chooses to apply, and send them to the
entryUrlstraight away.
- The
entryUrlis valid for 15 minutes from the request;expiresAtgives the exact time. The merchant can reopen it as often as they like until then.- Links created in advance, or in a scheduled batch, will have expired by the time the merchant opens them. The merchant then completes the standard registration instead.
Use the host for your region
Region Base URL UK and Europe https://platform.eu.liberis.comNorth America https://platform.us.liberis.comAuthenticate with the same client credentials and access token as the rest of the Liberis API. Unlike the other v3 endpoints, this one is served under
/journey/v1, not/v3.
OnlypartnerClientIdsis requiredThe request is refused only when
partnerClientIdsis missing or invalid, or the body isn't a JSON object. Anything else we can't use is left out and listed indroppedFields, never a reason to refuse the request. Send as much as you hold: the more you send, the less the merchant has to fill in.
Send exactly one client id
partnerClientIdsis an array to match the v3 registration request, but the registration uses only the first. Send exactly one.
Fields we couldn't use
Every field left out of the stored details is listed in droppedFields, with where it was in your request and why:
reason | Meaning |
|---|---|
NOT_SUPPORTED | The field isn't one this endpoint accepts. |
INVALID_VALUE | The value isn't in the expected format or list, or is an empty string. An industry category or identification number missing part of its value is left out whole. |
DUPLICATE | Another contact already has this email address, ignoring case. The first contact keeps it. |
A path uses a dot before each nested field and [n] for an array element, counted in your request as sent: contacts[1].email. A field name that isn't a plain identifier is quoted: ["company.businessType"].
Formats
| Field | Format | Example |
|---|---|---|
Every country | ISO 3166-1 alpha-3 | USA, not US |
Every state | ISO 3166-2 subdivision code, without the country prefix | CO, not US-CO or Colorado |
company.businessType | One of the v3 business types listed under businessType in the request schema | LLC |
industryCategory[].code | The code for its scheme: MCC 4 digits, SIC 4 or 5, ICC 5, NAICS 6 | { "scheme": "MCC", "code": "7230" } |
contacts[].dateOfBirth, company.businessStartDate | YYYY-MM-DD, not in the future | 2020-02-02 |
contacts[].ownershipPercentage | More than 0, at most 100 | 100 |
A value in another format is listed in droppedFields as INVALID_VALUE.
Addresses should be in the country your partnership serves. The registration doesn't use an address in another country.
How your values are used
Values are mapped onto the registration, not shown verbatim. Business types, for example, are kept as you send them, and the registration maps them onto the business types it offers in the merchant's country. Where it can't represent the one you sent, it asks the merchant.
The registration doesn't use some fields yet. They are kept with the details, so keep sending them:
bankDetailscompany.phoneNumber- client ids after the first in
partnerClientIds - industry codes in schemes other than MCC
Contacts
Send everyone who owns part of the business, and mark the person applying with "isPrimaryContact": true. If no contact is marked, the first is treated as the primary.
The primary contact's details prefill the merchant's own steps. Anything you don't send, the merchant fills in.
The registration also takes up to three other contacts, in the order you send them. Each is used only if it has firstName, lastName, email, a dateOfBirth of someone 16 or over, a complete home address in residences and an ownershipPercentage; otherwise the merchant can add that person themselves. If ownership across all the contacts would come to more than 100, only the primary contact is used. A sole proprietor has no other owners, so only the primary contact is used.
No two contacts can share an email address or an identification number.
Errors
| Status | When |
|---|---|
400 | partnerClientIds is missing or invalid, or the body isn't a JSON object. errors lists each problem with its path. A body that isn't valid JSON, or is a bare value such as a string, has no errors. |
413 | The body is larger than 100 KB. |
500 | The details could not be stored. Retrying is safe: each request creates a new link. |