Persona de Pago / KYC

La API de Persona de Pago le permite registrar y validar personas físicas o empresas antes de que participen en transacciones. Este es un paso requerido para el cumplimiento KYC (Conozca a su Cliente) en muchos corredores de pago.

Flujo de Trabajo

Consulte el esquema de persona — Llame a GET /schema/person?countryCode={code} para obtener los campos requeridos específicos del país (vea Esquemas)
Valide la persona — Llame a POST /person/validate para comprobar si los datos satisfacen los requisitos KYC sin crear un registro
Cree la persona — Llame a POST /person para registrar la persona en el sistema

Endpoints

POST https://{FQDN}/person
POST https://{FQDN}/person/validate

Encabezados:

Encabezado	Valor
`Authorization`	`Bearer {accessToken}`
`Content-Type`	`application/json`

Ambos endpoints aceptan el mismo cuerpo de solicitud. La única diferencia es:

Endpoint	Comportamiento
`POST /person`	Crea un registro de persona de pago
`POST /person/validate`	Valida los datos sin crear un registro

Solicitud

Campo	Tipo	Requerido	Descripción
`type`	string	No	Tipo de persona: `"INDIVIDUAL"` o `"BUSINESS"`
`identificationType`	string	No	Tipo de identificación (p. ej., `"NATIONAL_ID"`, `"PASSPORT"`, `"DRIVER_LICENSE"`, `"TAX_ID"`)
`identification`	string	No	Número de identificación
`gender`	string	No	Género: `"M"` o `"F"`
`firstName`	string	No	Nombre (requerido para personas físicas)
`lastName`	string	No	Apellido (requerido para personas físicas)
`companyName`	string	No	Razón social de la empresa (requerido para empresas)
`address`	object	No	Detalles de la dirección

Nota: Aunque la mayoría de los campos están marcados como opcionales en el esquema de la API, los requisitos específicos de cada país pueden hacerlos obligatorios. Siempre consulte primero GET /schema/person para determinar qué campos son requeridos para un país dado.

Objeto `address`

Campo	Tipo	Requerido	Descripción
`addressLine1`	string	Sí	Línea 1 de la dirección
`addressLine2`	string	No	Línea 2 de la dirección
`city`	string	Sí	Nombre de la ciudad
`state`	string	Sí	Estado o provincia
`postalCode`	string	Sí	Código postal/ZIP
`countryCode`	string	Sí	Código de país (ISO Alfa-2)
`phoneNumber`	string	Sí	Número de teléfono
`emailAddress`	string	Sí	Dirección de correo electrónico

Ejemplo — Crear una Persona Física

curl -X POST https://{FQDN}/person \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "INDIVIDUAL",
    "identificationType": "NATIONAL_ID",
    "identification": "050482156",
    "gender": "M",
    "firstName": "John",
    "lastName": "Smith",
    "address": {
      "addressLine1": "4429 Candlewood St",
      "addressLine2": "",
      "city": "Los Angeles",
      "state": "CA",
      "postalCode": "90712",
      "countryCode": "US",
      "phoneNumber": "5551234567",
      "emailAddress": "[email protected]"
    }
  }'

Ejemplo — Validar una Empresa

curl -X POST https://{FQDN}/person/validate \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "BUSINESS",
    "identificationType": "TAX_ID",
    "identification": "12-3456789",
    "companyName": "Acme Corp",
    "address": {
      "addressLine1": "100 Market St",
      "addressLine2": "Suite 300",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "countryCode": "US",
      "phoneNumber": "4155551234",
      "emailAddress": "[email protected]"
    }
  }'

Respuesta — Éxito (200)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "INDIVIDUAL",
  "firstName": "John",
  "lastName": "Smith",
  "status": "APPROVED"
}

Respuesta — Fallo de Validación (200)

{
  "type": "INDIVIDUAL",
  "firstName": "John",
  "lastName": "Smith",
  "status": "REJECTED",
  "message": "Identification number does not match country requirements"
}

Qué Sigue

Esquemas — Consulte los requisitos de campos específicos por país para personas, cuentas y payouts
Verificar Cuenta — Valide un método de pago antes de transaccionar
Transacción Push — Envíe payouts a destinatarios