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"
}
'{
"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."
}{
"code": "QUOTE_EXPIRED",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": [
{
"field": "<string>",
"reason": "<string>"
}
]
}{
"code": "QUOTE_EXPIRED",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": [
{
"field": "<string>",
"reason": "<string>"
}
]
}{
"code": "QUOTE_EXPIRED",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": [
{
"field": "<string>",
"reason": "<string>"
}
]
}{
"code": "QUOTE_EXPIRED",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": [
{
"field": "<string>",
"reason": "<string>"
}
]
}{
"code": "QUOTE_EXPIRED",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": [
{
"field": "<string>",
"reason": "<string>"
}
]
}Create a 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.
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"
}
'{
"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."
}{
"code": "QUOTE_EXPIRED",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": [
{
"field": "<string>",
"reason": "<string>"
}
]
}{
"code": "QUOTE_EXPIRED",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": [
{
"field": "<string>",
"reason": "<string>"
}
]
}{
"code": "QUOTE_EXPIRED",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": [
{
"field": "<string>",
"reason": "<string>"
}
]
}{
"code": "QUOTE_EXPIRED",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": [
{
"field": "<string>",
"reason": "<string>"
}
]
}{
"code": "QUOTE_EXPIRED",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"details": [
{
"field": "<string>",
"reason": "<string>"
}
]
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Unique key to prevent duplicate creation or execution.
8 - 128Body
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.
Remetente cadastrado, ACTIVE e com nível mínimo LEVEL_1.
Único por cliente.
128inventoryId é obrigatório quando mode = INVENTORY e não é aceito nas demais modalidades (VALIDATION_ERROR).
Show child attributes
Show child attributes
Finalidade declarada; mapeada internamente para a natureza da operação de câmbio. Enum extensível.
FAMILY_MAINTENANCE, GIFT, PERSONAL_SAVINGS, EDUCATION, MEDICAL, SERVICES_PAYMENT, GOODS_PAYMENT, SALARY, OTHER Relação do remetente com o beneficiário.
SELF, FAMILY, FRIEND, EMPLOYER, EMPLOYEE, BUSINESS_PARTNER, OTHER 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.
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.
^(0\.(0[1-9]|[1-9][0-9]?)|[1-9][0-9]*(\.[0-9]{1,2})?)$"1000.00"
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
Show child attributes
Opcional se o beneficiário tiver exatamente uma instrução APPROVED.
Obrigatório quando purpose = OTHER.
140Response
Remittance created and accepted for processing
Operação que originou a remessa. WITHDRAWAL: envio do remetente para um beneficiário no Brasil via Pix. Enum extensível: ignore tipos desconhecidos.
WITHDRAWAL null somente quando fundingMode = INVENTORY.
PROCESSING, ON_HOLD Preenchido somente quando fundingMode = INVENTORY.
PREFUNDED, CREDIT, INVENTORY "Remessa criada; câmbio e Pix ainda não confirmados."