Skip to content
Exa Docs

Submit KYC application

POST
/kyc/application

Submit information for KYC application.

Encrypted kyc payload

When the header has encrypted=true, the payload should be encrypted.

The steps to encrypt are:

  1. Generate AES Key: Create a random 256-bit AES key
  2. Encrypt Payload: Use AES-256-GCM to encrypt your KYC JSON data
  3. Encrypt AES Key: Use Rain-provided RSA public key with OAEP padding
  4. Encode Components: Base64-encode all encrypted components
  5. Set Header: Include encrypted: “true” header in your request
  6. Submit Request

KYC Encryption Public Key for sandbox is:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyZixoAuo015iMt+JND0y
usAvU2iJhtKRM+7uAxd8iXq7Z/3kXlGmoOJAiSNfpLnBAG0SCWslNCBzxf9+2p5t
HGbQUkZGkfrYvpAzmXKsoCrhWkk1HKk9f7hMHsyRlOmXbFmIgQHggEzEArjhkoXD
pl2iMP1ykCY0YAS+ni747DqcDOuFqLrNA138AxLNZdFsySHbxn8fzcfd3X0J/m/T
2dZuy6ChfDZhGZxSJMjJcintFyXKv7RkwrYdtXuqD3IQYakY3u6R1vfcKVZl0yGY
S2kN/NOykbyVL4lgtUzf0IfkwpCHWOrrpQA4yKk3kQRAenP7rOZThdiNNzz4U2BE
2wIDAQAB
-----END PUBLIC KEY-----

KYC Encryption Public Key for production needs to be provided.

A working and tested example is available in here

Payload structure before encryption

  1. Personal information (name, date of birth, address)
  2. Identity verification documents
  3. Compliance information (occupation, income, etc.)
  4. Terms of service acceptance

Here’s the markdown table with object notation for nested fields:

fieldNametypeexamplenotes
emailstringuser@domain.com
lastNamestringDoe
firstNamestringJohn
nationalIdstring123456789
birthDatestring1970-01-01
countryOfIssuestringUS
phoneCountryCodestring1
phoneNumberstring5551234567
address.line1string123 Main Street
address.line2stringApt 4B
address.citystringNew York
address.regionstringNY
address.postalCodestring10001
address.countryCodestringUS
ipAddressstring192.168.1.100
occupationstring11-1011Ask for the mandatory occupation codes
annualSalarystring75000
accountPurposestringPersonal Banking
expectedMonthlyVolumestring5000
isTermsOfServiceAcceptedbooleantrue

Authentication and organization verification

The exa account needs to be authenticated but also a member of the organization that submit the KYC application needs to probe that belong to the organization and needs to have kyc permission, every owner and admin of an organization has this permission.

To probe the member of the organization needs to generate a SIWE message with the following statement and viem library is recommended:

“I apply for KYC approval on behalf of address [checksum address] with payload hash [hash]”;

The hash is sha256(encryptedPayload.ciphertext)

The siwe message will be:

fieldNametypeexamplenotes
verify.messagestringSIWE message that includes the statement
verify.signatureHexsignature of the message
verify.walletAddressAddressaddress of the member of the organization that signed the message
verify.chainIdnumber11155420

A working and tested example is available in here

Note that the member of the organization must be created, the organization must exist and the member must be added as admin by another admin or owner.

Working example about how to login is here

The admin should add a member using addMember method.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters ”
encrypted
string

Request Body

Section titled “Request Body ”
Any of:
object
email
required

Email address

string format: email 
user@domain.com
lastName
required

The person’s last name

string
<= 50 characters
firstName
required

The person’s first name

string
<= 50 characters
nationalId
required

The person’s national ID

string
<= 50 characters
birthDate
required

Birth date (YYYY-MM-DD)

string
/^\d{4}-\d{2}-\d{2}$/ 
1970-01-01
countryOfIssue
required

The person’s country of issue of their national id, as a 2-digit country code

string
>= 2 characters <= 2 characters /^[A-Z]{2}$/
phoneCountryCode
required

The user’s phone country code

string
>= 1 characters <= 3 characters /^\d{1,3}$/
phoneNumber
required

The user’s phone number

string
>= 1 characters <= 15 characters /^\d{1,15}$/
address
required

The person’s address

object
line1
required
string
>= 1 characters <= 100 characters
line2
string
>= 1 characters <= 100 characters
city
required
string
>= 1 characters <= 50 characters
region
required
string
>= 1 characters <= 50 characters
country
string
>= 1 characters <= 50 characters
postalCode
required
string
>= 1 characters <= 15 characters /^[a-z0-9]{1,15}$/
countryCode
required
string
>= 2 characters <= 2 characters /^[A-Z]{2}$/
ipAddress
required
Any of:
string format: ipv4
<= 50 characters
occupation
required

The user’s occupation. Must be a valid SOC code.

string
<= 50 characters
annualSalary
required

The user’s annual salary

string
<= 50 characters
accountPurpose
required

The user’s account purpose

string
<= 50 characters
expectedMonthlyVolume
required

The user’s expected monthly volume

string
<= 50 characters
isTermsOfServiceAccepted
required

Whether the user has accepted the terms of service

boolean
verify
required
object
message
required
string
signature
required
walletAddress
required
string
chainId
required
number

Responses

Section titled “ Responses ”

200

Section titled “200 ”

KYC application submitted successfully

object
status
required
string

400

Section titled “400 ”

Bad request

Any of:
object
code
required
Allowed values: invalid encryption no account bad chain
message
required
string

401

Section titled “401 ”

Invalid Payload

object
code
required
Allowed values: invalid payload
message
string

403

Section titled “403 ”

Forbidden

object
code
required
Allowed values: no permission no organization
message
string

409

Section titled “409 ”

Bad request

Any of:
object
code
required
Allowed values: already started