White-labeled Hosted Application

Use the white-labeled hosted application when you want merchants to complete the BlueSnap application in a hosted experience that uses your platform branding.
This model helps you go live quickly because you do not need to fully build to BlueSnap's APIs, while still displaying your custom brand.

Though “BlueSnap” may appear in the application URL, the merchant does not need to create or sign in to a BlueSnap account to submit the application. BlueSnap stays behind the scenes while your platform remains the merchant’s starting point and return destination.

Check out this demo to see a white-labeled hosted application in action.

How It Works

The merchant will sign in to your portal and select Start Application, which redirects them to the BlueSnap-hosted application with your logo and brand colors. To do this:

1. Your platform identifies the merchant in your system.
2. Your platform calls the Create Hosted Application API.
3. BlueSnap returns a hosted application URL with a JSON web token (JWT).
4. Your platform redirects the merchant to the hosted application URL.
5. The merchant completes and submits the application.
6. BlueSnap redirects the merchant to your successUrl.
7. Your platform monitors onboarding webhooks for application status updates.

The JWT is valid for 24 hours. If the merchant does not finish the application in one session, they can return later and continue the application. If they return after the JWT expires, use the Create Hosted Application API to refresh the token.

After Submission

Your platform should monitor webhooks to track the merchant’s application status. Use these webhook updates to determine whether the merchant is approved for processing, approved for payout, requires more review, requires documents, or is declined.

Once the merchant is approved, proceed to generate their merchant credentials.

Test the Hosted Application

Before going live, test how your platform responds to hosted application outcomes.

Use the optional merchantInfo.approvalTesting property in the Create Hosted Application API request to simulate onboarding outcomes in sandbox. Each value triggers a MERCHANT_PARTNER_ONBOARDED webhook that corresponds to a specific application review status.

Use hosted application testing to confirm that your platform can:

• Create a hosted application session
• Redirect the merchant to the hosted application
• Refresh an expired JWT
• Receive onboarding webhooks
• Store the merchant ID and status fields
• Identify whether the merchant can process payments
• Identify whether the merchant is approved for payout
• Continue to credential generation when appropriate

Implementation Checklist

Before going live with the white-labeled hosted application:

1. Confirm your BlueSnap account setup and API credentials.
2. Provide your logo and primary brand color to BlueSnap.
3. Configure successUrl, returnUrl, and refreshUrl.
4. Decide whether your platform will send userId or rely on bluesnapId.
5. Create the hosted application from your backend.
6. Redirect merchants to the hosted application URL returned by BlueSnap.
7. Implement the token refresh flow for expired JWTs.
8. Store merchant identifiers returned by BlueSnap.
9. Monitor onboarding webhooks after submission.
10. Test hosted application outcomes in sandbox.
11. Continue to merchant credential generation after the merchant is approved for processing.