Customer

General Information

KYC is a mandatory regulatory process to identify and validate customer identity, ensure compliance, and assess potential risks.

The KYC process requires:

Registration Data Submission: Submit accurate and up-to-date registration data to Fiserv.
KYC Approval: Customers must be approved before accessing Fiserv's PIX PSP services.

KYC has different approval or rejection criteria depending on the environment. Therefore, it is necessary to send the approved CNPJ(s) to the Fiserv team to facilitate development. After the client registration a KYC validation will happen asynchronously, and the result will be notified to the configured webhook.

POST /v1/client

Add a client.

Request Fields

Name	Located in	Description	Mandatory	Type
apikey	header	API Key	yes	string
x-timestamp	header	Date/time of the request (used to prevent replay attacks)	yes	string
x-request-id	header	Random ID used to identify the request	yes	string
x-hmac-signature	header	HMAC signature generated by combining the request parameters: Example: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL)`	yes	string
Authorization	header	Bearer token used for authentication	yes	string (bearerToken)
address.city	body	Client's city (ISO 3166)	yes	string
address.country	body	Client's country (ISO 3166)	yes	string
address.locality	body	Client's district (ISO 3166)	yes	string
address.number	body	Client's address number	no	string
address.postalCode	body	Client's ZIP Code address	yes	string
address.province	body	Client's address State	yes	string
address.street	body	Client's address Street	yes	string
address.subNumber	body	Client's address Complement	no	string
document.number	body	Document Number	yes	string
document.type	body	CNPJ	yes	enum
contact.email	body	Client's E-mail	yes	string
contact.phone	body	Client's Phone number	yes	string
legalName	body	Client's legal name	yes	string
tradeName	body	Client's trade name	yes	string
averageTicket	body	Average ticket	yes	decimal

Request Example

{
  "address": {
    "city": "São Paulo",
    "country": "BR",
    "locality": "Vila Mariana",
    "number": "153",
    "postalCode": "04101-300",
    "province": "SP",
    "street": "Rua Vergueiro",
    "subNumber": "Suite 42"
  },
  "document": {
    "number": "60.664.745/0001-87",
    "type": "CNPJ"
  },
  "contact": {
    "email": "[email protected]",
    "phone": "+55 11 91234-5678"
  },
  "legalName": "Fiserv Inc",
  "tradeName": "Fiserv",
  "averageTicket": 100.00
}

Response Fields

Name	Description	Type
clientId	Customer's unique ID	string
protocolId	Async processing identifier (UUID) for the KYC validation. Use it to track the KYC progress via polling or webhook.	string

Response Example

{
  "clientId": "bb41c1e6-654f-4263-83f4-36e37678f548",
  "protocolId": "Request protocol"
}

GET /v1/client/{clientId}

Search for information about the customer's "Know Your Customer" status.

Request Fields

Name	Located in	Description	Mandatory	Type
apikey	header	API Key	yes	string
x-timestamp	header	Date/time of the request (used to prevent replay attacks)	yes	string
x-request-id	header	Random ID used to identify the request	yes	string
x-hmac-signature	header	HMAC signature generated by combining the request parameters: Example: `HMAC-SHA256( apikey + x-timestamp + requestBody + URL)`	yes	string
Authorization	header	Bearer token for authentication	yes	string (bearerToken)
clientId	path	client id	yes	string

Response Fields

Name	Description	Type
kycStatus	Customer's KYC status	string
kycReasonDisapproval	Reason for KYC disapproval	string

Response Example (Approved)

{
  "kycStatus": "Approved"
}

Response Example (Refused)

{
  "kycStatus": "Refused",
  "kycReasonDisapproval": "Falha de processamento"
}

Additional Information

KycStatus Values

Value	Description
APPROVED	KYC validation completed successfully; customer is eligible to continue accreditation and open a PIX Account.
PENDING	Customer registration was received, but KYC checks have not started yet.
PROCESSING	KYC validation is currently in progress with compliance and risk checks still running.
REFUSED	KYC validation was concluded with disapproval; customer is not eligible until identified issues are resolved.
ERROR	KYC processing failed due to a technical or integration issue and should be retried or reviewed.
NOT_FOUND	KYC status is not yet available; wait and poll again. If the status persists, retry or contact support.

Kyc Reason Disapproval Values

Value
Falha de processamento
Reprovado por política interna Fiserv
Reprovado por razões cadastrais