Pular para o conteúdo principal

Criar Link de Pagamento

Disponível apenas em Sandbox

Este endpoint está disponível somente no ambiente Sandbox. Não há suporte para Pix por Biometria em produção no momento.

O Pix por Biometria não está disponível para todas as contas e depende de habilitação prévia pela Marlim. Para verificar a elegibilidade da sua conta, entre em contato com o nosso time comercial.

Use esta rota para criar o link onde o cliente faz o vínculo do aparelho, quando necessário, e confirma o pagamento com biometria. A resposta traz a payment_url para onde o cliente deve ser enviado.

POSTv3/biometric_pix/links
Atenção

Faça esta chamada sempre a partir do seu servidor.

Request Body Params​

AtributoTipoDescrição
item_idstringParâmetro opcional. ID do link na sua plataforma.
descriptionstringParâmetro opcional. Texto exibido ao cliente na tela de confirmação e no extrato.
amountint32Valor do pagamento. Deve ser passado em centavos.
methodstringForma de recebimento.

Valores aceitos: default_account (conta de recebimento cadastrada na sua conta Marlim), bank_account (conta informada em creditor_account), pix_key (chave informada em pix_key) e qr_code (código informado em qr_code).
creditor_accountobjectObjeto Conta recebedora. Obrigatório quando method é bank_account.
creditor_account[document_number]stringCNPJ ou CPF do titular da conta recebedora, somente números.
creditor_account[ispb]stringISPB da instituição recebedora (8 dígitos).
creditor_account[agency]stringNúmero da agência, sem dígito.
creditor_account[account_number]stringNúmero da conta, com o dígito verificador.
creditor_account[type]stringTipo da conta.

Valores aceitos: checking (conta corrente), savings (poupança) e payment (conta de pagamento).
pix_keystringChave Pix do recebedor. Obrigatório quando method é pix_key.
qr_codestringCódigo Pix Copia e Cola do recebedor. Obrigatório quando method é qr_code. Se o código tiver valor, ele deve ser igual ao amount.
expires_atdateTimeParâmetro opcional. Data de expiração do link no formato ISODateTime. Após esse momento o cliente não consegue mais pagar.
customerobjectObjeto Pagador, titular da conta que será debitada.
customer[name]stringParâmetro opcional. Nome do pagador.
customer[document_number]stringCPF ou CNPJ do pagador, somente números. Envie sempre o mesmo documento para que a jornada reconheça o vínculo.
customer[ip_address]stringParâmetro opcional do endereço IP público do cliente ao acessar a sua página de checkout no formato IPv4 ou IPv6. Recomendado, pois é usado na análise de risco.
business_entityobjectParâmetro opcional. Use quando o pagador for pessoa jurídica.
business_entity[document_number]stringCNPJ da empresa pagadora, somente números.
participant_idstringParâmetro opcional. Banco do pagador, se já conhecido. Pula a etapa de escolha do banco na jornada.
redirect_urlstringParâmetro opcional. URL para onde o cliente volta após concluir o pagamento. Recomendado quando a jornada começa no seu site ou app. Se omitido, a jornada termina na tela de conclusão da Marlim.
redirect_on_error_urlstringParâmetro opcional. URL para onde o cliente volta em caso de erro na jornada. Se omitido, é usada a redirect_url.
webhook_urlstringParâmetro opcional para passar o endpoint do seu sistema que receberá as mudanças de status do link e do pagamento. Veja Webhooks.
webhook_auth_tokenstringParâmetro opcional para autenticar as notificações enviadas para o webhook_url. Caso o parâmetro não seja informado, as notificações serão enviadas sem autenticação.
metadataobjectParâmetro opcional. Objeto livre para guardar dados da sua aplicação. É devolvido nas consultas.

Response Object​

PropriedadeTipoDescrição
link_idstringID Marlim do link de pagamento. Guarde este ID: é com ele que você consulta e cancela o link e consulta o pagamento.
item_idstringID do link na sua plataforma.
current_statusstringStatus atual do link. No momento da criação, sempre created. Veja Status do Link.
payment_urlstringURL para onde o cliente deve ser enviado para pagar.
date_createddateTimeData de criação do link no formato ISODateTime.
expires_atdateTimeData de expiração do link no formato ISODateTime.

Error Object​

AtributoTipoDescrição
api_referencestringURL para a documentação. Retornado nos erros de parâmetro.
errorsarrayArray com todos os erros encontrados ao processar a requisição.
errors[][type]stringTipo de erro ocorrido.
errors[][message]stringMensagem detalhada do erro ocorrido.

Redirecione o cliente para a payment_url pelo servidor ou exiba um botão na sua página. Botões com âncora <a> costumam converter melhor do que redirecionamentos automáticos.

// Pelo servidor
redirect(link.payment_url)

// Pela interface
<a href={link.payment_url}>Pagar com Pix por Biometria</a>

A partir daqui, acompanhe o resultado pelos webhooks ou pela consulta do pagamento.

Recusa do Cliente​

A criação do link é síncrona e sempre responde com current_status igual a created. Os erros que acontecem durante a jornada, como o cliente recusar o vínculo ou o pagamento no banco, não são retornados nesta chamada: eles chegam depois pelo webhook biometric_pix_link_status_changed, com o current_status igual a error e o código da recusa em error.code.

CódigoSignificado
rejected_by_customerO cliente recusou o vínculo ou o pagamento no banco.
authorization_time_expiredO cliente não confirmou dentro do prazo.
journey_time_expiredO cliente não finalizou a jornada a tempo.

Para esses códigos, pergunte ao cliente se ele quer tentar de novo e crie um novo link. A lista completa está em Rejeições da Jornada.

🕹  Criar um link e receber a recusa do cliente com rejected_by_customer.
Request
curl -X POST "https://sandbox.api.marlim.co/v3/biometric_pix/links" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"item_id": "PEDIDO_1139",
"description": "Pedido 1139 Cantina Mos Eisley",
"amount": 4500,
"method": "pix_key",
"pix_key": "financeiro@cantinamoseisley.com.br",
"customer": {
"name": "Chewbacca",
"document_number": "00055544433"
},
"redirect_url": "https://suaaplicacao.com.br/pedido/1139",
"webhook_url": "https://suaaplicacao.com.br/webhook"
}'
Response200
{
"link_id": "kLo2Pz7XwQ4eRt9YuI1m",
"item_id": "PEDIDO_1139",
"current_status": "created",
"payment_url": "https://checkout.marlim.co/biometric-pix/kLo2Pz7XwQ4eRt9YuI1m",
"date_created": "2026-11-16T15:30:00.000Z",
"expires_at": "2026-11-17T15:30:00.000Z"
}

Recusa do Banco​

Depois que o cliente confirma, o pagamento ainda pode ser recusado pelo banco do cliente ou pelo SPI. Nesse caso, o webhook biometric_pix_payment_status_changed chega com o current_status igual a rejected e o código da recusa em error.code. Os mais comuns estão abaixo.

CódigoSignificado
insufficient_balanceConta do cliente sem saldo suficiente.
amount_above_limitValor acima do limite de Pix definido pelo cliente no banco.
refused_by_bankRecusado pelo banco do cliente. O motivo vem em error.detail.
reason_not_informedO banco do cliente não informou o motivo (pode ter sido bloqueio do antifraude do banco).

A lista completa e a ação recomendada para cada código estão em Rejeições de Pagamento.

🕹  Criar um link e receber a recusa do banco com refused_by_bank.
Request
curl -X POST "https://sandbox.api.marlim.co/v3/biometric_pix/links" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"item_id": "PEDIDO_1141",
"description": "Pedido 1141 Cantina Mos Eisley",
"amount": 15000,
"method": "default_account",
"customer": {
"name": "Han Solo",
"document_number": "00077766655"
},
"redirect_url": "https://suaaplicacao.com.br/pedido/1141",
"webhook_url": "https://suaaplicacao.com.br/webhook"
}'
Response200
{
"link_id": "qAz3Ws8XeD1cRf6VtG4b",
"item_id": "PEDIDO_1141",
"current_status": "created",
"payment_url": "https://checkout.marlim.co/biometric-pix/qAz3Ws8XeD1cRf6VtG4b",
"date_created": "2026-11-16T18:00:40.000Z",
"expires_at": "2026-11-17T18:00:40.000Z"
}

Exemplos​

ATENÇÃO

Os valores utilizados nos exemplos abaixo são apenas para ilustração e não devem ser usados para fazer requests nas APIs da Marlim. Em ambiente de desenvolvimento e testes, utilize dados mais próximos de uma transação real.

Sucesso​

Request
curl -X POST "https://sandbox.api.marlim.co/v3/biometric_pix/links" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"item_id": "PEDIDO_1138",
"description": "Pedido 1138 Cantina Mos Eisley",
"amount": 8990,
"method": "default_account",
"expires_at": "2026-11-16T15:19:18.000Z",
"customer": {
"name": "Han Solo",
"document_number": "00077766655",
"ip_address": "200.150.10.20"
},
"redirect_url": "https://suaaplicacao.com.br/pedido/1138",
"webhook_url": "https://suaaplicacao.com.br/webhook",
"webhook_auth_token": "1234567890",
"metadata": {
"canal": "app"
}
}'
Response200
{
"link_id": "bIo6Lm3NqZ8tRw1YcV5k",
"item_id": "PEDIDO_1138",
"current_status": "created",
"payment_url": "https://checkout.marlim.co/biometric-pix/bIo6Lm3NqZ8tRw1YcV5k",
"date_created": "2026-11-16T14:19:18.051Z",
"expires_at": "2026-11-16T15:19:18.000Z"
}

Erros​

Request
curl -X POST "https://sandbox.api.marlim.co/v3/biometric_pix/links" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
"amount": 8990,
"method": "boleto",
"redirect_url": "https://suaaplicacao.com.br/pedido/1138"
}'
Response400
{
"api_reference": "https://docs.api.marlim.co/biometric-pix/links/create",
"errors": [
{
"type": "method",
"message": "The parameter [ method ] must be one of: default_account, bank_account, pix_key, qr_code."
},
{
"type": "customer",
"message": "The parameter [ customer.document_number ] is missing."
}
]
}