Create Hosted Application API

The Create Hosted Application API lets you redirect prospective merchants from your platform to a white-labeled BlueSnap Merchant application. In response, you receive a JSON web token (JWT) that contains the merchant application and session information.

The JWT is valid for 24 hours. If the merchant returns to their application after the JWT expires, you can also use this API to refresh their token.

Endpoint

https://platform.bluesnap.com/services/2/merchants/partner-side-initiated-submission

Request Content

📘
When creating the initial merchant application, you can omit userId and let BlueSnap generate an identifier. BlueSnap will return the generated bluesnapId in the response.
Use either userId or bluesnapId to authenticate the merchant when refreshing the JWT.

Parameter	Required	Description
`userId`	No	Unique identifier that you can assign to the merchant application. You can use this ID to authenticate the merchant if they need to complete their application in the future.
`bluesnapId`	No	Unique identifier that BlueSnap assigns to the merchant application.
`returnUrl`	No	URL where BlueSnap redirects the merchant to complete the application at a later time.
`refreshUrl`	No	URL where BlueSnap redirects the merchant if the JWT is expired.
`successUrl`	No	URL where BlueSnap redirects the merchant after they submit the merchant application.
`merchantInfo`	Yes	Container object for merchant information. ASCII characters only.
`approvalTesting`	No	Use this property in sandbox to test hosted application review outcomes. Type: string Valid values: - `APPROVED` - `RECOMMEND_APPROVE` - `RECOMMEND_DECLINE` - `DECLINE`
`email`	Yes	Merchant's email address. This is required in the first request that creates a merchant application account.

Response

Parameter	Description
`userId`	`userId` sent in the request.
`bluesnapId`	Unique identifier that BlueSnap assigned to the merchant application.
`url`	Hosted application URL. The JWT is included as a query string parameter.

Examples

Request

curl -v -X POST https://platform.bluesnap.com/services/2/merchants/partner-side-initiated-submission \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "userId": "user007",
  "bluesnapId": 1234567,
  "returnUrl": "https://example.com/return",
  "refreshUrl": "https://example.com/refresh",
  "successUrl": "https://example.com/success",
  "merchantInfo": {
     "email": "[email protected]"
   }
}`

Response

{
  "userId": "user007",
  "bluesnapId": "1234567",
  "url": "https://sandbox.bluesnap.com/jsp/merchant_application.jsp?jwt=<jwt-string>"
}

Refresh an Expired JWT

If the merchant does not submit their application before the JWT expires and then attempts to return to it:

BlueSnap redirects them to the refreshUrl you provided in the initial request. The refreshUrl accepts either the merchant’s userId or bluesnapId as a query string parameter, such as in https://example.com/refresh?userId=user007
Your platform extracts the ID from the query string and sends another request to this API to refresh the session, as shown below.
Your platform redirects the merchant to the refreshed URL so they can continue the application.

curl -v -X POST https://platform.bluesnap.com/services/2/merchants/partner-side-initiated-submission \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "userId": "user007",
  "returnUrl": "https://example.com/return",
  "refreshUrl": "https://example.com/refresh",
  "successUrl": "https://example.com/success"
}'

{
  "bluesnapId": "1234567",
  "url": "https://sandbox.bluesnap.com/jsp/merchant_application.jsp?jwt=<jwt-string>"
}

🚧
Keep the following behavior in mind:

If BlueSnap cannot authenticate the bluesnapId, BlueSnap returns a 404 error.

If BlueSnap cannot authenticate the userId, BlueSnap creates a new application account and redirects the merchant to a new form. BlueSnap saves the userId for future authentication.

If the link expires and you did not send a refreshUrl in the initial request, BlueSnap displays an error screen. To restart the application flow, the merchant must return to your platform and start the application over again.