Users

Create and Retrieve Users

Endpoints to register end users (natural persons) and merchant users (legal entities), with integrated or delegated KYC.

Create End User

POSThttps://api.sandbox.sovera.io/cards/v2/managed/end/users

The creation of a new user for a natural person begins with a POST call in which an endpoint is consumed for sending the user's basic information:

{
  "email": "string",
  "firstName": "string",
  "lastName": "string",
  "alias": "string",
  "occupation": "string",
  "placeOfWork": "string",
  "pep": true,
  "salary": 0,
  "telephone": "string",
  "address": {
    "addressLine1": "string",
    "addressLine2": "string",
    "homeNumber": "string",
    "city": "string",
    "region": "string",
    "postalCode": "string",
    "country": "string"
  },
  "nationality": "string",
  "countryOfOperations": "string"
}
{
  "success": true,
  "data": {
    "id": "string",
    "firstName": "string",
    "lastName": "string",
    "alias": "string",
    "email": "string",
    "telephone": "string",
    "placeOfWork": "string",
    "pep": true,
    "salary": 0,
    "address": {
      "addressLine1": "string",
      "addressLine2": "string",
      "homeNumber": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "country": "string"
    },
    "nationality": "string",
    "countryOfOperations": "string",
    "isActive": false,
    "walletId": "string",
    "kycUrl": "string",
    "creationDate": "2025-01-01T00:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

Validation & Error Handling

Sovera validates the format and presence of key fields, plus the uniqueness of email and telephone within your customer account. Business accuracy (e.g., “is this the person’s real employer?”) remains the client’s responsibility.

  • The API will reject a reused email or telephone with 409 Conflict (see "Error Responses" below).

  • The API will not reject on business accuracy—duplicate names, addresses, or salaries pass.

  • The API will reject when format/validation rules are not met (see "Field Requirements" section below).

If the request passes validation and is processed, the API responds with HTTP 201 Created and returns the created userId, its initial walletId, and control fields such as isActive=false until KYC is completed.

email and telephone must be unique. Each must be unique within your customer account—reusing either returns 409 Conflict. Other fields aren't deduplicated: two users may share a name, address, or salary. If you need broader duplicate control, implement it on your side before calling the API.

Spam Control Identical payloads sent within 5 minutes of each other will result in a 422 error as a measure against erroneous spamming; the payload becomes acceptable again once the window passes.

User Name & Embossing Rules

  1. Sanitized character set: FirstName and LastName must be sent already sanitized to ITU-T50.

  2. 22-char emboss limit: (FirstName + LastName) without spaces must be ≤ 22 after sanitization.

  3. Alias requirement when > 22: If (FirstName + LastName) would exceed 22 after sanitization, you must provide an alias (max 22, ITU-T.50).

    • When a valid alias is provided, it is used for the card name line.

    • When the full name fits (≤ 22), alias is not required and may be ignored for embossing.

  4. No nicknames: alias is strictly for embossing overflow cases; do not use unrelated nicknames as it may impact in-person acceptance.

  5. Real Name Utilization: The fields of FirstName and LastName must match or resemble the real name found on IDs otherwise the KYC verification will fail repeatedly.

Field Requirements

FieldTypeExample ValueRequiredRules
firstNamestring"John"YesNon-null, non-empty, ITU-T.50 only; contributes to 22-char limit (with LastName)
lastNamestring"Smith"YesNon-null, non-empty, ITU-T.50 only; contributes to 22-char limit (with FirstName)
aliasstring"J Smith"Cond.Required only if (FirstName+LastName) > 22 after sanitization; ITU-T.50; max 22
occupationstring"21313" Representing "Computer Systems Designer"YesCode from the provided occupation list (exact match)

Find full list of values in CSV or JSON available upon request
emailstring"[email protected]"YesNon-null, standard email format (RFC-5322-compatible)
telephonestring"+50760001234"YesMust be E.164 (+ + country code + number)
placeOfWorkstring"ACME, Inc."Yes
pepbooleanfalseYestrue if the natural person is politically exposed; else false
salarynumber200000 Representing USD 2,000.00 monthly salaryYesMonthly salary in cents of USD;
address.addressLine1string"123 Main Street"Yes
address.addressLine2string"PH Residential Tower"NoOptional
address.homeNumberstring"12B"NoIf present, must be ISO-3166-1 alpha-2 (e.g., PA, US, BR)
address.citystring"Panama"Yes
address.regionstring"Panama Metropolitan Area"Yes
address.postalCodestring"000000"YesUse correct Postal Code formatting for countries where it applies. Use "000000" as a bypass for countries that do not use a Postal Code. Per country logic can evolve and will be communicated accordingly.
address.countrystring"PA"YesMust be ISO-3166-1 alpha-2 (e.g., PA, US, BR)
nationalitystring"PA"YesMust be ISO-3166-1 alpha-2 (e.g., PA, US, BR)
countryOfOperationsstring"PA, US"YesMust be ISO-3166-1 alpha-2 (e.g., PA, US, BR), if multiple values, separate them by commas in a single string.

Error Responses

The API returns one of the following error shapes depending on the failure.

422 — Field format / validation. The field is present but its value breaks a format or validation rule. The error envelope returns one item per offending field with code: "VALIDATION_ERROR" and a camelCase field. The message varies per field:

{
  "success": false,
  "errors": [
    { "code": "VALIDATION_ERROR", "message": "Invalid format for email", "field": "email" }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}
FieldCodeError title
firstNamespecial_chars (422)Error: special characters present in first name
lastNamespecial_chars (422)Error: special characters present in last name
aliasspecial_chars (422)Error: special characters present in alias

The field Alias is required when First and LastName are above 22 char
occupationnot_allowed_value (422)Error: value not in allowed occupation list
emailinvalid_format (422)Invalid format for email
telephoneinvalid_value (422)Telephone value is incorrect, allowed format: E.164 (+ + country code + number)
salaryinvalid_format (422)Error: salary must be an integer value in cents USD
address.addressLine1min_length (422)Error: AddressLine1 must be at least 5 characters long
address.homeNumberinvalid_value (422)Country value is incorrect
address.regioninvalid_format (422)Error: Region must be non-empty and alphabetic-only
address.countryinvalid_value (422)Country value is incorrect

422 — Missing required field. A required field is absent. Each missing field is returned as its own VALIDATION_ERROR item:

{
  "success": false,
  "errors": [
    { "code": "VALIDATION_ERROR", "message": "The FirstName field is required.", "field": "firstName" }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

409 — Duplicate email or telephone. The value is already registered to another user within your customer account; email and telephone must each be unique. The offending field is returned with code: "CONFLICT":

{
  "success": false,
  "errors": [
    { "code": "CONFLICT", "message": "A user with this email already exists", "field": "email" }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

500 Internal Server Error indicates an internal issue on our side. Please notify the Sovera team with the payload evidence so we can investigate promptly.

PEP definition: a natural person entrusted with prominent public responsibilities who, by virtue of position and influence, may present higher risk of bribery/corruption exposure.

KYC reminder: After IDs are assigned, the end-user must complete KYC to activate the profile. Until then, isActive remains false and all procedures are disabled. See KYC Verification

KYC Verification

In the user creation response (EndUserIntegrated POST), a link to the identity validation associated with the userId in Metamap is presented at the field kycUrl, where the instructions and steps to follow will be presented to the end-user to complete the verification.

{
  "kycUrl": "https%3a%2f%2fsignup.getmati.com%2f%3fmerchantToken%
  3d6046cc2a54816f001bedd641%26flowId%3d6046cc2a54816f0
  01bedd640%26metadata%3d%7b%22userid%22%3a%226955ea0f4
  f3-4254-b10a-0181f307298c%22%7d"
}

It is important to consider that the kycURL is shared by applying URL encoding that allows the sending of metadata (userId) that links the validation with the created user. To ensure the activation of the user upon successfully completing the validation, it is necessary to ensure that the URL to which the user is redirected from the front-end interface loads the following structure:

https://signup.getmati.com/?merchantToken=6046cc2a54816f001dedd641&flowId=6046cc2a54816f001bedd640&metadata=\{"userid":"a955ea0f-34f3-4254-b10a-0181f30729kd"\}

For complete information on KYC, please find detailed information on this documentation's KYC chapter.

Retrieve End User

GEThttps://api.sandbox.sovera.io/cards/v2/managed/end/users/

The GET call for an endUser allows you to know the stored data of a particular userId, especially the walletId of their initial wallet and the activity status of this user in the "isActive" field. Both data are crucial for the other calls to the Sovera API.

This call can be used to verify the user's status at any point in the flow.

 https://api.sandbox.sovera.io/cards/v2/managed/end/users/${USER_ID}
{
  "success": true,
  "data": {
    "id": "string",
    "firstName": "string",
    "lastName": "string",
    "alias": "string",
    "email": "string",
    "telephone": "string",
    "placeOfWork": "string",
    "pep": true,
    "salary": 0,
    "address": {
      "addressLine1": "string",
      "addressLine2": "string",
      "homeNumber": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "country": "string"
    },
    "nationality": "string",
    "countryOfOperations": "string",
    "isActive": false,
    "walletId": "string",
    "kycUrl": "string",
    "creationDate": "2025-01-01T00:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

On success, the API responds with HTTP 200 OK and returns the user's stored data.

Not found. A nonexistent userId returns HTTP 404:

{
  "success": false,
  "errors": [
    { "code": "NOT_FOUND", "message": "User '{userId}' not found" }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

Create Merchant User

POSThttps://api.sandbox.sovera.io/cards/v2/managed/merchant/users

The creation of a new user for a legal entity begins with a POST call in which an endpoint is consumed for sending the basic data of the legal entity.

{
  "email": "string",
  "registeredName": "string",
  "taxId": "string",
  "legalRepresentation": "string",
  "kindOfBusiness": "string",
  "telephone": "string",
  "address": {
    "addressLine1": "string",
    "addressLine2": "string",
    "homeNumber": "string",
    "city": "string",
    "region": "string",
    "postalCode": "string",
    "country": "string"
  },
  "firstName": "string",
  "lastName": "string",
  "nationality": "string",
  "countryOfOperations": "string",
  "certificateOfGoodStanding": "string",
  "businessLicense": "string",
  "registerShareholder": "string",
  "idShareholders": "string",
  "addressVerificationShareholders": "string"
}
{
  "success": true,
  "data": {
    "id": "string",
    "email": "string",
    "registeredName": "string",
    "taxId": "string",
    "legalRepresentation": "string",
    "kindOfBusiness": "string",
    "telephone": "string",
    "address": {
      "addressLine1": "string",
      "addressLine2": "string",
      "homeNumber": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "country": "string"
    },
    "isActive": true,
    "walletId": "string",
    "firstName": "string",
    "lastName": "string",
    "nationality": "string",
    "countryOfOperations": "string",
    "certificateOfGoodStanding": "string",
    "businessLicense": "string",
    "registerShareholder": "string",
    "idShareholders": "string",
    "addressVerificationShareholders": "string",
    "creationDate": "2025-10-13T21:04:11.970Z"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

It should be noted that the responsibility for validating the accuracy of the entered data falls on the Sovera client, meaning that our API will return a successful response as long as the following parameters are met, regardless of the factual accuracy of the information. Note that email and telephone must each be unique within your customer account—reusing either returns 409 Conflict.

Spam Control Identical payloads sent within 5 minutes of each other will result in a 422 error as a measure against erroneous spamming; the payload becomes acceptable again once the window passes.

Field Requirements

FieldTypeRequiredRules
emailstringYesMust follow RFC-5322 format. Non-null, non-empty.
registeredNamestringYesLegal entity’s registered name. Must be sanitized (ITU-T50), ≤ 22 chars, no emojis or symbols.
taxIdstringYesUnique taxpayer identifier (RUC, VATIN, CUIT, CNPJ, NIT, etc.). Alphanumeric + hyphens only.
legalRepresentationstringYesFull name of legal representative. ITU-T.50 characters only, ≤ 60 chars.
kindOfBusinessstringYesDescription or code of economic activity. Must match allowed list.

Find full list of values in CSV or JSON available upon request
telephonestringYesMust follow E.164 format (+ + country code + number).
address.addressLine1stringYesMinimum 5 characters. Descriptive physical address.
address.regionstringYesMust be alphabetic-only, non-empty.
address.countrystringYesISO-3166-1 alpha-2 code (e.g., PA, US, BR).
firstNamestringYesFirst name of owner/representative. ITU-T50 only, part of 22-char limit combined with lastName.
lastNamestringYesLast name of owner/representative. ITU-T50 only, part of 22-char limit combined with firstName.
nationalitystringYesMust be ISO-3166-1 alpha-2 country code.
countryOfOperationsstringYesCountry where entity primarily operates; ISO-3166-1 alpha-2 code.

Multiple codes can be introduced as comma separated values, e.g.: "BR, PA"
certificateOfGoodStandingstring (URL)YesMust be valid URL to official document uploaded for KYB.
businessLicensestring (URL)YesMust be valid URL to active business license document.
registerShareholderstring (URL)YesMust be valid URL to official shareholder register document.
idShareholdersstring (URL)YesMust be valid URL to scanned IDs of shareholders.
addressVerificationShareholdersstring (URL)YesMust be valid URL to proof of address documents for shareholders.

KYB Activation & Additional Field Responsibilities

In addition to the format verifications, it is important to highlight the responsibility of the client to consistently send accurate and verifiable business information for KYB compliance review:

  1. The taxId field must include the official taxpayer identification number of the entity (e.g., RUC, VATIN, CUIT, CNPJ, NIT, or RUT), depending on the jurisdiction.

  2. The legalRepresentation field must contain the full legal name of the person authorized to represent the company, as registered in its incorporation or government record.

  3. The fields firstName and lastName must correspond to the natural person associated with the legal representation or the individual aimed to become the cardholder. These must comply with the same ITU-T.50 sanitization and character restrictions used for natural persons. These will be the names printed in the card, so they must aim to identify the cardholder.

  4. The fields certificateOfGoodStanding, businessLicense, registerShareholder, idShareholders, and addressVerificationShareholders should contain valid URLs or document references for the company’s compliance documentation.

    • Each uploaded document must be instantly accessible for programatic capture, the expected files must be at least 5kb and no more than 10mb in size and either a PDF, JPG or PNG filetype.

    • The document URLs must be valid and publicly accessible for at least 24 hours after the request, so that Sovera's compliance team can retrieve and review the files.

    • Missing or invalid links will result in a validation error and the user creation will fail.

  5. Sovera's compliance team will review the shared information for approval and user activation. Ensuring the information is correctly shared diminishes rejection rates.

Error Responses

The API returns one of the following error shapes depending on the failure.

422 — Field format / validation. The field is present but its value breaks a format or validation rule. The error envelope returns one item per offending field with code: "VALIDATION_ERROR" and a camelCase field. The message varies per field:

{
  "success": false,
  "errors": [
    { "code": "VALIDATION_ERROR", "message": "Error: Tax ID must contain alphanumeric or hyphen characters only", "field": "taxId" }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}
FieldCodeError title
emailinvalid_format (422)Invalid format for email
registeredNamespecial_chars (422)Error: special characters present in registeredName
taxIdinvalid_format (422)Error: Tax ID must contain alphanumeric or hyphen characters only
legalRepresentationspecial_chars (422)Error: special characters present in legalRepresentation
kindOfBusinessnot_allowed_value (422)Error: value not in allowed kindOfBusiness list
telephoneinvalid_value (422)Telephone value is incorrect, allowed format: E.164 (+ + country code + number)
address.addressLine1min_length (422)Error: AddressLine1 must be at least 5 characters long
address.regioninvalid_format (422)Error: Region must be non-empty and alphabetic-only
address.countryinvalid_value (422)Country value is incorrect
firstNamespecial_chars (422)Error: special characters present in firstName
lastNamespecial_chars (422)Error: special characters present in lastName
nationalityinvalid_value (422)Error: nationality must be a valid ISO alpha-2 code
countryOfOperationsinvalid_value (422)Error: countryOfOperations must be a valid ISO alpha-2 code
certificateOfGoodStandinginvalid_format (422)Error: certificateOfGoodStanding must be a valid URL
businessLicenseinvalid_format (422)Error: businessLicense must be a valid URL
registerShareholderinvalid_format (422)Error: registerShareholder must be a valid URL
idShareholdersinvalid_format (422)Error: idShareholders must be a valid URL
addressVerificationShareholdersinvalid_format (422)Error: addressVerificationShareholders must be a valid URL

422 — Missing required field. A required field is absent. Each missing field is returned as its own VALIDATION_ERROR item:

{
  "success": false,
  "errors": [
    { "code": "VALIDATION_ERROR", "message": "The RegisteredName field is required.", "field": "registeredName" }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

409 — Duplicate email or telephone. The value is already registered to another user within your customer account; email and telephone must each be unique. The offending field is returned with code: "CONFLICT":

{
  "success": false,
  "errors": [
    { "code": "CONFLICT", "message": "A user with this email already exists", "field": "email" }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

500 Internal Server Error indicates an internal issue on our side. Please notify the Sovera team with the payload evidence so we can investigate promptly.

Retrieve Merchant User

GEThttps://api.sandbox.sovera.io/cards/v2/managed/merchant/users/

The GET call for a merchantUser allows you to know the stored data of a particular userId, especially the walletId of their initial wallet and the activity status of this user in the "isActive" field. Both data are crucial for the other calls to the Sovera API.

This call can be used to verify the user's status at any point in the flow.

 https://api.sandbox.sovera.io/cards/v2/managed/merchant/users/{MERCHANT_ID}
{
  "success": true,
  "data": {
    "id": "string",
    "email": "string",
    "registeredName": "string",
    "taxId": "string",
    "legalRepresentation": "string",
    "kindOfBusiness": "string",
    "telephone": "string",
    "address": {
      "addressLine1": "string",
      "addressLine2": "string",
      "homeNumber": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "country": "string"
    },
    "isActive": true,
    "walletId": "string",
    "firstName": "string",
    "lastName": "string",
    "nationality": "string",
    "countryOfOperations": "string",
    "certificateOfGoodStanding": "string",
    "businessLicense": "string",
    "registerShareholder": "string",
    "idShareholders": "string",
    "addressVerificationShareholders": "string",
    "creationDate": "2025-10-13T21:04:11.970Z"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

On success, the API responds with HTTP 200 OK and returns the user's stored data.

Not found. A nonexistent userId returns HTTP 404:

{
  "success": false,
  "errors": [
    { "code": "NOT_FOUND", "message": "User '{userId}' not found" }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

Create End User – Delegated KYC

POSThttps://api.sandbox.sovera.io/cards/v2/delegated/end/users

The creation of a new user with Delegated KYC type for a natural person begins with a POST call in which an endpoint is consumed for sending the user's basic information, in the case of EndUserDelegated, users are created active by default. This endpoint is not openly available, it must have been enabled by Sovera's compliance team during the integration process

{
  "email": "string",
  "firstName": "string",
  "lastName": "string",
  "alias": "string",
  "occupation": "string",
  "placeOfWork": "string",
  "pep": true,
  "salary": 0,
  "telephone": "string",
  "address": {
    "addressLine1": "string",
    "addressLine2": "string",
    "homeNumber": "string",
    "city": "string",
    "region": "string",
    "postalCode": "string",
    "country": "string"
  },
  "nationality": "string",
  "countryOfOperations": "string",
  "idUrlFront": "string",
  "idUrlBack": "string",
  "residenceProofUrl": "string"
}
{
  "success": true,
  "data": {
    "id": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "telephone": "string",
    "placeOfWork": "string",
    "pep": true,
    "salary": 0,
    "address": {
      "addressLine1": "string",
      "addressLine2": "string",
      "homeNumber": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "country": "string"
    },
    "isActive": true,
    "walletId": "string",
    "idUrlFront": "string",
    "idUrlBack": "string",
    "residenceProofUrl": "string",
    "alias": "string",
    "occupation": "string",
    "nationality": "string",
    "countryOfOperations": "string",
    "creationDate": "2025-10-14T19:24:26.919Z"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

Validation & Error Handling

Sovera validates the format and presence of key fields, plus the uniqueness of email and telephone within your customer account. Business accuracy (e.g., “is this the person’s real employer?”) remains the client’s responsibility.

  • The API will reject a reused email or telephone with 409 Conflict (see "Error Responses" below).

  • The API will not reject on business accuracy—duplicate names, addresses, or salaries pass.

  • The API will reject when format/validation rules are not met (see "Field Requirements" section below).

If the request passes validation and is processed, the API responds with HTTP 201 Created and returns the created userId, its initial walletId, and control fields such as isActive=true for this type of user with Delegated KYC flow.

email and telephone must be unique. Each must be unique within your customer account—reusing either returns 409 Conflict. Other fields aren't deduplicated: two users may share a name, address, or salary. If you need broader duplicate control, implement it on your side before calling the API.

Spam Control Identical payloads sent within 5 minutes of each other will result in a 422 error as a measure against erroneous spamming; the payload becomes acceptable again once the window passes.

User Name & Embossing Rules

  1. Sanitized character set: FirstName and LastName must be sent already sanitized to ITU-T.50.

  2. 22-char emboss limit: (FirstName + LastName) without spaces must be ≤ 22 after sanitization.

  3. Alias requirement when > 22: If (FirstName + LastName) would exceed 22 after sanitization, you must provide an alias (max 22, ITU-T.50).

    • When a valid alias is provided, it is used for the card name line.

    • When the full name fits (≤ 22), alias is not required and may be ignored for embossing.

  4. No nicknames: alias is strictly for embossing overflow cases; do not use unrelated nicknames as it may impact in-person acceptance.

  5. Real Name Utilization: The fields of FirstName and LastName must match or resemble the real name found on IDs to ensure future compliance checks don't flag users for misuse.

Field Requirements

FieldTypeExample ValueRequiredRules
firstNamestring"John"YesNon-null, non-empty, ITU-T.50 only; contributes to 22-char limit (with LastName)
lastNamestring"Smith"YesNon-null, non-empty, ITU-T.50 only; contributes to 22-char limit (with FirstName)
aliasstring"J Smith"Cond.Required only if (FirstName+LastName) > 22 after sanitization; ITU-T.50; max 22
occupationstring"21313" Representing "Computer Systems Designer"YesCode from the provided occupation list (exact match)

Find full list of values in CSV or JSON available upon request
emailstring"[email protected]"YesNon-null, standard email format (RFC-5322-compatible)
telephonestring"+50760001234"YesMust be E.164 (+ + country code + number)
placeOfWorkstring"ACME, Inc."Yes
pepbooleanfalseYestrue if the natural person is politically exposed; else false
salarynumber200000 Representing USD 2,000.00 monthly salaryYesMonthly salary in cents of USD;
address.addressLine1string"123 Main Street"Yes
address.addressLine2string"PH Residential Tower"NoOptional
address.homeNumberstring"12B"NoIf present, must be ISO-3166-1 alpha-2 (e.g., PA, US, BR)
address.citystring"Panama"Yes
address.regionstring"Panama Metropolitan Area"Yes
address.postalCodestring"000000"YesUse correct Postal Code formatting for countries where it applies. Use "000000" as a bypass for countries that do not use a Postal Code. Per country logic can evolve and will be communicated accordingly.
address.countrystring"PA"YesMust be ISO-3166-1 alpha-2 (e.g., PA, US, BR)
nationalitystring"PA"YesMust be ISO-3166-1 alpha-2 (e.g., PA, US, BR)
countryOfOperationsstring"PA, US"YesMust be ISO-3166-1 alpha-2 (e.g., PA, US, BR), if multiple values, separate them by commas in a single string.
idUrlFrontstring"https://cdn.prod.server-files.com/directory/user\_idFile.jpg"YesURL must direct to a real, reachable file, either PDF,JPGor PNG with between 5kb and 10mb size. It's expected that this file will contain the correct accepted document types.

Sovera's team reserves the right to regularly block users that present misuse of these fields
idUrlBackstring"https://cdn.prod.server-files.com/directory/user\_idFileBack.jpg"YesURL must direct to a real, reachable file, either PDF,JPGor PNG with between 5kb and 10mb size. It's expected that this file will contain the correct accepted document types.

Sovera's team reserves the right to regularly block users that present misuse of these fields
residenceProofstring"https://cdn.prod.server-files.com/directory/residenceProof.jpg"YesURL must direct to a real, reachable file, either PDF,JPGor PNG with between 5kb and 10mb size. It's expected that this file will contain the correct accepted document types.

Sovera's team reserves the right to regularly block users that present misuse of these fields

Error Responses

The API returns one of the following error shapes depending on the failure.

422 — Field format / validation. The field is present but its value breaks a format or validation rule. The error envelope returns one item per offending field with code: "VALIDATION_ERROR" and a camelCase field. The message varies per field. Unreachable, invalid, or unsupported document URLs (idUrlFront, idUrlBack, residenceProofUrl) are rejected with this same shape.

{
  "success": false,
  "errors": [
    { "code": "VALIDATION_ERROR", "message": "The value provided for the IdUrlFront presents some issues in the process of validation", "field": "idUrlFront" }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}
FieldCodeError title
firstNamespecial_chars (422)Error: special characters present in first name
lastNamespecial_chars (422)Error: special characters present in last name
aliasspecial_chars (422)Error: special characters present in alias

The field Alias is required when First and LastName are above 22 char
occupationnot_allowed_value (422)Error: value not in allowed occupation list
emailinvalid_format (422)Invalid format for email
telephoneinvalid_value (422)Telephone value is incorrect, allowed format: E.164 (+ + country code + number)
salaryinvalid_format (422)Error: salary must be an integer value in cents USD
address.addressLine1min_length (422)Error: AddressLine1 must be at least 5 characters long
address.homeNumberinvalid_value (422)Country value is incorrect
address.regioninvalid_format (422)Error: Region must be non-empty and alphabetic-only
address.countryinvalid_value (422)Country value is incorrect
idUrlFrontinvalid_value (422)The value provided for the IdUrlFront presents some issues in the process of validation
idUrlBackinvalid_value (422)The value provided for the IdUrlBack presents some issues in the process of validation
residenceProofinvalid_value (422)The value provided for the residenceProof presents some issues in the process of validation

422 — Missing required field. A required field is absent. Each missing field is returned as its own VALIDATION_ERROR item:

{
  "success": false,
  "errors": [
    { "code": "VALIDATION_ERROR", "message": "The FirstName field is required.", "field": "firstName" }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

409 — Duplicate email or telephone. The value is already registered to another user within your customer account; email and telephone must each be unique. The offending field is returned with code: "CONFLICT":

{
  "success": false,
  "errors": [
    { "code": "CONFLICT", "message": "A user with this email already exists", "field": "email" }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

500 Internal Server Error indicates an internal issue on our side. Please notify the Sovera team with the payload evidence so we can investigate promptly.

PEP definition: a natural person entrusted with prominent public responsibilities who, by virtue of position and influence, may present higher risk of bribery/corruption exposure.

Delegated KYC: Users of the EndUserDelegated type are used exclusively by clients who've been assigned said privilege. These users are create with their activity status as "Active" and do not require a KYC verification link.

Delegated KYC – Document URLs

For EndUserDelegated, there is no kycUrl for post-creation KYC verification. Instead, you must provide within the creation request the following documents:

{
  "idUrlFront": "https://... (front of ID)",
  "idUrlBack": "https://... (back of ID)",
  "residenceProofUrl": "https://... (proof of residence)"
}

  • URLs must be HTTPS and publicly reachable by Sovera’s backend (accessible for at least 24hs, no IP-locked links).

  • Content must be an image (image/*) or application/pdf.

  • Ensure links remain valid for at least 24 hours.

  • If any URL is invalid, unreachable, or file type is unsupported, the request will be rejected with 422.

Activation: EndUserDelegated users are created isActive=true immediately upon success. Downstream actions remain subject to standard compliance checks and ongoing monitoring.

Retrieve End User – Delegated KYC

GEThttps://api.sandbox.sovera.io/cards/v2/delegated/end/users/

The GET call for an EndUserDelegated allows you to know the stored data of a particular userId, especially the walletId of their initial wallet and the activity status of this user in the "isActive" field. Both data are crucial for the other calls to the Sovera API.

 https://api.sandbox.sovera.io/cards/v2/delegated/end/users/{USER_ID}
{
  "success": true,
  "data": {
    "id": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "telephone": "string",
    "placeOfWork": "string",
    "pep": true,
    "salary": 0,
    "address": {
      "addressLine1": "string",
      "addressLine2": "string",
      "homeNumber": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "country": "string"
    },
    "isActive": true,
    "walletId": "string",
    "idUrlFront": "string",
    "idUrlBack": "string",
    "residenceProofUrl": "string",
    "alias": "string",
    "occupation": "string",
    "nationality": "string",
    "countryOfOperations": "string",
    "creationDate": "2025-10-14T19:24:26.919Z"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

On success, the API responds with HTTP 200 OK and returns the user's stored data.

Not found. A nonexistent userId returns HTTP 404:

{
  "success": false,
  "errors": [
    { "code": "NOT_FOUND", "message": "User '{userId}' not found" }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

Create Merchant User – Delegated KYC

POSThttps://api.sandbox.sovera.io/cards/v2/delegated/merchant/users

The creation of a new user for a legal entity with Delegated KYB begins with a POST call in which an endpoint is consumed for sending the basic data of the legal entity, in the case of MerchantUserDelegated, users are created active by default. This endpoint is not openly available, it must have been enabled by Sovera's compliance team during the integration process

{
  "email": "string",
  "registeredName": "string",
  "taxId": "string",
  "legalRepresentation": "string",
  "kindOfBusiness": "string",
  "telephone": "string",
  "address": {
    "addressLine1": "string",
    "addressLine2": "string",
    "homeNumber": "string",
    "city": "string",
    "region": "string",
    "postalCode": "string",
    "country": "string"
  },
  "firstName": "string",
  "lastName": "string",
  "nationality": "string",
  "countryOfOperations": "string",
  "certificateOfGoodStanding": "string",
  "businessLicense": "string",
  "registerShareholder": "string",
  "idShareholders": "string",
  "addressVerificationShareholders": "string"
}
{
  "success": true,
  "data": {
    "id": "string",
    "email": "string",
    "registeredName": "string",
    "taxId": "string",
    "legalRepresentation": "string",
    "kindOfBusiness": "string",
    "telephone": "string",
    "address": {
      "addressLine1": "string",
      "addressLine2": "string",
      "homeNumber": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "country": "string"
    },
    "isActive": true,
    "walletId": "string",
    "firstName": "string",
    "lastName": "string",
    "nationality": "string",
    "countryOfOperations": "string",
    "certificateOfGoodStanding": "string",
    "businessLicense": "string",
    "registerShareholder": "string",
    "idShareholders": "string",
    "addressVerificationShareholders": "string",
    "creationDate": "2025-10-13T21:04:11.970Z"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

It should be noted that the responsibility for validating the accuracy of the entered data falls on the Sovera client, meaning that our API will return a successful response as long as the following parameters are met, regardless of the factual accuracy of the information. Note that email and telephone must each be unique within your customer account—reusing either returns 409 Conflict.

Spam Control Identical payloads sent within 5 minutes of each other will result in a 422 error as a measure against erroneous spamming; the payload becomes acceptable again once the window passes.

Field Requirements

FieldTypeRequiredRules
emailstringYesMust follow RFC-5322 format. Non-null, non-empty.
registeredNamestringYesLegal entity’s registered name. Must be sanitized (ITU-T.50), ≤ 22 chars, no emojis or symbols.
taxIdstringYesUnique taxpayer identifier (RUC, VATIN, CUIT, CNPJ, NIT, etc.). Alphanumeric + hyphens only.
legalRepresentationstringYesFull name of legal representative. ITU-T.50 characters only, ≤ 60 chars.
kindOfBusinessstringYesDescription or code of economic activity. Must match allowed list.

Find full list of values in CSV or JSON available upon request
telephonestringYesMust follow E.164 format (+ + country code + number).
address.addressLine1stringYesMinimum 5 characters. Descriptive physical address.
address.regionstringYesMust be alphabetic-only, non-empty.
address.countrystringYesISO-3166-1 alpha-2 code (e.g., PA, US, BR).
firstNamestringYesFirst name of owner/representative. ITU-T.50 only, part of 22-char limit combined with lastName.
lastNamestringYesLast name of owner/representative. ITU-T.50 only, part of 22-char limit combined with firstName.
nationalitystringYesMust be ISO-3166-1 alpha-2 country code.
countryOfOperationsstringYesCountry where entity primarily operates; ISO-3166-1 alpha-2 code.

Multiple codes can be introduced as comma separated values, e.g.: "BR, PA"
certificateOfGoodStandingstring (URL)YesMust be valid URL to official document uploaded for KYB.
businessLicensestring (URL)YesMust be valid URL to active business license document.
registerShareholderstring (URL)YesMust be valid URL to official shareholder register document.
idShareholdersstring (URL)YesMust be valid URL to scanned IDs of shareholders.
addressVerificationShareholdersstring (URL)YesMust be valid URL to proof of address documents for shareholders.

Additional Field Responsibilities

In addition to the format verifications, it is important to highlight the responsibility of the client to consistently send accurate and verifiable business information for KYB compliance review:

  1. The taxId field must include the official taxpayer identification number of the entity (e.g., RUC, VATIN, CUIT, CNPJ, NIT, or RUT), depending on the jurisdiction.

  2. The legalRepresentation field must contain the full legal name of the person authorized to represent the company, as registered in its incorporation or government record.

  3. The fields firstName and lastName must correspond to the natural person associated with the legal representation or the individual aimed to become the cardholder. These must comply with the same ITU-T.50 sanitization and character restrictions used for natural persons. These will be the names printed in the card, so they must aim to identify the cardholder.

  4. The fields certificateOfGoodStanding, businessLicense, registerShareholder, idShareholders, and addressVerificationShareholders should contain valid URLs or document references for the company’s compliance documentation.

    • Each uploaded document must be instantly accessible for programatic capture, the expected files must be at least 5kb and no more than 10mb in size and either a PDF, JPG or PNG filetype.

    • The document URLs must be valid and publicly accessible for at least 24 hours after the request, so that Sovera's compliance team can retrieve and review the files.

    • Missing or invalid links will result in a validation error and the user creation will fail.

  5. Sovera's compliance team will review the shared information for approval and user activation. Ensuring the information is correctly shared diminishes rejection rates.

Error Responses

The API returns one of the following error shapes depending on the failure.

422 — Field format / validation. The field is present but its value breaks a format or validation rule. The error envelope returns one item per offending field with code: "VALIDATION_ERROR" and a camelCase field. The message varies per field:

{
  "success": false,
  "errors": [
    { "code": "VALIDATION_ERROR", "message": "Error: certificateOfGoodStanding must be a valid URL", "field": "certificateOfGoodStanding" }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}
FieldCodeError title
emailinvalid_format (422)Invalid format for email
registeredNamespecial_chars (422)Error: special characters present in registeredName
taxIdinvalid_format (422)Error: Tax ID must contain alphanumeric or hyphen characters only
legalRepresentationspecial_chars (422)Error: special characters present in legalRepresentation
kindOfBusinessnot_allowed_value (422)Error: value not in allowed kindOfBusiness list
telephoneinvalid_value (422)Telephone value is incorrect, allowed format: E.164 (+ + country code + number)
address.addressLine1min_length (422)Error: AddressLine1 must be at least 5 characters long
address.regioninvalid_format (422)Error: Region must be non-empty and alphabetic-only
address.countryinvalid_value (422)Country value is incorrect
firstNamespecial_chars (422)Error: special characters present in firstName
lastNamespecial_chars (422)Error: special characters present in lastName
nationalityinvalid_value (422)Error: nationality must be a valid ISO alpha-2 code
countryOfOperationsinvalid_value (422)Error: countryOfOperations must be a valid ISO alpha-2 code
certificateOfGoodStandinginvalid_format (422)Error: certificateOfGoodStanding must be a valid URL
businessLicenseinvalid_format (422)Error: businessLicense must be a valid URL
registerShareholderinvalid_format (422)Error: registerShareholder must be a valid URL
idShareholdersinvalid_format (422)Error: idShareholders must be a valid URL
addressVerificationShareholdersinvalid_format (422)Error: addressVerificationShareholders must be a valid URL

422 — Missing required field. A required field is absent. Each missing field is returned as its own VALIDATION_ERROR item:

{
  "success": false,
  "errors": [
    { "code": "VALIDATION_ERROR", "message": "The RegisteredName field is required.", "field": "registeredName" }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

409 — Duplicate email or telephone. The value is already registered to another user within your customer account; email and telephone must each be unique. The offending field is returned with code: "CONFLICT":

{
  "success": false,
  "errors": [
    { "code": "CONFLICT", "message": "A user with this email already exists", "field": "email" }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

500 Internal Server Error indicates an internal issue on our side. Please notify the Sovera team with the payload evidence so we can investigate promptly.

Retrieve Merchant User – Delegated KYC

GEThttps://api.sandbox.sovera.io/cards/v2/delegated/merchant/users/

The GET call for a merchantUser allows you to know the stored data of a particular userId, especially the walletId of their initial wallet and the activity status of this user in the "isActive" field. Both data are crucial for the other calls to the Sovera API.

This call can be used to verify the user's status at any point in the flow.

 https://api.sandbox.sovera.io/cards/v2/delegated/merchant/users/{MERCHANT_ID}
{
  "success": true,
  "data": {
    "id": "string",
    "email": "string",
    "registeredName": "string",
    "taxId": "string",
    "legalRepresentation": "string",
    "kindOfBusiness": "string",
    "telephone": "string",
    "address": {
      "addressLine1": "string",
      "addressLine2": "string",
      "homeNumber": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "country": "string"
    },
    "isActive": true,
    "walletId": "string",
    "firstName": "string",
    "lastName": "string",
    "nationality": "string",
    "countryOfOperations": "string",
    "certificateOfGoodStanding": "string",
    "businessLicense": "string",
    "registerShareholder": "string",
    "idShareholders": "string",
    "addressVerificationShareholders": "string",
    "creationDate": "2025-10-13T21:04:11.970Z"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

On success, the API responds with HTTP 200 OK and returns the user's stored data.

Not found. A nonexistent userId returns HTTP 404:

{
  "success": false,
  "errors": [
    { "code": "NOT_FOUND", "message": "User '{userId}' not found" }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

Credit Operations Flow

Issue credit lines, track usage, accrue interest and reconcile payments.

Update and Block User

Modify a previously created user's profile fields — name, contact, address, business info.

On this page

Create End UserValidation & Error HandlingUser Name & Embossing RulesField RequirementsError ResponsesKYC VerificationRetrieve End UserCreate Merchant UserField RequirementsKYB Activation & Additional Field ResponsibilitiesError ResponsesRetrieve Merchant UserCreate End User – Delegated KYCValidation & Error HandlingUser Name & Embossing RulesField RequirementsError ResponsesDelegated KYC – Document URLsRetrieve End User – Delegated KYCCreate Merchant User – Delegated KYCField RequirementsAdditional Field ResponsibilitiesError ResponsesRetrieve Merchant User – Delegated KYC