Skip to main content

Getting Started

This guide walks you through making your first successful request to the Paynovus Card Management API.

Prerequisites​

  • A partner account registered with Paynovus (you will receive your issuer URL and partner ID)
  • Your EC private key (see Authentication → Key Generation)
  • Node.js 18+ or any HTTP client

Step 1 — Verify the service is healthy​

The /health-check endpoint is public and requires no authentication:

curl https://api.card-management-staging.paynovus.com/api/partner/health-check

Expected response: OK with status 200.

Step 2 — Generate a JWT token​

Install the required packages:

npm install jsonwebtoken

Use the same signing flow described in Authentication to create a token:

const jwt = require('jsonwebtoken');
const fs = require('fs');

const privateKey = fs.readFileSync('./private.pem', 'utf8');

function createPartnerToken() {
  const payload = {
    iss: 'https://your-partner-url.com',
    sub: 'YOUR_PARTNER_ID',
    exp: Math.floor(Date.now() / 1000) + 60,
    iat: Math.floor(Date.now() / 1000)
  };

  return jwt.sign(payload, privateKey, { algorithm: 'ES512' });
}

Step 3 — Call /me to verify authentication​

Use GET /me to confirm that your token is accepted and your account is configured correctly:

curl https://api.card-management-staging.paynovus.com/api/partner/me \
  -H "Authorization: Bearer $TOKEN"

If authentication is working properly, the response will return your account details and the account context associated with your configured partner setup. The response includes:

  • partner — your authenticated partner record (name, url, status, webhooks, …).
  • b2bAccounts — every B2B tenant linked to your partner (empty if you don't own any). Use these _ids in the /business/accounts/:b2bAccountId/* paths.
  • individuals — every individual onboarding owned by your partner.

Next steps​

  • For critical operations, learn about Idempotency & Rate Limiting →
  • Continue with the protected endpoints, depending on which account types you own:
  • To be told when a workflow finishes without polling, set up Webhooks → — one endpoint, signed payloads, and your own delivery history