> ## Documentation Index > Fetch the complete documentation index at: https://developers.javalibridge.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml api-reference/openapi.yaml POST /v1/remittances/withdrawals openapi: 3.0.3 info: title: LB Pay Cross-Border Payouts API version: 1.21.0 description: > Cross-border payouts API da LB Pay — v1: USD→BRL (fromCurrency/toCurrency), câmbio contratado remessa a remessa (SPOT) e pagamento via Pix. ## Princípios - Cotação e operação são domínios separados. A cotação (`POST /v1/fx/quotes`) é apenas preço e não cria remessa. A remessa nasce da operação que o cliente quer realizar — na v1, um withdrawal para um beneficiário: `POST /v1/fx/quotes` → `POST /v1/remittances/withdrawals`. - A cotação é apenas preço: um único preço, igual para PREFUNDED e CREDIT, válido para qualquer remetente do cliente. A única tarifa da remessa é o spread de câmbio, em percentual. O custo da antecipação (CREDIT) segue o contrato e é cobrado no lote de liquidação. Remetente, beneficiário, finalidade e funding são informados no withdrawal. - USDC Inventory: o cliente pode contratar câmbio antecipadamente. Uma cotação com `usage = INVENTORY` é usada uma única vez para criar um Inventory Lot (`POST /v1/inventories`), que fixa taxa, volume e validade e gera a promessa de pagamento em USDC. O lote é consumido depois por withdrawals com `funding.mode = INVENTORY`. - Valores monetários são strings decimais. Valores de requisição devem ser maiores que zero. - Listas usam paginação por cursor (`cursor`, `limit`; resposta com `nextCursor`). ## Rate limiting Respostas 429 trazem `Retry-After` (segundos). Clientes devem respeitar o header e aplicar backoff exponencial com jitter. ## Erros Todo erro retorna `ApiError`. O campo `code` segue o catálogo em `components.x-error-catalog`; novos códigos podem ser adicionados sem mudança de versão — clientes devem tratar códigos desconhecidos pelo HTTP status. ## Webhooks Eventos documentados em `x-webhooks`. Cada entrega é um `POST` com envelope `WebhookEvent` e os headers: - `LBPay-Event-Id`: igual a `eventId`; use para deduplicar (entrega é at-least-once). - `LBPay-Timestamp`: unix epoch (segundos) do envio. - `LBPay-Signature`: `v1=`. Rejeite se a assinatura não bater ou se |agora − timestamp| > 300s. Responda 2xx em até 10s; falhas são reenviadas com backoff exponencial por até 24h. A ordem de entrega não é garantida — use `occurredAt` e o estado do recurso, ou consulte o recurso via GET. ## Chaves de conciliação Toda remessa é rastreável pelas mesmas chaves em todos os objetos: `externalId` (ID da MSB, único por cliente e imutável) · `quoteId` · `remittanceId` · `settlementId` (CREDIT) · `transactionId` (pagamento Pix) · `inventoryId` (INVENTORY). - Quote → `remittanceId`, `externalId` (preenchidos quando a cotação é usada por um withdrawal) - Remittance → `externalId`, `quoteId` (null em INVENTORY), `inventoryId` (INVENTORY), `settlement.settlementId`, `payout.transactionId` - Inventory → `quoteId` (cotação que originou o lote), `externalId`; remessas do lote em `GET /v1/remittances?inventoryId=` - SettlementItem → `remittanceId`, `externalId`, `quoteId`, `transactionId` - WalletTransaction → `remittanceId`, `externalId`, `quoteId`, `settlementId` - Receipt → `remittanceId`, `externalId`, `quoteId`, `transactionId` - Webhooks de remessa → snapshot completo da Remittance servers: - url: https://api.lbpay.example.com description: Example production URL - replace before use - url: https://sandbox.lbpay.example.com description: Example sandbox URL - replace before use security: - BearerAuth: [] tags: - name: Health - name: FX Quotes - name: Inventories - name: Remittances - name: Senders - name: Beneficiaries - name: Credit Line - name: Limits - name: Wallets - name: Settlements - name: Webhooks paths: /v1/remittances/withdrawals: post: tags: - Remittances summary: Create a withdrawal to a beneficiary (creates a remittance) description: >- 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. operationId: createWithdrawal parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWithdrawalRequest' examples: credit: summary: Funding por crédito value: quoteId: qt_01J9Z3 senderId: snd_789 externalId: remittance-123 funding: mode: CREDIT beneficiaryId: ben_123 paymentInstructionId: pi_456 purpose: FAMILY_MAINTENANCE senderRelationship: FAMILY prefunded: summary: Funding pré-fundado value: quoteId: qt_01J9Z4 senderId: snd_789 externalId: remittance-124 funding: mode: PREFUNDED beneficiaryId: ben_124 purpose: GIFT senderRelationship: FRIEND inventory: summary: Funding por Inventory Lot value: senderId: snd_789 externalId: remittance-125 destinationAmount: '10000.00' funding: mode: INVENTORY inventoryId: inv_01JA2B beneficiaryId: ben_125 purpose: FAMILY_MAINTENANCE senderRelationship: FAMILY senderQuote: rate: '5.55000000' source: currency: USD amount: '1801.80' destination: currency: BRL amount: '10000.00' quotedAt: '2026-11-04T14:00:00Z' reference: msb-quote-8812 responses: '201': description: Remittance created and accepted for processing content: application/json: schema: $ref: '#/components/schemas/WithdrawalResponse' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/BusinessRuleViolation' '429': $ref: '#/components/responses/TooManyRequests' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: true description: Unique key to prevent duplicate creation or execution. schema: type: string minLength: 8 maxLength: 128 schemas: CreateWithdrawalRequest: type: object description: >- 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`. required: - senderId - externalId - funding - beneficiaryId - purpose - senderRelationship properties: quoteId: type: string description: >- 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: allOf: - $ref: '#/components/schemas/PositiveAmount' description: >- 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. senderQuote: $ref: '#/components/schemas/SenderQuote' senderId: type: string description: Remetente cadastrado, ACTIVE e com nível mínimo LEVEL_1. externalId: type: string maxLength: 128 description: Único por cliente. funding: $ref: '#/components/schemas/FundingSelection' beneficiaryId: type: string paymentInstructionId: type: string description: Opcional se o beneficiário tiver exatamente uma instrução APPROVED. purpose: type: string enum: - FAMILY_MAINTENANCE - GIFT - PERSONAL_SAVINGS - EDUCATION - MEDICAL - SERVICES_PAYMENT - GOODS_PAYMENT - SALARY - OTHER description: >- Finalidade declarada; mapeada internamente para a natureza da operação de câmbio. Enum extensível. purposeDescription: type: string maxLength: 140 description: Obrigatório quando purpose = OTHER. senderRelationship: type: string enum: - SELF - FAMILY - FRIEND - EMPLOYER - EMPLOYEE - BUSINESS_PARTNER - OTHER description: Relação do remetente com o beneficiário. metadata: type: object additionalProperties: true WithdrawalResponse: type: object required: - remittanceId - type - quoteId - senderId - status - externalId properties: remittanceId: type: string type: $ref: '#/components/schemas/RemittanceType' quoteId: type: string nullable: true description: null somente quando fundingMode = INVENTORY. inventoryId: type: string nullable: true description: Preenchido somente quando fundingMode = INVENTORY. senderId: type: string externalId: type: string status: type: string enum: - PROCESSING - ON_HOLD fundingMode: type: string enum: - PREFUNDED - CREDIT - INVENTORY message: type: string example: Remessa criada; câmbio e Pix ainda não confirmados. PositiveAmount: type: string pattern: ^(0\.(0[1-9]|[1-9][0-9]?)|[1-9][0-9]*(\.[0-9]{1,2})?)$ description: Decimal como string, estritamente maior que zero. example: '1000.00' SenderQuote: type: object required: - rate - source - destination description: >- 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. properties: rate: allOf: - $ref: '#/components/schemas/Rate' description: Taxa BRL por USD aplicada pela MSB ao remetente. source: allOf: - $ref: '#/components/schemas/Money' description: Valor em USD da operação para o remetente. destination: allOf: - $ref: '#/components/schemas/Money' description: Valor em BRL informado ao remetente. quotedAt: type: string format: date-time description: Momento em que a MSB cotou para o remetente. reference: type: string maxLength: 128 description: Identificador da cotação no sistema da MSB. FundingSelection: type: object required: - mode description: >- `inventoryId` é obrigatório quando mode = INVENTORY e não é aceito nas demais modalidades (VALIDATION_ERROR). properties: mode: type: string enum: - PREFUNDED - CREDIT - INVENTORY description: >- PREFUNDED: saldo USD pré-fundado. CREDIT: limite de crédito. INVENTORY: volume de câmbio contratado em um Inventory Lot. Enum extensível. inventoryId: type: string description: >- Inventory Lot que financia a remessa. Somente mode = INVENTORY. O lote informado é o único consumido. RemittanceType: type: string enum: - WITHDRAWAL description: >- Operação que originou a remessa. WITHDRAWAL: envio do remetente para um beneficiário no Brasil via Pix. Enum extensível: ignore tipos desconhecidos. ApiError: type: object required: - code - message - requestId properties: code: type: string description: >- Código do catálogo `x-error-catalog`. Extensível: trate códigos desconhecidos pelo HTTP status. example: QUOTE_EXPIRED message: type: string requestId: type: string retryable: type: boolean description: >- Indica se a mesma requisição pode ser repetida (com a mesma Idempotency-Key). details: type: array items: type: object properties: field: type: string reason: type: string Rate: type: string pattern: ^[0-9]+(\.[0-9]{1,8})?$ description: BRL por USD, até 8 casas decimais. example: '5.43210000' Money: type: object required: - currency - amount description: >- Valor monetário (saldos, extratos, custos). Pode ser zero. Para valores de requisição use PositiveMoney. properties: currency: type: string enum: - USD - BRL description: v1 suporta apenas USD e BRL. amount: type: string pattern: ^[0-9]+(\.[0-9]{1,2})?$ description: Decimal como string; nunca float binário. example: '1000.00' responses: BadRequest: description: Requisição inválida (VALIDATION_ERROR) content: application/json: schema: $ref: '#/components/schemas/ApiError' NotFound: description: Recurso não encontrado no tenant autenticado content: application/json: schema: $ref: '#/components/schemas/ApiError' Conflict: description: Conflito de estado ou de idempotência content: application/json: schema: $ref: '#/components/schemas/ApiError' BusinessRuleViolation: description: Requisição rejeitada por regra de negócio content: application/json: schema: $ref: '#/components/schemas/ApiError' TooManyRequests: description: Limite de requisições excedido (RATE_LIMITED) headers: Retry-After: description: Segundos até nova tentativa schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.