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. For an address in another country, the registration doesn't use the state, and uses its other fields only where they fit the formats of the country your partnership serves.
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.
Each value is also checked against the registration's own rules for the merchant's country: postcode and phone number formats, an SSN or EIN pattern, a contact's age. A value that doesn't pass is left out, and the merchant fills it in. These checks happen when the merchant opens the link, so they aren't listed in droppedFields.
company.registrationNumber is used only for the business types the registration asks for one (in the US: limited partnerships, LLCs, limited companies and corporations), and not when it matches a contact's identification number.
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, and MCC codes after the first
phoneNumberfor any contact but the primary contactresidencesafter the first, which is taken as the contact's home address
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 with whatever details you send that pass the registration's rules, and the merchant completes the rest. A contact is used only if at least one of firstName, lastName or email passes the registration's rules: without one, the merchant couldn't tell who the rest of their details belong to. A sole proprietor or sole trader has no other owners, so only the primary contact is used, without an ownershipPercentage.
An ownershipPercentage is used only as a whole number. A fractional one, such as 12.5, isn't rounded: it's left out, and the merchant enters that contact's share. If the percentages that are used come to more than 100, percentages are left out, smallest first and the later contact's first between equal ones, until the rest come to 100 or less. The contacts themselves are kept.
No two contacts can share an email address or an identification number. A shared email address stays with the first contact that has it, as DUPLICATE describes. A shared identification number stays with the primary contact, otherwise with the earlier contact.
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. |