@mdp/sdk

SDK de Mesa de Pagos — auth + onboarding hacia Persona y Borderless (BYOK).

Instalación

npm install @alvarochaval/mdp-sdk

Variables de entorno

Auth (obligatorias)

| Variable | Descripción | |----------|-------------| | PERSONA_API_KEY | API key Persona | | PERSONA_API_URL | Default: https://api.withpersona.com/api/v1/ | | BORDERLESS_API_URL | Base URL Borderless | | BORDERLESS_CLIENT_ID | M2M client id | | BORDERLESS_CLIENT_SECRET | M2M secret |

Onboarding (obligatorias para sdk.onboarding)

| Variable | Descripción | |----------|-------------| | PERSONA_API_TEMPLATE_PERSONA | Template inquiry KYC personal | | PERSONA_API_TEMPLATE_BUSINESS_DEFAULT | KYB empresa — país distinto de CL/US/ES/AR/BR o sin address.country | | PERSONA_API_TEMPLATE_BUSINESS_CL | KYB Chile | | PERSONA_API_TEMPLATE_BUSINESS_US | KYB USA | | PERSONA_API_TEMPLATE_BUSINESS_ES | KYB España | | PERSONA_API_TEMPLATE_BUSINESS_AR | KYB Argentina | | PERSONA_API_TEMPLATE_BUSINESS_BR | KYB Brasil |

Compatibilidad: si no defines PERSONA_API_TEMPLATE_BUSINESS_DEFAULT, se usa PERSONA_API_TEMPLATE_BUSISNESS o PERSONA_API_TEMPLATE_BUSINESS.

En start({ type: 'business', profile: { address: { country: 'CL' } } }) se elige el template según ISO 3166-1 alpha-2 del país.

Sincronizar campos al inquiry Persona (PATCH)

En start el email es obligatorio (email en el body o profile.email). Tras crear el inquiry el SDK siempre guarda el email en Persona (email-address + email_address para personal). En submit-eu-us no hace falta repetir el email.

| Campo integrador | Key Persona (personal) | Key Persona (business) | |------------------|------------------------|-------------------------| | email | email_address | form_filler_email_address | | phone | phone_number | input_phone_number | | firstName / legalName | name_first / — | business_name | | lastName | name_last | — | | taxId | identification_number | business_tax_identification_number | | address.* | address_street_1, … | business_physical_address_* |

Override por template: createMdpSdk({ onboarding: { personaFieldMaps: { personal: { email: 'mi_campo_email' } } } }).

Sin email en inquiry ni en profile → ONBOARDING_MISSING_EMAIL antes de llamar a Borderless.

Uso

import { createMdpSdk } from '@alvarochaval/mdp-sdk'

const sdk = createMdpSdk()

// --- Fase 1: verificación básica (personal) ---
const { inquiryId, verificationUrl } = await sdk.onboarding.start({
  type: 'personal',
  externalCustomerId: 'cust_123',
  profile: { email: '[email protected]' }
})
// Guardar en TU BD: inquiryId, externalCustomerId

const status = await sdk.onboarding.getStatus({
  externalCustomerId: 'cust_123',
  inquiryId,
  type: 'personal'
})

// --- Fase 2: Europa/EE.UU. (opt-in) — paso 1: identidad + documentos + términos ---
const euUs = await sdk.onboarding.submitEuUs({
  externalCustomerId: 'cust_123',
  inquiryId,
  input: {
    target: 'person',
    operationType: 'send' // opcional; email desde inquiry (profile en start)
  }
})
// Guardar euUs.identityId; revisar euUs.documentUpload (éxito parcial no aborta el flujo)
// Enviar euUs.termsOfServiceUrl al usuario

// Usuario acepta términos en Borderless (sin webhook)

// --- paso 2: tras aceptar TOS ---
await sdk.onboarding.activateComplianceCheck({
  identityId: euUs.identityId
})

// Renovar URL de términos si hace falta:
await sdk.onboarding.getTermsOfServiceUrl({
  externalCustomerId: 'cust_123',
  identityId: euUs.identityId,
  country: 'US',
  regenerate: true
})

API pública

• createMdpSdk() → { auth, onboarding }
• Tipos exportados desde el paquete (OnboardingStartInput, OnboardingStatusResponse, etc.)
• OnboardingError para errores con code y retryable

sdk.onboarding

| Método | Descripción | |--------|-------------| | start | Inquiry Persona + verificationUrl | | getVerificationUrl | Renovar enlace (requiere inquiryId) | | getStatus | Estado básico + EU/US (requiere inquiryId; identityId?) | | submitEuUs | Fase 2: identidad Borderless + documentos desde Persona included + URL términos | | activateComplianceCheck | Tras aceptar TOS: refresca compliance (idempotente si ya existe) | | getTermsOfServiceUrl | Obtener o regenerar URL términos (regenerate?, country?) | | listOwners | Socios KYB (requiere businessInquiryId + mapas opcionales de ids) | | getOwnerVerificationUrl | Enlace básico del socio | | getOwnerStatus | Estado del socio | | saveOwnerOccupation | Dato auxiliar (memoria del proceso) | | handleWebhook | Normalizar evento Persona/Borderless | | syncOwnerStatus | Debug: estado inquiry |

Qué guardar en la BD del integrador

| Dato | Cuándo | |------|--------| | externalCustomerId | Siempre (tu PK) | | inquiryId | Tras start | | identityId | Tras submitEuUs | | ownerId → ownerInquiryId / ownerIdentityId | KYB, por socio |

KYB (resumen)

1. start({ type: 'business', ... })
2. Representante completa KYB → listOwners({ businessInquiryId, ownerInquiryIds? })
3. Por socio: getOwnerVerificationUrl / submitEuUs({ target: 'person', ownerId, ownerInquiryId })
4. Cuando canSubmitBusiness: submitEuUs({ target: 'business', ownerBorderlessIdentityIds: [...] })

Scripts

npm run build
npm test

Documentación

OpenAPI: docs/openapi/mdp-onboarding-sdk.yaml en el monorepo MDP.