Criar Link de Pagamento
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.
Faça esta chamada sempre a partir do seu servidor.
Request Body Params
| Atributo | Tipo | Descrição |
|---|---|---|
| item_id | string | Parâmetro opcional. ID do link na sua plataforma. |
| description | string | Parâmetro opcional. Texto exibido ao cliente na tela de confirmação e no extrato. |
| amount | int32 | Valor do pagamento. Deve ser passado em centavos. |
| method | string | Forma 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_account | object | Objeto Conta recebedora. Obrigatório quando method é bank_account. |
| creditor_account[document_number] | string | CNPJ ou CPF do titular da conta recebedora, somente números. |
| creditor_account[ispb] | string | ISPB da instituição recebedora (8 dígitos). |
| creditor_account[agency] | string | Número da agência, sem dígito. |
| creditor_account[account_number] | string | Número da conta, com o dígito verificador. |
| creditor_account[type] | string | Tipo da conta. Valores aceitos: checking (conta corrente), savings (poupança) e payment (conta de pagamento). |
| pix_key | string | Chave Pix do recebedor. Obrigatório quando method é pix_key. |
| qr_code | string | Có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_at | dateTime | Parâmetro opcional. Data de expiração do link no formato ISODateTime. Após esse momento o cliente não consegue mais pagar. |
| customer | object | Objeto Pagador, titular da conta que será debitada. |
| customer[name] | string | Parâmetro opcional. Nome do pagador. |
| customer[document_number] | string | CPF ou CNPJ do pagador, somente números. Envie sempre o mesmo documento para que a jornada reconheça o vínculo. |
| customer[ip_address] | string | Parâ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_entity | object | Parâmetro opcional. Use quando o pagador for pessoa jurídica. |
| business_entity[document_number] | string | CNPJ da empresa pagadora, somente números. |
| participant_id | string | Parâmetro opcional. Banco do pagador, se já conhecido. Pula a etapa de escolha do banco na jornada. |
| redirect_url | string | Parâ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_url | string | Parâmetro opcional. URL para onde o cliente volta em caso de erro na jornada. Se omitido, é usada a redirect_url. |
| webhook_url | string | Parâ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_token | string | Parâ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. |
| metadata | object | Parâmetro opcional. Objeto livre para guardar dados da sua aplicação. É devolvido nas consultas. |
Response Object
| Propriedade | Tipo | Descrição |
|---|---|---|
| link_id | string | ID Marlim do link de pagamento. Guarde este ID: é com ele que você consulta e cancela o link e consulta o pagamento. |
| item_id | string | ID do link na sua plataforma. |
| current_status | string | Status atual do link. No momento da criação, sempre created. Veja Status do Link. |
| payment_url | string | URL para onde o cliente deve ser enviado para pagar. |
| date_created | dateTime | Data de criação do link no formato ISODateTime. |
| expires_at | dateTime | Data de expiração do link no formato ISODateTime. |
Error Object
| Atributo | Tipo | Descrição |
|---|---|---|
| api_reference | string | URL para a documentação. Retornado nos erros de parâmetro. |
| errors | array | Array com todos os erros encontrados ao processar a requisição. |
| errors[][type] | string | Tipo de erro ocorrido. |
| errors[][message] | string | Mensagem detalhada do erro ocorrido. |
Enviando o cliente para o link
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ódigo | Significado |
|---|---|
rejected_by_customer | O cliente recusou o vínculo ou o pagamento no banco. |
authorization_time_expired | O cliente não confirmou dentro do prazo. |
journey_time_expired | O 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.
- 1º Criar Link
- 2º Receber o Webhook
- 3º Consultar o Link
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"
}'
{
"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"
}
curl -X POST "https://suaaplicacao.com.br/webhook" \
-H "Content-Type: application/json" \
-H "User-Agent: Marlim/1.0.0" \
-H "Marlim-Api-Signature: Star98765Wars43210ANewHope1977" \
-H "Authorization: Bearer 1234567890" \
-d '{
"event": "biometric_pix_link_status_changed",
"link_id": "kLo2Pz7XwQ4eRt9YuI1m",
"item_id": "PEDIDO_1139",
"current_status": "error",
"payment_url": "https://checkout.marlim.co/biometric-pix/kLo2Pz7XwQ4eRt9YuI1m",
"error": {
"code": "rejected_by_customer",
"title": "Rejected by customer",
"detail": "The customer rejected the device link at the bank."
},
"metadata": {},
"date_created": "2026-11-16T15:30:00.000Z",
"date_updated": "2026-11-16T15:34:51.000Z",
"expires_at": "2026-11-17T15:30:00.000Z"
}'
curl -X GET "https://sandbox.api.marlim.co/v3/biometric_pix/links/kLo2Pz7XwQ4eRt9YuI1m" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{}'
{
"link_id": "kLo2Pz7XwQ4eRt9YuI1m",
"item_id": "PEDIDO_1139",
"current_status": "error",
"payment_url": "https://checkout.marlim.co/biometric-pix/kLo2Pz7XwQ4eRt9YuI1m",
"error": {
"code": "rejected_by_customer",
"title": "Rejected by customer",
"detail": "The customer rejected the device link at the bank."
},
"metadata": {},
"date_created": "2026-11-16T15:30:00.000Z",
"date_updated": "2026-11-16T15:34:51.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ódigo | Significado |
|---|---|
insufficient_balance | Conta do cliente sem saldo suficiente. |
amount_above_limit | Valor acima do limite de Pix definido pelo cliente no banco. |
refused_by_bank | Recusado pelo banco do cliente. O motivo vem em error.detail. |
reason_not_informed | O 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.
- 1º Criar Link
- 2º Receber o Webhook
- 3º Consultar o Pagamento
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"
}'
{
"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"
}
curl -X POST "https://suaaplicacao.com.br/webhook" \
-H "Content-Type: application/json" \
-H "User-Agent: Marlim/1.0.0" \
-H "Marlim-Api-Signature: Star98765Wars43210ANewHope1977" \
-H "Authorization: Bearer 1234567890" \
-d '{
"event": "biometric_pix_payment_status_changed",
"payment_id": "pMt4Hn7UjM2kIo9LpQ3a",
"link_id": "qAz3Ws8XeD1cRf6VtG4b",
"item_id": "PEDIDO_1141",
"current_status": "rejected",
"amount": 15000,
"description": "Pedido 1141 Cantina Mos Eisley",
"method": "default_account",
"customer": {
"name": "Han Solo",
"document_number": "00077766655"
},
"participant": {
"participant_id": "c8f0bf49-4744-4933-8960-7add6e590841",
"name": "Banco da Aliança"
},
"end_to_end_id": null,
"error": {
"code": "refused_by_bank",
"title": "Payment refused",
"detail": "Payment refused by the account holding institution."
},
"metadata": {},
"date_created": "2026-11-16T18:02:11.000Z",
"date_updated": "2026-11-16T18:02:19.540Z"
}'
curl -X GET "https://sandbox.api.marlim.co/v3/biometric_pix/links/qAz3Ws8XeD1cRf6VtG4b/payment" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{}'
{
"payment_id": "pMt4Hn7UjM2kIo9LpQ3a",
"link_id": "qAz3Ws8XeD1cRf6VtG4b",
"item_id": "PEDIDO_1141",
"current_status": "rejected",
"amount": 15000,
"description": "Pedido 1141 Cantina Mos Eisley",
"method": "default_account",
"customer": {
"name": "Han Solo",
"document_number": "00077766655"
},
"participant": {
"participant_id": "c8f0bf49-4744-4933-8960-7add6e590841",
"name": "Banco da Aliança"
},
"end_to_end_id": null,
"error": {
"code": "refused_by_bank",
"title": "Payment refused",
"detail": "Payment refused by the account holding institution."
},
"metadata": {},
"date_created": "2026-11-16T18:02:11.000Z",
"date_updated": "2026-11-16T18:02:19.540Z"
}
Exemplos
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
- Conta padrão
- Chave Pix
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"
}
}'
{
"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"
}
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"
}'
{
"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"
}
Erros
- Parâmetros inválidos
- Chave Pix ausente
- Valor diferente do QR Code
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"
}'
{
"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."
}
]
}
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": 4500,
"method": "pix_key",
"customer": {
"document_number": "00055544433"
}
}'
{
"api_reference": "https://docs.api.marlim.co/biometric-pix/links/create",
"errors": [
{
"type": "pix_key",
"message": "The parameter [ pix_key ] is required when [ method ] is pix_key."
}
]
}
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": 5000,
"method": "qr_code",
"qr_code": "00020101021226870014br.gov.bcb.pix2565qrcode.exemplo.com.br/pix/v2/cobv/9d36b84f5204000053039865406120.005802BR5925CANTINA MOS EISLEY LTDA6009SAO PAULO62070503***6304ABCD",
"customer": {
"document_number": "00055544433"
}
}'
{
"api_reference": "https://docs.api.marlim.co/biometric-pix/links/create",
"errors": [
{
"type": "amount",
"message": "The parameter [ amount ] must be equal to the amount of the [ qr_code ]."
}
]
}