API Application

Use an API-based application when you want to build your own merchant application experience and submit merchant data to BlueSnap through the New Application API.

This model gives your platform the most control over the merchant onboarding UI, data collection flow, validation, and merchant-facing experience. It also means your platform is responsible for securely collecting the required business, banking, ownership, and agreement information before submitting the application to BlueSnap.

Understanding Onboarding

This walkthrough demonstrates the full onboarding process.

How It Works

In an API-based application, your platform collects merchant application information and sends it to BlueSnap using the New Application API.

1. Your platform builds the merchant-facing application form.
2. The merchant enters business, banking, ownership, and agreement information.
3. Your platform collects the data directly or uses Secure Customer Data Fields.
4. Your server submits the application to BlueSnap.
5. BlueSnap returns a sandboxId when the application is received.
6. Your platform stores the sandboxId and monitors onboarding webhooks.
7. BlueSnap reviews the application and sends status updates through webhooks.
8. Your platform updates the merchant-facing onboarding status in your system.

Collect Merchant Information

The merchant application requires business, banking, ownership, company representative, and agreement information. Required fields vary by country or region. For the full request schema, supported countries and regions, required fields, and validation rules, refer to the New Application API documentation.

You can collect merchant data with either plain text or Secure Customer Data Fields.

Plain Text Collection

Use plain text collection when your platform wants to capture, validate, and submit merchant application data using your own form fields.
With this method, your platform collects merchant data directly and sends the required application fields in the New Application API request.

Because this method can require your platform to handle sensitive merchant information, your platform is responsible for securing the data you collect, transmit, store, and display.

Secure Customer Data Fields

Use Secure Customer Data Fields when you want BlueSnap to help collect and tokenize sensitive merchant information.
With this method, your platform embeds BlueSnap-hosted fields into your application form. BlueSnap collects sensitive values and returns a token. Your platform submits that token in the pfToken property when creating the application.

Use this method when you want to reduce the amount of sensitive merchant data stored on your own servers.

Submit the Application

To submit a merchant application, send a server-to-server request to the New Application API.

The request format depends on how your platform collected the merchant data.
If you collected merchant data directly, include the required fields for the merchant’s country or region.
If you used Secure Customer Data Fields, include the token in the pfToken property:

curl -v -X POST https://platform.bluesnap.com/services/2/merchants/new-application \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "pfToken": "5ad59e4389abba704ee2d61580d1d5cc1ba0ccf114470d404f771a198d99891b_"
}'

When BlueSnap receives the application, the response includes a sandboxId and a message. Store the sandboxId so your platform can associate later onboarding webhooks with the merchant in your system.

{
  "sandboxId": 1234567,
  "message": "success"
}

After Submission

After you submit the application, monitor onboarding webhooks for the next step in the merchant onboarding process.
Your platform should use webhook updates to track whether the merchant:

• Is approved for processing
• Is approved for payout
• Requires additional review
• Requires documents
• Is declined

Store the merchant status fields returned in onboarding webhooks so your platform can show the correct merchant-facing status and decide when to enable payment processing, payouts, and related account workflows.

Test the Application

Before going live, test how your platform responds to different application outcomes. Use the optional approvalTesting property in the New Application API request to simulate onboarding outcomes in sandbox.

Your platform should confirm that it can receive the onboarding webhook, store the merchant ID and status fields, identify whether the merchant can process payments, identify whether the merchant is approved for payout, and continue to credential generation when appropriate.

Implementation Checklist

Before going live with an API-based application:

1. Confirm your platform account setup and credentials with BlueSnap.
2. Decide whether to collect merchant data directly or use Secure Customer Data Fields.
3. Build validation based on the merchant’s country or region.
4. Present and capture the required merchant agreement consent.
5. Submit the merchant application through the New Application API.
6. Store the sandboxId returned in the response.
7. Monitor onboarding webhooks and store merchant status fields.
8. Test each onboarding outcome in sandbox.
9. Continue to merchant API credential generation after the merchant is approved for processing.
10. Show the correct merchant-facing onboarding status in your platform.