API Reference

Input parameters

The request data is sent as an additional input parameter:

ParameterTypeDescription
boardingrequestbase64Base64-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.
    1. ascii for strings composed of ASCII characters (like alphabetic and numeric characters, spaces, line feeds, etc.)
    2. 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

ElementTypeQuantityValue
IsPlatform-0..1Flag 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.
PlatformReferenceascii0..1Reference 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.
PricingGroupascii0..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.
Referenceascii1[A-Z0-9]{1,32}
Unique merchant reference, assigned by the submitting partner. This reference is used in all method calls regarding the merchant.
NotificationUrlascii1URL notifications are posted to when there is a status change.
BusinessDetailsBusinessDetails1Business details of the merchant.
PaymentMethodsPaymentMethod
[1..N]		1List of payment methods to activate for the merchant.
LegalEntityLegalEntity1Legal entity related to the boarding request.

BusinessDetails

ElementTypeQuantityValue
MerchantCategoryCodeascii1[0-9]{4}
MCC
PaymentDescriptorascii1[0-9a-zA-Z.%,&/+*${|}- {0,255}
Descriptor put on the charge to the customer
TradeNameascii0..1[^A-Za-z0-9:?/+(),_. -]
Non-empty string up to 255 characters Trade name / Doing Business As (DBA) name.
WebsitesWebsite
[0..100]		1List 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.
MonthlyTransactionsMonthlyTransactions1Expected transaction count.
PhoneNumberPhoneNumber0..1[+]?[0-9]{8,19}
Merchant phone number
EmailAddressEmailAddress0..1[ˆ@ ]+@[ˆ@ ]+.[ˆ@ ]+
Merchant email address
IncorporationDateDate0..1Merchant incorporation data

PaymentMethod

ElementTypeQuantityValue
nameascii1[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.
creditorIdascii0..1[A-Z]{2}[0-9]{2}[A-Z0-9]{3}[A-Z0-9]{3,28}
Creditor ID, only for SEPA Direct Debit.
creditorNameascii0..1.{0, 255}
Creditor name, only for SEPA Direct Debit.
CreditorResidenceResidence0..1Residence address, only for SEPA Direct Debit.
AdditionalDataAdditionalData0..1A list of LPM-specific key-value pairs, up to 10000 items.

AdditionalData

ElementTypeQuantityValue
KeyValueKeyValue0..10000Key-value pairs.

KeyValue

ElementTypeQuantityValue
keyascii1[0-9a-zA-Z]{1, 31}
Key attribute.
valueascii1.{1, 255}
Value attribute.

LegalEntity

ElementTypeQuantityValue
IndividualIndividual0..1Information 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.
OrganizationOrganization0..1Information 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.
NonprofitOrganizationNonprofitOrganization0..1Information 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.
PartnershipPartnership0..1Information 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

ElementTypeQuantityValue
Nameutf81.{0,255}
Name of the person. Must be the same name as on the passport/company registration documents.
RegistrationNumberascii0..1[0-9a-zA-Z]{1, 255}
Registration number of the person.
ResidenceResidence1Business address of the person.
PersonPerson1Personal details.

Organization

ElementTypeQuantityValue
Nameutf81.{0, 255}
Name of the organization.
RegistrationNumberascii1[0-9a-zA-Z]{1, 255}
Registration number of the organization.
ResidenceResidence1Residence of the organization.
DirectorsPerson
[1..30]		1List of all the directors of the organization.
UltimateBeneficialOwnersPerson
[0..30]		1List 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

ElementTypeQuantityValue
Nameutf81.{0, 255}
Name of the partnership.
RegistrationNumberascii0..1[0-9a-zA-Z]{1, 255}
Registration number of the partnership.
ResidenceResidence1Residence of the partnership.
PartnersPerson
[1..30]		1List of members of the partnership.

MonthlyTransactions

ElementTypeQuantityValue
Countnumeric1Number of transactions.
AverageValueascii1[0-9]+(.[0-9]{1,3})?
Currencyascii1ISO 4217 - Alphabetic Currency Code

Person

ElementTypeQuantityValue
NameName1Name of the person.
DateOfBirthDate1Date of birth of the person.
ResidenceResidence1Residence of the person.

Name

ElementTypeQuantityValue
Titleutf-80..1.{0, 255}
The title of the person.
For example: Mr, Ms, Senator.
This tag is not present if there is no title.
FirstNameutf-81.{0, 255}
First name of the person.
MiddleNameutf-80..1.{0, 255}
Middle name of the person.
This tag is not present if there is no middle name.
LastNameutf-81.{0, 255}
Last name of the person.

Date

ElementTypeQuantityValue
Yearnumeric1Year. YYYY
Monthnumeric1Month. MM
Daynumeric1Day of the month. DD

Residence

ElementTypeQuantityValue
AddressAddressLine
[1..4]		1Residence address.
ZipCodeascii0..1[0-9a-zA-Z- ]{1,31}
ZIP code of the residence - optional as there are situations where an address lacks a zip code.
Cityutf-81[0-9a-zA-Z- ]{1, 255}
City of the residence.
Stateascii0..1[0-9a-zA-Z- ]{0, 255}
State of the residence. This is an optional field.
Countryascii1ISO 3166 - Country Code of the residence.

Payment Method Specific Elements

Afterpay

ElementTypeQuantityValue
tradingCountriesstring1^[A-Z]{2}(,[A-Z]{2})*$
List of trading countries in country code. Used for CN/HK merchants (CBT).

Alipay

ElementTypeQuantityValue
RegistrationNumberascii1[0-9a-zA-Z]{1, 255}
Registration number of the organisation.
The registration number is mandatory for all types of merchants.

Klarna

ElementTypeQuantityValue
EmailAddressEmailAddress1[^@]+@[^@]+.[^@]+
Merchant email address.
store.disputesEmailEmail Address1This is an optional field that would allow the dispute notifications to be sent to it instead of the main Email Address. If this is absent during onboarding, it will default to the main Email Address.

SEPA DD

ElementTypeQuantityValue
creditorIdascii1Mandatory element for SEPA DD.
creditorNameascii0..1[0-9a-zA-Z]{2, 31}
Name of the creditor. This is an optional element.
creditorResidenceascii0..1[0-9a-zA-Z]{2, 31}
Country of the creditor. This is an optional element.

Swish

ElementTypeQuantityValue
RegistrationNumberascii1[0-9a-zA-Z]{1, 255}
Registration number of the merchant.
This is mandatory for all legal entity types for Swish.

WeChat Pay

ElementTypeQuantityValue
EmailaddressEmailAddress1[^@]+@[^@]+.[^@]+
Merchant email address.
RegistrationNumberascii0..1[0-9a-zA-Z]{1, 255}
Registration number of the organization.
This is mandatory if the legal entity type is Organization or Partnership.
PhoneNumberPhoneNumber1[+]?[0-9]{8,19}
Merchant phone number.

Other Types

ElementTypeQuantityValue
Websiteascii1URL of the websites of the legal entity’s business
AddressLineutf-81.{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>