Merchant (acc_xxx)            ← CRM org — provisioned separately (or inferred)
  ├── TPA (tpa_xxx)           ← sub-merchant: KYB, keys, reporting, settlement
  └── Store (store_xxx)       ← checkout & payment routing (independent, via CRM)

1. tpas.create()                    → TPA exists (pending)
2. requirements.update() × N        → business, representative AND banking.* values
3. documents.upload() × N           → KYB documents (bytes, multipart)
4. tpas.provision()                 → ★ pushes everything to the acquirer
   └── read the response: nextAction, requirements.dueCodes, rejectedDocuments
       fix what it points at, call provision() again — it converges.
5. merchant signs the agreement     → ★ mandatory in live mode
   └── sent automatically by email to representative.email once step 4
       completes; the TPA activates automatically on signature.

const partner = new Tagada(process.env.TAGADA_PARTNER_KEY!);

const tpa = await partner.partners.processing.tpas.create({
  legalName: 'Acme SAS',          // required — the KYB legal entity
  accountId: 'acc_xxx',          // owning merchant (acc_xxx)
  country: 'FR',                  // ISO 3166-1 alpha-2
  currency: 'EUR',                // ISO 4217 settlement currency
  externalRef: 'merchant_42_eu',  // YOUR id — used for idempotency
  markup: {                       // optional — YOUR price for THIS merchant
    cardMarkupBps: 100,           // +1.00% margin for you
    cardFixedCents: 10,           // +$0.10 margin for you
  },
  metadata: { region: 'eu' },
});

// →
// {
//   object: 'tpa',
//   id: 'tpa_xxx',
//   accountId: 'acc_xxx',
//   partnerId: 'par_xxx',
//   externalRef: 'merchant_42_eu',
//   status: 'pending_operator_assignment',
//   applicationStatus: 'created',
//   mode: 'live',
//   createdAt: '2026-04-29T…',
//   nextSteps: [
//     '1. Fill the requirements (accounts.updateRequirement) — including the banking.* codes…',
//     '2. Upload KYB documents (documents.upload — multipart bytes…)',
//     '3. Call tpas.provision(id) — NOTHING is sent to the acquirer until you do…',
//     '4. Inspect the provision() response: nextAction, requirements.dueCodes…',
//   ],
// }
//
// `country` / `currency` are provisioning inputs — they drive KYB and the
// auto-created store, but are not echoed back on the TPA object.
// Discover the store via: stores.list({ accountId: tpa.accountId })

const a = await partner.partners.processing.tpas.create({ legalName: 'Acme SAS', accountId: 'acc_xxx', externalRef: 'merchant_42_eu' });
const b = await partner.partners.processing.tpas.create({ legalName: 'Acme SAS', accountId: 'acc_xxx', externalRef: 'merchant_42_eu' });
console.log(a.id === b.id); // true

// Read the merchant's current pricing
const pricing = await partner.partners.processing.tpas.retrieveMarkup('tpa_xxx');
// { object: 'tpa_markup', tpaId, markup, source: 'tpa' | 'partner', sellRate: {...} }

// Set a per-merchant markup (replaces your partner-level grid for this TPA)
await partner.partners.processing.tpas.updateMarkup('tpa_xxx', {
  cardMarkupBps: 250,    // +2.50% for you
  cardFixedCents: 25,    // +$0.25 for you
});

// Revert to your partner-level grid
await partner.partners.processing.tpas.clearMarkup('tpa_xxx');

const tpa = await partner.partners.processing.tpas.retrieve('tpa_xxx');
const byRef = await partner.partners.processing.tpas.retrieveByExternalRef('merchant_42_eu'); // null if none

const { data, hasMore } = await partner.partners.processing.tpas.list({
  limit: 50,
  accountId: 'acc_xxx',     // optional — only this merchant's TPAs
  externalRef: 'merchant_42_eu',
});

const key = await partner.partners.processing.tpas.keys.create('tpa_xxx');
// { object: 'processing_key', id: 'ak_xxx', tpaId: 'tpa_xxx',
//   prefix: 'tp_sk_live_…', secret: 'tp_sk_live_…' /* once */, label: 'Your Partner — merchant_42_eu' }

const keys = await partner.partners.processing.tpas.keys.list('tpa_xxx');
await partner.partners.processing.tpas.keys.revoke(key.id);

const { data: requirements } = await partner.partners.processing.tpas.requirements.list('tpa_xxx');

// Submit a value for a non-document requirement. Pass the value directly —
// a primitive or a free-form object (e.g. { iban, bic } for banking.iban).
await partner.partners.processing.tpas.requirements.update(
  'tpa_xxx',
  'business.vat_number',
  'FR12345678901',
);

import { readFile } from 'node:fs/promises';

const bytes = await readFile('./passport-jane-doe.pdf');
await partner.partners.processing.tpas.documents.upload('tpa_xxx', {
  file: new Blob([bytes], { type: 'application/pdf' }),
  kind: 'identity_proof',
  filename: 'passport-jane-doe.pdf',
  requirementCode: 'documents.identity_proof',
});

await partner.partners.processing.tpas.documents.record('tpa_xxx', {
  requirementCode: 'documents.identity_proof',
  kind: 'identity_proof',
  filename: 'passport-jane-doe.pdf',
  // Must be an HTTPS URL we can download right now (e.g. a fresh presigned URL).
  storageUrl: 'https://your-bucket.s3.amazonaws.com/passport-jane-doe.pdf?X-Amz-...',
});

const { data: docs } = await partner.partners.processing.tpas.documents.list('tpa_xxx');

const result = await partner.partners.processing.tpas.provision('tpa_xxx');

if (!result.completed) {
  console.log(result.nextAction);
  // e.g. "Fill the outstanding requirements (banking.iban), then call provision again."

  console.log(result.requirements.dueCodes);   // exact codes still due
  console.log(result.rejectedDocuments);       // [{ kind, rejectionReason, … }]
}

const result = await partner.partners.processing.tpas.provision('tpa_xxx');

if (result.contract?.status === 'pending_signature') {
  // Surface this link in YOUR dashboard / onboarding flow —
  // don't wait for the merchant to find the email.
  console.log(result.contract.signingUrl);
  console.log(result.contract.signerEmail); // who received the request
}
// status: 'not_required' | 'not_sent' | 'pending_signature' | 'signed'