Merchant SDK overview


What is Merchant SDK?

Merchant SDK is a UI modal (web component) that helps you speed up integration with the Sprinque B2B payments platform, decreasing your integration efforts by more than half. Though you are still required to do some backend work, we have automated most of it.

Why should you use it?

  1. Faster integration;
  2. You don't need to implement all new features delivered by Sprinque on your own;
  3. We are constantly working on improving the buyer acceptance rate, reducing fraud risk, UX, and other enhancements that you will get just by installing the next version.

What does the Merchant SDK offer?

The below API calls are all automated through the Merchant SDK, so you can skip a couple of APIs and go directly to the invoices.

  1. Search and register buyer business with Sprinque;
  2. Place an order if the buyer is immediately approved for the credit (95+% of cases);
  3. Place an order for the existing buyer (if you already have Sprinque buyer id);
  4. Pass initial values to be pre-filled in the modal;

Merchant SDK in action

Please visit our demo site to see it in action. Check out the flow here.
For now, you will not be able to check the outcome in the Sprinque Merchant Control Center (MCC).


import { open, close } from "@sprinque/js-sdk";

  onClick={() => {
        // use 'token' or you can pass 'getTokenUrl', that must return response like {access: 'token'}
        token: '<temporary_access_token>',
        env: 'sandbox',
        lang: 'nl', // 'en', 'es', 'de', 'fr', 'pl' are supported for now
        onBuyerResponse: (buyer) => console.log(`Buyer is created: ${JSON.stringify(buyer)}`),
        onClose: () => console.log('Buyer closed Sprinque modal')
  Start Sprinque flow
<button onClick={close}>Close Sprinque modal</button>


The code sample for buyer creation will look like this (change the token):

<!DOCTYPE html>
  <title>Sprinque Merchant SDK</title>
  <script src="" crossorigin></script>
<button id="button">Open</button>

  document.getElementById("button").addEventListener("click", () => {{
      // use 'token' or you can pass 'getTokenUrl', that must return response like {access: 'token'}
      token: '<temporary_access_token>',
      env: 'sandbox', // or 'production'
      lang: 'nl', // 'en', 'es', 'de', 'fr', 'pl' are supported for now
      onBuyerResponse: (buyer) => {
        console.log('You can call any callback here after the buyer is created:', JSON.stringify(buyer))
      onClose: () => console.log('Buyer closed Sprinque modal')

Authorization token

Please check this section to get the temporary access token.

Merchant SDK supports 2 strategies on how you can do authentication:

  1. Pass the token using the tokenparam{
      token: 'temporary_access_token', // example `eyJ2eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjgxMzA2MzIxLCJqdGkiOiJmMDEyM2E3N2MyOGI0NWRjYTYxMWFkZDgzYThmY2IwYSIsInVzZXJfaWQiOjQzM30.naWUL_Aw6ZYZ3YEKDOxTRjrowVk5QSE-_m5Mw-Z1f_3`
  2. Pass your server URL that will be ready to generate temporary_access_token using permanent API KEY{
      getTokenUrl: '', // endpoint can proxy Sprinque's Auth (/token/temp) endpoint and should return {access: 'temporary_access_token_you_need', refresh:''} 

Supported parameters

ParameterDescriptionIs requiredTypeExample
token (or getTokenUrl)Please check the above section or visit
envWhich Sprinque environment Merchant SDK will be calling. Make sure that the token is matching the env.required'sandbox', 'production'sandbox
langUsed for translating the content in the modalrequired'en', 'de', 'nl', 'fr', 'es', 'pl'nl
onBuyerResponseCallback function that will be called after the buyer is created or fetched from Sprinque side.optionalfunction(buyer) => {}
onCloseCallback function that is called when the buyer closes the modal (even at the end of the flow)optionalfunctiononClose: () => console.log('Buyer closed Sprinque modal')
orderPass this object if you want to place an order after buyer is approved.optionalObject like

order: {
merchant_order_id: "string",
order_amount: "number",
order_currency: "string",
payment_terms: "string",
shipping_address: {...}
Check body params of transaction authorization
onOrderCreatedCallback that is called after the order is placedoptionalfunction(order) => {}
onOrderFailedCallback that is called when order failedoptionalfunction(errors) => {}
buyerIdSprinque buyer id for returning (known) buyer. Use in combination with order to place an order and skip all other steps.optionalstringbyr_9IGckclMza4jT3P3
initialValuesPrefill buyer's data that you already know (if vatId is passed, search by VAT will be auto-executed, but note that Sprinque doesn't support search by VAT for all countries)optionalObject{
// step 1
countryCode: "IT",
companyName: "Initial Company Name",
registrationNumber: 'init123456789',
billingEmail: '[email protected]',
// step 2
addressLine1: 'InitialAddress 1',
addressLine2: 'InitialAddress 2',
city: 'Initial City',
zip: '1017 init',
// step 3
userName: 'Initial Username',
userLastName: 'Initial Lastname',
userEmail: '[email protected]',
userPhone: '+31612345678',
userLanguage: 'nl'
initialShippingAddressUsually, the shipping address is passed in order. But you can use this if the SDK is used just for buyer creation flow. Will increase the acceptance rate for the credit.optionalObject{
country_code: 'NL',
address_line1: 'Prinsengracht 526 H',
address_line2: '',
zip_code: '1017 KJ',
city: 'Amsterdam',
initialOrderAmountUse this only if you're not passing the order. It's needed for Sprinque to understand the order intent of the buyer during the manual review (from v.1.16.0)optionalnumber20.16
initialOrderCurrencyCodeSame as above, use only if the order is not passed to the Merchant SDK. Will help Sprinque with manual buyer assessment (from v.1.16.0)optionalstringUSD
disabledValuesAbility to disable some inputs. For now only userEmail is available. Should be used in combination with initialValues or buyerIdoptionalArray['userEmail']
showSprinqueLogoDisplay the Sprinque logo in the popup instead of the one configured in MCCoptionalbooleantrue
showCloseModalIconOnSuccessPageThis might be useful if you're passing an order to the SDK and want to show a close X icon on the success/failure screen. (from v.1.17.0)optionalbooleantrue (false is by default)
targetSelectorSpecify a selector where the Sprinque web component will be rendered (for example to use as a form instead of popup)optionalstring# render-modal-here
merchantBuyerIdId to link Sprinque buyer with the business buyer in your system (from v.1.15.0)optionalstring"1736355"
buyersMetadataAny metadata object that can be linked to the business buyer registration call (from v.1.15.0)optionalObject{location: "London", "timezone": "+1", userFlow: "3"}
allowedCountriesLimit countries that user can pick their business from. Useful if you're operating just in some countries (from v.1.19.0)optionalArray of country codes['DE', 'BE', 'NL']
customStylesAbility to change the layout of the modaloptionalstringp, .sprinque-header h3 {color: purple}
lastScreenCustomHTMLPass additional instructions to your buyers after the Sprinque flow is finished (from v.1.14.0).optionalobject{
buyerWentToManualReview: '


buyerWasApproved: '


buyerWasRejected: '


pendingOrderPlaced: '

Order is pending

orderFailed: '

Order failed!


Backend effort needed

Use our demo site to see an example.

  1. Implement an endpoint to generate a temporary token using Sprinque API key (from MCC). (Sprinque endpoint to generate temporary access from API key)
  2. Implement a capture call after the order is shipped to share the invoice pdf with us.
  3. Take care of canceled orders (use the refund for captured orders and void for authorized orders).
  4. Handle unhappy flow when the buyer is not approved for credit immediately. Sprinque is sending an email (configurable) and a webhook in this case with APPROVAL or REJECTION within 24 hours.

What’s Next