Skip to main content

​
Authentication

Every endpoint requires a bearer token (Authorization: Bearer <token>), except GET /v1/health.

​
Principles

  • Quote and operation are separate. The quote (POST /v1/fx/quotes) is only a price and does not create a remittance. The remittance is created by the operation you want to perform; in v1, a withdrawal to a beneficiary: POST /v1/fx/quotes → POST /v1/remittances/withdrawals.
  • A quote is only a price: one price, the same for PREFUNDED and CREDIT, valid for any of your senders. The only remittance fee is the FX spread, as a percentage. The advance cost (CREDIT) follows your agreement and is charged in the settlement batch. Sender, beneficiary, purpose and funding are informed in the withdrawal.
  • USDC Inventory: you can contract FX in advance. A quote with usage = INVENTORY is used once to create an Inventory Lot (POST /v1/inventories), which locks rate, volume and validity and creates the USDC payment promise. The lot is then used by withdrawals with funding.mode = INVENTORY. See USDC Inventory.
  • Monetary amounts are decimal strings. Request amounts must be greater than zero.
  • Lists use cursor pagination (cursor, limit; the response has nextCursor).

​
Rate limiting

429 responses carry Retry-After (seconds). Respect the header and apply exponential backoff with jitter.

​
Errors

Every error returns ApiError. The code field follows the catalog below. New codes can be added without a version change, so treat unknown codes by their HTTP status.

​
Webhook deliveries

The events are listed in Notifications (webhooks). Each delivery is a POST with a WebhookEvent envelope and these headers:
  • LBPay-Event-Id: same as eventId. Use it to deduplicate; delivery is at-least-once.
  • LBPay-Timestamp: Unix epoch (seconds) of the delivery.
  • LBPay-Signature: v1=<hex(HMAC-SHA256(signingSecret, timestamp + "." + rawBody))>. Reject the delivery if the signature does not match or if the difference between now and the timestamp is greater than 300 seconds.
Respond with 2xx within 10 seconds. Failures are retried with exponential backoff for up to 24 hours. Delivery order is not guaranteed: use occurredAt and the state of the resource, or fetch the resource with GET.

​
Reconciliation keys

Every remittance can be traced by the same keys in every object: externalId (your ID, unique in your account and immutable), quoteId, remittanceId, settlementId (CREDIT), transactionId (Pix payment) and inventoryId (INVENTORY).
  • Quote → remittanceId, externalId (filled in when the quote is used by a withdrawal)
  • Remittance → externalId, quoteId (null in INVENTORY), inventoryId (INVENTORY), settlement.settlementId, payout.transactionId
  • Inventory → quoteId (the quote that created the lot), externalId; the lot’s remittances in GET /v1/remittances?inventoryId=
  • SettlementItem → remittanceId, externalId, quoteId, transactionId
  • WalletTransaction → remittanceId, externalId, quoteId, settlementId
  • Receipt → remittanceId, externalId, quoteId, transactionId
  • Remittance webhooks → full Remittance snapshot