Request PIX Key Verification (OTP)

POST https://api.somossimpay.com.br/v3/key/verifications/send

Requests the sending of an OTP (One-Time Password) code via email or SMS to validate ownership of a PIX key of type EMAIL or CELL_PHONE before registering it in the DICT (Brazilian PIX Key Directory).

Headers

Parameter	Type	Description	Example
Authorization	String	Bearer + Access_token	Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo
hmac	String	HMAC (Hash-based Message Authentication Code) is an authentication algorithm that combines a private key with a message to create a Message Authentication Code (MAC). This header is required only for API audience.	hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b99f4081ff231b87f82118c1e77a959e1f40eacf690a8fa61a827a9ba01d546f6

Body Details

Body JSON (Raw)

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "123456",
  "key_type": "EMAIL",
  "key_value": "[email protected]",
  "purpose": "PIX_KEY_INCLUSION"
}

Field	Type	Description	Required or Optional
source_account_branch_identifier	String	Source account branch (agency) identifier.	required
source_account_number	String	Source account number.	required
key_type	String	PIX key type. Accepts only: EMAIL or CELL_PHONE.	required
key_value	String	PIX key value to be verified. Full email address or phone number in international format (e.g., [phone]).	required
purpose	String	Verification purpose. Default: PIX_KEY_INCLUSION.	optional

Request Examples

Request EMAIL key verification:

HTTP

POST /v3/key/verifications/send
Authorization: Bearer <access_token>
hmac: <computed_hmac>
Content-Type: application/json

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "123456",
  "key_type": "EMAIL",
  "key_value": "[email protected]",
  "purpose": "PIX_KEY_INCLUSION"
}

Request CELL_PHONE key verification:

HTTP

POST /v3/key/verifications/send
Authorization: Bearer <access_token>
hmac: <computed_hmac>
Content-Type: application/json

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "654321",
  "key_type": "CELL_PHONE",
  "key_value": "[phone]",
  "purpose": "PIX_KEY_INCLUSION"
}

Response Details

Response

{
  "worked": true,
  "verification_request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "message": "Verification request created. Use this ID and the code you received when calling the include PIX key endpoint.",
  "expires_at": "2026-05-07T14:35:00Z"
}

Field	Type	Description
worked	Boolean	Always true for successful requests.
verification_request_id	String	Unique verification request ID. Must be sent along with the OTP code in the include PIX key request.
message	String	Informative message about the next step in the flow.
expires_at	DateTime	Expiration date and time (UTC) of the OTP code. After this moment, a new code must be requested.

Error Responses

HTTP Code	Error Message	Description
400	HMAC header required for API audience	The hmac header is required when the request is made with API audience.
400	Authentication failed	The authentication token could not be validated.
400	Account not found	The account identified by branch and number does not exist, is inactive, or the user does not have permission to access it.
400	Account is closed	The account is closed and cannot be used for PIX key verification.
400	key_type must be EMAIL or CELL_PHONE for this endpoint	This endpoint only accepts EMAIL or CELL_PHONE key types. For other types (CPF, CNPJ, EVP), use the include PIX key endpoint directly.
401	Unauthorized	Invalid or missing authentication token. Ensure you are sending a valid Bearer token and HMAC signature (when applicable).
409	An active verification code already exists for this key. Use the code you received or wait for it to expire before requesting another. X minutes remaining...	A still-valid verification code was recently sent for this key. Wait for expiration or use the code already received.
422	Validation error	Request validation failed. Check that all required fields are present and in the correct format.

Business Rules

OTP Verification Flow:

• The OTP code is sent by email (when key_type is EMAIL) or by SMS (when key_type is CELL_PHONE).
• The code consists of 6 numeric digits.
• The code expires after 3 minutes (configurable via environment variable).
• The verification_request_id returned in this response must be sent along with the OTP code in the token field of the include PIX key request.
• It is not possible to request a new code while there is a valid, unexpired code for the same key and account.

Validations:

• key_type must be either EMAIL or CELL_PHONE.
• key_value must be a valid email or phone number in international format.
• The account identified by source_account_branch_identifier and source_account_number must exist, be active, and be accessible by the authenticated user.
• The authenticated user must have PIX key creation permission for the specified account.

Authentication:

• API Audience: The hmac header is required and must sign the raw JSON body of the request using your secret key.
• Web Audience: The access token (Bearer token) is sufficient.

Notes:

• This endpoint is the required first step to register EMAIL or CELL_PHONE PIX keys.
• After receiving the OTP code, use the POST /v3/key endpoint sending the verification_request_id and the code in the token field to complete the key registration.
• For CPF, CNPJ, or EVP key types, it is not necessary to call this endpoint — go directly to the include PIX key endpoint.