API Application

BlueSnap provides the New Application API so you can submit a merchant application from a custom solution. This gives you the most control over the merchant application experience, so this is the best option for partners that white-label BlueSnap.

An API integration requires that you develop a web page that securely collects the application information. This information varies depending on the merchant's country or region, so refer to the applicable New Application API documentation for comprehensive details about all data that you must collect and submit.

Before you go live with your API application, you can test your integration to ensure that your implementation responds appropriately to all possible merchant application review outcomes.

Collecting Merchant Information

Collecting and storing sensitive merchant data comes with security risks, so you must plan carefully. You have the following options to collect merchant data:

Plain text — Capture, validate, and store merchant data with standard HTML input fields. This method requires that you store merchant data on your own servers, so you are responsible for securing the data.
Secure Customer Data Fields — BlueSnap helps mitigate security risks with these discrete input fields that seamlessly integrate into your website design. You can capture and tokenize sensitive merchant information without storing it on your servers.

After you send the application request and receive a success response, you must monitor your webhooks for the next step in the onboarding process.

Request Examples

To submit a new application, send a server-to-server API request with the merchant information.

The method you used to collect merchant data determines the content of your request. The following sections demonstrate API requests for both Secure Customer Data Fields and plain text data collection methods.

The response uses the same format, regardless of the request format.

Plain Text Collection Request

If you collected merchant data in plain text, send a request that includes the required properties for the merchant's country or region. For example, this request creates a new merchant application for a US customer:

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 '
     {
       "businessInfo": {
         "businessName": "Business Name",
         "legalName": "Business LLC",
         "productAndServiceDesc": "Provide a detailed description of your product or service.",
         "phone": "1555123456",
         "website": "https://www.website.com",
         "businessType": "Public Corporation ",
         "businessCategory": "Software",
         "taxId": "770770770",
         "address": "1234 Main Street",
         "city": "City",
         "state": "fl",
         "zip": "12345",
         "country": "US",
         "email": "first.last@merchant.com",
         "accountUsername": "MerchantUsername7707",
         "salesVolume": "100000",
         "averageTransactionAmount": "100",
         "highestTransactionAmount": "1000",
         "riskMonitoring": "No",
         "riskPayment": "No",
         "riskByCommission": "No"
       },
       "bankingInfo": {
         "routingNumber": "123456789",
         "accountNumber": "123456",
         "accountType": "CHECKING",
         "bankState": "FL",
         "payoutCurrency": "USD",
         "minimalPayoutAmount": "100",
         "refundReserve": "100"
       },
       "ownershipInfoArr": [
         {
           "ownerFirstName": "Chris",
           "ownerLastName": "Jones",
           "ownerDateOfBirth": "01/01/2000",
           "ownerGovID": "1111",
           "ownerPhone": "1555123456",
           "address": "1234 Main Street",
           "city": "Waltham",
           "state": "FL",
           "zip": "02453",
           "country": "US",
           "ownerPercent": "50"
         },
         {
           "ownerFirstName": "Jamie",
           "ownerLastName": "Doe",
           "ownerDateOfBirth": "02/01/2000",
           "ownerGovID": "2222",
           "ownerPhone": "1555123456",
           "address": "200 Broadway",
           "city": "Happy",
           "state": "FL",
           "zip": "12345",
           "country": "US",
           "ownerPercent": "50"
         }
       ],
       "companyRep": {
         "companyRepFirstName": "Jesse",
         "companyRepLastName": "Smith",
         "companyRepDateOfBirth": "12/13/1967",
         "companyRepGovID": "1234",
         "companyRepAddress": "123 South Street",
         "companyRepCity": "Happy",
         "companyRepState": "FL",
         "companyRepZip": "12345",
         "companyRepCountry": "US",
         "companyRepPhone": "1555123456"
       },
       "merchantAgreementsSign": {
         "serviceAgreementDate": "01/01/2019",
         "pricingAgreementDate": "01/01/2019",
         "merchantIp": "192.168.20.15"
       }
     }'

For example requests for all supported countries and regions, see New Application API.

Secure Customer Data Fields Token Request

If you collected merchant data with BlueSnap's Secure Customer Data Fields, then you need to send only the token that contains the merchant data. Send the encrypted token with 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_"
     }'

Response Example

Regardless of your request format, BlueSnap sends a JSON response when an application is received. A successful request returns a response with a sandboxId and a message property:

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

The sandboxId is a unique identifier for the merchant's sandbox account. You need this value to identify webhooks associated with this merchant.

Testing your API Integration

Before your integration goes into production, use the New Application API endpoint's approvalTesting property to test how your platform responds to all possible merchant application review outcomes.

The approvalTesting property accepts an enumerated value, where each value triggers a MERCHANT_PARTNER_ONBOARDED webhook that corresponds to a specific application review status. For example, you can send a request with approvalTesting set to APPROVED to test how your platform responds when a merchant application is approved for processing and payout.

For additional details about the different application statuses, see Determining Your Status.

Parameter Values

approvalTesting accepts the following values:

Value	Description
`APPROVED`	Merchant application is approved for processing transactions and payout. You receive a merchant ID (MID) to create API credentials for the sandbox account.
`RECOMMEND_APPROVE`	Merchant application is approved for processing but not approved for payout. You receive a merchant ID (MID) to create API credentials for the sandbox account. You receive another webhook that notifies you when the merchant is approved for payout.
`RECOMMEND_DECLINE`	Merchant is not approved for transaction processing or payout. You receive another webhook when the merchant is approved.
`DECLINE`	Merchant application was declined. BlueSnap will not send additional webhooks.

Example

The following example simulates an approved application for a US merchant:

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 '
   {
     "approvalTesting": "APPROVED",
     "businessInfo": {
       "businessName": "Business Name",
       "legalName": "Business LLC",
       "productAndServiceDesc": "Provide a detailed description of your product or service.",
       "phone": "5555555555",
       "website": "https://www.website.com",
       "businessType": "Public Corporation ",
       "businessCategory": "Software",
       "taxId": "770770770",
       "address": "1234 Main Street",
       "city": "City",
       "state": "fl",
       "zip": "12345",
       "country": "US",
       "email": "first.last@merchant.com",
       "accountUsername": "MerchantUsername7707",
       "salesVolume": "100000",
       "averageTransactionAmount": "100",
       "highestTransactionAmount": "1000",
       "riskMonitoring": "No",
       "riskPayment": "No",
       "riskByCommission": "No"
     },
     "bankingInfo": {
       "routingNumber": "123456789",
       "accountNumber": "123456",
       "accountType": "CHECKING",
       "bankState": "FL",
       "payoutCurrency": "USD",
       "minimalPayoutAmount": "100",
       "refundReserve": "100"
     },
     "ownershipInfoArr": [
       {
         "ownerFirstName": "Chris",
         "ownerLastName": "Jones",
         "ownerDateOfBirth": "01/01/2000",
         "ownerGovID": "1111",
         "ownerPhone": "1555123456",
         "address": "1234 Main Street",
         "city": "Waltham",
         "state": "FL",
         "zip": "02453",
         "country": "US",
         "ownerPercent": "50"
       },
       {
         "ownerFirstName": "Jamie",
         "ownerLastName": "Doe",
         "ownerDateOfBirth": "02/01/2000",
         "ownerGovID": "2222",
         "ownerPhone": "1555123456",
         "address": "200 Broadway",
         "city": "Happy",
         "state": "FL",
         "zip": "12345",
         "country": "US",
         "ownerPercent": "50"
       }
     ],
     "companyRep": {
       "companyRepFirstName": "Jesse",
       "companyRepLastName": "Smith",
       "companyRepDateOfBirth": "12/13/1967",
       "companyRepGovID": "1234",
       "companyRepAddress": "123 South Street",
       "companyRepCity": "Happy",
       "companyRepState": "FL",
       "companyRepZip": "12345",
       "companyRepCountry": "US",
       "companyRepPhone": "1555123456"
     },
     "merchantAgreementsSign": {
       "serviceAgreementDate": "01/01/2019",
       "pricingAgreementDate": "01/01/2019",
       "merchantIp": "192.168.20.15"
     }
   }'

This request triggers a webhook similar to the following:

transactionType=MERCHANT_PARTNER_ONBOARDED&merchantId=13224446&sandboxId=1165743&payoutStatus=Y&accountCanProcess=Y&merchantName="Business Name"