API Reference

Cria um pagamento por biometria (Pix confirmado no aparelho de quem paga) e devolve o link de quem paga

Cria o pedido de um Pix que a pessoa confirma no próprio aparelho, com biometria ou bloqueio de tela. Entregue o payer_url a quem paga. O Pix é iniciado via Open Finance Brasil por uma instituição iniciadora de pagamento autorizada pelo Banco Central; o dinheiro vai direto da conta de quem paga para a conta de destino, e a UNIFOKAL não guarda nem movimenta o valor. Exige uma chave secreta criada COM o escopo pix_payments:write (chaves sem restrição não o têm) e o cadastro da organização aprovado. Idempotência pelo reference_id do corpo, sem janela e sem Idempotency-Key: repetir com o mesmo corpo devolve 200 com Idempotent-Replay: true, o estado ATUAL e o mesmo payer_url; com outro corpo é 422 idempotency_key_reuse. Não existe GET nem cancelamento pela API: o desfecho chega pelos webhooks pix_payment.succeeded, pix_payment.failed, pix_payment.expired e pix_payment.refunded, no webhook do flow. A volta do navegador de quem paga nunca prova pagamento. No sandbox (chave unifokal_test_) a confirmação acontece num banco de teste, com redirecionamento, e nenhum dado pessoal seu sai; estados e webhooks são os de produção, e nada é cobrado. Em produção, a tarifa sai do seu saldo só no Pix concluído.

curl --request POST \
  --url https://api.unifokal.com/v1/pix-payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "flow_id": "<string>",
  "reference_id": "<string>",
  "amount_cents": 1073741824,
  "description": "<string>",
  "destination_id": "<string>",
  "return_url": "<string>",
  "expires_in_seconds": 303300
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    flow_id: '<string>',
    reference_id: '<string>',
    amount_cents: 1073741824,
    description: '<string>',
    destination_id: '<string>',
    return_url: '<string>',
    expires_in_seconds: 303300
  })
};

fetch('https://api.unifokal.com/v1/pix-payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.unifokal.com/v1/pix-payments"

payload = {
    "flow_id": "<string>",
    "reference_id": "<string>",
    "amount_cents": 1073741824,
    "description": "<string>",
    "destination_id": "<string>",
    "return_url": "<string>",
    "expires_in_seconds": 303300
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "id": "<string>",
  "object": "pix_payment",
  "livemode": true,
  "reference_id": "<string>",
  "flow_id": "<string>",
  "verification_session_id": "<string>",
  "status": "awaiting_payer",
  "amount_cents": 2,
  "currency": "BRL",
  "description": "<string>",
  "destination": {
    "id": "<string>",
    "holder_name": "<string>",
    "holder_document": "<string>",
    "ispb": "<string>",
    "branch": "<string>",
    "account": "<string>",
    "account_type": "checking"
  },
  "payer_url": "<string>",
  "return_url": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "paid_at": "2023-11-07T05:31:56Z",
  "end_to_end_id": "<string>",
  "failure": {
    "code": "destination_rejected",
    "message": "<string>"
  },
  "last_attempt": {
    "code": "not_completed_by_payer",
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "id": "<string>",
  "object": "pix_payment",
  "livemode": true,
  "reference_id": "<string>",
  "flow_id": "<string>",
  "verification_session_id": "<string>",
  "status": "awaiting_payer",
  "amount_cents": 2,
  "currency": "BRL",
  "description": "<string>",
  "destination": {
    "id": "<string>",
    "holder_name": "<string>",
    "holder_document": "<string>",
    "ispb": "<string>",
    "branch": "<string>",
    "account": "<string>",
    "account_type": "checking"
  },
  "payer_url": "<string>",
  "return_url": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "paid_at": "2023-11-07T05:31:56Z",
  "end_to_end_id": "<string>",
  "failure": {
    "code": "destination_rejected",
    "message": "<string>"
  },
  "last_attempt": {
    "code": "not_completed_by_payer",
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": "invalid_json",
  "message": "<string>"
}

{
  "error": "invalid_api_key",
  "message": "<string>"
}

{
  "error": "insufficient_credit",
  "message": "<string>"
}

{
  "error": "credential_type_not_allowed",
  "message": "<string>"
}

{
  "error": "flow_not_found",
  "message": "<string>"
}

{
  "error": "payload_too_large",
  "message": "<string>"
}

{
  "error": "flow_without_pix_payment",
  "message": "<string>"
}

{
  "error": "rate_limited",
  "message": "<string>"
}

{
  "error": "pix_unavailable",
  "message": "<string>"
}

Autorizações

Authorization

string

header

obrigatório

Chave secreta (unifokal_live_ em produção, unifokal_test_ no sandbox: 64 hex mais CRC-32) no Authorization: Bearer. Só no seu servidor: nunca no browser ou app (o widget monta apenas com o id vs_ da sessão). Não existe chave publishable.

Corpo

application/json

flow_id

string

obrigatório

Flow do mesmo ambiente da chave, com o módulo pix_payment e um webhook do mesmo ambiente: os eventos pix_payment.* chegam no webhook desse flow.

Pattern: ^flow_[0-9A-Za-z_]{1,64}$

reference_id

string

obrigatório

O id do PEDIDO no seu sistema e a chave de idempotência, permanente: repetir com o mesmo corpo devolve o estado atual e o mesmo payer_url (200, Idempotent-Replay: true); com outro corpo é 422 idempotency_key_reuse. Depois de failed ou expired, um pagamento novo usa outro reference_id. Nunca ponha CPF, e-mail ou telefone aqui.

Required string length: 1 - 255

amount_cents

integer

obrigatório

Valor em centavos de real, inteiro de 1 a 2147483647. Não é teto de negócio: o limite é o do banco de quem paga.

Intervalo obrigatório: 1 <= x <= 2147483647

description

string

Opcional, até 140 caracteres, sem caractere de controle. É mostrada a quem paga.

Required string length: 1 - 140

Pattern: ^[^\u0000-\u001f\u007f-\u009f]*$

destination_id

string

Conta de destino cadastrada no painel (pxr_). Sem destination_id nem destination vale o destino padrão do flow; sem nenhum dos três é 422 destination_required.

Pattern: ^pxr_[0-9A-Za-z_]{1,64}$

destination

object

A conta de destino por extenso, no lugar do destination_id. Em produção tem de casar com uma conta cadastrada no painel, ativa e já utilizável; no sandbox qualquer conta válida passa e nada sai.

Show child attributes

payer

object

Opcional: CPF (11 dígitos, dígito verificador conferido) e nome de quem paga. Presente, a confirmação não pede o CPF de novo. Nunca volta em resposta nem em webhook.

Show child attributes

return_url

string

Opcional: https para onde quem paga volta ao terminar, com ?pix_payment_id=pxp_... e sem estado na URL. A volta do navegador não prova pagamento: o webhook é a fonte da verdade.

expires_in_seconds

integer

Validade do link de quem paga, de 1800 (30 minutos) a 604800 (7 dias). Padrão 86400 (24 horas).

Intervalo obrigatório: 1800 <= x <= 604800

Resposta

Repetição do mesmo reference_id com o mesmo corpo: o estado atual e o mesmo payer_url.

Um pagamento por biometria. Nada de quem paga sai neste objeto. Campo novo pode surgir sem subir a versão: ignore chave desconhecida.

string

obrigatório

Id do pagamento por biometria (pxp_ + ULID).

Pattern: ^pxp_[0-9A-HJKMNP-TV-Z]{26}$

object

string

obrigatório

Allowed value: "pix_payment"

livemode

boolean

obrigatório

true em produção (chave unifokal_live_), false no sandbox.

reference_id

string | null

obrigatório

O id do pedido no seu sistema, o mesmo do corpo da criação.

flow_id

string

obrigatório

Id de flow (flow_ + ULID). Criado no painel, nunca pela API da chave secreta.

Pattern: ^flow_[0-9A-HJKMNP-TV-Z]{26}$

verification_session_id

string | null

obrigatório

A sessão de verificação que criou o pagamento, quando ele nasceu no widget; null quando nasceu pela API.

Pattern: ^vs_[0-9A-HJKMNP-TV-Z]{26}$

status

enum<string>

obrigatório

awaiting_payer: esperando quem paga; processing: a confirmação começou; succeeded: Pix concluído e confirmado; failed: falha definitiva do pedido; expired: prazo vencido sem Pix; refunded: devolvido depois do sucesso.

Opções disponíveis:

awaiting_payer,

processing,

succeeded,

failed,

expired,

refunded

amount_cents

integer

obrigatório

Intervalo obrigatório: x >= 1

currency

string

obrigatório

Allowed value: "BRL"

description

string | null

obrigatório

destination

object

obrigatório

A conta de destino, mascarada.

Show child attributes

payer_url

string<uri> | null

obrigatório

O link de quem paga, com a credencial no fragmento (#). Só na resposta da criação e na repetição; null no webhook. Não registre em log.

return_url

string<uri> | null

obrigatório

expires_at

string<date-time>

obrigatório

created_at

string<date-time>

obrigatório

paid_at

string<date-time> | null

obrigatório

end_to_end_id

string | null

obrigatório

O identificador fim a fim do Pix, depois do sucesso.

failure

object | null

obrigatório

Só em failed e expired.

Show child attributes

last_attempt

object | null

obrigatório

A categoria da última tentativa que não concluiu. not_completed_by_payer cobre tudo que é de quem paga (recusa, tempo, saldo, limite); o motivo exato só quem paga vê.

Show child attributes

Cria um pagamento por biometria (Pix confirmado no aparelho de quem paga) e devolve o link de quem paga

curl --request POST \
  --url https://api.unifokal.com/v1/pix-payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "flow_id": "<string>",
  "reference_id": "<string>",
  "amount_cents": 1073741824,
  "description": "<string>",
  "destination_id": "<string>",
  "return_url": "<string>",
  "expires_in_seconds": 303300
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    flow_id: '<string>',
    reference_id: '<string>',
    amount_cents: 1073741824,
    description: '<string>',
    destination_id: '<string>',
    return_url: '<string>',
    expires_in_seconds: 303300
  })
};

fetch('https://api.unifokal.com/v1/pix-payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.unifokal.com/v1/pix-payments"

payload = {
    "flow_id": "<string>",
    "reference_id": "<string>",
    "amount_cents": 1073741824,
    "description": "<string>",
    "destination_id": "<string>",
    "return_url": "<string>",
    "expires_in_seconds": 303300
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "id": "<string>",
  "object": "pix_payment",
  "livemode": true,
  "reference_id": "<string>",
  "flow_id": "<string>",
  "verification_session_id": "<string>",
  "status": "awaiting_payer",
  "amount_cents": 2,
  "currency": "BRL",
  "description": "<string>",
  "destination": {
    "id": "<string>",
    "holder_name": "<string>",
    "holder_document": "<string>",
    "ispb": "<string>",
    "branch": "<string>",
    "account": "<string>",
    "account_type": "checking"
  },
  "payer_url": "<string>",
  "return_url": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "paid_at": "2023-11-07T05:31:56Z",
  "end_to_end_id": "<string>",
  "failure": {
    "code": "destination_rejected",
    "message": "<string>"
  },
  "last_attempt": {
    "code": "not_completed_by_payer",
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "id": "<string>",
  "object": "pix_payment",
  "livemode": true,
  "reference_id": "<string>",
  "flow_id": "<string>",
  "verification_session_id": "<string>",
  "status": "awaiting_payer",
  "amount_cents": 2,
  "currency": "BRL",
  "description": "<string>",
  "destination": {
    "id": "<string>",
    "holder_name": "<string>",
    "holder_document": "<string>",
    "ispb": "<string>",
    "branch": "<string>",
    "account": "<string>",
    "account_type": "checking"
  },
  "payer_url": "<string>",
  "return_url": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "paid_at": "2023-11-07T05:31:56Z",
  "end_to_end_id": "<string>",
  "failure": {
    "code": "destination_rejected",
    "message": "<string>"
  },
  "last_attempt": {
    "code": "not_completed_by_payer",
    "at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": "invalid_json",
  "message": "<string>"
}

{
  "error": "invalid_api_key",
  "message": "<string>"
}

{
  "error": "insufficient_credit",
  "message": "<string>"
}

{
  "error": "credential_type_not_allowed",
  "message": "<string>"
}

{
  "error": "flow_not_found",
  "message": "<string>"
}

{
  "error": "payload_too_large",
  "message": "<string>"
}

{
  "error": "flow_without_pix_payment",
  "message": "<string>"
}

{
  "error": "rate_limited",
  "message": "<string>"
}

{
  "error": "pix_unavailable",
  "message": "<string>"
}