After you submit a merchant application, BlueSnap reviews it and sends onboarding status updates to your platform via webhooks. Use these status updates to determine when a merchant can process payments, when they can receive payouts, and when your platform should create merchant API credentials.
Before your platform goes live, the BlueSnap Implementation team collects your publicly accessible HTTPS endpoint URL and configures it to receive merchant status notifications.
For more information about BlueSnap webhooks, refer to Webhooks Setup.
How It Works
BlueSnap sends merchant onboarding updates using the MERCHANT_PARTNER_ONBOARDED webhook. Use this webhook to keep your platform in sync with BlueSnap’s review process and update each merchant’s state in your system.
Your platform must receive status updates to get the Merchant ID assigned by BlueSnap. You need this ID to create merchant API credentials and process payments on behalf of the merchant.
Webhook Payload
The webhook payload includes the merchantId, processing status, payout status, and identifying information your platform can use to update the merchant record. For example:
transactionType=MERCHANT_PARTNER_ONBOARDED
&merchantId=1322444
&sandboxId=1165743
&payoutStatus=Y
&accountCanProcess=Y
&merchantName="Business Name"
&[email protected]| Field | How To Use It |
|---|---|
merchantId | Unique merchant ID assigned by BlueSnap. Use this ID to create merchant API credentials after the merchant is approved to process. |
sandboxId | Unique sandbox ID account assigned to the merchant. Use this ID to match the webhook to the merchant in your platform before a merchant ID is assigned. |
accountCanProcess | Indicates whether the merchant can process payments. Possible values are Y, N, and Pending. |
payoutStatus | Indicates whether the merchant can receive payouts. Possible values are Y, N, and Pending. |
merchantName | Merchant business name submitted in the application. |
merchantEmail | Merchant email submitted in the application. |
metadata | Custom metadata submitted with the merchant application. Use this field to map the webhook to your internal merchant record. |
Determine Merchant Status
You will use merchantId, accountCanProcess, and payoutStatus to determine the merchant’s state:
| Is merchantId present? | accountCanProcess | payoutStatus | Meaning | Recommended Platform action |
|---|---|---|---|---|
| Yes | Y | Y | Merchant is approved for processing and payouts. | Create merchant API credentials, enable payment processing, and show payouts as active. |
| Yes | Y | Pending | Merchant is approved for processing, but payout approval is still pending. | Create merchant API credentials and enable payment processing. Show payout status as pending. |
| No | Pending | Pending | Merchant is still under review. | Keep the merchant in a pending state. Do not create merchant API credentials yet. |
| No | N | N | Merchant was declined. | Do not enable processing. No further approval updates are sent. |
Processing approval does not always mean payout approval. A merchant may be approved to process payments before they are approved to receive payouts.
Handling Merchant Statuses
When you receive a MERCHANT_PARTNER_ONBOARDED webhook:
-
Store the webhook event.
-
Match the event to the merchant in your platform using
sandboxId,merchantId, ormetadata. -
Update the merchant’s status.
-
Create merchant API credentials and enable payment processing only when
accountCanProcessis "Y". -
Enable payout-related actions or show payouts as active only when
payoutStatusis "Y". -
If
payoutStatusis "Pending", clearly show that the merchant can process payments but cannot receive payouts yet.
You can also view merchant status in the Partner Portal, which lets your team monitor merchant status manually. However, it does not replace webhook handling. Your platform still needs the webhook to automate status updates and retrieve the merchant ID required for API credentials.
Merchant Notifications
Merchant notifications depend on how your onboarding experience is managed.
- If your platform owns the merchant experience, your platform is responsible for notifying merchants about application status, additional information requests, approval, payout status, or decline.
- If BlueSnap owns the merchant experience, BlueSnap notifies merchants directly about key onboarding outcomes such as approval or decline.
Regardless of who notifies the merchant, your platform must still listen for the MERCHANT_PARTNER_ONBOARDED webhook to update internal status, retrieve the merchantId, and continue technical setup.