# Pix Key Validation and Details Endpoint

## Account Validation Request

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark>  | string | `application/json`                                       |
| X-Date<mark style="color:red;">\*</mark>        | string | ISO8601 Datetime with Timezone: `yyyy-MM-dd'T'HH:mm:ssZ` |
| X-Login<mark style="color:red;">\*</mark>       | string | Merchant X-Login Cashouts API Key                        |
| Authorization<mark style="color:red;">\*</mark> | string | Authorization control hash                               |

#### Request Body

| Name                                                | Type   | Description                                                                      |
| --------------------------------------------------- | ------ | -------------------------------------------------------------------------------- |
| key\_type<mark style="color:red;">\*</mark>         | String | Type of the PIX, this can be either `DOCUMENT`, `EMAIL` , `PHONE` or `RANDOM_ID` |
| document<mark style="color:red;">\*</mark>          | String | CPF of the customer.                                                             |
| pix\_key<mark style="color:red;">\*</mark>          | String | Contains the value of the PIX key that you want to get the details for.          |
| notification\_url<mark style="color:red;">\*</mark> | String | API URL utilized to receive the banking information from your side.              |

**Example Request**

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

**Response**

{% tabs %}
{% tab title="200 Response" %}

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

{% endtab %}

{% tab title="400 Response" %}

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

{% endtab %}
{% endtabs %}

\
**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:

```json
{
"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
}
```

{% hint style="info" %}
In this case, the PIX KEY DOCUMENT "29318456719" would be tied to the banking details in the response.
{% endhint %}

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

```json
{
    "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.                                              |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.onekeypayments.com/api-documentation/bank-account-validation/endpoints/bank-account-validation-endpoint/pix-key-validation-and-details-endpoint.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.