Pix Key Validation and Details Endpoint

Validate PIX Keys in real time, with their full banking details.

Account Validation Request

POST https://api-stg.onekeypayments.com/v5/account/pix_key/validate/details

This endpoint allows you to validate if a Pix Key exists, and what banking details are tied to this PIX key

Check with your Account Manager or Technical Account Manager regarding the production API endpoint.

Headers

Name	Type	Description
Content-Type*	string	application/json
X-Date*	string	ISO8601 Datetime with Timezone: yyyy-MM-dd'T'HH:mm:ssZ
X-Login*	string	Merchant X-Login Cashouts API Key
Authorization*	string	Authorization control hash

Request Body

Name	Type	Description
key_type*	String	Type of the PIX, this can be either DOCUMENT, EMAIL , PHONE or RANDOM_ID
document*	String	CPF of the customer.
pix_key*	String	Contains the value of the PIX key that you want to get the details for.
notification_url*	String	API URL utilized to receive the banking information from your side.

Example Request

{
"key_type": "DOCUMENT",
"document": "29318456719",
"pix_key": "29318456719",
"notification_url": "https://test.com"
}

Response

200 Response

{
"document": "29318456719",
"pix_key": "29318456719",
"message": "The Pix validation is in progress",
"status": "IN_PROGRESS"
}

400 Response

{
"document" : "29318456719",
"pix_key" : "29318456719",
"status" : "ERROR",
"message" : "The Pix key is not valid."
}

Callback After obtaining the HTTP 200 response, we'll send a callback to your previously designated notification_url, this will include all the following banking information, tied to the Pix key:

{
"key_type": "DOCUMENT",
"pix_key": "29318456719",
"bank_account": 1234567,
"bank_branch": 0199,
"bank_code": 33,
"ispb_code": 90400888,
"account_type": "SAVINGS",
"is_licensed": true | false
}

In this case, the PIX KEY DOCUMENT "29318456719" would be tied to the banking details in the response.

Error callback This happens for example when the account CPF does not match the one sent

{
    "document": "96247806175",
    "pix_key": "96247806175",
    "message": "An error ocurred during the validation",
    "status": "ERROR"
}

API Messages

status	Message	Description
IN_PROGRESS	The Pix validation is in progress	The PIX Key exists and we are validating the bank account details
ERROR	The Pix key does not belong to the document	The account associated to PIX Key sent does not belong to the document sent in the request.
ERROR	The document is not a CPF	The CPF provided is invalid.
ERROR	The Pix Key is invalid	The PIX Key does not exist or it’s greylisted.