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

Query the person schema — Call GET /schema/person?countryCode={code} to get country-specific required fields (see Schemas)
Validate the person — Call POST /person/validate to check if the data satisfies KYC requirements without creating a record
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

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]"
    }
  }'

Example — Validate a Business

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]"
    }
  }'

Response — Success (200)

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

Response — Validation Failure (200)

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

What's Next

Schemas — Query country-specific field requirements for persons, accounts, and payouts
Check Account — Validate a payment method before transacting
Push Transaction — Send payouts to recipients