Integração com Validador
O Validador de Compra da Marlim permite confirmar a identidade do portador do cartão no momento da transação, diretamente no fluxo de checkout. Quando acionado, o comprador é solicitado a se autenticar por um ou mais métodos de validação definidos pela análise de risco da transação — como OTP por e-mail, OTP por telefone ou microtransação via Octopus.
Isso reduz fraudes e chargebacks sem adicionar atrito desnecessário para o comprador.
SDK
Instalação
CDN
<script src="https://cdn.validator.marlim.co/sdk.min.js"></script>
Essa URL usa a versão mais recente publicada no CDN. Para fixar uma versão específica, use o caminho versionado:
<script src="https://cdn.validator.marlim.co/v1.0.0/sdk.min.js"></script>
NPM
npm install marlim-sdk-validator
Autenticação pré-transação
O primeiro passo para utilizar o Validador da Marlim é gerar um validator_authentication_id através da nossa API. Esse identificador é obrigatório para sinalizar que o seller possui a integração do Validador habilitada e está apto a participar do fluxo de validação quando o fluxo de segurança solicitar essa etapa.
O validator_authentication_id funciona como uma credencial temporária vinculada à tentativa de transação. Sem ele, a transação segue o fluxo padrão e não poderá entrar em pending_user_validation.
Como essa geração exige a sua api_key, ela deve ser feita no backend da sua integração:
curl -X POST "https://api.marlim.co/v3/validator/init" \
-H "api_key: sua-api-key" \
-d '{}'
{
"validator_authentication_id": "8c8a0a5d-6fcb-449f-8cc8-2bbca3b2ed29",
"expires_at": "2026-04-29T14:35:00.000Z"
}
O validator_authentication_id tem validade curta, é de uso único e deve ser usado somente na criação de uma única transação. Ele não é a sessão do validador e não abre a interface de validação por si só.
Esse valor é um identificador opaco retornado pela API da Marlim. Trate-o apenas como uma string única vinculada à transação, sem tentar decodificar, assinar ou reutilizar esse valor.
O validator_authentication_id deve ser gerado pelo seu backend para não expor sua api_key no frontend. Nunca faça essa chamada diretamente do cliente.
Inicialização
Após gerar o validator_authentication_id no backend da sua integração, envie esse identificador na criação da transação.
{
"validator_authentication_id": "8c8a0a5d-6fcb-449f-8cc8-2bbca3b2ed29",
"amount": 1000,
"installments": "1",
"..."
}
Se a análise da transação indicar necessidade de validação adicional, a resposta da transação retorna o status pending_user_validation e a sessão que deve ser usada no SDK:
{
"status": "pending_user_validation",
"transaction_id": "transaction_123",
"session": {
"session_token": "eyJhbGciOiJIUzI1NiIs...",
"created_at": 1777471200000,
"expires_at": 1777485600000
},
"..."
}
O validator_authentication_id deve ser enviado no mesmo payload da transação, junto com os demais campos obrigatórios. Para ver o payload completo, consulte nossa documentação de criação de transação com cartão.
A presença do validator_authentication_id não obriga a validação a acontecer. Ele apenas sinaliza para a Marlim que esse seller tem o Validador integrado. A validação só é disparada se a análise da transação indicar necessidade de validação adicional.
Mesmo quando o fluxo de segurança não solicitar validação adicional, o validator_authentication_id continua pertencendo somente àquela tentativa de transação e não pode ser reutilizado em outra.
Simulação em Sandbox
Em ambiente Sandbox, você pode forçar quais métodos do Validador serão solicitados usando simulate_validator na criação da transação. Esse campo deve ser enviado junto com validator_authentication_id:
{
"validator_authentication_id": "8c8a0a5d-6fcb-449f-8cc8-2bbca3b2ed29",
"simulate_validator": ["otp_phone"],
"amount": 1000,
"installments": "1",
"..."
}
Valores aceitos:
| Valor | Comportamento |
|---|---|
| octopus | Solicita validação por microtransação Octopus. |
| otp_email | Solicita validação por código enviado ao e-mail do comprador. |
| otp_phone | Solicita validação por código enviado ao telefone do comprador. |
Você também pode combinar métodos, por exemplo: ["octopus", "otp_email"].
O parâmetro simulate_validator só é aceito em ambiente Sandbox. Em Produção, esse campo é rejeitado.
No frontend, use o SDK apenas se a transação voltar pending_user_validation:
if (transaction.status === 'pending_user_validation') {
await MarlimSDK_Validator.init({
token: transaction.session.session_token,
env: 'sandbox', // ou 'production'
mode: 'modal', // 'modal' | 'redirect' | 'standalone'
soft_descriptor_validator: 'Loja Exemplo 1',
on_finish: ({ status, payload }) => {
console.log(status); // 'success' | 'error'
console.log(payload); // resultado da experiência de validação
},
});
}
O campo soft_descriptor_validator é opcional, aceita no máximo 30 caracteres e define o nome exibido nas telas do Validador quando a integração representa uma loja ou subseller diferente do seller principal. Se não for informado, o Validador usa o nome do seller associado à transação.
Use soft_descriptor_validator apenas como dado de exibição para o comprador. Para regras financeiras, antifraude, conciliação, split, cobrança ou auditoria, continue usando os identificadores e dados canônicos da transação, do seller e do sub_seller.
O Validador também pode ser adaptado para ficar mais próximo da identidade da sua marca, incluindo cor do cabeçalho e logo. Para habilitar essa personalização, entre em contato com a equipe Marlim.
Experiência do comprador
A interface do Validador é exibida somente quando a transação retorna pending_user_validation. Nessa etapa, o comprador vê um resumo da compra, o prazo para concluir a validação e o método solicitado para aquela transação.
Validador aberto em modo modal após a transação retornar pending_user_validation. A tela exibe o resumo da compra, o prazo para conclusão e o método de validação solicitado para aquela sessão.
Modos de Comportamento do Validador
| Modo | Comportamento |
|---|---|
| modal | Abre a interface de validação em um iframe sobre a página atual. O comprador valida sem sair do checkout. |
| redirect | Redireciona o comprador para a página de validação. Ao concluir, direciona para a `redirect_url` informada na integração. Se nenhuma `redirect_url` for informada, o SDK direciona para a página padrão de conclusão. |
| standalone | Gera um link externo que pode ser enviado por WhatsApp, e-mail ou SMS. O comprador abre em qualquer browser e valida de forma assíncrona. |
Validador aberto em página externa. O conteúdo da validação é o mesmo do modo modal, mas a experiência ocupa a própria página do navegador em vez de aparecer sobre o checkout.
Modo standalone
No modo standalone, se a transação entrar em pending_user_validation, use o session_token retornado pela transação para gerar um link de validação:
const { validation_url } = await MarlimSDK_Validator.init({
token: transaction.session.session_token,
env: 'sandbox', // ou 'production'
mode: 'standalone',
});
// Envie validation_url por WhatsApp, e-mail ou SMS
console.log(validation_url);
O link gerado pode ser reaberto pelo comprador quantas vezes precisar dentro da validade de acesso.
No modo standalone, o validation_url gerado fica válido por 4 horas para acesso ao Validador. Depois que o comprador abre o link, ele inicia uma sessão de validação com prazo próprio para concluir os desafios.
Propriedades
| Atributo | Tipo | Descrição |
|---|---|---|
| token | string | Parâmetro obrigatório. Token retornado pela transação em pending_user_validation. É usado para iniciar o fluxo do validador no frontend. |
| env | string | Parâmetro opcional. Ambiente da integração. Valores aceitos: sandbox, production. Recomendamos informar explicitamente. |
| mode | string | Parâmetro opcional. Modo de abertura do validador. Valores aceitos: modal, redirect, standalone. Padrão: modal. Valores diferentes são rejeitados no início da sessão de validação. |
| redirect_url | string | Parâmetro opcional. URL para onde o comprador será redirecionado após concluir a validação nos modos redirect e modal. O SDK adiciona o resultado na query string dessa URL: status, data e, quando houver, display_name. Exemplo de leitura: new URLSearchParams(window.location.search).get('data'). Exemplo de destino final: https://lojaexemplo.com.br/obrigado?status=success&data=.... |
| soft_descriptor_validator | string | Parâmetro opcional. Nome de exibição da loja ou subseller nas telas do Validador. Máximo de 30 caracteres. Use quando o comprador deve ver um nome diferente do seller principal. |
| on_success | function | Parâmetro opcional. Callback chamado quando a validação é concluída com sucesso. Disponível no modo modal. Recebe o payload da validação. |
| on_error | function | Parâmetro opcional. Callback chamado quando a validação termina com erro. Disponível no modo modal. Recebe o payload do erro. |
| on_finish | function | Parâmetro opcional. Callback chamado ao final da validação, independente do resultado. Disponível no modo modal. Recebe { status, payload }. Quando definido, o redirecionamento automático não ocorre. Em bloqueio por excesso de tentativas, o callback é disparado automaticamente; o botão Fechar apenas fecha o modal. |
No modo modal, o SDK chama on_success ou on_error conforme o resultado. Se on_finish também estiver definido, ele é chamado depois do callback específico. Quando on_finish é definido, o redirecionamento automático não ocorre, a menos que você também informe redirect_url. Se não houver redirect_url nem on_finish, o SDK direciona o comprador para a página padrão /validation/obrigado.
Retornos por etapa
O fluxo possui retornos em momentos diferentes da integração:
| Etapa | Retorno | Uso |
|---|---|---|
| Autenticação pré-transação | validator_authentication_id | Retornado por POST /v3/validator/init no backend da sua integração. Deve ser enviado na criação da transação em POST /v3/transactions. |
| Criação da transação | session.session_token | Retornado somente quando a transação fica com status pending_user_validation. Esse token inicia o Validador no frontend. |
| SDK em modo standalone | validation_url | Retornado por MarlimSDK_Validator.init() apenas quando mode é standalone. Envie esse link ao comprador por WhatsApp, e-mail ou SMS. |
Métodos de validação
Os métodos de validação são definidos automaticamente pelo motor de antifraude, com base na análise de risco da transação. O vendedor não escolhe quais métodos serão exigidos — essa decisão é feita em tempo real pelo antifraude, que pode solicitar um ou mais métodos em sequência dependendo do perfil de risco identificado.
| Método | Descrição |
|---|---|
| otp_email | Código de verificação enviado para o e-mail do comprador. |
| otp_phone | Código de verificação enviado por SMS ou WhatsApp para o telefone do comprador. |
| octopus | Validação via micro transação: um valor aleatório entre R$ 1,00 e R$ 3,00 é cobrado no cartão e o comprador deve informar o valor exato. |
Tempo de validade da validação
O controle de tempo do Validador acontece em duas janelas independentes:
- Janela de acesso: forma como o comprador chega à tela de validação. Em
modaleredirect, o acesso acontece imediatamente após o SDK iniciar. Emstandalone, o link pode ser aberto depois. - Janela de validação: tempo que o comprador tem para concluir os desafios depois que a tela de validação carrega. São sempre 10 minutos e a contagem só começa quando a tela carrega — não na chamada de
init().
| Modo | Janela de acesso | Janela de validação | Observação |
|---|---|---|---|
| modal | Imediata | 10 minutos | A tela abre sobre o checkout assim que o SDK inicia a sessão. Os 10 minutos de validação começam quando a tela carrega. |
| redirect | Imediata | 10 minutos | O SDK redireciona o comprador para a tela de validação assim que a sessão inicia. Os 10 minutos de validação começam quando a tela carrega; ao concluir, segue para a URL de conclusão configurada. |
| standalone | 4 horas | 10 minutos | O link pode ser enviado por WhatsApp, e-mail ou SMS e fica acessível por 4 horas. Ao abrir o link e a tela carregar, começam os 10 minutos para validar. |
As duas janelas funcionam em sequência e cada uma expira por conta própria:
- A janela de acesso começa na chamada de
init(). Emmodaleredirect, o acesso é imediato porque o SDK abre ou redireciona para a tela de validação na hora. Emstandalone, o link permanece acessível por 4 horas antes de ser aberto. - A janela de validação (10 minutos) começa apenas quando a tela de validação carrega, igual nos três modos. É esse o prazo exibido ao comprador para concluir os desafios.
Se a janela de acesso expirar antes de a tela carregar, ou se a janela de validação expirar sem conclusão, a sessão expira e a transação segue automaticamente para o fluxo de resolução configurado.
Resultado da validação
Ao concluir a validação (via on_finish ou redirect), você receberá:
| Propriedade | Tipo | Descrição |
|---|---|---|
| status | string | Resultado da validação: success ou error. |
| payload | object | Informações para a tomada de decisão do seu frontend: traz o resultado da experiência de validação no checkout, incluindo os métodos executados e o status da captura no momento do callback. |
type ValidatorFinishResult = {
status: 'success' | 'error';
payload: {
timestamp: string;
reason?: 'blocked' | 'session_expired' | 'validation_failed';
payment: {
action: 'capture_pending' | 'captured' | 'cancel_requested' | 'manual_challenge';
captureStatus?: 'pending' | 'captured';
};
validations: Array<{
method: 'otp_email' | 'otp_phone' | 'octopus';
verified: boolean;
reason?: 'blocked' | 'session_expired' | 'validation_failed';
}>;
};
};
| Campo | Descrição |
|---|---|
| status | Resultado geral da experiência de validação. success significa que todas as validações exigidas foram concluídas. error significa que o fluxo terminou sem aprovação. |
| payload.timestamp | Data/hora em que o fluxo terminou. |
| payload.reason | Motivo geral quando status é error. Pode ser blocked, session_expired ou validation_failed. |
| payload.payment.action | Ação financeira/resolução disparada no momento do callback. captured indica captura confirmada. capture_pending indica captura solicitada ou ainda não confirmada. cancel_requested indica que a validação falhou e o cancelamento/refund da pré-autorização foi solicitado. manual_challenge indica que a transação voltou para análise manual. |
| payload.payment.captureStatus | Status da captura quando houver caminho de captura. Pode ser pending ou captured. |
| payload.validations | Lista das validações executadas. Sempre é retornada como array, mesmo quando há apenas uma validação. |
| payload.validations[].method | Método executado na etapa. |
| payload.validations[].verified | Indica se aquela etapa específica foi validada. |
| payload.validations[].reason | Motivo do erro da etapa, quando houver. |
O callback do SDK indica o resultado da experiência de validação no checkout. Ele não substitui o webhook nem a consulta da transação para confirmação financeira.
Mesmo quando status for success, libere o pedido somente após confirmar que a transação está paid via webhook ou consulta da transação.
Se payload.payment.action for cancel_requested, a validação terminou sem aprovação e o cancelamento/refund da pré-autorização foi solicitado.
Se payload.payment.action for capture_pending ou payload.payment.captureStatus for pending, a validação foi aprovada, mas a captura ainda não foi confirmada.
{
"status": "success",
"payload": {
"timestamp": "2026-04-17T14:30:00.000Z",
"payment": {
"action": "captured",
"captureStatus": "captured"
},
"validations": [
{ "method": "otp_email", "verified": true }
]
}
}
{
"status": "success",
"payload": {
"timestamp": "2026-04-17T14:32:00.000Z",
"payment": {
"action": "capture_pending",
"captureStatus": "pending"
},
"validations": [
{ "method": "otp_email", "verified": true },
{ "method": "octopus", "verified": true }
]
}
}
{
"status": "error",
"payload": {
"timestamp": "2026-04-17T14:35:00.000Z",
"reason": "blocked",
"payment": {
"action": "cancel_requested"
},
"validations": [
{ "method": "otp_email", "verified": true },
{ "method": "octopus", "verified": false, "reason": "blocked" }
]
}
}
{
"status": "error",
"payload": {
"timestamp": "2026-04-17T14:40:00.000Z",
"reason": "session_expired",
"payment": {
"action": "cancel_requested"
},
"validations": []
}
}
Tela final do comprador
Esta tela pode ser exibida quando o SDK usa a página padrão de conclusão, por exemplo quando não há uma redirect_url própria configurada ou quando a integração opta por encerrar o fluxo dentro da experiência padrão do Validador. Se a sua integração informar uma URL de conclusão, o comprador pode ser direcionado para uma tela própria da loja. Em qualquer caso, essa confirmação encerra apenas a experiência do comprador; a liberação do pedido deve continuar considerando o webhook ou a consulta da transação.
Resultado da transação
Validação concluída com sucesso
Quando o comprador conclui todos os desafios de validação, a transação é capturada automaticamente. Você receberá um webhook com o status paid, caso tenha configurado um webhook_url ao criar a transação.
O payload recebido segue o mesmo contrato de webhook de transação documentado em Webhook URL. Para validação concluída com sucesso, o campo current_status será paid.
Prazo expirado sem validação
Se o comprador não concluir a validação dentro do prazo, a transação é cancelada automaticamente e o valor autorizado é estornado ao portador do cartão. Você receberá um webhook com o status refunded.
O payload recebido segue o mesmo contrato de webhook de transação documentado em Webhook URL. Para expiração sem validação, o campo current_status será refunded.
Se sua conta tiver o recurso de revisão manual habilitado, a equipe Marlim pode intervir antes do cancelamento e analisar a transação manualmente. Nesse caso, a transação entra em revisão e você recebe um webhook com current_status igual a review — o valor segue autorizado e reservado no cartão, mas ainda não capturado. Após a análise, você recebe um novo webhook com a resolução final: paid se a revisão aprovar ou refunded se recusar. Todos seguem o mesmo contrato documentado em Webhook URL.
Para criar uma transação, consulte nossa documentação sobre como criar uma transação com cartão.