Aqui você vai encontrar tudo que precisa para realizar a sua integração da melhor forma possível. Venha conosco e ajudaremos a alavancar o seu negócio!
\nPara acessar os EndPoints é necessário gerar as chaves de acesso da conta do usuário. Isto é feito acessando a conta pela web com o email e senha do cliente.
\nDentro da conta, basta clicar no menu INTEGRAÇÃO.
\nSerá exibido o Client ID (vpi) e Client Secret (vps) ao final do procedimento. Estes dados devem ser armazenados em local seguro.
\nAs chaves devem ser enviadas juntos da requisição no cabeçalho HTTP das mesmas com os nomes vspi para Client ID e vsps para Client Secret.
\nProdução:
\nhost: https://api.versellpay.com
\n200 - Sucesso.
\n401 - Falha na autenticação.
\n400 - Erro na solicitação, verifique o response do retorno.
\n500 - Erro interno.
\nO webhook é utilizado para notificar automaticamente o sistema do cliente sobre atualizações de status das transações processadas pelo Versell Pay.
\nSempre que ocorrer uma mudança no estado de uma transação de cash-in (entrada) ou cash-out (saída), uma requisição HTTP POST será enviada para a URL configurada no campo callbackUrl no momento da criação da transação.
\nAbaixo você encontra os parâmetros retornados no webhook para transações de cash-in e cash-out.
\nO webhook de PIX Cash-in é utilizado para receber notificações automáticas sempre que um pagamento PIX é recebido com sucesso. Ele pode ser configurado diretamente na requisição de geração do QR Code, informando a URL de callback desejada, ou de forma permanente através do painel administrativo, acessando a aba Configurações > Webhook.
\n| Variável | Tipo | Descrição |
|---|---|---|
requestNumber | String | Número de requisição enviado na requisição. |
statusTransaction | String | Status da transação (PAID_OUT). |
idTransaction | String | ID da transação. |
typeTransaction | String | Tipo da transação (PIX). |
value | Number | Valor do pagamento. |
debtorName | String | Nome do pagador. |
debtorDocument | String | Documento do pagador. |
date | Date | Data do pagamento. |
endToEnd | String | Identificador único gerado pelo banco ou adquirente para rastrear a transação PIX. |
PAID_OUT - Transação Paga.
\nWAITING_FOR_APPROVAL - Aguardando Pagamento.
\nO webhook de PIX Cash-out é utilizado para receber notificações automáticas sempre que um pagamento PIX for enviado. Ele pode ser configurado diretamente na requisição de Transferência PIX (Cash-out), informando a URL de callback desejada, ou de forma permanente através do painel administrativo, acessando a aba Configurações > Webhook.
\n| Variável | Tipo | Descrição |
|---|---|---|
id | String | Identificador único gerado no momento da criação do cash-out. |
status | String | Status da transação (not paid, insufficient balance, liquidated e success). |
date | Date | Data do evento. |
message | String | Campo que descreve o motivo de não ter sido pago no evento not paid. |
value | Number | Valor do cash-out. |
endToEnd | String | Identificador único gerado pelo banco ou adquirente para rastrear a transação PIX. |
not paid – Não foi pago. O motivo é enviado pelo sistema no campo message do webhook.
\ninsufficient balance – Quando a conta não possui saldo suficiente.
\nliquidated – Quando o pagamento já foi efetuado e não deve ser duplicado.
\nsuccess – Quando o cash-out é concluído com sucesso.
\nO webhook de Reembolso (MED) é utilizado para enviar notificações automáticas sempre que um pagamento PIX é estornado. Ele pode ser configurado de forma permanente pelo painel administrativo, na aba Configurações > Webhook.
\n| Variável | Tipo | Descrição |
|---|---|---|
requestNumber | String | Número de requisição enviado na requisição. |
statusTransaction | String | Status da transação (PAID_OUT). |
idTransaction | String | ID da transação. |
typeTransaction | String | Tipo da transação (PIX_REFUND). |
value | Number | Valor do pagamento. |
debtorName | String | Nome do pagador. |
debtorDocument | String | Documento do pagador. |
date | Date | Data do estorno. |
endToEnd | String | Identificador único gerado pelo banco ou adquirente para rastrear a transação PIX. |
PAID_OUT - Transação Devolvida.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Autenticação","slug":"autenticacao"},{"content":"Variável de ambiente","slug":"variavel-de-ambiente"},{"content":"Retornos - Status Code","slug":"retornos-status-code"},{"content":"Webhooks","slug":"webhooks"},{"content":"Webhook (PIX Cash-in)","slug":"webhook-pix-cash-in"},{"content":"Webhook (PIX Cash-out)","slug":"webhook-pix-cash-out"},{"content":"Webhook (Rembolso - MED)","slug":"webhook-rembolso-med"}],"owner":"20615272","collectionId":"b5736012-6f96-4b9e-9bfa-8d47e0c985da","publishedId":"2sAXjM3reY","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"BDCF03"},"publishDate":"2024-11-06T17:03:13.000Z"},"item":[{"name":"API de Pix","item":[{"name":"Gerar PIX (Cash-in)","id":"d5de0302-2ad5-4741-8bf3-4162e8fe626e","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{}},"request":{"method":"POST","header":[{"key":"vspi","value":"","type":"text"},{"key":"vsps","value":"","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"requestNumber\": \"UUID/CODE\",\n \"amount\": 1,\n \"callbackUrl\": \"https://webhook.versellpay.com\",\n \"client\": {\n \"name\": \"José da Silva\",\n \"document\": \"92730030018\",\n \"phoneNumber\": \"62999815500\",\n \"email\": \"josesilva@gmail.com\",\n \"address\": {\n \"codIbge\": \"5208707\",\n \"street\": \"Rua Paraíba\",\n \"number\": \"150\",\n \"complement\": \"\",\n \"zipCode\": \"74663-520\",\n \"neighborhood\": \"Goiânia 2\",\n \"city\": \"Goiânia\",\n \"state\": \"GO\"\n }\n },\n \"products\": [\n {\n \"description\": \"Tênis\",\n \"quantity\": 1,\n \"value\": 20\n },\n {\n \"description\": \"Camiseta M\",\n \"quantity\": 2,\n \"value\": 50\n }\n ]\n\t// \"split\": { \n // \"account\": \"8\",\n // \"percentageSplit\": 10\n // }\n}","options":{"raw":{"language":"json"}}},"url":"http://localhost:8100/api/v1/gateway/request-qrcode","description":"Este endpoint permite a criação de um código de pagamento PIX (QR Code) para recebimentos via Versell Pay.
\nO QR Code gerado pode ser utilizado para pagamentos instantâneos via PIX.
\nApós o pagamento, a API pode enviar notificações via webhook para atualização do status da transação.
\nO webhook de retorno de cash-in é disparado automaticamente quando ocorre uma atualização no status de uma transação de entrada, como a confirmação ou cancelamento do pagamento.
\nEsse webhook tem como objetivo notificar o sistema do cliente sobre o resultado do pagamento recebido, permitindo a atualização automática de status, liberação de produtos ou serviços e conciliação financeira.
\nA notificação é enviada via HTTP POST para a URL configurada no campo callbackUrl no momento da criação da transação.
\nO objeto split é utilizado para habilitar o repasse automático de parte do valor da transação para outra conta cadastrada no Versell Pay.
\nQuando informado, o valor do pagamento é dividido entre a conta principal e a conta de split, de acordo com a porcentagem definida.
\n| Campo | Tipo | Descrição | Exemplo |
|---|---|---|---|
account | string | Identificador da conta que receberá o valor do split. | 8 |
percentageSplit | number | Percentual do valor total da transação que será repassado para a conta informada. | 10 |
| Regra | Detalhe |
|---|---|
Opcional | O envio do objeto split é opcional. |
Sem split | Se não informado, 100% do valor da transação é creditado na conta principal. |
Intervalo permitido | O percentageSplit deve ser um valor entre 1 e 100. |
Processamento | O split é processado automaticamente no momento da confirmação do pagamento. |
A Versell possui integração nativa com a Utmify para rastreamento de conversões e análise de campanhas de marketing.
Para habilitar o rastreamento das vendas, basta enviar parâmetros UTM na URL ao criar um pedido de depósito.
Para rastrear pedidos, adicione os parâmetros UTM como query parameters na URL do endpoint de criação de depósito.
\n| Parâmetro | Descrição | Exemplo |
|---|---|---|
utm_source | Origem do tráfego | FB, Google, Instagram |
utm_campaign | Nome da campanha | CAMPANHA_2|413591587909524 |
utm_medium | Meio de marketing (conjunto, mídia ou placement) | CONJUNTO_2|498046723566488 |
utm_content | Conteúdo ou variação do anúncio | ANUNCIO_2|504346051220592 |
utm_term | Termo, público ou posicionamento | Instagram_Feed |
Quando parâmetros UTM são enviados na requisição de depósito, o sistema envia automaticamente os dados para a Utmify nos seguintes momentos:
\n| Momento | Evento | Status enviado | Descrição |
|---|---|---|---|
1 | PIX gerado | waiting_payment | Disparado no momento da criação do pedido e geração do QR Code / Copia e Cola |
2 | PIX pago | paid ou approved | Disparado quando o pagamento é confirmado |
3 | Estorno | chargedback | Disparado em caso de estorno ou chargeback |
| Item | Descrição |
|---|---|
Obrigatoriedade | Todos os parâmetros UTM são opcionais. |
Comportamento padrão | Se nenhum parâmetro UTM for enviado, o rastreamento continuará funcionando, porém sem dados de campanha. |
Codificação | Os parâmetros devem ser enviados com URL Encoding para garantir a correta interpretação dos valores. |
Separador \"|\" | O caractere | (pipe) é aceito nos valores e pode ser utilizado para separar informações, como nome|id. |
Integração com Utmify | A integração é automática e não requer nenhuma configuração adicional por parte do integrador. |
Envio dos dados | Os dados UTM são enviados em tempo real no momento da geração do PIX e também na confirmação do pagamento. |
A API da Versell Pay permite a realização de saques via PIX, oferecendo dois tipos de processamento:
\nSaque Interno: Quando autorizado, o valor fica disponível no seu dashboard da Versell Pay, podendo ser gerenciado manualmente pelo usuário.
\nSaque Automático: Caso o parâmetro automaticWithdraw seja definido como true, o saque é processado automaticamente para a conta do destinatário.
O campo typeKey define o tipo de chave PIX utilizada para transferência (cash-out) na Versell Pay.
\nCada tipo de chave possui um formato específico definido pelo padrão PIX. É obrigatório respeitar o formato correto no envio da requisição para evitar rejeições ou falhas no processamento da transferência.
\n| TypeKey | Descrição | Formato Esperado | Exemplo |
|---|---|---|---|
CPF | Chave PIX do tipo CPF | CPF válido (somente números) | 92730030018 |
CNPJ | Chave PIX do tipo CNPJ | CNPJ válido (somente números) | 12345678000199 |
EMAIL | Chave PIX do tipo E-mail | Endereço de e-mail válido | cliente@email.com |
PHONE | Chave PIX do tipo Telefone | Somente números (DDD + número, sem +55 e sem zero) | 62999815500 |
EVP | Chave PIX Aleatória | UUID da chave aleatória PIX | a1b2c3d4-e5f6-7890-abcd |
QRCODE | PIX Copia e Cola | Código PIX completo (payload) e valor exato. | 00020126...6304ABCD |
Esta API oferece endpoints para a geração de QR Codes de pagamento PIX, possibilitando tanto a entrada (Cash-in) quanto a saída (Cash-out) de valores. Ideal para operações que necessitam de flexibilidade em recebimentos e pagamentos via PIX.
\n","_postman_id":"a354868f-acdf-4145-a05f-518450fe4171"},{"name":"API de Cripto","item":[{"name":"Gerar Crypto Pay (Cash-in)","id":"572b4d75-6a34-4f10-b1a3-deec80151942","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{"user-agent":true}},"request":{"method":"POST","header":[{"key":"vspi","value":"","type":"text"},{"key":"vsps","value":"","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"requestNumber\": \"UUID/CODE\",\n \"currency\": \"BTC\", /* BTC ou USDT */\n \"amount\": 10,\n \"callbackUrl\": \"https://webhook.versellpay.com\",\n\t\"split\": { /* (Opcional - Usar se necessário) */\n \"account\": \"8\", /* Pegar no Perfil, Após a Conta ser Aprovada */\n \"percentageSplit\": 10\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.versellpay.com/api/v1/gateway/request-crypto","description":"Este endpoint permite a geração de um endereço de carteira (wallet address) para recebimento em USDT ou BTC via Versell Pay.
\nOs valores recebidos em cripto são automaticamente convertidos para Reais (BRL), permitindo que os fundos sejam utilizados para pagamentos instantâneos via PIX.
\nApós a confirmação da transação na blockchain, a API envia uma notificação via webhook com a atualização do status, possibilitando o processamento automatizado da operação em seu sistema.
\nEsta API oferece endpoints para a geração de endereços de pagamento em criptomoedas, permitindo o recebimento de valores em BTC, USDT e outros ativos suportados.
\n","_postman_id":"84085bb8-47cb-4a6e-88fe-a7b1b989975c"},{"name":"API de Wallet","item":[{"name":"Consultar Saldo (Wallet)","id":"9c9312ba-4103-41ff-9dfc-e49c2d45ed84","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"vspi","value":"","type":"text"},{"key":"vsps","value":"","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"https://api.versellpay.com/api/v1/gateway/walletBalance","description":"Esse endpoint permite consultar o saldo disponível na sua wallet dentro da Versell Pay.
\n","urlObject":{"protocol":"https","path":["api","v1","gateway","walletBalance"],"host":["api","versellpay","com"],"query":[],"variable":[]}},"response":[{"id":"e2e57d60-5368-4143-8073-d4de35c9abd8","name":"Consultar Saldo (Wallet)","originalRequest":{"method":"POST","header":[{"key":"vspi","value":"","type":"text"},{"key":"vsps","value":"","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"url":"https://api.versellpay.com/api/v1/gateway/walletBalance"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Tue, 04 Feb 2025 02:25:03 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"27"},{"key":"Connection","value":"keep-alive"},{"key":"ETag","value":"W/\"1b-aEGd+Oz/6OrbbSfyWLWwuFQiD0M\""},{"key":"Vary","value":"Accept-Encoding"},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Report-To","value":"{\"endpoints\":[{\"url\":\"https:\\/\\/a.nel.cloudflare.com\\/report\\/v4?s=IP9pzY5bXvaZIAmyCsPOCKAqV%2BbxOFzlXiWgH8Cnn2fguLzELUrZpExqf%2BGu%2FjBt06WuW%2BtTKp6YlYPfMIK4HMEySyFyyeJPG9t06paQId%2B7WtcA%2BaHYGU3qYalm2IgzQipP9b0%3D\"}],\"group\":\"cf-nel\",\"max_age\":604800}"},{"key":"NEL","value":"{\"success_fraction\":0,\"report_to\":\"cf-nel\",\"max_age\":604800}"},{"key":"Server","value":"cloudflare"},{"key":"CF-RAY","value":"90c735399916621a-GRU"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"},{"key":"server-timing","value":"cfL4;desc=\"?proto=TCP&rtt=23605&min_rtt=23221&rtt_var=7300&sent=40&recv=41&lost=0&retrans=0&sent_bytes=4151&recv_bytes=1327&delivery_rate=122944&cwnd=252&unsent_bytes=0&cid=f153ded19a184896&ts=38252&x=0\""}],"cookie":[],"responseTime":null,"body":"{\n \"currentBalance\": \"397.70\"\n}"}],"_postman_id":"9c9312ba-4103-41ff-9dfc-e49c2d45ed84"},{"name":"Consultar Transação (Wallet)","id":"30378026-b8b0-4f2a-943f-265afa5e612f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"vspi","value":"","type":"text"},{"key":"vsps","value":"","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"requestNumber\": \"requestNumber\",\n \"idTransaction\": \"idTransaction\",\n \"endToEnd\": \"endToEnd\" // É necessário informar pelo menos um desses campos para localizar a transação.\n}","options":{"raw":{"language":"json"}}},"url":"https://api.versellpay.com/api/v1/gateway/walletTransaction","description":"Esse endpoint permite consultar uma transação disponível na sua wallet dentro da Versell Pay.
\nPAID_OUT - Transação Paga.
WAITING_FOR_APPROVAL - Aguardando Pagamento.
Este endpoint permite consultar, em tempo real, o saldo disponível em sua conta na Versell Pay.
\n","_postman_id":"3ec5dba4-21bb-4e2b-bdbc-de3d8353a3ec"}]}