React Native

The React Native SDK (@spare-technologies/spare-link) runs the Spare Link payment flow inside your iOS and Android app. Your backend creates a payment request; the SDK shows bank selection, consent, and the bank redirect, then hands you the result to confirm on your server. It makes no API calls and holds no credentials.

Function of the SDK

The SDK shows the payment flow to the payer. It sends the payer to their bank. Then it tells you the result.

1. Your backend makes a payment request. The backend gives the reference to the app.
2. Your app calls spareLink.start({ reference }). The SDK shows the payment flow in a modal.
3. The payer selects a bank, checks the payee and gives consent.
4. The SDK opens the bank in a browser. It uses expo-web-browser.
5. Your app sends the return deep link to spareLink.handleRedirect().
6. Your backend reads the result with GET /payment-requests/{reference}.

The SDK opens the bank in a browser for two reasons. Banks usually refuse to authorize a payment inside an app. The address bar also helps the payer to identify a correct bank page.

The SDK makes no API calls. It holds no credentials. Thus it can tell you only what the payment flow and the deep link tell it. This is why step 6 is necessary.

Prerequisites

Do these tasks before you call start() on a device.

Backend

Spare platform

App

Prohibited in the app

Do not put these items in the app:

• Spare API keys
• Private keys for signatures
• Bearer tokens that call Spare from the device

Signature of the payload

POST /payment-requests needs a detached ES256 JWS in the x-signature header. The signature shows that your backend controls the request.

WARNING: Make the signature on your server. Do not put the private key in the app bundle.

Object to sign

Sign the request object only. Do not sign the full HTTP body.

{
  "user_ref": "optional",
  "provider_id": "optional",
  "request": { "...": "sign this object" }
}

Give the request object to your signature function. Send the full body as the JSON body.

Algorithm and key

A detached JWS has an empty payload segment. Thus it has two dots: header..signature. You use the canonical JSON bytes to calculate the signature. You do not put these bytes in the JWS.

Canonical serialization

The server compares the signature with this exact string. If one byte is different, the server sends a 401 error.

1. Sort the keys of each object into alphabetical order. Do this at each level.
2. Remove the fields that are null or undefined.
3. If a top-level value is a number, round it to 5 decimal places. Then remove the zeros at the end. For example, 1000.00 becomes "1000", and 1000.5 becomes "1000.5".
4. Keep the numbers inside objects as JSON numbers. This is the usual result of JSON.stringify.
5. Serialize each element of an array. Then put the elements in a JSON array.

Steps to make the signature

1. Make the payment request object (the `request` field).
2. canonical = serializePayload(request)   // the rules above
3. headerB64 = base64url('{"alg":"ES256"}')
4. payloadB64 = base64url(utf8(canonical))
5. signingInput = ascii(headerB64 + '.' + payloadB64)
6. signature = ECDSA-P256-SHA256(signingInput, privateKey)
7. x-signature = headerB64 + '..' + base64url(signature)   // detached

The rules above are the complete scheme. For the request contract, see the API Reference.

Example of a request

POST /payment-requests HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json
X-CLIENT-ID: <app-uuid>
X-Tenant: UAE
x-signature: eyJhbGciOiJFUzI1NiJ9..<signature>

{
  "request": {
    "type": "SingleInstantPayment",
    "channel": "sdk_react_native",
    "creditorType": "MERCHANT",
    "debtorReference": "debtorRef2",
    "creditorReference": "creditorRef",
    "creditorAccount": {
      "schemeName": "IBAN",
      "identification": "10000109010101",
      "name": "Mario International"
    },
    "purpose": "ACM",
    "merchantReference": "order12345",
    "successRedirectUrl": "myapp://callback",
    "failureRedirectUrl": "myapp://callback",
    "instructions": {
      "isInternationalPayment": false,
      "amount": { "amount": "1.01", "currency": "AED" }
    }
  }
}

Send the reference from the response to the app. The record also shows this value as internalReference. The SDK needs no other data.

Usual errors

Setup

1. Install the package

bun add @spare-technologies/spare-link
# or: npm i @spare-technologies/spare-link

This flow is a new major version of the SDK. Set an exact version in your package.json.

Then install the peer dependencies with Expo:

npx expo install react-native-webview react-native-safe-area-context react-native-screens \
  expo-web-browser expo-linking expo-secure-store expo-font expo-linear-gradient

WARNING: Install these packages with expo install. Do not let your package manager select the versions.

npm and bun install these packages automatically. The SDK declares the versions for the Expo 52 module line. Thus an automatic installation selects a version that operates.

expo install is safer. It reads your Expo SDK and selects the exact version for it. It also prevents an error if you change your Expo SDK later.

This release operates with Expo 52 only. If your app uses a more recent Expo SDK, the package manager gives a conflict of the peer dependencies. This is an error at the installation. It is not a failure of the build or a failure on the device.

The SDK uses these packages in this way:

• expo-web-browser opens the bank.
• expo-secure-store keeps the data for the recovery function.
• The other packages show the payment flow.
• react-native-svg is an optional peer dependency. If it is not available, the SDK shows a different indicator.

The SDK needs no runtime permission. Earlier versions asked for the location of the device. The SDK now reads no data from the device.

2. Configure the Expo plugin

// app.config.ts
plugins: [
  [
    '@spare-technologies/spare-link/expo-plugin',
    {
      merchantScheme: 'myapp',
      merchantHost: 'callback',
    },
  ],
]

The plugin registers the deep link for the return only. On iOS it adds an entry to CFBundleURLSchemes. On Android it adds an intent-filter for myapp://callback. The plugin asks for no runtime permissions.

Use the same scheme and host that your backend puts in successRedirectUrl and failureRedirectUrl.

Then make the development client again. The plugin changes the native configuration.

npx expo prebuild --clean && npx expo run:android   # or run:ios

3. Make the SDK object

Make one object and one host component. Put both near the root of the app.

import {
  SpareLink,
  SpareLinkHost,
  SecureStorePendingSessionStore,
  useSpareLinkDeepLinks,
} from '@spare-technologies/spare-link';
import { useMemo } from 'react';

export default function App() {
  const spareLink = useMemo(
    () =>
      new SpareLink({
        environment: 'sandbox',
        tenant: 'uae',
        pendingSessionStore: new SecureStorePendingSessionStore(),
      }),
    [],
  );

  useSpareLinkDeepLinks(spareLink); // step 4

  return (
    <SpareLinkHost spareLink={spareLink}>
      <YourApp spareLink={spareLink} />
    </SpareLinkHost>
  );
}

Use useMemo with an empty array of dependencies. If your app makes a new object at each render, it loses the active flow and the subscribers of the events.

The constructor checks the configuration. It causes an error for a baseUrl that is not a URL, and for a tenant that the payment flow cannot serve. Thus you find a bad value immediately, and not later as a payment that does not open.

4. Send the deep links to the SDK

useSpareLinkDeepLinks(spareLink) connects Linking.addEventListener('url', …) and Linking.getInitialURL() to the SDK. If your app has its own router, call the SDK yourself:

const handled = await spareLink.handleRedirect(url);
if (handled) return; // this URI is a payment return

The SDK keeps a return that arrives too early. Then start() or resumeIfNeeded() uses it.

5. Start a payment

async function pay(spareLink: SpareLink, reference: string) {
  const session = await spareLink.start({ reference });
  const result = await session.result;

  switch (result.status) {
    case 'success': {
      // Confirm with your backend first. Do not fulfil the order here.
      const record = await backend.getPaymentRequest(result.reference);
      // `Scheduled` is also settled. The bank accepted a payment for a later date.
      // The record also holds the paymentId. The deep link to your app does not.
      if (record.status === 'Processed' || record.status === 'Scheduled') {
        await fulfil(result.reference, record.paymentId);
      }
      break;
    }
    case 'cancelled':
      // The payer stopped. The server rejects the request.
      break;
    case 'failed':
      // result.errorCode always has a value. Show a message. Record the code.
      break;
    case 'abandoned':
      // The result is unknown. The payment can be complete. Ask your backend.
      await backend.getPaymentRequest(result.reference);
      break;
  }
}

Get the reference when the payer selects the pay button. Make a new payment request after each cancellation, failure or confirmed success. You cannot use a reference two times.

Disable the pay button during a payment. The spareLink.isFlowActive property tells you when a payment is active. A second call to start() gives a failed result with the code concurrent_start.

6. Add the recovery function

Call this function when the app becomes active:

const recovery = await spareLink.resumeIfNeeded();

if (recovery.kind === 'recovered') {
  // The return arrived before the flow started. The SDK read the result from it.
} else if (recovery.reason === 'outcomeUnknown' && recovery.reference) {
  // A payment was in progress. No return arrived. The payment can be complete.
  await backend.getPaymentRequest(recovery.reference);
}

The other values of reason need no action: noPendingSession, flowAlreadyActive and persistenceUnavailable. Without a pendingSessionStore, the function always gives persistenceUnavailable. Then you get no report of a payment that did not complete.

The return deep link

The SDK reads the result from the URI. This is the URI in your successRedirectUrl and failureRedirectUrl.

Your app gets a deep link. A browser gets an https redirect. Both carry the same parameters with the same names and the same values. Only one thing differs: the deep link has no signature.

This is an example of a success:

myapp://callback?reference=6G0TcjUlQDE&status=Processed
  &paymentId=537f72c3&merchantRef=order12345

This is an example of a failure:

myapp://callback?reference=6381GLdXnPQ&errorCode=SP500&status=Rejected
  &merchantRef=order12345

The deep link to your app has no sig parameter. Thus you cannot verify it. Read the record from your backend. See Confirmation of a result.

WARNING: Use errorCode to tell a failure from a success. Do not use the status value, because it can be empty. The service puts errorCode on each failure and on no success.

Older builds of the service send status=success or status=failure, and send the failure code as error_code. The SDK reads these values too.

Statuses

The status parameter holds the status of the payment request. Each value is in one of three groups. The first group goes to your successRedirectUrl. All other values go to your failureRedirectUrl. Thus you must register both URLs, and both URLs must open your app.

Scheduled is a success. The bank accepted a payment for a later date. The money did not move, but the payment is correct. If your fulfilment needs the money in the account, read the status from your backend. Do not use the 'success' result only.

The values in the third group are not results. The payer can still pay a request with one of these values. Thus a return must not have one of them. If the SDK finds one, it reports 'abandoned'. Then you must ask your backend.

The SDK does the same for a value that it does not know, and for an empty value. Spare can add new values. If the SDK reads an unknown value as a success, it can tell a payer that the money moved when the money did not move.

An empty status with an errorCode is a failure. The SDK reads it as one.

The failure code

errorCode is on each failure and on no success. Thus it is what tells the two apart, and it is more reliable than status, which can be empty.

The value today is always SP500. Spare can add more codes. Use the code for your messages. Do not use it to find the result.

WARNING: A payment request also has its own status. Read GET /payment-requests/{reference} from your backend before you fulfil an order. The deep link tells you what to do next. It does not prove what happened.

Older builds of the service send the code as error_code. The SDK reads that name too, and reports the value as errorCode.

Confirmation of a result

The SDK reads each result from a deep link. A deep link is not proof. The operating system sends the deep link to your app. Each installed app can register the same custom scheme. The deep link has a reference, a result and your own merchant reference. It has no bank identifiers and no confidential data.

WARNING: Do not fulfil an order after a 'success' result. First confirm the payment with your backend.

Your backend must use its own credentials and read the record:

GET /payment-requests/{reference}

The deep link to your app has no sig parameter. Thus there is nothing on it to verify, and the record is the only way to know what happened.

The signed redirect does have sig. It is an ES256 JWS of the full return URL with all the parameters, and a different app cannot make it. The SDK does not verify sig. A verification needs the Spare public key, and the SDK does not hold this key. Verify it on your backend if you receive it.

Two more conditions make this step necessary:

• An 'abandoned' result does not mean that the payment failed. A payer can authorize the payment at the bank and then close the app.
• outcomeUnknown is the same condition after a restart of the app. The SDK holds no credentials. Thus it cannot ask Spare.

Error codes

PaymentFailed.errorCode always has a value. The value is an SDK error code from the table below, or an error key from the return.

page_unavailable is not always terminal. If the SDK cannot open the payment flow, it tells the payer that it started no payment. It also shows a retry button. The flow gives a failure only if the payer stops.

Environments

Do your tests in sandbox. Then change this one value. If Spare gives you a different host, put it in baseUrl.

Events

The spareLink.events emitter sends these events: initialized, pageReady, redirectToBank and bankCallbackReceived. Then it sends one of succeeded, failed, cancelled or abandoned.

Use the events for analytics only. They cannot control the flow. Always use session.result for the result.

The SDK does not send an event for each step of the payment. For example, it sends no event when the payer selects a bank or reads the consent. The events show only the steps that the SDK can identify.

Checklist before the first payment

Do these checks before your first payment in the sandbox on a device.

Backend

• The x-signature header has a canonical JSON and ES256 detached JWS signature of the request object
• Each request has channel: 'sdk_react_native'
• successRedirectUrl and failureRedirectUrl agree with merchantScheme://merchantHost
• GET /payment-requests/{reference} operates, and the fulfilment needs a settled status (Processed or Scheduled)
• The fulfilment is idempotent by merchantReference

Native

• The Expo plugin is in the configuration, and you made the development client again
• The redirect URL opens your app from a browser
• You do not use Expo Go for the tests

TypeScript

• Your app makes one SpareLink object in a useMemo, and puts one SpareLinkHost near the root
• Your app has a pendingSessionStore, and calls resumeIfNeeded() when the app becomes active
• handleRedirect gets each URI
• Your app processes the four values of status, and uses outcomeUnknown
• Your app disables the pay button when isFlowActive is true

Identifiers

Sequence of the integration

1. Make and read payment requests in the sandbox from your backend. Confirm that the signature operates.
2. Install the package. Configure the plugin. Make the development client again.
3. Make the object and the host component. Add the deep links and resumeIfNeeded.
4. Do a full payment in the sandbox on a device. Include the confirmation from your backend.
5. Set an exact version of the SDK in package.json.