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?

Faster integration;
You don't need to implement all new features delivered by Sprinque on your own;
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.

Search and register buyer business with Sprinque;
Place an order if the buyer is immediately approved for the credit (95+% of cases);
Place an order for the existing buyer (if you already have Sprinque buyer id);
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).

Usage

NPM https://www.npmjs.com/package/@sprinque/js-sdk

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

<button
  onClick={() => {
    open({
        // 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>
<button onClick={close}>Close Sprinque modal</button>

UMD

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

<!DOCTYPE html>
<html>
<head>
  <title>Sprinque Merchant SDK</title>
  <script src="https://unpkg.com/@sprinque/js-sdk@1/dist/index.umd.min.js" crossorigin></script>
</head>
<body>
<button id="button">Open</button>

<script>
  document.getElementById("button").addEventListener("click", () => {
    Sprinque.open({
      // 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')
    });
  });
</script>
</body>
</html>

Authorization token

Please check this section to get the temporary access token.

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

Pass the token using the tokenparam

Sprinque.open({
  token: 'temporary_access_token', // example `eyJ2eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjgxMzA2MzIxLCJqdGkiOiJmMDEyM2E3N2MyOGI0NWRjYTYxMWFkZDgzYThmY2IwYSIsInVzZXJfaWQiOjQzM30.naWUL_Aw6ZYZ3YEKDOxTRjrowVk5QSE-_m5Mw-Z1f_3`
  ...
});

Pass your server URL that will be ready to generate temporary_access_token using permanent API KEY

Sprinque.open({
  getTokenUrl: 'https://your-site.com/api/token/', // endpoint can proxy Sprinque's Auth (/token/temp) endpoint and should return {access: 'temporary_access_token_you_need', refresh:''} 
  ...
});

Supported parameters

Parameter	Description	Is required	Type	Example
token (or getTokenUrl)	Please check the above section or visit https://sprinque.readme.io/reference/overview#public-or-temporary-token	required	string	eyJ2eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjgxMzA2MzIxLCJqdGkiOiJmMDEyM2E3N2MyOGI0NWRjYTYxMWFkZDgzYThmY2IwYSIsInVzZXJfaWQiOjQzM30.naWUL_Aw6ZYZ3YEKDOxTRjrowVk5QSE-_m5Mw-Z1f_3
env	Which Sprinque environment Merchant SDK will be calling. Make sure that the token is matching the env.	required	'sandbox', 'production'	sandbox
lang	Used for translating the content in the modal	required	'en', 'de', 'nl', 'fr', 'es', 'pl'	nl
onBuyerResponse	Callback function that will be called after the buyer is created or fetched from Sprinque side.	optional	function	(buyer) => {}
onClose	Callback function that is called when the buyer closes the modal (even at the end of the flow)	optional	function	onClose: () => console.log('Buyer closed Sprinque modal')
order	Pass this object if you want to place an order after buyer is approved.	optional	Object like order: { merchant_order_id: "string", order_amount: "number", order_currency: "string", payment_terms: "string", shipping_address: {...} }	Check body params of transaction authorization
onOrderCreated	Callback that is called after the order is placed	optional	function	(order) => {}
onOrderFailed	Callback that is called when order failed	optional	function	(errors) => {}
buyerId	Sprinque buyer id for returning (known) buyer. Use in combination with order to place an order and skip all other steps.	optional	string	byr_9IGckclMza4jT3P3
initialValues	Prefill 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)	optional	Object	{ // 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' }
initialShippingAddress	Usually, 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.	optional	Object	{ country_code: 'NL', address_line1: 'Prinsengracht 526 H', address_line2: '', zip_code: '1017 KJ', city: 'Amsterdam', }
initialOrderAmount	Use 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)	optional	number	20.16
initialOrderCurrencyCode	Same 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)	optional	string	USD
disabledValues	Ability to disable some inputs. For now only `userEmail` is available. Should be used in combination with `initialValues` or `buyerId`	optional	Array	['userEmail']
showSprinqueLogo	Display the Sprinque logo in the popup instead of the one configured in MCC	optional	boolean	true
showCloseModalIconOnSuccessPage	This 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)	optional	boolean	true (false is by default)
targetSelector	Specify a selector where the Sprinque web component will be rendered (for example to use as a form instead of popup)	optional	string	# render-modal-here
merchantBuyerId	Id to link Sprinque buyer with the business buyer in your system (from v.1.15.0)	optional	string	"1736355"
buyersMetadata	Any metadata object that can be linked to the business buyer registration call (from v.1.15.0)	optional	Object	{location: "London", "timezone": "+1", userFlow: "3"}
allowedCountries	Limit countries that user can pick their business from. Useful if you're operating just in some countries (from v.1.19.0)	optional	Array of country codes	['DE', 'BE', 'NL']
customStyles	Ability to change the layout of the modal	optional	string	p, .sprinque-header h3 {color: purple}

Backend effort needed

Use our demo site to see an example.

Implement an endpoint to generate a temporary token using Sprinque API key (from MCC). (Sprinque endpoint to generate temporary access from API key)
Implement a capture call after the order is shipped to share the invoice pdf with us.
Take care of canceled orders (use the refund for captured orders and void for authorized orders).
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.