@mdpsdk/mdp-sdk

SDK de Mesa de Pagos para Node.js — auth y onboarding (verificación básica + verificación Europa/EE.UU. opcional). Credenciales BYOK en el servidor del integrador.

• Versión: 0.5.0
• Node: ≥ 18

Instalación

npm install @mdpsdk/mdp-sdk

import { createMdpSdk, OnboardingError } from '@mdpsdk/mdp-sdk'

const sdk = createMdpSdk() // lee variables de entorno

Inicio rápido (cliente personal)

const { verificationUrl, externalCustomerId } = await sdk.onboarding.start({
  type: 'personal',
  externalCustomerId: 'cust_123',
  profile: { email: '[email protected]' }
})
// Redirigir al usuario a verificationUrl

await sdk.onboarding.getStatus({
  externalCustomerId: 'cust_123',
  type: 'personal'
})
// Cuando basicVerification.status === 'approved':

const euUs = await sdk.onboarding.submitEuUs({
  externalCustomerId: 'cust_123',
  input: { target: 'person' }
})
// Enviar euUs.termsOfServiceUrl al usuario; tras aceptar términos:

await sdk.onboarding.activateComplianceCheck({
  externalCustomerId: 'cust_123',
  walletAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  asset: 'USDC_POLYGON'
})

Variables de entorno

Los nombres son los del runtime; en producto se habla de verificación básica y cumplimiento EU/US.

Auth (obligatorias)

| Variable | Uso | |----------|-----| | MDP_SDK_BASIC_VERIFY_API_KEY | API key — verificación básica | | MDP_SDK_BASIC_VERIFY_API_URL | Default: https://api.withpersona.com/api/v1/ | | MDP_SDK_COMPLIANCE_API_URL | Base URL — cumplimiento / cuentas EU-US | | MDP_SDK_COMPLIANCE_CLIENT_ID | M2M client id | | MDP_SDK_COMPLIANCE_CLIENT_SECRET | M2M secret |

Onboarding (obligatorias para sdk.onboarding)

| Variable | Uso | |----------|-----| | MDP_SDK_TEMPLATE_PERSONAL | Template KYC personal | | MDP_SDK_TEMPLATE_BUSINESS_DEFAULT | KYB empresa (país fuera de CL/US/ES/AR/BR o sin país) | | MDP_SDK_TEMPLATE_BUSINESS_CL | KYB Chile | | MDP_SDK_TEMPLATE_BUSINESS_US | KYB USA | | MDP_SDK_TEMPLATE_BUSINESS_ES | KYB España | | MDP_SDK_TEMPLATE_BUSINESS_AR | KYB Argentina | | MDP_SDK_TEMPLATE_BUSINESS_BR | KYB Brasil |

Breaking change 0.5.0: no se leen nombres PERSONA_* ni BORDERLESS_*.

En start({ type: 'business', profile: { address: { country: 'CL' } } }) se elige el template por ISO 3166-1 alpha-2.

Email en start

Email obligatorio (email en el argumento o profile.email). El SDK lo sincroniza al proceso de verificación básica. Sin email → ONBOARDING_MISSING_EMAIL antes de EU/US.

Override de campos del template: createMdpSdk({ onboarding: { inquiryFieldMaps: { personal: { email: 'mi_campo' } } } }).

API pública

• createMdpSdk(config?) → { auth, onboarding }
• Tipos exportados: OnboardingStartInput, OnboardingStatusResponse, SubmitEuUsParams, etc.
• Errores: OnboardingError con code y retryable

sdk.onboarding

| Método | Descripción | |--------|-------------| | start | Verificación básica + verificationUrl; devuelve inquiryId (KYB: guardar como businessInquiryId) | | getVerificationUrl | Renovar enlace si el usuario perdió el URL (externalCustomerId) | | getStatus | Estado titular/empresa; polling principal | | submitEuUs | Opt-in Europa/EE.UU. (titular, socio o empresa) | | activateComplianceCheck | Cuenta operativa + cumplimiento tras aceptar términos | | getTermsOfServiceUrl | URL de términos (regenerate?, country?) | | listOwners | Socios KYB (businessInquiryId + mapas opcionales) | | getOwnerVerificationUrl | Enlace básica de un socio | | getOwnerStatus | Estado de un socio | | saveOwnerOccupation | Dato auxiliar pre-básica (KYB) | | syncOwnerStatus | Debug — no usar en flujo productivo |

El SDK no envía emails; el integrador reenvía termsOfServiceUrl. Usa polling con getStatus / getOwnerStatus.

Flujo — Cliente personal

| Paso | Acción | |------|--------| | 1 | start — externalCustomerId + email | | 2 | Usuario completa verificación básica | | 3 | getVerificationUrl solo si perdió el enlace | | 4 | getStatus hasta basicVerification.status === 'approved' | | 5 | submitEuUs({ input: { target: 'person' } }) | | 6 | Enviar termsOfServiceUrl al usuario | | 7 | Usuario acepta términos | | 8 | activateComplianceCheck({ externalCustomerId, walletAddress }) | | 9 | getStatus hasta compliance_approved / account_ready |

Flujo — Empresa KYB

Orden obligatorio: socios EU/US primero → empresa al final.

| Paso | Acción | |------|--------| | 1 | start({ type: 'business', ... }) — guardar inquiryId como businessInquiryId | | 2 | Representante completa KYB básico | | 3 | getStatus({ type: 'business' }) — básica approved | | 4 | listOwners({ businessInquiryId, ownerInquiryIds? }) | | 5 | saveOwnerOccupation? por socio | | 6 | getOwnerVerificationUrl por socio | | 7 | getOwnerStatus (polling) — básica socio approved | | 8 | submitEuUs({ target: 'person', ownerId, ownerInquiryId }) por socio (opt-in) | | 9 | Usuario acepta términos del socio | | 10 | activateComplianceCheck({ identityId: socio, walletAddress }) | | 11 | Actualizar ownerIdentityIds en tu BD | | 12 | listOwners → canSubmitBusiness === true | | 13 | submitEuUs({ target: 'business', ownerComplianceIdentityIds: [...] }) | | 14 | Términos empresa + activateComplianceCheck + getStatus |

Ejemplo start KYB:

const { verificationUrl, inquiryId } = await sdk.onboarding.start({
  type: 'business',
  externalCustomerId: 'emp_001',
  profile: {
    email: '[email protected]',
    legalName: 'ACME SA',
    taxId: '123',
    address: {
      street1: 'Av Test 1',
      city: 'Santiago',
      state: 'RM',
      postalCode: '8320000',
      country: 'CL'
    }
  }
})
const businessInquiryId = inquiryId!

Qué guardar en tu BD

| Campo | Cuándo | |-------|--------| | externalCustomerId | Siempre — tu PK única | | businessInquiryId | KYB — inquiryId de start | | ownerInquiryIds | Mapa ownerId → inquiry del socio | | ownerIdentityIds | Mapa ownerId → identidad EU/US del socio |

No es obligatorio persistir identityId del titular: el SDK resuelve por externalCustomerId cuando aplica.

Campos de estado (interpretación)

| Campo | Significado | |-------|-------------| | canContinueEuUsVerification: true | Puedes llamar submitEuUs (básica OK, EU/US no iniciada) | | canContinueEuUsVerification: false + euUsVerification.started: true | EU/US ya en curso — no repetir submitEuUs | | canSubmitBusiness: true | KYB — puedes submitEuUs({ target: 'business' }) | | accountCreated: false | En activateComplianceCheck: cuenta ya existía; reintento válido |

Errores frecuentes

| Código | Cuándo | |--------|--------| | ONBOARDING_DUPLICATE_REFERENCE_ID | Segundo start mismo externalCustomerId → usar getVerificationUrl | | ONBOARDING_INQUIRY_NOT_FOUND | Sin proceso de verificación básica para ese id | | ONBOARDING_MISSING_EMAIL | Falta email en start | | ONBOARDING_BASIC_NOT_APPROVED | submitEuUs antes de aprobar básica | | ONBOARDING_BUSINESS_NOT_READY | target: business sin ownerComplianceIdentityIds o socios incompletos |

Estados EU/US (euUsVerification.status)

| Estado cumplimiento (interno) | SDK | |------------------------------|-----| | Sin check + link términos | tos_pending | | En revisión | compliance_in_review | | Aprobado | compliance_approved | | Rechazado / cancelado | compliance_rejected |

El campo JSON complianceProviderStatus es valor técnico de depuración.

Documentación en el monorepo MDP

| Recurso | Ruta | |---------|------| | Integración TypeScript (prompt IA) | docs/openapi/mdp-sdk-onboarding-integrator.yaml | | Contrato HTTP (prueba-sdk / Postman) | docs/openapi/mdp-onboarding-sdk.yaml | | Guías markdown | docs/onboarding/README.md |

Desarrollo y publicación en npm

cd api-mdp/packages/mdp-sdk
npm install
npm run build
npm test