The request data is sent as an additional input parameter:
Parameter | Type | Description |
---|---|---|
boardingrequest | base64 | Base64-encoded BoardingRequest XML message. |
The BoardingRequest XML format is specified by the Schema. The fields are listed below using the following conventions:
- Every table describes the XML structure of the element in the title
- The Element denotes the name of the XML element or attribute
- The Type denotes the type of the element which is either
- a simple type, e.g.
- ascii for strings composed of ASCII characters (like alphabetic and numeric characters, spaces, line feeds, etc.)
- utf8 for strings allowing all UTF-8 characters (the max sizes specified by the regular expressions refer to the byte size)
- a complex type, e.g. BusinessDetails
- a list of elements of a certain type, e.g. PaymentMethod[1..N] which denotes a list of elements of type PaymentMethod containing at least 1 and maximum N elements.
- The Quantity denotes the quantity of the elements
- The Value holds information about the content of the field and about the format, e.g. a regular expression.
- Attributes of an element are listed at the beginning of an element specification and their tags are italic
- In general, we only allow printable characters in XML Elements. Leading whitespaces are not allowed and trailing whitespaces are trimmed.
Boarding requests can relate to an individual, an organization, or a partnership as a legal entity. An example of each type of boarding request is given in the Appendix (Individual, Organization, and Partnership)
BoardingRequest
Element | Type | Quantity | Value |
---|---|---|---|
IsPlatform | - | 0..1 | Flag which defines if the given merchant is a platform provider. If this tag exists in the xml then the given merchant is a platform provider, otherwise it is an independent merchant. |
PlatformReference | ascii | 0..1 | Reference to the platform provider. This field references to the platform provider merchant. If this field is present in the request then the given merchant is a submerchant of the platform. Platform provider merchant should have been registered in the system prior to the boarding of the submerchant. IsPlatform field can’t be used at the same time as this field. |
PricingGroup | ascii | 0..1 | [0-9a-zA-Z_-]{1,32} Pricing group to assign the merchant to. PlatformReference field can’t be used at the same time as this field. |
Reference | ascii | 1 | [A-Z0-9]{1,32} Unique merchant reference, assigned by the submitting partner. This reference is used in all method calls regarding the merchant. |
NotificationUrl | ascii | 1 | URL notifications are posted to when there is a status change. |
BusinessDetails | BusinessDetails | 1 | Business details of the merchant. |
PaymentMethods | PaymentMethod [1..N] | 1 | List of payment methods to activate for the merchant. |
LegalEntity | LegalEntity | 1 | Legal entity related to the boarding request. |
BusinessDetails
Element | Type | Quantity | Value |
---|---|---|---|
MerchantCategoryCode | ascii | 1 | [0-9]{4} MCC |
PaymentDescriptor | ascii | 1 | [0-9a-zA-Z.%,&/+*${|}- {0,255} Descriptor put on the charge to the customer |
TradeName | ascii | 0..1 | [^A-Za-z0-9:?/+(),_. -] Non-empty string up to 255 characters Trade name / Doing Business As (DBA) name. |
Websites | Website [0..100] | 1 | List of website URLs the business operates. Should be left empty if and only if the merchant is a submerchant. Mandatory for all merchants and platforms. |
MonthlyTransactions | MonthlyTransactions | 1 | Expected transaction count. |
PhoneNumber | PhoneNumber | 0..1 | [+]?[0-9]{8,19} Merchant phone number |
EmailAddress | EmailAddress | 0..1 | [ˆ@ ]+@[ˆ@ ]+.[ˆ@ ]+ Merchant email address |
IncorporationDate | Date | 0..1 | Merchant incorporation data |
PaymentMethod
Element | Type | Quantity | Value |
---|---|---|---|
name | ascii | 1 | [0-9a-zA-Z]{2, 31} Name of the payment method the legal entity applies for. List of valid values is set by PPRO and communicated to the partner. |
creditorId | ascii | 0..1 | [A-Z]{2}[0-9]{2}[A-Z0-9]{3}[A-Z0-9]{3,28} Creditor ID, only for SEPA Direct Debit. |
creditorName | ascii | 0..1 | .{0, 255} Creditor name, only for SEPA Direct Debit. |
CreditorResidence | Residence | 0..1 | Residence address, only for SEPA Direct Debit. |
AdditionalData | AdditionalData | 0..1 | A list of LPM-specific key-value pairs, up to 10000 items. |
AdditionalData
Element | Type | Quantity | Value |
---|---|---|---|
KeyValue | KeyValue | 0..10000 | Key-value pairs. |
KeyValue
Element | Type | Quantity | Value |
---|---|---|---|
key | ascii | 1 | [0-9a-zA-Z]{1, 31} Key attribute. |
value | ascii | 1 | .{1, 255} Value attribute. |
LegalEntity
Element | Type | Quantity | Value |
---|---|---|---|
Individual | Individual | 0..1 | Information of an individual. Mandatory if the legal entity of the business is an individual. If present, this is the only child of the LegalEntity element. |
Organization | Organization | 0..1 | Information of an organization. Mandatory if the legal entity of the business is an organization. If present, this is the only child of the LegalEntity element. |
NonprofitOrganization | NonprofitOrganization | 0..1 | Information of a nonprofit organization. Mandatory if the legal entity of the business is a nonprofit organization. If present, this is the only child of the LegalEntity element. |
Partnership | Partnership | 0..1 | Information of a partnership. Mandatory if the legal entity of the business is a partnership. If present this is the only child of the LegalEntity element. |
Individual
Organization
Element | Type | Quantity | Value |
---|---|---|---|
Name | utf8 | 1 | .{0, 255} Name of the organization. |
RegistrationNumber | ascii | 1 | [0-9a-zA-Z]{1, 255} Registration number of the organization. |
Residence | Residence | 1 | Residence of the organization. |
Directors | Person [1..30] | 1 | List of all the directors of the organization. |
UltimateBeneficialOwners | Person [0..30] | 1 | List of the ultimate beneficial owners with at least 25% ownership of the organization, if any. If an organization is a beneficial owner, its ultimate beneficial owners must be listed. |
Partnership
MonthlyTransactions
Element | Type | Quantity | Value |
---|---|---|---|
Count | numeric | 1 | Number of transactions. |
AverageValue | ascii | 1 | [0-9]+(.[0-9]{1,3})? |
Currency | ascii | 1 | ISO 4217 - Alphabetic Currency Code |
Person
Name
Element | Type | Quantity | Value |
---|---|---|---|
Title | utf-8 | 0..1 | .{0, 255} The title of the person. For example: Mr, Ms, Senator. This tag is not present if there is no title. |
FirstName | utf-8 | 1 | .{0, 255} First name of the person. |
MiddleName | utf-8 | 0..1 | .{0, 255} Middle name of the person. This tag is not present if there is no middle name. |
LastName | utf-8 | 1 | .{0, 255} Last name of the person. |
Date
Element | Type | Quantity | Value |
---|---|---|---|
Year | numeric | 1 | Year. YYYY |
Month | numeric | 1 | Month. MM |
Day | numeric | 1 | Day of the month. DD |
Residence
Element | Type | Quantity | Value |
---|---|---|---|
Address | AddressLine [1..4] | 1 | Residence address. |
ZipCode | ascii | 0..1 | [0-9a-zA-Z- ]{1,31} ZIP code of the residence - optional as there are situations where an address lacks a zip code. |
City | utf-8 | 1 | [0-9a-zA-Z- ]{1, 255} City of the residence. |
State | ascii | 0..1 | [0-9a-zA-Z- ]{0, 255} State of the residence. This is an optional field. |
Country | ascii | 1 | ISO 3166 - Country Code of the residence. |
Payment Method Specific Elements
Afterpay
Element | Type | Quantity | Value |
---|---|---|---|
tradingCountries | string | 1 | ^[A-Z]{2}(,[A-Z]{2})*$ List of trading countries in country code. Used for CN/HK merchants (CBT). |
Alipay
Element | Type | Quantity | Value |
---|---|---|---|
RegistrationNumber | ascii | 1 | [0-9a-zA-Z]{1, 255} Registration number of the organisation. The registration number is mandatory for all types of merchants. |
Klarna
Element | Type | Quantity | Value |
---|---|---|---|
EmailAddress | EmailAddress | 1 | [^@]+@[^@]+.[^@]+ Merchant email address. |
SEPA DD
Element | Type | Quantity | Value |
---|---|---|---|
creditorId | ascii | 1 | Mandatory element for SEPA DD. |
creditorName | ascii | 0..1 | [0-9a-zA-Z]{2, 31} Name of the creditor. This is an optional element. |
creditorResidence | ascii | 0..1 | [0-9a-zA-Z]{2, 31} Country of the creditor. This is an optional element. |
WeChat Pay
Element | Type | Quantity | Value |
---|---|---|---|
Emailaddress | EmailAddress | 1 | [^@]+@[^@]+.[^@]+ Merchant email address. |
RegistrationNumber | ascii | 0..1 | [0-9a-zA-Z]{1, 255} Registration number of the organization. This is mandatory if the legal entity type is Organization or Partnership . |
PhoneNumber | PhoneNumber | 1 | [+]?[0-9]{8,19} Merchant phone number. |
Other Types
Element | Type | Quantity | Value |
---|---|---|---|
Website | ascii | 1 | URL of the websites of the legal entity’s business |
AddressLine | utf-8 | 1 | .{1, 255} Line of an address |
Example Request
<BoardingRequest>
<Reference>MERCHANT0001</Reference
<NotificationUrl>https://notify.url</NotificationUrl
<BusinessDetails>
<MerchantCategoryCode>742</MerchantCategoryCode
<PaymentDescriptor>Musical Instruments</PaymentDescriptor
<TradeName>MusicInstr</TradeName>
<Websites>
<Website>https://www.example.com</Website
<Website>https://www.example2.com</Website>
</Websites>
<MonthlyTransactions>
<Count>100</Count>
<AverageValue>10</AverageValue>
<Currency>EUR</Currency>
</MonthlyTransactions>
</BusinessDetails>
<PaymentMethods>
<PaymentMethod name="afterpay">
<AdditionalData>
<KeyValue key="tradingCountries" value="US,GB" />
</AdditionalData>
</PaymentMethod>
<PaymentMethod name="ideal" />
<PaymentMethod name="p24" />
<PaymentMethod name="bcmc" />
<PaymentMethod name="multibanco" />
<PaymentMethod name="eps" />
<PaymentMethod name="zip">
<AdditionalData>
<KeyValue key="segmentType" value="Standard" />
</AdditionalData>
</PaymentMethod>
<PaymentMethod name="sepaddmodelc">
<AdditionalData>
<KeyValue key="creditorAddressLine" value="Any Street 999" />
<KeyValue key="creditorPostCode" value="813710" />
<KeyValue key="creditorCity" value="SomeCity" />
<KeyValue key="creditorState" value="SomeState" />
<KeyValue key="creditorCountry" value="GB" />
<KeyValue key="creditorId" value="DE98ZZZ09999999999" />
</AdditionalData>
</PaymentMethod>
<PaymentMethod name="sepaddmodeld" creditorId="DE98ZZZ09999999999" creditorName="Custom Creditor Name">
<CreditorResidence>
<Address>
<AddressLine>Another Street 999</AddressLine>
</Address>
<ZipCode>800000</ZipCode>
<City>Another Cit</City>
<State>Another State</State>
<Country>GB</Country>
</CreditorResidence>
</PaymentMethod>
<PaymentMethod name="sofort" />
</PaymentMethods>
<LegalEntity>
<Individual>
<Name>Any Artist Name</Name>
<RegistrationNumber>r000123</RegistrationNumber>
<Residence>
<Address>
<AddressLine>Any Street 888</AddressLine>
</Address>
<ZipCode>12345</ZipCode>
<City>Any City</City>
<State>Any State</State>
<Country>GB</Country>
</Residence>
<Person>
<Name>
<FirstName>John</FirstName>
<LastName>Smith</LastName>
</Name>
<DateOfBirth>
<Year>1950</Year>
<Month>1</Month>
<Day>1</Day>
</DateOfBirth>
<Residence>
<Address>
<AddressLine>Any Street 123</AddressLine>
</Address>
<ZipCode>12345</ZipCode>
<City>Any City</City>
<State>Any State</State>
<Country>GB</Country>
</Residence>
</Person>
</Individual>
</LegalEntity>>
<BoardingRequest>
<Reference>MERCHANT0002</Reference>
<NotificationUrl>https://notify.url</NotificationUrl>
<BusinessDetails>
<MerchantCategoryCode>742</MerchantCategoryCode>
<PaymentDescriptor>Artist's Musical Instruments</PaymentDescriptor>
<TradeName>AMI</TradeName>
<Websites>
<Website>https://www.example.com</Website>
<Website>https://www.example2.com</Website>
</Websites>
<MonthlyTransactions>
<Count>100</Count>
<AverageValue>10</AverageValue>
<Currency>EUR</Currency>
</MonthlyTransactions>
<PhoneNumber>+123456789</PhoneNumber>
<EmailAddress>[email protected]</EmailAddress>
</BusinessDetails>
<PaymentMethods>
<PaymentMethod name="multibanco"/>
<PaymentMethod name="eps"/>
</PaymentMethods>
<LegalEntity>
<Organization>
<Name>Any Company</Name>
<RegistrationNumber>r000123</RegistrationNumber>
<Residence>
<Address>
<AddressLine>Any Street 1</AddressLine>
</Address>
<ZipCode>12345</ZipCode>
<City>Any City</City>
<State>Any State</State>
<Country>GB</Country>
</Residence>
<Directors>
<Person>
<Name>
<FirstName>John</FirstName>
<LastName>Smith</LastName>
</Name>
<DateOfBirth>
<Year>1950</Year>
<Month>1</Month>
<Day>1</Day>
</DateOfBirth>
<Residence>
<Address>
<AddressLine>Any Street 123</AddressLine>
</Address>
<ZipCode>12345</ZipCode>
<City>Any City</City>
<State>Any State</State>
<Country>GB</Country>
</Residence>
</Person>
<Person>
<Name>
<FirstName>Jack</FirstName>
<LastName>Any</LastName>
</Name>
<DateOfBirth>
<Year>1950</Year>
<Month>1</Month>
<Day>2</Day>
</DateOfBirth>
<Residence>
<Address>
<AddressLine>Any Street 124</AddressLine>
</Address>
<ZipCode>12345</ZipCode>
<City>Any City</City>
<State>Any State</State>
<Country>GB</Country>
</Residence>
</Person>
</Directors>
<UltimateBeneficialOwners>
<Person>
<Name>
<FirstName>John</FirstName>
<LastName>Smith</LastName>
</Name>
<DateOfBirth>
<Year>1950</Year>
<Month>1</Month>
<Day>1</Day>
</DateOfBirth>
<Residence>
<Address>
<AddressLine>Any Street 123</AddressLine>
</Address>
<ZipCode>12345</ZipCode>
<City>Any City</City>
<State>Any State</State>
<Country>GB</Country>
</Residence>
</Person>
</UltimateBeneficialOwners>
</Organization>
</LegalEntity>
</BoardingRequest>
<BoardingRequest>
<Reference>MERCHANT0003</Reference>
<NotificationUrl>https://notify.url</NotificationUrl>
<BusinessDetails>
<MerchantCategoryCode>742</MerchantCategoryCode>
<PaymentDescriptor>anypartnership</PaymentDescriptor>
<Websites>
<Website>https://www.example.com</Website>
<Website>https://www.example2.com</Website>
</Websites>
<MonthlyTransactions>
<Count>100</Count>
<AverageValue>10</AverageValue>
<Currency>EUR</Currency>
</MonthlyTransactions>
</BusinessDetails>
<PaymentMethods>
<PaymentMethod name="ideal"/>
</PaymentMethods>
<LegalEntity>
<Partnership>
<Name>Any Partnership</Name>
<Residence>
<Address>
<AddressLine>Any Street 3</AddressLine>
</Address>
<ZipCode>12345</ZipCode>
<City>Any City</City>
<State>Any State</State>
<Country>GB</Country>
</Residence>
<Partners>
<Person>
<Name>
<FirstName>John</FirstName>
<LastName>Smith</LastName>
</Name>
<DateOfBirth>
<Year>1950</Year>
<Month>1</Month>
<Day>1</Day>
</DateOfBirth>
<Residence>
<Address>
<AddressLine>Any Street 123</AddressLine>
</Address>
<ZipCode>12345</ZipCode>
<City>Any City</City>
<State>Any State</State>
<Country>GB</Country>
</Residence>
</Person>
<Person>
<Name>
<FirstName>Jack</FirstName>
<LastName>Any</LastName>
</Name>
<DateOfBirth>
<Year>1950</Year>
<Month>1</Month>
<Day>2</Day>
</DateOfBirth>
<Residence>
<Address>
<AddressLine>Any Street 124</AddressLine>
</Address>
<ZipCode>12345</ZipCode>
<City>Any City</City>
<State>Any State</State>
<Country>GB</Country>
</Residence>
</Person>
</Partners>
</Partnership>
</LegalEntity>
</BoardingRequest>
<BoardingRequest>
<IsPlatform/>
<PricingGroup>Tier1</PricingGroup>
<Reference>MERCHANT0001</Reference>
<NotificationUrl>https://notify.url</NotificationUrl>
<BusinessDetails>
<MerchantCategoryCode>742</MerchantCategoryCode>
<PaymentDescriptor>Musical Instruments</PaymentDescriptor>
<TradeName>MusicInstr</TradeName>
<Websites>
<Website>https://www.example.com</Website>
<Website>https://www.example2.com</Website>
</Websites>
<MonthlyTransactions>
<Count>100</Count>
<AverageValue>10</AverageValue>
<Currency>EUR</Currency>
</MonthlyTransactions>
</BusinessDetails>
<PaymentMethods>
<PaymentMethod name="ideal"/>
<PaymentMethod name="p24"/>
<PaymentMethod name="bcmc"/>
<PaymentMethod name="multibanco"/>
<PaymentMethod name="eps"/>
<PaymentMethod name="giropay"/>
<PaymentMethod name="sofort"/>
</PaymentMethods>
<LegalEntity>
<Individual>
<Name>Any Artist Name</Name>
<Residence>
<Address>
<AddressLine>Any Street 888</AddressLine>
</Address>
<ZipCode>12345</ZipCode>
<City>Any City</City>
<State>Any State</State>
<Country>GB</Country>
</Residence>
<Person>
<Name>
<FirstName>John</FirstName>
<LastName>Smith</LastName>
</Name>
<DateOfBirth>
<Year>1950</Year>
<Month>1</Month>
<Day>1</Day>
</DateOfBirth>
<Residence>
<Address>
<AddressLine>Any Street 123</AddressLine>
</Address>
<ZipCode>12345</ZipCode>
<City>Any City</City>
<State>Any State</State>
<Country>GB</Country>
</Residence>
</Person>
</Individual>
</LegalEntity>
</BoardingRequest>
<BoardingRequest>
<PlatformReference>MERCHANT0000</PlatformReference>
<Reference>MERCHANT0001</Reference>
<NotificationUrl>https://notify.url</NotificationUrl>
<BusinessDetails>
<MerchantCategoryCode>1234</MerchantCategoryCode>
<PaymentDescriptor>anyshop</PaymentDescriptor>
<TradeName>anyshop</TradeName>
<Websites>
<Website>https://www.example.com</Website>
<Website>https://www.example2.com</Website>
</Websites>
<MonthlyTransactions>
<Count>100</Count>
<AverageValue>10</AverageValue>
<Currency>EUR</Currency>
</MonthlyTransactions>
</BusinessDetails>
<PaymentMethods>
<PaymentMethod name="ideal"/>
<PaymentMethod name="p24"/>
<PaymentMethod name="bcmc"/>
<PaymentMethod name="multibanco"/>
<PaymentMethod name="eps"/>
<PaymentMethod name="giropay"/>
<PaymentMethod name="sofort"/>
</PaymentMethods>
<LegalEntity>
<Individual>
<Name>Any Artist Name</Name>
<Residence>
<Address>
<AddressLine>Any Street 888</AddressLine>
</Address>
<ZipCode>12345</ZipCode>
<City>Any City</City>
<State>Any State</State>
<Country>GB</Country>
</Residence>
<Person>
<Name>
<FirstName>John</FirstName>
<LastName>Smith</LastName>
</Name>
<DateOfBirth>
<Year>1950</Year>
<Month>1</Month>
<Day>1</Day>
</DateOfBirth>
<Residence>
<Address>
<AddressLine>Any Street 123</AddressLine>
</Address>
<ZipCode>12345</ZipCode>
<City>Any City</City>
<State>Any State</State>
<Country>GB</Country>
</Residence>
</Person>
</Individual>
</LegalEntity>
</BoardingRequest>