Prefilling Merchant Information

If your platform uses the White-label Hosted Application, you can prefill merchant applications with business details, contact information, and other data you have already collected. This reduces repeated data entry and helps your merchants complete their onboarding faster.

When your platform initiates onboarding, BlueSnap adds your pre-approved values to the merchant's application. The merchant opens your white-label application, reviews the information, and completes any remaining required fields before submitting for approval.

Note: Prefilling is optional. You can send as much or as little application information as you have available.

When to Use Prefilling

Use prefilling when your platform already has information that belongs in the merchant application. Some examples include:

• Onboarding a new merchant: Reuse the business name, website, and contact details collected during signup on your platform.
• Enabling payments for an existing platform user: Start the application with information from their existing business profile.
• Migrating a merchant portfolio: Use existing records to prefill each merchant's individual application for them to review and complete.

Before You Begin

Use the White-label Hosted Application with partner-initiated onboarding.

Prepare the following information:

• Your API credentials
• The merchant's email address
• Your integration's redirect URL configuration

The API request supplies the starting values. The merchant submits the application through the White-label Hosted Application flow.

Prepare the Merchant Information

Include the application data you want to prefill in merchantInfo.merchantResource. You can supply any of the following groups. All paths in this table are relative to that object.

Initiate the Application with Prefilled Data

Add the optional merchantInfo.merchantResource object to your partner-initiated onboarding request:
POST /services/2/merchants/partner-side-initiated-submission

Use the base URL, authentication, userId, and redirect URL values for your White-label Hosted Application integration.

Example

Your platform already has the US merchant's business profile so now you can send those details in the request and have the merchant provide their banking, ownership, and other required information in the application.

The following request demonstrates partial prefilling and you can replace the sample identifiers, URLs, and merchant details with your own values.

POST {{server}}/services/2/merchants/partner-side-initiated-submission
Authorization: Basic {{base64EncodedCredentials}}
Content-Type: application/json

For Basic authentication, base64EncodedCredentials represents the Base64-encoded username:password for your API credentials.

{
  "userId": "merchant123",
  "returnUrl": "https://partner.example.com/account/settings",
  "refreshUrl": "https://partner.example.com/account/settings?refresh=1",
  "successUrl": "https://partner.example.com/onboarding/complete",
  "merchantInfo": {
    "email": "[email protected]",
    "merchantResource": {
      "businessInfo": {
        "businessName": "Example Learning",
        "legalName": "Example Learning LLC",
        "productAndServiceDesc": "Online courses and educational materials.",
        "phone": "5125550100",
        "website": "https://merchant.example.com",
        "businessType": "Limited Liability",
        "businessCategory": "Educational Services",
        "address": "123 Example Street",
        "city": "Austin",
        "state": "TX",
        "zip": "78701",
        "country": "US",
        "salesVolume": "100000"
      }
    }
  }
}

Direct Your Merchant to the Application

BlueSnap validates the supplied application data, saves the accepted values, and returns an onboarding URL.

• Direct the merchant to that URL to continue in the White-label Hosted Application.
• The merchant reviews the prefilled information, completes any remaining required fields, and submits the application through the hosted flow.
• If a supplied value could not be prefilled, the merchant provides that information in the application when required.

How the Application is Validated

Prefilled data uses the same country-specific, application validation rules as the New Application API. Only valid values are prefilled and invalid application values are skipped, while other values that pass validation are retained.

For example, if the second owner's ZIP code is invalid, that ZIP code is excluded while the first owner's valid information and the second owner's other valid fields can still prefill.

Validation can depend on country and related field values and it also applies to supported alternative field names so an invalid value supplied through an alternative field is excluded from prefilling. These rules apply to application data in merchantInfo.merchantResource. The endpoint's authentication and other request requirements still apply.

Array Limits

The following limits apply to arrays within merchantInfo.merchantResource

Note: If an array exceeds its limit, entries beyond the limit are discarded. Entries within the limit are still processed and can prefill if valid.