@payconnect.me/kyc-core

The parts of the PayConnect KYC integration that have nothing to do with the user interface: the Partners API client, the request and response types, validation rules, and the country data.

There is no React or React Native code in this package.

Do you need this?

| You are | Install | | --- | --- | | Building a React Native app with the KYC flow in it | @payconnect.me/kyc-react-native. This package comes with it — you do not install it separately. | | Building the backend that starts KYC sessions | This package. Keep reading. | | Building a client that is not React Native | This package. |

Most people reading this are here for one function: createKycSession.

Install

npm install @payconnect.me/kyc-core

Node 20.19 or newer. This package is ESM-only, so import works directly. If your backend is CommonJS you can still require('@payconnect.me/kyc-core') — Node supports requiring an ESM package from that version onwards. You do not need a bundler; the example below runs under plain node.

Mint a session code

Your app cannot start a KYC session on its own. Your backend does it, using your secret API key, and hands the app only the resulting code.

// On YOUR backend. Never in the app.
import express from 'express';
import { createKycSession } from '@payconnect.me/kyc-core';

const app = express();
app.use(express.json());

app.post('/kyc-session', async (req, res) => {
  try {
    const code = await createKycSession({
      baseUrl: 'https://partners-api.payconnect.me',
      apiKey: process.env.PARTNERS_API_KEY, // secret — server environment only
      productId: req.body.productId, // the KYC product you are starting
    });
    res.json({ code }); // hand ONLY the code to the app
  } catch (error) {
    res.status(502).json({ error: String(error) });
  }
});

app.listen(3000);

Your app fetches { code } from that endpoint and passes it to <PayConnectKyc sessionCode={code} />.

Options

| Option | Type | Required | What it is | | --- | --- | --- | --- | | baseUrl | string | Yes | The PayConnect Partners API: https://partners-api.payconnect.me. | | apiKey | string | Yes | Your partner API key. A secret. | | productId | string | Yes | The UUID of the KYC product to start. PayConnect gives you this. | | fetch | typeof fetch | No | Your own fetch, if you need one. Defaults to the global. |

It returns the session code as a string, or throws a KycApiError carrying status and errorCode.

Keep the key on the server

Three rules, and they are not negotiable:

1. The X-API-Key never ships in an app. A mobile app can be unpacked, and a key inside one cannot be rotated without a new release.
2. The app only ever gets the session code. It is short-lived and scoped to one applicant.
3. The webhook is the verdict. The SDK's completed event means the applicant reached the end of the flow, not that they passed. Verify the x-pc-signature HMAC on PayConnect's webhook with your webhook secret — also a backend secret — and use that.

createKycSession is deliberately not re-exported by @payconnect.me/kyc-react-native, so it cannot reach app code by accident.

What else is in here

You will not need most of this unless you are writing your own client. Everything is fully typed.

| Export | What it is | | --- | --- | | KycClient | The Partners API client. Takes { baseUrl, sessionCode } — plus optional token, surfaceId and fetch — and covers assessments, questions, identity, additional documents and submission. | | KycApiError | The only error class in the package. Carries status, errorCode and kind. | | classifyIdentityError | Turns a Partners API error code into the category the UI should react to. | | passportVerifySchema, thaiIdVerifySchema, kycAddressSchema | Zod schemas for the identity and address forms — document number formats, the minimum age (MIN_AGE_YEARS), and the Thai postcode and district rules. | | countries, countryByIso3, countryLabel, countryFlagEmoji, suggestedCountries | The 249-country dataset used by the nationality pickers. | | normalizeNationality | Canonicalise an ISO-3 nationality code, or null if it names no country in the dataset. | | safeReturnTo, appendKycStatus | Validate a return URL and add the session and status query values to it. | | surfaceIdFor | Derive a stable device identifier from a session code, for handing a session between devices. | | normalizeNfcAvailability, chipErrorCodeForVendorFailure | Working out whether a chip read is possible, and what a failed one means. | | Route helpers and the flow model | The URL templates and step arithmetic every PayConnect KYC client shares. |

The wire values these are built on — enums, route templates, the error-code map, the reference datasets — come from @payconnect.me/kyc-contract, which this package depends on.

Support

• Partners API: https://partners-api.payconnect.me
• API reference and your productId: ask your PayConnect contact.
• Source and issues: https://github.com/fractionco/payconnect-kyc-sdk-react-native