Criar withdrawal

Realiza um withdrawal do remetente para um beneficiário a partir de uma cotação, criando uma remessa do tipo WITHDRAWAL de forma idempotente. A cotação informa apenas o preço; remetente, beneficiário, finalidade e funding são informados aqui. Na criação a LB Pay, de forma síncrona: valida a cotação (existente, AVAILABLE e não expirada); valida o remetente (existe, ACTIVE, nível LEVEL_1 ou superior) e seus limites por janela; valida beneficiário e instrução de pagamento, inclusive a coerência entre relationshipType do beneficiário e senderRelationship; executa checkKey (existência da chave Pix); aplica os limites por transação e diário da conta, do remetente (24h/30d/180d) e do beneficiário (24h/30d/180d); reserva atomicamente o limite de crédito (CREDIT) ou o saldo USD pré-fundado (PREFUNDED) e marca a cotação como USED. Screening, câmbio, funding e Pix seguem de forma assíncrona e são notificados por webhook. Uma cotação só pode ser usada por uma remessa.

Com funding.mode = INVENTORY não há cotação por remessa: não envie quoteId; envie funding.inventoryId e destinationAmount (BRL que o beneficiário recebe). A LB Pay valida o Inventory (existente no tenant, ACTIVE, dentro da validade e com saldo disponível em BRL suficiente), aplica as demais validações acima e reserva atomicamente o volume no lote, sem seleção automática de outro lote. Valores e taxa da remessa vêm do lote.

Em INVENTORY, senderQuote é obrigatório: são os dados da operação de câmbio da MSB com o remetente. A LB Pay valida a estrutura, grava o objeto como recebido na remessa e o usa na formalização da operação. senderQuote não altera os valores da remessa nem a taxa do lote. Em PREFUNDED e CREDIT, senderQuote é opcional e esses fluxos não mudam.

POST /v1/remittances/withdrawals

cURL

credit

curl --request POST \
  --url https://api.lbpay.example.com/v1/remittances/withdrawals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "quoteId": "qt_01J9Z3",
  "senderId": "snd_789",
  "externalId": "remittance-123",
  "funding": {
    "mode": "CREDIT"
  },
  "beneficiaryId": "ben_123",
  "paymentInstructionId": "pi_456",
  "purpose": "FAMILY_MAINTENANCE",
  "senderRelationship": "FAMILY"
}
'

201

{
  "remittanceId": "<string>",
  "type": "WITHDRAWAL",
  "quoteId": "<string>",
  "senderId": "<string>",
  "externalId": "<string>",
  "status": "PROCESSING",
  "inventoryId": "<string>",
  "fundingMode": "PREFUNDED",
  "message": "Remessa criada; câmbio e Pix ainda não confirmados."
}

Autorizações

Authorization · string · header · obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Cabeçalhos

Idempotency-Key · string · obrigatório

Unique key to prevent duplicate creation or execution.

Required string length: 8 - 128

Corpo

application/json

Campos condicionais por funding.mode. PREFUNDED e CREDIT: quoteId obrigatório; destinationAmount e funding.inventoryId não aceitos; senderQuote opcional. INVENTORY: funding.inventoryId e destinationAmount obrigatórios; quoteId não aceito; senderQuote obrigatório. Violação retorna VALIDATION_ERROR (400) com o campo em details.

senderId · string · obrigatório

Remetente cadastrado, ACTIVE e com nível mínimo LEVEL_1.

externalId · string · obrigatório

Único por cliente.

Maximum string length: 128

funding · object · obrigatório

inventoryId é obrigatório quando mode = INVENTORY e não é aceito nas demais modalidades (VALIDATION_ERROR).

Show child attributes

beneficiaryId · string · obrigatório

purpose · enum<string> · obrigatório

Finalidade declarada; mapeada internamente para a natureza da operação de câmbio. Enum extensível.

Opções disponíveis: FAMILY_MAINTENANCE, GIFT, PERSONAL_SAVINGS, EDUCATION, MEDICAL, SERVICES_PAYMENT, GOODS_PAYMENT, SALARY, OTHER

senderRelationship · enum<string> · obrigatório

Relação do remetente com o beneficiário.

Opções disponíveis: SELF, FAMILY, FRIEND, EMPLOYER, EMPLOYEE, BUSINESS_PARTNER, OTHER

quoteId · string

Obrigatório em PREFUNDED e CREDIT; não aceito em INVENTORY. Cotação usage = REMITTANCE, AVAILABLE e não expirada. Define valores e taxa da remessa.

destinationAmount · string

Somente INVENTORY (obrigatório). Valor em BRL que o beneficiário recebe; é o volume reservado no lote. O equivalente em USD é calculado na taxa do lote.

Pattern: ^(0\.(0[1-9]|[1-9][0-9]?)|[1-9][0-9]*(\.[0-9]{1,2})?)$

Exemplo:

"1000.00"

senderQuote · object

Dados da operação de câmbio da MSB com o remetente (usuário final). Obrigatório em INVENTORY. Não é informativo: é gravado na remessa como recebido e usado na formalização da operação. Não altera valores da remessa, taxa do lote nem cobrança. Não confundir com a cotação da LB Pay (quoteId) nem com a taxa do Inventory Lot.

A estrutura pode receber novos campos.

Show child attributes

paymentInstructionId · string

Opcional se o beneficiário tiver exatamente uma instrução APPROVED.

purposeDescription · string

Obrigatório quando purpose = OTHER.

Maximum string length: 140

metadata · object

Resposta

201

application/json

Remittance created and accepted for processing

remittanceId · string · obrigatório

type · enum<string> · obrigatório

Operação que originou a remessa. WITHDRAWAL: envio do remetente para um beneficiário no Brasil via Pix. Enum extensível: ignore tipos desconhecidos.

Opções disponíveis: WITHDRAWAL

quoteId · string | null · obrigatório

null somente quando fundingMode = INVENTORY.

senderId · string · obrigatório

externalId · string · obrigatório

status · enum<string> · obrigatório

Opções disponíveis: PROCESSING, ON_HOLD

inventoryId · string | null

Preenchido somente quando fundingMode = INVENTORY.

fundingMode · enum<string>

Opções disponíveis: PREFUNDED, CREDIT, INVENTORY

message · string

Exemplo:

"Remessa criada; câmbio e Pix ainda não confirmados."