API Reference

Cadastra uma conta de destino do pagamento por biometria, sem criar pagamento

Põe uma conta de destino na lista da sua organização sem criar pagamento: é a porta de quem usa só a sessão e o widget, cujo flow escolhe a conta padrão nessa lista no painel. A regra é a MESMA do destination da criação do pagamento: em produção, a conta do CNPJ da sua organização recebe na hora; a de outro titular recebe 24 horas depois (available_from), com aviso por e-mail a quem administra a conta, que pode liberar antes ou bloquear no painel. Se a organização aceita só contas da lista, a conta de outro titular entra com release_required true e available_from null: ela só recebe depois que um administrador libera no painel, com o segundo fator, e nenhum relógio a libera. Uma mesma chave que cadastra muitas contas novas de terceiro de repente, acima da própria base, tem esse poder pausado por um tempo (422 destination_not_registered); as contas que já estão na lista seguem recebendo. A webhook_url é obrigatória: é o endereço dos eventos da conta. A que ainda não existe na sua organização vira um endereço de webhook deste ambiente; o segredo de assinatura dele volta em webhook_secret só no 201 que o criou. Idempotente pela identidade da conta (documento, instituição, agência, conta e tipo), sem janela e sem Idempotency-Key: a mesma conta ativa devolve 200 com Idempotent-Replay: true e a conta como está agora; conta revogada cadastrada de novo é outra conta, com outro id. 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. Não cobra e nada sai para fora na chamada. No sandbox (chave unifokal_test_) qualquer conta válida recebe na hora e nenhum dado seu sai.

curl --request POST \
  --url https://api.unifokal.com/v1/pix-destinations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "destination": {
    "holder_name": "<string>",
    "holder_document": "<string>",
    "ispb": "<string>",
    "branch": "<string>",
    "account": "<string>"
  },
  "webhook_url": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    destination: {
      holder_name: '<string>',
      holder_document: '<string>',
      ispb: '<string>',
      branch: '<string>',
      account: '<string>'
    },
    webhook_url: '<string>'
  })
};

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

import requests

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

payload = {
    "destination": {
        "holder_name": "<string>",
        "holder_document": "<string>",
        "ispb": "<string>",
        "branch": "<string>",
        "account": "<string>"
    },
    "webhook_url": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "id": "<string>",
  "object": "pix_destination",
  "livemode": true,
  "status": "active",
  "in_review": true,
  "available_from": "2023-11-07T05:31:56Z",
  "release_required": true,
  "ownership": "organization",
  "holder_name": "<string>",
  "holder_document": "<string>",
  "ispb": "<string>",
  "branch": "<string>",
  "account": "<string>",
  "account_type": "checking",
  "created_at": "2023-11-07T05:31:56Z",
  "revoked_at": "2023-11-07T05:31:56Z",
  "webhook_secret": "<string>"
}

{
  "id": "<string>",
  "object": "pix_destination",
  "livemode": true,
  "status": "active",
  "in_review": true,
  "available_from": "2023-11-07T05:31:56Z",
  "release_required": true,
  "ownership": "organization",
  "holder_name": "<string>",
  "holder_document": "<string>",
  "ispb": "<string>",
  "branch": "<string>",
  "account": "<string>",
  "account_type": "checking",
  "created_at": "2023-11-07T05:31:56Z",
  "revoked_at": "2023-11-07T05:31:56Z",
  "webhook_secret": "<string>"
}

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

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

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

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

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

{
  "error": "rate_limited",
  "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

destination

object

obrigatório

A conta por extenso, no MESMO formato do destination da criação do pagamento: titular, CPF ou CNPJ (dígito verificador conferido), ISPB da instituição, agência, conta e tipo. A identidade da conta é o documento, a instituição, a agência, a conta e o tipo; o nome do titular não entra nela.

Show child attributes

webhook_url

string

obrigatório

Obrigatório (sem ele, 400 webhook_required): o endereço https do seu servidor que recebe os eventos desta conta. Um endereço igual a um que você já tem neste ambiente é reaproveitado; um novo nasce aqui e o segredo de assinatura volta em webhook_secret só no 201. Endereço interno ou sem https é 422 webhook_url_invalid. A conta guarda o endereço do primeiro cadastro.

Required string length: 1 - 2048

Resposta

A mesma conta já está ativa na lista: a conta como está agora.

A resposta do cadastro: o objeto pix_destination e o webhook_secret. Campo novo pode surgir sem subir a versão: ignore chave desconhecida.

string

obrigatório

Id da conta de destino da sua lista (pxr_ + ULID), cadastrada pelo POST /v1/pix-destinations ou na criação de um pagamento.

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

object

string

obrigatório

Allowed value: "pix_destination"

livemode

boolean

obrigatório

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

status

enum<string>

obrigatório

active: na lista; revoked: revogada ou bloqueada no painel (não recebe mais).

Opções disponíveis:

active,

revoked

in_review

boolean

obrigatório

true enquanto a conta ativa ainda não recebe: a espera de 24 horas da conta nova de outro titular, ou a liberação de um administrador (release_required).

available_from

string<date-time> | null

obrigatório

Desde quando a conta recebe. null quando ela espera a liberação de uma pessoa (release_required true), porque nenhum relógio a libera.

release_required

boolean

obrigatório

true quando a conta de outro titular espera a liberação de um administrador da organização no painel, com o segundo fator.

ownership

enum<string>

obrigatório

organization: o CNPJ da sua organização; third_party: outro titular.

Opções disponíveis:

organization,

third_party

holder_name

string

obrigatório

holder_document

string

obrigatório

CPF ou CNPJ do titular, mascarado.

ispb

string

obrigatório

Pattern: ^\d{8}$

branch

string

obrigatório

account

string

obrigatório

Número da conta, mascarado.

account_type

enum<string>

obrigatório

Opções disponíveis:

checking,

savings

created_at

string<date-time>

obrigatório

revoked_at

string<date-time> | null

obrigatório

webhook_secret

string | null

obrigatório

O segredo de assinatura (X-IDSAAS-Signature) do endereço de webhook criado por esta chamada a partir da webhook_url. Só aparece no 201 que criou o endereço; null na repetição e quando o endereço já existia. Não registre em log.

Cadastra uma conta de destino do pagamento por biometria, sem criar pagamento

curl --request POST \
  --url https://api.unifokal.com/v1/pix-destinations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "destination": {
    "holder_name": "<string>",
    "holder_document": "<string>",
    "ispb": "<string>",
    "branch": "<string>",
    "account": "<string>"
  },
  "webhook_url": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    destination: {
      holder_name: '<string>',
      holder_document: '<string>',
      ispb: '<string>',
      branch: '<string>',
      account: '<string>'
    },
    webhook_url: '<string>'
  })
};

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

import requests

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

payload = {
    "destination": {
        "holder_name": "<string>",
        "holder_document": "<string>",
        "ispb": "<string>",
        "branch": "<string>",
        "account": "<string>"
    },
    "webhook_url": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "id": "<string>",
  "object": "pix_destination",
  "livemode": true,
  "status": "active",
  "in_review": true,
  "available_from": "2023-11-07T05:31:56Z",
  "release_required": true,
  "ownership": "organization",
  "holder_name": "<string>",
  "holder_document": "<string>",
  "ispb": "<string>",
  "branch": "<string>",
  "account": "<string>",
  "account_type": "checking",
  "created_at": "2023-11-07T05:31:56Z",
  "revoked_at": "2023-11-07T05:31:56Z",
  "webhook_secret": "<string>"
}

{
  "id": "<string>",
  "object": "pix_destination",
  "livemode": true,
  "status": "active",
  "in_review": true,
  "available_from": "2023-11-07T05:31:56Z",
  "release_required": true,
  "ownership": "organization",
  "holder_name": "<string>",
  "holder_document": "<string>",
  "ispb": "<string>",
  "branch": "<string>",
  "account": "<string>",
  "account_type": "checking",
  "created_at": "2023-11-07T05:31:56Z",
  "revoked_at": "2023-11-07T05:31:56Z",
  "webhook_secret": "<string>"
}

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

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

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

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

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

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