Iniciar jornada Pix com biometria

curl --request POST \
  --url https://gateway.staging.azentech.dev/api/pix/journey \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 25,
  "merchant_transaction_id": "50000000-0000-4000-8000-000000000006",
  "document_number": "12345678909",
  "widget_description": "Pagamento de exemplo",
  "payer_bank_description": "AZENTECH DEMO"
}
'

import requests

url = "https://gateway.staging.azentech.dev/api/pix/journey"

payload = {
    "amount": 25,
    "merchant_transaction_id": "50000000-0000-4000-8000-000000000006",
    "document_number": "12345678909",
    "widget_description": "Pagamento de exemplo",
    "payer_bank_description": "AZENTECH DEMO"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 25,
    merchant_transaction_id: '50000000-0000-4000-8000-000000000006',
    document_number: '12345678909',
    widget_description: 'Pagamento de exemplo',
    payer_bank_description: 'AZENTECH DEMO'
  })
};

fetch('https://gateway.staging.azentech.dev/api/pix/journey', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "transaction": {
    "id": "10000000-0000-4000-8000-000000000001",
    "merchant_id": "20000000-0000-4000-8000-000000000001",
    "user_id": "30000000-0000-4000-8000-000000000001",
    "processor_id": "40000000-0000-4000-8000-000000000001",
    "merchant_transaction_id": "50000000-0000-4000-8000-000000000006",
    "transaction_type": "pix",
    "first_name": "Cliente",
    "last_name": "Exemplo",
    "email": "cliente@example.com",
    "updated_at": "2026-10-23T14:30:00+00:00",
    "created_at": "2026-10-23T14:30:00+00:00",
    "events": [
      {
        "id": "60000000-0000-4000-8000-000000000001",
        "success": true,
        "status": "success",
        "event_type": "auth",
        "amount": "25.00",
        "ip_address": null,
        "processor_code": null,
        "processor_message": null,
        "processor_transaction_id": "sandbox-event-1001",
        "batch_id": null,
        "qrcode": "00020101021226850014br.gov.bcb.pix2563example.invalid/pix/1001",
        "qrcode_image": "",
        "pix_key_type": null,
        "pix_key_value": null,
        "pix_message": "Jornada Pix com Biometria para: CONTA DEMO",
        "updated_at": "2026-10-23T14:30:00+00:00",
        "created_at": "2026-10-23T14:30:00+00:00"
      }
    ],
    "document_number": "12345678909",
    "status": "pending",
    "flow_type": "cashin",
    "error": null,
    "e2e_id": null,
    "source": "player",
    "tag": null
  },
  "url": "https://journey.example/10000000-0000-4000-8000-000000000001"
}

POST

api

pix

journey

Iniciar jornada Pix com biometria

curl --request POST \
  --url https://gateway.staging.azentech.dev/api/pix/journey \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 25,
  "merchant_transaction_id": "50000000-0000-4000-8000-000000000006",
  "document_number": "12345678909",
  "widget_description": "Pagamento de exemplo",
  "payer_bank_description": "AZENTECH DEMO"
}
'

import requests

url = "https://gateway.staging.azentech.dev/api/pix/journey"

payload = {
    "amount": 25,
    "merchant_transaction_id": "50000000-0000-4000-8000-000000000006",
    "document_number": "12345678909",
    "widget_description": "Pagamento de exemplo",
    "payer_bank_description": "AZENTECH DEMO"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 25,
    merchant_transaction_id: '50000000-0000-4000-8000-000000000006',
    document_number: '12345678909',
    widget_description: 'Pagamento de exemplo',
    payer_bank_description: 'AZENTECH DEMO'
  })
};

fetch('https://gateway.staging.azentech.dev/api/pix/journey', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "transaction": {
    "id": "10000000-0000-4000-8000-000000000001",
    "merchant_id": "20000000-0000-4000-8000-000000000001",
    "user_id": "30000000-0000-4000-8000-000000000001",
    "processor_id": "40000000-0000-4000-8000-000000000001",
    "merchant_transaction_id": "50000000-0000-4000-8000-000000000006",
    "transaction_type": "pix",
    "first_name": "Cliente",
    "last_name": "Exemplo",
    "email": "cliente@example.com",
    "updated_at": "2026-10-23T14:30:00+00:00",
    "created_at": "2026-10-23T14:30:00+00:00",
    "events": [
      {
        "id": "60000000-0000-4000-8000-000000000001",
        "success": true,
        "status": "success",
        "event_type": "auth",
        "amount": "25.00",
        "ip_address": null,
        "processor_code": null,
        "processor_message": null,
        "processor_transaction_id": "sandbox-event-1001",
        "batch_id": null,
        "qrcode": "00020101021226850014br.gov.bcb.pix2563example.invalid/pix/1001",
        "qrcode_image": "",
        "pix_key_type": null,
        "pix_key_value": null,
        "pix_message": "Jornada Pix com Biometria para: CONTA DEMO",
        "updated_at": "2026-10-23T14:30:00+00:00",
        "created_at": "2026-10-23T14:30:00+00:00"
      }
    ],
    "document_number": "12345678909",
    "status": "pending",
    "flow_type": "cashin",
    "error": null,
    "e2e_id": null,
    "source": "player",
    "tag": null
  },
  "url": "https://journey.example/10000000-0000-4000-8000-000000000001"
}

Comportamento observado

urls_callback é um objeto. Se o objeto for enviado, envie as URLs success e failure.
A configuração do processador ainda pode exigir nome, email, telefone, documento e endereço.
Envie sempre document_number: a execução da jornada e a criação da transação podem lê-lo mesmo quando a validação condicional não o exige.
Quando is_biometrics_pix não é enviado, o Gateway define o valor como true.
Quando pix_message não é enviado, o Gateway usa Jornada Pix com Biometria para: {alias do processador}.
Os limites mínimo e máximo do processador também são aplicados ao valor.
A validade da URL e o comportamento do widget dependem do processador ativo.
A jornada biométrica exige um processador que ofereça essa operação. A implementação atual da LBPay não é elegível. Se a seleção escolher LBPay, o Gateway devolve o erro genérico HTTP 500.

Os exemplos usam identificadores e credenciais sintéticos. Os resultados do processador dependem do credenciamento e da configuração do estabelecimento.

Authorizations

Authorization

string

header

required

Token de acesso fornecido para o estabelecimento.

Body

application/json

amount

number

required

Valor em reais, com no máximo duas casas decimais. Deve ser maior que zero e menor que 99.999.999 antes da aplicação dos limites do processador.

Must be a multiple of 0.01

merchant_transaction_id

string

required

Identificador da transação no estabelecimento.

Maximum string length: 255

document_number

string | null

required

CPF ou CNPJ. A obrigatoriedade depende da configuração do processador.

Texto exibido no widget.

Maximum string length: 255

payer_bank_description

string

required

Texto exibido no extrato do pagador.

Maximum string length: 255

first_name

string | null

Nome. Pode se tornar obrigatório conforme a configuração do processador.

Maximum string length: 255

last_name

string | null

Sobrenome. Pode se tornar obrigatório conforme a configuração do processador.

Maximum string length: 255

string<email> | null

Email. Pode se tornar obrigatório conforme a configuração do processador.

Maximum string length: 255

mobile_phone

string | null

Telefone. O validador usa o nome mobile_phone e pode torná-lo obrigatório conforme o processador.

Maximum string length: 15

phone_number

string | null

Telefone lido pelo processador e persistido na transação. Quando o telefone for exigido, envie também mobile_phone com o mesmo valor.

Maximum string length: 15

ip_address

string | null

Endereço IP do pagador. O valor segue para o processador e para o evento da transação.

bank_accounts_allowed

object[] | null

Contas bancárias permitidas para o pagamento. O controller não valida o formato; os campos aceitos e seu efeito dependem do processador ativo.

Show child attributes

processor_id

string<uuid> | null

UUID do processador. Na seleção comum, o Gateway usa o primeiro Pix habilitado por precedência; este campo só restringe a seleção quando source é settlement.

dynamic_descriptor

string | null

Descrição dinâmica opcional, com até 38 caracteres.

Maximum string length: 38

street_address_1

string | null

Primeira linha do endereço. Pode ser obrigatória conforme o processador.

Maximum string length: 255

street_address_2

string | null

Segunda linha do endereço.

Maximum string length: 255

city

string | null

Cidade. Pode ser obrigatória conforme o processador.

Maximum string length: 255

state

string | null

Estado alfanumérico. Pode ser obrigatório conforme o processador.

Maximum string length: 3

country

string | null

País em código alfanumérico de dois caracteres. Pode ser obrigatório conforme o processador.

Required string length: 2

zip

string | null

CEP, com pelo menos dois caracteres.

Minimum string length: 2

shipping_street_address_1

string | null

Primeira linha do endereço de entrega.

Maximum string length: 255

shipping_street_address_2

string | null

Segunda linha do endereço de entrega.

Maximum string length: 255

shipping_city

string | null

Cidade de entrega.

Maximum string length: 255

shipping_state

string | null

Estado de entrega alfanumérico.

Maximum string length: 3

shipping_country

string | null

País de entrega em código alfanumérico de dois caracteres.

Required string length: 2

shipping_zip

string | null

CEP de entrega, com pelo menos dois caracteres.

Minimum string length: 2

return_url

string<uri> | null

URL de retorno, obrigatória quando o processador selecionado é do tipo wallet.

Response

Jornada criada.

transaction

object

required

Show child attributes

url

string<uri>

required

URL da jornada.

Pix

Transações

Saldos

Relatórios

Sandbox

Webhooks

Iniciar jornada Pix com biometria

Comportamento observado

Authorizations

Body

Response

​Comportamento observado

Authorizations

Body

Response

Comportamento observado