Referência da API pública (merchant PAY-IN)

Base de produção: https://api.yoobank.net

Prefixo actual: /api/v1/

API_VERSIONING_POLICY_FORMALIZED=no

Não há política formal de deprecação. Não assuma um calendário de /v2.

O OpenAPI completo da plataforma está em docs/openapi/openapi.yaml. Muitos paths são operação de plataforma (identidades, activação de merchant, bindings). Esta página documenta só o que um merchant integrado (Modelos B/C) deve chamar: CREATE / LIST / READ de PAY-IN.

Health operacional (não versionado, sem topologia interna):

GET https://api.yoobank.net/health

Resposta mínima: status=ok e request_id.

Autenticação

Authorization: Bearer <machine credential>

Ver AUTHENTICATION.md.

Endpoints PAY-IN

Substitua {merchant_uuid} pelo UUID do merchant dono da credencial.

Criar

POST /api/v1/merchants/{merchant_uuid}/pay-in-intents
Idempotency-Key: <1–64 caracteres>
Content-Type: application/json

O header Idempotency-Key é obrigatório.

Listar

GET /api/v1/merchants/{merchant_uuid}/pay-in-intents

Query opcional: limit (1–100, omissão = 20), offset (≥ 0), status (created \| awaiting_payment \| paid), asset (código de asset).

Ler

GET /api/v1/merchants/{merchant_uuid}/pay-in-intents/{intent_uuid}

Contrato de criação

Campo de correlação do merchant: reference. Não existe merchant_reference no JSON público.

Corpo (campos extra são rejeitados):

Campo	Obrigatório	Notas
`asset`	sim	`usdt` ou `usdc`
`amount`	sim	string decimal; ver PAYIN.md
`jurisdiction`	sim	ISO 3166-1 alpha-2 em maiúsculas (`BR`)
`expires_at`	sim	data/hora futura (UTC)
`reference`	não	até 255 caracteres

Não envie rail. O rail é escolhido pelo routing e volta na resposta (bep20 para USDT, erc20 para USDC no âmbito actual).

Combinações de produção: ver ASSETS.md.

Idempotência de CREATE

PUBLIC_CREATE_PAYIN_IDEMPOTENCY_CONTRACT=Idempotency-Key header required; same key+payload replays 201; mismatch => 400

Mesma chave + mesmo payload → 201 com o intent original (replay).
Mesma chave + payload diferente → 400 (Pay-in idempotency key was reused with a different payload.).
Sem chave, vazia, ou > 64 caracteres → 400.

Não faça retry cego de POST se a resposta anterior for incerta (timeout). Gere uma chave nova só para um pagamento novo. Para o mesmo pagamento, reenvie a mesma Idempotency-Key e o mesmo JSON.

Resposta 201 (criar)

Campos reais:

Campo	Significado
`intent_uuid`	Identidade do PAY-IN
`status`	`created` na criação bem-sucedida
`asset`	código
`rail`	rail seleccionado
`expected_amount`	string decimal canónica
`address`	endereço de depósito único
`allocation_reference`	referência de alocação (pode ser `null`)
`expires_at`	prazo

A resposta de criação não inclui reference nem merchant_uuid. Use GET para a representação completa.

Resposta GET (ler)

Campo	Significado
`intent_uuid`	identidade
`merchant_uuid`	merchant
`status`	`created` \	`awaiting_payment` \	`paid`
`asset`	código
`rail`	rail
`expected_amount`	string decimal
`address`	endereço, ou `null` se ainda não houver
`reference`	referência do merchant, ou `null`
`created_at`	criação
`expires_at`	prazo
`updated_at`	última actualização

Resposta LIST

Cada item tem: intent_uuid, status, asset, rail, expected_amount, reference, created_at, expires_at.

LIST não devolve address, merchant_uuid nem updated_at. Use GET se precisar do endereço.

Envelope:

{
  "data": [],
  "pagination": { "total": 0, "limit": 20, "offset": 0 }
}

Retry HTTP no cliente

Método	Orientação
GET	Seguro repetir
POST create	Só repetir com a mesma `Idempotency-Key` e o mesmo body. Sem chave pública extra além desse header

429 e 5xx transitórios: backoff. Não inventar POST “automático” sem a chave.

Exemplos

Ver PHP-EXAMPLES.md.