Merchant boarding

PPRO offers two entry points to board your merchants and obtain a merchant ID - a UI and API. This page outlines the process to board via API. For detailed information on the boarding process via the PPRO Dashboard (UI), please refer to Merchant Management within the PPRO Dashboard documentation.

Boarding via API

The data model

Boarding with PPRO via API models two distinct entities - the merchant and people.

• Merchant: Contains legal entity data for the specific merchant (e.g., legalEntityName, mcc, url).
• People: Contains identity data for individuals associated with one or more merchants (e.g., firstName, birthDate, address).

Key Relationship: A single merchant can have multiple people associated with it, defined by specific roles such as ULTIMATE_BENEFICIAL_OWNER or DIRECTOR. Furthermore, a single person may be shared across multiple merchants.

Data collection workflow

PPRO supports flexible boarding workflows for creation of merchants and people to align with your integration logic. While we only mandate data strictly required for specific payment methods or regulatory compliance, you can choose how and when to supply this information:

• Full merchant boarding (recommended): You can provide the full merchant data inventory and all associated people in a single initial request. Providing all data upfront is the most efficient method, as it significantly reduces the need for follow-up amendments which may be required to unlock further payment methods later in the lifecycle.

• Progressive boarding: Alternatively, you can adopt a staged approach by submitting the minimum required merchant details first, and adding people entities or supplementary data later. This allows you to match PPRO boarding to your own progressive data collection flow. Specific payment methods or bank requirements may require identifying the people behind a business, which may require you to update the merchant profile with people data in the future if not provided initially.

Creating merchants requests

The primary method for boarding is the merchants endpoint. Depending on your data collection strategy (see above), you will choose between Method A or Method B.

Method A: Full merchant boarding (single-call)

Use this to create the merchant and all required people in one atomic operation. This reduces overhead by ensuring the merchant has all potential required data immediately.

{
  "externalMerchantReference": "MERCH001",
  "legalEntityName": "Example LLC",
  "legalEntityType": "COMPANY",
  "tradeName": "Example Store",
  "registrationNumber": "US-12345678",
  "incorporationDate": "2020-01-15",
  "mcc": "5411",
  "url": "https://www.example-store.com",
  "currency": "EUR",
  "averageTransactionValue": 50.00,
  "monthlyTransactionCount": 1000,
  "paymentDescriptor": "Example Store London",
  "address": {
    "street": "123 Market Street",
    "city": "London",
    "postalCode": "W1T 1JY",
    "country": "GB"
  },
  "phoneNumber": "+44 20 7946 0958",
  "people": [
    {
      "type": "ULTIMATE_BENEFICIAL_OWNER",
      "person": {
        "externalPersonReference": "PER001",
        "firstName": "Jane",
        "lastName": "Doe",
        "email": "[email protected]",
        "birthDate": "1990-01-01",
        "address": {
          "street": "123 Main Street",
          "city": "London",
          "postalCode": "SW1A 2AA",
          "country": "GB"
        }
      }
    }
  ]
}

Method B: Progressive boarding (modular)

Use this if you prefer to create the merchant shell first and optionally provide people data based on future requirements.

Step 1: Create the merchant

Create merchant (omitting non-required fields and the people array).

{
  "externalMerchantReference": "MERCH002",
  "legalEntityName": "Sole Trader John",
  "legalEntityType": "SOLE_TRADER",
  "mcc": "5732",
  "url": "https://www.johns-electronics.com",
  "currency": "USD",
  "address": {
    "street": "123 Main Street",
    "city": "San Francisco",
    "region": "CA",
    "postalCode": "94107",
    "country": "US"
  },
  "phoneNumber": "+1 415 555 0199"
}

Step 2: Enrich data

When you are ready to add more data, use the patch endpoint for the data you are adding.

Creating merchants response

When you successfully create a merchant, PPRO will return the merchant object containing all submitted data plus the merchant ID. It is key you store this merchant ID, as this will be the key required for all calls after boarding.

{
  "id": "merchant_2B3c4D5e6F7g8H9i0j1k2",
  "externalMerchantReference": "MERCH001",
  "legalEntityName": "Example LLC",
  "legalEntityType": "COMPANY",
  "createdAt": "2024-05-20T10:15:30Z",
  "updatedAt": "2024-05-20T10:15:30Z",
  "url": "https://www.example-store.com",
  "mcc": "5411",
  "address": {
    "street": "123 Market Street",
    "city": "London",
    "postalCode": "W1T 1JY",
    "country": "GB"
  },
  "people": [
    {
      "id": "person_9A8b7C6d5E4f3G2h1I0j9",
      "merchantId": "merchant_2B3c4D5e6F7g8H9i0j1k2",
      "type": "ULTIMATE_BENEFICIAL_OWNER",
      "firstName": "Jane",
      "lastName": "Doe"
    }
  ]
}

Merchant updates and maintenance

As merchant details change (e.g., address change, renaming, new logos) or additional data per merchant is required, you must keep the boarding data current to ensure enrollment, payment charges, and risk checks can continue as desired.

Further Details

A PATCH can be used to update specific fields (e.g., changing just the email or paymentDescriptor).

{
  "paymentDescriptor": "Johns Electronics SF",
  "averageTransactionValue": 120.50
}

For making updates to people specifically, see our People documentation.

Merchant status

Every merchant has a status that reflects where it is in the onboarding lifecycle.

Call Get Merchant Status at any time to check a merchant's current status, capabilities (canPay, canRefund), and — for SUSPENDED/CLOSED — the reason:

Merchant notifications

PPRO notifies you by webhook whenever a merchant's status changes — for example, when it moves from PENDING to ACTIVE, or becomes SUSPENDED.

Event type: MERCHANT_STATUS_UPDATED

previousStatus is null on the very first status event for a newly created merchant.

See Merchant Status Updated for the full schema, and Webhooks for more details.