# Introdução Esta página contém uma breve introdução sobre o conteúdo da API 4P Finance. ### API 4P Finance A API da 4P Finance disponibiliza nossos serviços no contexto de tecnologia Blockchain e Web3, permitindo que empresas integrem facilmente funcionalidades de on-ramp e off-ramp via Pix em suas aplicações. Com a nossa API, é possível: * Criar transações para receber pagamentos via Pix; * Realizar automaticamente a conversão (swap) do valor pago para criptomoedas; * Enviar os fundos diretamente para uma carteira informada na requisição, em stablecoins, eliminando a exposição à volatilidade; * Executar operações de off-ramp, convertendo cripto em Pix de forma automática; * Receber notificações via webhook com a confirmação e conclusão das transações na blockchain. **Tudo isso sem a necessidade de lidar com smart contracts ou linguagem Solidity.** Os serviços da API 4P Finance permitem que sua empresa integre facilmente sua plataforma web, website, aplicativo ou sistema aos nossos serviços de pagamento digital, oferecendo uma experiência rápida, segura e totalmente automatizada para seus usuários. ### Sobre a 4P Finance A 4P Finance é um Provedor de Serviços de Pagamento (PSP) para operações em blockchain e Web3. Com nossas soluções, sua empresa pode: * Receber pagamentos em criptomoedas e stablecoins; * Emitir cobranças para seus clientes através de links de pagamento; * Integrar-se via API com checkout transparente; * Oferecer criptomoedas como método de pagamento dentro da sua aplicação, site ou sistema; * Automatizar todo o processo de conversão, liquidação e envio de fundos entre Pix e blockchain. Nossa infraestrutura foi projetada para abstrair a complexidade técnica da blockchain, permitindo que você foque no seu produto enquanto a 4P Finance cuida de toda a camada de pagamentos e liquidação cripto. # Credenciais Informações sobre credenciais e autorização da API 4P Finance. Para integrar a API **4P Finance** ao seu sistema ou sua plataforma, é necessário ter uma conta digital **4P Finance**. Não tem conta? [Clique aqui para criar sua conta](https://app.4p.finance/new-account) Uma vez com acesso, você poderá obter Api Key necessária para a comunicação com a API **4P Finance**. Veja a seguir como obter as credenciais. ### Obtendo sua credencial Após criar sua conta, [efetue login](https://app.4p.finance/login) na plataforma para registrar sua aplicação e gerar sua Api Key. Após efetuar login na plataforma siga os seguintes passos: 1. No menu, na sessão API, clique em **Criar integração**. 2. No formulário que aparece digite o nome da sua aplicação e o host/domínio da mesma. 3. Após preencher clique em **Cadastrar aplicação**. 4. Na tela seguinte, copie a sua API KEY para que seja utilizada na integração da sua aplicação. {% hint style="warning" %} [**Antes de iniciar sua integração, é necessário entrar em contato com o nosso suporte para solicitar a liberação da sua API Key.**](https://4p.finance/whatsapp-redirect) {% endhint %} Para isso: 1. [Clique aqui e fale com nosso atendimento via WhatsApp.](https://4p.finance/whatsapp-redirect) 2. Informe o e-mail utilizado no cadastro da sua conta à nossa equipe de suporte. 3. Após a validação, sua API Key será liberada para uso na API. {% hint style="danger" %} Atenção! As chamadas para a API da **4P Finance** devem ser realizadas no back-end da sua aplicação. Dessa forma, sua API KEY não será exposta. \ \ **Nunca execute as chamadas para a API da 4P Finance usando sua API KEY no front-end de sua aplicação web / website.** {% endhint %} Tudo certo! Agora que você já tem sua API KEY, guarde-a em um lugar seguro e nunca compartilhe a sua chave com terceiros. # On-ramp Aprenda como realizar chamadas para a API da 4P Finance e criar transações, conversão de moedas e callbacks/notificações. # Redes suportadas Instruções de como obter as redes suportadas pela a API da 4P Finance. A API da 4P Finance oferece suporte a múltiplas blockchains, permitindo que você escolha a rede mais adequada para receber os criptoativos diretamente na carteira do seu usuário. Atualmente, o serviço de On-Ramp suporta as seguintes redes: * **Ethereum** * **Bitcoin** * **HyperEVM** * **Solana** * **Tron** * **Arbitrum** * **Base** * **Polygon** * **BNB Smart Chain (BSC)** * **Avalanche** * **Optimism** Ao realizar a ativação da sua API Key junto ao nosso atendimento, você irá informar a rede e a moeda que deseja. A 4P Finance cuidará automaticamente de todo o processo de: * Geração da cobrança via Pix * Conversão do valor pago * Envio dos fundos na blockchain escolhida * Confirmação da transação via webhook Isso garante flexibilidade total para sua aplicação operar com múltiplos ecossistemas blockchain sem qualquer complexidade operacional. # Criando uma transação Esta página contém instruções de como solicitar a criação de uma transação na API da 4P Finance. ### Serviço • Envia um JSON contendo os dados necessários para a criação de uma cobrança imediata. • Retorna um JSON contendo os dados da cobrança criada, inclusive Pix Copia-e-Cola. ### Solicitação de registro/transação A requisição para realizar a criação/registro de uma transação deverá ter como corpo da solicitação JSON as informações necessárias para registrar a transação. ### Exemplo de payload ```json { "cpf": "01234567899", // Troque esta chave para "cnpj" no caso de CNPJ / Pessoa Jurídica. "email": "usuario@example.com", "amount": 1.10, "expires": 3600, "custom_id": "PN123", "custom_data": { "chain": "Arbitrum", // Opcional (Default: Arbitrum) "asset": "USDT", // // Opcional (Default: USDT) "receiver_wallet": "0x4328...edFB995B6I" }, "description": "Cobrança de assinatura #PN123", "notification_url": "https://seu-dominio-webhook.com.br/param=tes&token=abcd-dfg" } ``` ### Requisição ## Solicita a criação/registro de uma transação. `PUT` `https://api.4p.finance/v1/pix/transaction` Realiza a solicitação do registro de uma transação. #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | -------------- | | x-api-key\* | String | Sua chave API. | #### Request Body
NameTypeDescription
expires*IntegerT empo de vida da cobrança, em segundos, a partir da data de criação. Deve ser igual ou maior do que 300. Máximo: 259200 segundos.
amount*NumberValor original da cobrança. Deve ser informado um valor maior ou igual a 0.01, com casas decimais.
custom_id *StringId da transação ou Id do Pix. Permite que o usuário recebedor faça a conciliação dos pagamentos. Deve ser único por transação PIX e conter no máximo 255 caracteres.
description*StringRepresenta um texto ( campo solicitacaoPagador do PIX ), a ser apresentado ao usuário pagador para que ele possa digitar uma informação correlata, em formato livre, a ser enviada ao usuário recebedor. Máximo 140 caracteres.
notification_url *StringURL que receberá as notificações POST encaminhadas pelo serviço de webhook logo após o PIX ser pago.
custom_data*ObjectObjeto pai para dados customizados.
receiver_wallet*StringChave filha de custom_data para envio da carteira do cliente pagador do PIX, no qual receberá as criptomoedas. Usado para compras de criptomoedas através de API PIX para (P2P).
{% tabs %} {% tab title="200: OK Retorno após criar/registrar uma transação." %} ```json { "http_code": 200, "success": true, "info": { "result": "pix_transaction_created", "message": "The Pix transaction was successfully created.", "data": { "calendario": { "criacao": "2026-01-01T11:05:53.009Z", "expiracao": 3600 }, "devedor": { "cnpj": "00000000000000", "nome": "" }, "valor": { "modalidadeAlteracao": 0, "original": 1.1 }, "chave": "4cf1bb22-71c1-4530-b735-d240c3c0f88a", "solicitacaoPagador": "Cobrança de assinatura #PN123", "infoAdicionais": [], "txid": "2ce3608c77264388b956c039", "location": "brcode.infra.com/v2/8657085674d44db288430cftb155ca62", "revisao": 0, "status": "ATIVA", "pixCopiaECola": "00010301021226190014br.gov.bcb.pix2557brcode.infra.com/v2/1652085674d33db965430cfab255ba405204000053039865802BR59254Pay Finance Prestadora d6106Recife62070503***6304F9E1", "code": 201 } } } ``` {% endtab %} {% endtabs %} ### Retorno Observe que o objeto *data* contém os dados do PIX incluindo chave Copia e Cola (pixCopiaECola). Ao criar uma cobrança Pix, o usuário recebedor obtém as informações para a geração da imagem do QR Code dinâmico, juntamente com sua representação em forma de Pix Copia-e-Cola. Destacamos que a geração da imagem do QR Code não é gerada, e fica a cargo de cada implementador. ### Conclusão Após a confirmação do pagamento, o valor convertido em criptomoeda será enviado automaticamente para a carteira informada no payload da requisição. O tempo médio para envio e finalização da transação é de aproximadamente 10 segundos, podendo variar de acordo com a rede blockchain selecionada e as condições da própria rede no momento da operação. Saiba mais sobre as notificações e callbacks na próxima sessão. # Off-ramp Aprenda como realizar chamadas para a API da 4P Finance e criar transações, conversão de moedas e callbacks/notificações. # Redes suportadas Instruções de como obter as redes suportadas pela a API da 4P Finance. A API da 4P Finance oferece suporte a múltiplas blockchains, permitindo que você escolha a rede mais adequada para enviar os criptoativos diretamente na carteira da 4P Finance indicada no momento da criação da transação. Atualmente, o serviço de Off-Ramp suporta as seguintes redes: * **Ethereum** * **Bitcoin** * **HyperEVM** * **Solana** * **Tron** * **Arbitrum** * **Base** * **Polygon** * **BNB Smart Chain (BSC)** * **Avalanche** * **Optimism** Ao realizar a ativação da sua API Key junto ao nosso atendimento, você irá informar a rede e a moeda que deseja. A 4P Finance cuidará automaticamente de todo o processo de: * Monitoramento e confirmação do envios dos criptoativos pelo seu cliente * Conversão dos criptoativos enviados * Envio do valor fiat correspondente para o destino escolhido na requisição ou antecipadamente * Confirmação da transação via webhook Isso garante flexibilidade total para sua aplicação operar com múltiplos ecossistemas blockchain sem qualquer complexidade operacional. # Criando uma transação Esta página contém instruções de como solicitar a criação de uma transação na API da 4P Finance. ### Serviço • Envia um JSON contendo os dados necessários para a criação de uma venda imediata. • Retorna um JSON contendo os dados da conversão criada, inclusive rede, token e carteira para qual os criptoativos deverão ser enviados. ### Solicitação de registro/transação A requisição para realizar a criação/registro de uma transação deverá ter como corpo da solicitação JSON as informações necessárias para registrar a transação. ### Exemplo de payload ```json { "person_document": "01234567899", "email": "usuario@example.com", "amount_crypto": 1.10, "custom_id": "PN123", "custom_data": { "chain": "Arbitrum", "asset": "USDT" }, "sender_wallet": "0x4328...edFB995B6I", "destination_pix_key": "01234567899", "notification_url": "https://seu-dominio-webhook.com.br/param=tes&token=abcd-dfg" } ``` ### Requisição ## Solicita a criação/registro de uma transação. `PUT` `https://api.4p.finance/v1/cryptopix/transaction` Realiza a solicitação do registro de uma transação. #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | -------------- | | x-api-key\* | String | Sua chave API. | #### Request Body
NameTypeDescription
custom_id *StringId da transação. Permite que o usuário recebedor faça a conciliação dos pagamentos. Deve ser único por transação e conter no máximo 255 caracteres.
destination_pix_key*StringChave PIX para qual o valor fiat (BRL) será enviado após o recebimento e conversão dos criptoativos. Caso não seja enviada, o PIX será enviado para chave que deverá ter sido previamente informada.
sender_wallet*StringChave para envio da carteira do cliente pagador da qual obrigatoriamente deverá se originar os envio de criptoativos.
notification_url *StringURL que receberá as notificações POST encaminhadas pelo serviço de webhook logo após ao criptoativos serem enviados e convertidos.
amount_crypto*FloatValor original da cobrança em criptoativos. Deve ser informado um valor maior ou igual a 0.01, com casas decimais.
person_document*StringNúmero de documento ou identificação do usuário ao qual a transação deverá ser associada, equivalente ao CPF.
custom_data*ObjectObjeto pai para dados relacionados a rede e token que serão alvo da transação.
{% tabs %} {% tab title="200: OK Retorno após criar/registrar uma transação." %} ```json { "http_code": 200, "success": true, "info": { "result": "p2p_transaction_cryptopix_created", "message": "P2P transaction promise has been created. Please transfer the crypto to the indicated wallet to proceed.", "data": { "txid": "da75257ce3f19483ef1049fef890a310", "amount_crypto": 1.10, "asset": "USDT", "chain": "arbitrum", "amount_brl": 5.49, "receiver_wallet": "0x4328...edFB995B6I", "expires": 1769608117 } } } ``` {% endtab %} {% endtabs %} ### Retorno Observe que o objeto data contém as informações da transação, incluindo a carteira de destino dos criptoativos (receiver\_wallet). É necessário que os ativos sejam enviados exatamente no valor informado para essa carteira, a partir da carteira do cliente pagador indicada no momento da criação da transação. > Destacamos que será retornada no *data* uma chave *expire*, ela representa o período máximo de monitoramento da transação. Após essa expiração, uma nova transação deverá ser criada antes do envio dos criptoativos. ### Conclusão Após a confirmação do recebimento das criptomoedas, o valor convertido em fiat será enviado automaticamente para o PIX informado no payload da requisição ou anteriormente associado a conta do usuário. O tempo médio para envio e finalização da transação é de aproximadamente 10 segundos, podendo variar de acordo com a rede blockchain selecionada e as condições da própria rede no momento da operação. Saiba mais sobre as notificações e callbacks na próxima sessão. # Cotação Esta página contém instruções de como realizar a cotação de valores/moedas através da API da 4P Finance. Caso deseje realizar a cotação do valor em BRL (Real) para a moeda ou token de destino, você pode utilizar o endpoint de cotação antes de criar a transação. Essa conversão tem como objetivo: * Obter a taxa de conversão atual da moeda/token selecionado; * Retornar o valor final já convertido para criptomoeda; Utilizando o endpoint `/transaction/price_conversion` você conseguirá obter a cotação do valor solicitado em BRL/REAL para o valor atualizado na criptomoeda escolhida. ### Exemplo de payload ```json { "amount": "50.10", "currency_from_symbol": "BRL", "convert": "USDT" } ``` ## Realiza a conversão de moeda/token. `POST` `https://api.4p.finance/v1/transaction/price_conversion` Retorna JSON com o valor total solicitado convertido na moeda/token escolhido. #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | -------------- | | x-api-key\* | String | Sua chave API. | #### Request Body | Name | Type | Description | | -------------------------------------------------------- | ------ | --------------------------------------------------------------------- | | amount\* | String | Valor a ser convertido. Exemplo: 35.99. | | convert\* | String | Símbolo da moeda/token em que o valor será convertido. Exemplo: USDT. | | currency\_from\_symbol\* | String | Símbolo da moeda/token de origem. Exemplo: BRL. | {% tabs %} {% tab title="200: OK JSON com dados do valor convertido." %} ```javascript { "http_code": 200, "success": true, "info": { "result": "price_conversion_success", "message": "Price conversion successfully.", "data": { "id": 2783, "symbol": "BRL", "name": "Brazilian Real", "amount": "250.00", "last_updated": "2023-02-16T20:49:27.000Z", "quote": { "BTC": { "price": 47.33, "last_updated": "2026-01-01T20:49:00.000Z" } }, "origin": "api", "dbprice": "bce" } } } ``` {% endtab %} {% endtabs %} # Webhook Aqui você encontrará informações de como utilizar as notificações de status de transações. # Entendendo o fluxo das notificações Entendendo o fluxo das notificações (callbacks) da API 4P Finance. Esta página tem como objetivo apresentar as notificações ( webhook ). Este recurso está disponível na API de sua conta **4P Finance** e permite visualizar os POSTs que a **4P Finance** dispara para a URL de retorno definida pelo integrador. Este POST contém apenas uma informação: um token de notificação. Outras informações sobre o processo de definição da URL de notificação e a mecânica envolvendo a consulta de detalhes de uma notificação podem ser observadas na página [Obtendo dados de notificações.](/webhook/obtendo-dados-de-notificacoes) ## Conhecendo o fluxo de notificações Assim que é enviado com *Sucesso (200)* para sua URL de retorno, não significa, por si só, que o fluxo ocorreu completamente. Quando você receber o POST, precisará consultar as informações dessa notificação. {% hint style="danger" %} Atenção! O POST que a **4P Finance** envia para a sua URL de retorno **não contém os dados da transação, mas apenas o token de notificação.** Todas as informações sobre a referida transação serão retornadas assim que você consumir o endpoint `GET /notification/:token.` {% endhint %} O processo de notificação funciona como uma "via de mão dupla", ou seja, será realizada uma requisição POST para a sua URL de retorno após confirmado o pagamento do PIX, em seguida, o seu sistema, em posse do token de notificação, envia uma requisição de consumo ao endpoint GET `/pix/notification/:token`, em que `:token` é o token de notificação contido no POST enviado. O fluxo é determinado pela seguinte ordem: 1. A 4P Finance enviará uma requisição HTTP POST para a URL de callback (webhook) informada no momento da criação da transação. Essa notificação é disparada automaticamente após: #### On-ramp: 1. Após a confirmação do pagamento; e 2. Após a confirmação do envio das criptomoedas na blockchain. #### Off-ramp: 1. Após a confirmação do recebimento das criptomoedas. O POST conterá apenas um token de notificação, permitindo que seu sistema valide e processe o status final da operação de forma segura e automatizada. Assim que você receber a requisição POST, realize uma requisição `GET` para a rota `/notification/:token`, em que `:token` será o token de notificação que enviamos para você. > Ao realizar novas requisições `GET` para `/notification/:token`, você receberá atualizações sobre a transação sempre que houver mudanças, como por exemplo no status: `pending`, `processing`, `success` ou `error`. {% hint style="warning" %} **Importante!** Se o seu sistema consulta o token enviado, consideramos que a notificação foi realizada com sucesso. Caso não consulte, tentaremos novamente por até 05 dias. Ou seja, se houver uma requisição ao endpoint `GET /notification/:token,` entenderemos que você recebeu o POST com o token de notificação e que o consultou, recebendo como resposta todos os dados informativos sobre a confirmação da transação. {% endhint %} ## Segurança Para garantir a segurança da comunicação entre os servidores, é obrigatório que a sua URL de callback (webhook) utilize o protocolo HTTPS. **As notificações são enviadas a partir dos seguintes IPs de saída:** 44.196.63.157 Recomendamos que você configure sua infraestrutura para aceitar requisições apenas desse IP (allowlist), garantindo que somente nossos servidores possam acessar o seu endpoint. Recomendamos fortemente que o seu sistema: * Gere um token único por transação no seu backend; * Inclua esse token como parâmetro na URL de notificação (notification\_url) no momento da criação da transação; * Utilize esse token para validar a autenticidade das notificações recebidas via POST; * Valide que a requisição foi originada do IP informado. Dessa forma, ao receber uma notificação da 4P Finance, seu sistema poderá: * Confirmar que a requisição foi originada de nossos servidores; * Validar o token recebido e garantir que a requisição corresponde exatamente à transação esperada. **Exemplo de URL webhook (notification\_url):** {% hint style="info" %} `https://webhook.minhaempresa.com.br/pix/?custom_id=12345&seu-token=eae1fe563265167f8d88aec8cd4a7609` {% endhint %} # Obtendo dados de notificações Saiba como consultar os dados das notificações enviadas ao seu sistema. Uma vez que a sua URL de retorno recebeu um POST com o token de notificação da **4P Finance**, o seu sistema deverá realizar uma requisição GET para o endpoint `/notification/:token` que retornará os dados da transação/notificação. ## Realiza requisição dos dados da notificação `GET` `https://api.4p.finance/v1/notification/:token` Realiza uma requisição enviando o token recebido via POST na URL de retorno cadastrada na criação da transação. #### Path Parameters | Name | Type | Description | | --------------------------------------- | ------ | --------------------------------------------------------- | | token\* | String | Token recebido via POST na sua URL de retorno cadastrada. | #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | -------------- | | x-api-key\* | String | Sua chave API. | {% tabs %} {% tab title="200: OK Retorno token recebimento do Pix" %} ```javascript { "http_code": 200, "success": true, "info": { "data": { "id": "936e8ae54933c2f8c10f3908e50be15c", "txid": "1ae3808c17364388b956c039", "status": "paid", "amount": "1.10", "description": "Cobrança de assinatura #PN123", "payer_info": "Nome do pagador - 123.456.789-00", "payment_date_time": "01/01/2026, 11:46:21", "created_at": "01/01/2026, 08:05:52", "confirmed_at": "01/01/2026, 11:46:25", "custom_id": "PN123" } } } ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="200: OK Retorno token envio das criptos" %} ```javascript { "http_code": 200, "success": true, "info": { "data": { "id": "936e8ae54933c2f8c10f3908e50be15c", "txid": "1ae3808c17364388b956c039", "status": "paid", "amount": "1.10", "description": "Cobrança de assinatura #PN123", "payer_info": "Nome do pagador - 123.456.789-00", "payment_date_time": "01/01/2026, 11:46:21", "created_at": "01/01/2026, 08:05:52", "confirmed_at": "01/01/2026, 11:46:25", "custom_id": "PN123", "custom_data": { "chain_name": "Arbitrum", "amount_usdt": "0.20216", "receiver_wallet": "0x4328437bf03FFDBb0f64358a6a2947edFB995B6I", "transaction_hash": "0x63aaer69c90bafbb11f36b4a1adacedce28b84803e82f7a68b8442357ffe0f33" } } } } ``` {% endtab %} {% endtabs %} {% hint style="info" %} **Importante!** Se o seu sistema consulta o token enviado, consideramos que a notificação foi realizada com sucesso. Caso não consulte, tentaremos novamente por até 05 dias. Ou seja, se houver uma requisição ao endpoint `GET /notification/:token,` entenderemos que você recebeu o POST com o token de notificação e que o consultou, recebendo como resposta todos os dados informativos sobre a confirmação da transação. {% endhint %} Uma vez que consultou os dados da transação, o seu sistema já pode efetuar a baixa de pagamento, confirmação, ou conclusão da transação. # Abertura de Conta (KYC/KYB) Requer liberação / autorização Este documento descreve, passo a passo, as rotas que um parceiro deve consumir para realizar o fluxo completo de abertura de conta (KYC) na 4Pay a partir do frontend do parceiro. *** ## 1. Visão Geral Esta API permite que um parceiro construa seu próprio frontend de cadastro e conduza o cliente final por todo o fluxo de abertura de conta na 4Pay, incluindo validação de identidade (KYC) e liveness. O fluxo é composto por múltiplas etapas sequenciais. Cada etapa deve ser concluída com sucesso antes de avançar para a próxima. ### 1.1 Endereços Base **Laboratório (sandbox):** `https://verify-api.4p.finance/lab/` {% hint style="warning" %} **⚠️ Acesso ao ambiente de laboratório** O ambiente de laboratório exige liberação prévia de IP em whitelist. Envie o(s) IP(s) de origem das requisições para a equipe 4Pay antes de iniciar os testes. {% endhint %} **Produção:** `https://verify-api.4p.finance/` {% hint style="warning" %} **🔑 Partner ID — somente em produção** O segmento de Partner ID (hash que identifica o parceiro) é usado apenas no ambiente de produção. No laboratório, as rotas são chamadas diretamente após `/lab/`, sem esse segmento. {% endhint %} ``` ex. (laboratório): https://verify-api.4p.finance/lab/account/initial_registration ex. (produção): https://verify-api.4p.finance/v1/{hash-partner-id}/account/initial_registration ``` Nas seções seguintes, o path de cada rota é mostrado de forma relativa (ex.: `/account/initial_registration`). Monte a URL completa combinando com o endereço base do ambiente e, em produção, adicionando o Partner ID logo após o domínio. ### 1.2 Formato Padrão de Resposta Todas as respostas da API seguem o mesmo formato-base. O campo mais importante para tratar a resposta programaticamente é sempre `info.result` — ele identifica de forma única o resultado da operação, independentemente do valor de `success` ou `http_code`. ```json { "http_code": 200, "success": true, "info": { "result": "identificador_do_resultado", "message": "Mensagem legível para exibir ou logar.", "data": {} } } ``` {% hint style="info" %} **💡 Dica de integração** Trate sempre a lógica da sua aplicação com base em `info.result`, não apenas em `success` ou `http_code`. Isso porque um `http_code` 200 pode conter tanto sucesso quanto falha de regra de negócio (ex.: documento já cadastrado). O campo `message` é amigável e pode ser exibido diretamente ao usuário final quando fizer sentido. {% endhint %} ### 1.3 Arquitetura de Integração {% hint style="info" %} **🌐 Chamadas diretas do browser — sem backend intermediário** O frontend do parceiro deve requisitar a API da 4Pay diretamente do browser do cliente final, sem passar por um servidor/backend do parceiro como intermediário. Essa é uma exigência de arquitetura: é o que possibilita à 4Pay aplicar controle de IP e análises de risco via WAF diretamente sobre o tráfego do usuário final (ex.: listas de reputação de IP, detecção de proxy/VPN/datacenter, rate limiting por usuário). Se as requisições passarem pelo backend do parceiro, essa visibilidade se perde. {% endhint %} As rotas descritas neste documento são específicas do parceiro e possuem CORS liberado apenas para o domínio informado no cadastro da integração. ### 1.4 Autenticação — reCAPTCHA v3 {% hint style="warning" %} **🔒 Escopo do reCAPTCHA** Apenas a primeira rota do fluxo — `/account/initial_registration` — exige o token do reCAPTCHA v3 (campo `rid`). As demais rotas do fluxo não requerem esse token. {% endhint %} O token deve ser gerado no frontend do parceiro com o site key exclusivo fornecido pela 4Pay para esse parceiro. * O domínio autorizado a gerar tokens com esse site key é restrito ao domínio do parceiro cadastrado. * O token é validado no backend da 4Pay (score mínimo e ação esperada).\ \ [Veja a documentação do reCAPTCHA v3](https://developers.google.com/recaptcha/docs/v3?hl=pt-br) ### 1.5 Visão Geral do Fluxo As etapas abaixo devem ser executadas nesta ordem: 1. Cadastro inicial (e-mail e senha) — envia e-mail de confirmação de posse do e-mail 2. Validação da hash de abertura de conta — confirma que a hash da URL recebida por e-mail é válida 3. Envio do documento (CPF/CNPJ) — verifica se já existe conta com esse documento 4. Solicitação do código de verificação de telefone (WhatsApp ou SMS) 5. Validação do código de verificação enviado ao telefone 6. Envio dos dados de endereço 7. Início do processo de liveness (validação facial) 8. Envio do documento de identidade (KYC) 9. Verificação do status final da conta / KYC *** ## 2. Cadastro Inicial Primeira etapa do fluxo. Cria o cadastro inicial do cliente com e-mail e senha. #### **`POST`** `/account/initial_registration` {% hint style="info" %} **📧 O que acontece após essa chamada** Um e-mail é enviado ao cliente com um link de confirmação. O cliente precisa clicar nesse link para validar que é o dono do e-mail e continuar o cadastro. O link contém um parâmetro `h` (hash) que identifica essa abertura de conta — esse hash será reutilizado nas próximas etapas. {% endhint %} **Payload (body)** ```json { "email": "cliente@example.com", "password": "SenhaForte@123", "newsletter": 1, "rid": "0cAFcW" } ``` **Resposta — Sucesso** ```json { "http_code": 200, "success": true, "info": { "result": "successful_registration", "message": "Successful registration." } } ``` Campos do payload: `email` (e-mail do cliente), `password` (senha escolhida pelo cliente — ver requisitos abaixo), `newsletter` (1 = aceite de comunicações, 0 = recusa), `rid` (token do reCAPTCHA v3). **Requisitos de senha** A senha informada no campo `password` deve atender a todos os critérios abaixo: * Mínimo de 6 caracteres. * Máximo de 20 caracteres. * Combinação de letras maiúsculas e minúsculas. * Pelo menos um caractere especial (ex.: !, @, #, $). * Pelo menos um número. *** ## 3. Validação da Hash de Abertura de Conta Executada quando o cliente acessa a URL recebida por e-mail (após clicar no link de confirmação). Valida se a hash daquela abertura de conta existe e retorna os dados já cadastrados até o momento. #### **`GET`** `/account/customer_hash/{hash}` {% hint style="info" %} **🔑 Sobre a hash** É a mesma hash usada em todas as demais etapas do fluxo — recebida no parâmetro `h` da URL de confirmação enviada por e-mail. Aqui ela é enviada diretamente no path da URL, não no body. {% endhint %} **Resposta — Hash encontrada** A hash é válida. O campo `data` traz os dados já cadastrados do cliente até o momento, incluindo o progresso do KYC (`status_kyc` e `step_kyc`). ```json { "http_code": 200, "success": true, "info": { "result": "customer_by_hash", "message": "Select Customer by Hash.", "data": { "email": "cliente@example.com", "hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "status_kyc": 0, "step_kyc": 4 } } } ``` **Resposta — Hash não encontrada** Não existe abertura de conta com essa hash (pode ter expirado, já ter sido concluída, ou ser inválida). ```json { "http_code": 200, "success": true, "info": { "result": "customer_hash_empty", "message": "Data not found." } } ``` *** ## 4. Envio do Documento (Verificação de Existência) Etapa executada assim que o cliente clica no link recebido por e-mail e preenche o CPF ou CNPJ no formulário do parceiro. Essa chamada verifica se já existe uma conta 4Pay associada a esse documento. #### **`POST`** `/account/update_customer` {% hint style="info" %} **🔑 Sobre o hash** O hash é o identificador único e temporário dessa abertura de conta. Ele vem no parâmetro `h` da URL enviada por e-mail (ex.: `https://lab-app.4p.finance/complete-registration?h=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6`) e deve ser reaproveitado em todas as etapas seguintes do fluxo. Esse hash é invalidado automaticamente assim que a conta é concluída. {% endhint %} **Payload (body)** ```json { "person_document": "111.222.333-44", "hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "step_kyc": 1 } ``` **Resposta — Documento não encontrado (pode prosseguir)** Não existe conta com esse documento. O cadastro pode continuar normalmente. ```json { "http_code": 200, "success": true, "info": { "details": { "result": "document_not_found", "message": "Document not found." } } } ``` **Resposta — Documento já cadastrado** Já existe uma conta 4Pay com esse documento. O fluxo deve ser interrompido e o cliente informado. ```json { "http_code": 200, "success": false, "info": { "details": { "result": "document_already_exists", "message": "The document sent already exists in the database." } } } ``` Campos do payload: `person_document` (CPF ou CNPJ, sempre formatado/com máscara — ex.: `111.222.333-44`), `hash` (identificador da abertura de conta), `step_kyc` (fixo em 1 nesta etapa). {% hint style="warning" %} Atenção: nesta rota específica, o resultado vem em `info.details.result` (não em `info.result` como nas demais rotas). {% endhint %} *** ## 5. Solicitação do Código de Verificação do Telefone {% hint style="warning" %} **⏱️ Expiração do código** O código de verificação enviado por WhatsApp ou SMS expira em 5 minutos. Após esse prazo, é necessário solicitar um novo código. {% endhint %} {% hint style="success" %} **✅ WhatsApp é o canal preferencial** A validação via WhatsApp é o método recomendado e possui aproximadamente 99% de sucesso de entrega. O SMS é oferecido como alternativa, mas costuma apresentar problemas de recebimento — utilize-o apenas como fallback caso o WhatsApp não esteja disponível para o número do cliente. {% endhint %} Envia um código de verificação para o telefone do cliente via WhatsApp. Canal recomendado. #### **`POST`** `/account/verification_code` **Payload (body)** ```json { "hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "phone": "5511999998888", "type_message": "whatsapp" // "whatsapp" ou "sms" } ``` **Resposta — Código enviado** ```json { "http_code": 200, "success": true, "info": { "result": "code_sent", "message": "Verification code successfully sent.", "userdata": { "phone": "5511999998888" } } } ``` *** ## 6. Validação do Código de Verificação Valida o código recebido pelo cliente via WhatsApp ou SMS. #### **`POST`** `/account/validation_code` **Payload (body)** ```json { "hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "phone_only_number": "5511999998888", "confirmation_code": "123456" } ``` **Resposta — Código válido** ```json { "http_code": 200, "success": true, "info": { "result": "valid_code", "message": "The code sent is the same as the code generated." } } ``` **Resposta — Código inválido** ```json { "http_code": 200, "success": false, "info": { "result": "invalid_code", "message": "The code sent is the same as the code generated." } } ``` ## 7. Envio dos Dados de Endereço Envia os dados de endereço e demais dados cadastrais complementares do cliente. #### **`POST`** `/account/update_customer` {% hint style="info" %} **📌 Mesma rota da Etapa 4** Esta é a mesma rota `/account/update_customer` usada na Etapa 4, porém com um payload mais completo e `step_kyc = 4`, indicando avanço no fluxo de KYC. {% endhint %} **Payload (body)** ```json { "person_type": "personal", // "personal" para Pessoa Física e "empresarial" para Pessoa Jurídica. "person_document": "111.222.333-44", // CPF ou se caso for Pessoa Jurídica envia CNPJ. "legal_representative_document": "111.222.333-44", // Envia o CPF do representante legal se person_type for Pessoa Jurídica. "company_website": "example.com", // Opcional. "company_activity": "E-commerce", // Opcional. "post_code": "01310100", "address": "Rua das Flores", "number_address": "123", "neighborhood": "Jardim Exemplo", "city": "São Paulo", "state": "SP", "hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "complement_address": "", "status_kyc": 0, "step_kyc": 4 } ``` **Resposta — Sucesso** ```json { "http_code": 200, "success": true, "info": { "result": "registration_completed", "message": "Registration completed successfully.", "data": { "hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" } } } ``` Campo `person_type` aceita dois valores: `"personal"` (pessoa física) ou `"empresarial"` (pessoa jurídica). {% hint style="danger" %} **🚨 Importante — não é o fim do cadastro** Apesar do result retornar `registration_completed`, o cadastro ainda não está finalizado. A próxima etapa obrigatória é iniciar o processo de liveness. {% endhint %} *** ## 8. Início do Processo de Liveness Solicita a URL de liveness (validação facial) do cliente, via integração com a Didit. #### **`POST`** `/account/liveness` **Payload (body)** ```json { "hash": "a1b2g3d4e5f6n1b8c9d0e1f2a3b4c5d6" } ``` **Resposta — Sucesso** ```json { "http_code": 200, "success": true, "info": { "result": "liveness_initiated", "message": "Liveness process initiated.", "data": { "required": true, "selfie": false, "token": "aBcD1234EfGh", "sessionId": "11111111-2222-3333-4444-555555555555", "url": "https://verify.4payfinance.com/pt-BR/session/abcd123", "kyc_provider": false, "registration_step": "doc" } } } ``` {% hint style="info" %} **🎥 Como executar o liveness** A URL retornada em `data.url` deve ser aberta utilizando o SDK Web ou o SDK Mobile da Didit ([Documentação/SDK Didit](https://docs.didit.me/integration/web-sdks/overview)). Caso o cliente esteja no computador, ele pode escanear um QR Code e concluir o liveness pelo celular, retornando em seguida ao fluxo no computador — ou, se estiver iniciando o cadastro diretamente pelo celular, conclui tudo no próprio dispositivo.\ \ ATENÇÃO: No desktop, utilizando o SDK da Didit, seu frontend monitora a conclusão do liveness e envia o usuário para a próxima etapa de envio do documento. {% endhint %} *** ## 9. Envio do Documento de Identidade (KYC) Após a conclusão do liveness, o cliente envia a imagem do documento de identidade. #### **`POST`** `/account/complete_kyc` **Arquivo (multipart/form-data)** Envie as Keys "files" para o arquivo e "customer" contendo o Value com um JSON para a hash da conta. **Exemplo multipart/form-data:** ```json files: customer: {"hash": "1464703ee9c1cec3958a6154502818e6"} ``` **ATENÇÃO:** * O arquivo do documento deve ser renomeado para "document" caso não tenha esse nome. * Deve conter a FOTO e CPF (preferencialmente CNH) para que seja feita o Face Match, OCR e Documentoscopia para validação dos dados e KYC. {% hint style="warning" %} **📷 Qualidade da imagem** A imagem do documento deve ser enviada em boa qualidade — nítida, bem iluminada, sem cortes ou reflexos. Imagens de baixa qualidade aumentam a chance de reprovação no KYC (ex.: `kyc_data_is_invalid`). {% endhint %} *** ## 10. Verificação do Status Final da Conta / KYC Consulta o status final da conta após a conclusão do envio do documento de KYC. #### **`POST`** `/account/kyc_validation` **Payload (body)** ```json { "hash": "a1b2c3d4e5f1a7b8c0a0e1f2a3b4c5d5" } ``` **Resposta — Tudo certo (conta aprovada)** Após esta chamada, se a conta estiver completa e validada, o cliente recebe um e-mail de confirmação de abertura de conta na 4Pay. ```json { "http_code": 200, "success": true, "info": { "result": "all_data_is_valid", "message": "" } } ``` **Respostas — Conta não aprovada / dados inválidos** Nestes casos, o campo `info.result` identifica o motivo específico da reprovação: | info.result | O que significa | | ----------------------- | ------------------------------------------------------------------------- | | `account_not_approved` | A conta não pôde ser aprovada neste momento. | | `invalid_data` | Dados enviados durante o cadastro são inválidos, de forma geral. | | `invalid_owner_data` | Dados do titular da conta (pessoa física) são inválidos. | | `invalid_company_data` | Dados da empresa (pessoa jurídica) são inválidos. | | `kyc_data_is_invalid` | Os dados extraídos do processo de KYC (documento/liveness) são inválidos. | | `basic_data_is_invalid` | Dados básicos do cadastro são inválidos. | | `all_data_is_invalid` | Todos os dados enviados são inválidos. | Exemplo de resposta de reprovação: ```json { "http_code": 200, "success": false, "info": { "result": "account_not_approved", "message": "This account could not be approved at this time." } } ``` # Fale Conosco Como entrar em contato com a 4P Finance? ### WhatsApp * [Clique aqui para falar no WhatsApp](https://4p.finance/whatsapp-redirect) ### Suporte para Integração Para suporte referente a integração com a API da **4P Finance**, recomendamos utilizar a comunicação através do e-mail: **** Teremos o maior prazer em ajudar! :relaxed: