---
description: >-
  Create and validate payment persons for KYC compliance using POST /person
  and POST /person/validate. Supports individual and business entity types
  with country-specific identification requirements.
---

# Payment Person / KYC

The Payment Person API lets you register and validate individuals or businesses before they participate in transactions. This is a required step for KYC (Know Your Customer) compliance in many payment corridors.

## Workflow

1. **Query the person schema** — Call `GET /schema/person?countryCode={code}` to get country-specific required fields (see [Schemas](reference-data/schemas.md))
2. **Validate the person** — Call `POST /person/validate` to check if the data satisfies KYC requirements without creating a record
3. **Create the person** — Call `POST /person` to register the person in the system

## Endpoints

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

**Headers:**

| Header | Value |
|---|---|
| `Authorization` | `Bearer {accessToken}` |
| `Content-Type` | `application/json` |

Both endpoints accept the same request body. The only difference is:

| Endpoint | Behavior |
|---|---|
| `POST /person` | Creates a payment person record |
| `POST /person/validate` | Validates the data without creating a record |

## Request

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string | ❌ | Person type: `"INDIVIDUAL"` or `"BUSINESS"` |
| `identificationType` | string | ❌ | ID type (e.g., `"NATIONAL_ID"`, `"PASSPORT"`, `"DRIVER_LICENSE"`, `"TAX_ID"`) |
| `identification` | string | ❌ | Identification number |
| `gender` | string | ❌ | Gender: `"M"` or `"F"` |
| `firstName` | string | ❌ | First name (required for individuals) |
| `lastName` | string | ❌ | Last name (required for individuals) |
| `companyName` | string | ❌ | Company legal name (required for businesses) |
| `address` | object | ❌ | Address details |

> **Note:** While most fields are marked as optional in the API schema, country-specific requirements may make them mandatory. Always query `GET /schema/person` first to determine which fields are required for a given country.

### `address` Object

| Field | Type | Required | Description |
|---|---|---|---|
| `addressLine1` | string | ✅ | Street address line 1 |
| `addressLine2` | string | ❌ | Street address line 2 |
| `city` | string | ✅ | City name |
| `state` | string | ✅ | State or province |
| `postalCode` | string | ✅ | Postal/ZIP code |
| `countryCode` | string | ✅ | Country code (ISO Alpha-2) |
| `phoneNumber` | string | ✅ | Phone number |
| `emailAddress` | string | ✅ | Email address |

## Example — Create an Individual

```bash
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": "john.smith@example.com"
    }
  }'
```

## Example — Validate a Business

```bash
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": "finance@acmecorp.com"
    }
  }'
```

## Response — Success (200)

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

## Response — Validation Failure (200)

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

## What's Next

- [Schemas](reference-data/schemas.md) — Query country-specific field requirements for persons, accounts, and payouts
- [Check Account](check-account.md) — Validate a payment method before transacting
- [Push Transaction](payment/push-transaction.md) — Send payouts to recipients