Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stric.io/llms.txt

Use this file to discover all available pages before exploring further.

Enviar um Pix pela Stric envolve geralmente três passos:
1

Consultar a chave Pix (opcional mas recomendado)

Confirma o titular e devolve um dictLookupId para você vincular ao pagamento.
2

Iniciar a transferência Pix

Envie pixKey, pixKeyType e amountCents; opcionalmente o dictLookupId do passo anterior.
3

Confirmar a liquidação

Por webhook (recomendado) ou consultando o recurso da transferência (GET /v1/payouts/{id}).

​
Passo 1 — Consulta do titular (POST /v1/dict/lookup)

Use os mesmos valores de chave e tipo que você vai mandar na transferência. O corpo aceita:
CampoTipoDescrição
pixKeystringTexto da chave (formato conforme o tipo).
pixKeyTypestringCPF, CNPJ, EMAIL, PHONE ou EVP.
curl -X POST "$STRIC_BASE_URL/v1/dict/lookup" \
  -H "Authorization: Bearer $STRIC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "pixKey": "11999999999",
    "pixKeyType": "PHONE"
  }'
Resposta: 
{
  "id": "dlk_01HXYZABC",
  "key": "11999999999",
  "keyType": "PHONE",
  "owner": { "name": "Maria Silva", "document": "***.123.456-**" },
  "bankName": "Banco Exemplo",
  "ispb": "12345678",
  "branch": "0001",
  "account": "1234567",
  "accountType": "CACC",
  "cached": false
}
Sempre mostre o owner.name ao usuário antes de confirmar o pagamento. É um requisito regulatório de Pix e protege contra fraude.

​
Passo 2 — Criar a transferência Pix

O POST /v1/payouts exige pixKey, pixKeyType e amountCents (valor em centavos, conforme formato monetário). Opcionalmente envie dictLookupId com o id retornado na consulta do passo anterior, para correlacionar com a conferência do titular. 
curl -X POST "$STRIC_BASE_URL/v1/payouts" \
  -H "Authorization: Bearer $STRIC_API_KEY" \
  -H "Idempotency-Key: transferencia-pedido-12345" \
  -H "Content-Type: application/json" \
  -d '{
    "pixKey": "11999999999",
    "pixKeyType": "PHONE",
    "dictLookupId": "dlk_01HXYZABC",
    "amountCents": "10000",
    "description": "Pagamento pedido #12345"
  }'
amountCents: "10000" = R$ 100,00. A resposta inicial geralmente vem com status PENDING ou PROCESSING. A liquidação é assíncrona.

​
Passo 3 — Confirmar a liquidação

​
Opção A: webhook (recomendado)

Configure um endpoint que recebe os eventos pix.payout.* (ciclo da transferência Pix enviada). Você é notificado assim que o status muda. Veja Webhooks.

​
Opção B: polling na transferência

curl "$STRIC_BASE_URL/v1/payouts/$PAYOUT_ID" \
  -H "Authorization: Bearer $STRIC_API_KEY"
Polling em loop apertado vai disparar 429. Use o webhook ou intervalos longos (ex.: 30s) com exponential backoff.

​
Pagar QR Code (decode obrigatório)

Se em vez de chave Pix você tem um BR Code (string copia e cola), o fluxo é sempre decodificar → pagar. Não há pagamento por QR sem passar pelo decode.
1

1. Decodificar o BR Code

POST /v1/qr-code/decode — devolve valor, beneficiário, identificadores e um id para usar como qrCodeDecodeId no passo seguinte.
2

2. Pagar o QR Code

POST /v1/payouts/qr-code — mesmo contrato de liquidação que Pix por chave (webhooks pix.payout.*). Envie o BR Code, amountCents e, quando aplicável, qrCodeDecodeId do passo anterior.

​
Tratando erros comuns

CenárioComo tratar
DICT_KEY_NOT_FOUND (404)Chave não existe no diretório Pix — peça ao usuário pra verificar
INSUFFICIENT_BALANCE (422)Bloqueie a operação e avise o usuário
LIMIT_EXCEEDED (422)Limite diário/mensal — guie o usuário a aumentá-lo
Timeout ao criar a transferênciaReenvie com a mesma Idempotency-Key — sem duplicar

​
Reconciliação

Para um processo robusto:
  1. Persista seu Idempotency-Key antes de chamar POST /v1/payouts.
  2. Receba o webhook de mudança de status.
  3. Confirme consultando GET /v1/payouts/{id}/movement para o movimento financeiro associado.