Integration Builder v2 — Deep Research

Consolidated from 3 parallel research agents: Integration Guide docs, BRLAV2 proxy, BRLAForPlatforms handlers. Total: 167 tool calls, ~360K tokens of analysis.

1. Environment URLs (NEW — must be selectable in builder)

Environment	Base URL	Notes
Sandbox	`https://api.sandbox.avenia.io:10952`	Mock funds, `sandboxReject` flag in KYC
Production	`https://api.avenia.io`	Real funds, real KYC
Developer	`http://localhost:10952`	Local dev, emailToken bypass = `000000`

CORS origins per env:

Developer: localhost:3000, localhost:5173
Sandbox: app.sandbox.avenia.io, pay.sandbox.avenia.io
Production: app.avenia.io, pay.avenia.io

2. Runtime Combinations Endpoint (CRITICAL DISCOVERY)

GET /v2/quote-config-validation (public, no auth)

Returns the single source of truth for all valid combinations at runtime:

{
  "validCurrencyInputPaymentMethods": { "BRL-PIX": true, "EUR-SEPA": true, ... },
  "validCurrencyOutputPaymentMethods": { "BRL-PIX": true, "BRL-PIX-BRCODE": true, ... },
  "validBlockchainSendMethods": { "BRLA-POLYGON:TRANSFER": true, ... }
}

Builder implication: Instead of hardcoding combinations in JSON configs, the builder can fetch this endpoint at page load per environment and dynamically populate the dropdowns. This means adding a new currency on the backend automatically shows up in the builder — zero config changes needed.

3. ALL Valid Combinations (Complete Matrix)

Fiat Currencies

BRL, USD, EUR, ARS, COP, MXN

Blockchain Currencies

BRLA, USDC, USDCe, USDT, USDM, EURC, ETH, GLMR, POL, CHZ, CELO, AVAX

Underlying Currency Map

BRL/BRLA → BRL
USD/USDC/USDCe/USDT/USDM → USD
EUR/EURC → EUR
ARS → ARS
COP → COP
MXN → MXN

Valid Input Payment Methods

Currency	Payment Method
BRL	PIX
USD	WIRE, ACH
EUR	SEPA
ARS	BANK-TRANSFER
COP	BANK-TRANSFER
MXN	SPEI
BRLA	INTERNAL, POLYGON, MOONBEAM, CELO, GNOSIS, BASE, ETHEREUM, AVALANCHE
USDC	INTERNAL, POLYGON, MOONBEAM, CELO, GNOSIS, BASE, ETHEREUM
USDCe	POLYGON
USDT	INTERNAL, POLYGON, MOONBEAM, CELO, GNOSIS, ETHEREUM, TRON
USDM	INTERNAL
EURC	INTERNAL

Valid Output Payment Methods

Same as input PLUS these output-only methods:

BRL-PIX-BRCODE (pay a BR code directly)
BRL-REFUND (refund a previous deposit)
BRL-TED
USD-ACH_SAME_DAY

Valid Blockchain Send Methods

Currency-Chain	PERMIT	TRANSFER
BRLA-POLYGON	Yes	Yes
BRLA-MOONBEAM	Yes	Yes
BRLA-CELO	Yes	Yes
BRLA-GNOSIS	Yes	Yes
BRLA-BASE	Yes	Yes
BRLA-ETHEREUM	Yes	Yes
BRLA-AVALANCHE	Yes	Yes
USDC-POLYGON	Yes	Yes
USDC-CELO	Yes	Yes
USDC-GNOSIS	Yes	Yes
USDC-BASE	Yes	Yes
USDC-ETHEREUM	Yes	Yes
USDC-MOONBEAM	No	Yes
USDCe-POLYGON	Yes	Yes
USDT-POLYGON	Yes	Yes
USDT-CELO	Yes	Yes
USDT-GNOSIS	Yes	Yes
USDT-ETHEREUM	No	Yes
USDT-MOONBEAM	No	Yes
USDT-TRON	No	Yes

Combination Restrictions

Rule	Details
COP off-ramp	`outputCurrency=COP, outputPaymentMethod=BANK-TRANSFER` requires `inputCurrency=USDC` ONLY
PIX-BRCODE output	Requires `outputBrCode` query param with valid BR code
REFUND output	Only with `inputPaymentMethod=BRLA-INTERNAL`, requires `ticketRefundId`
COP amount bounds	min 1,000 COP, max 50,000,000 COP
Markup currencies	Only BRLA, USDC, USDT (NOT EURC)
Fiat decimals	max 2 decimal places
Crypto decimals	max 6 decimal places

Documented Combination Flows

Fiat On-Ramp (Fiat → Crypto)

Input	Output	inputPaymentMethod	outputPaymentMethod	Response contains
BRL	BRLA/USDC/USDT/EURC	PIX	INTERNAL or chain	`brCode`
USD	USDC/USDT	WIRE	INTERNAL or chain	`usdDepositInstructions`
USD	USDC/USDT	ACH	INTERNAL or chain	`usdDepositInstructions` (paymentRail: ACH)
EUR	EURC	SEPA	INTERNAL	`eurDepositInstructions` (IBAN, BIC)
ARS	crypto	BANK-TRANSFER	INTERNAL or chain	`arsDepositInfo`
COP	crypto	BANK-TRANSFER	INTERNAL or chain	`depositUrl` (PSE link)
MXN	crypto	SPEI	INTERNAL or chain	`speiClabe`, `speiBankName`, `speiBankCode`

Fiat Off-Ramp (Crypto → Fiat)

Input	Output	inputPaymentMethod	outputPaymentMethod	Requires
BRLA/USDC/USDT/EURC	BRL	INTERNAL	PIX	`beneficiaryBrlBankAccountId` or pixKey or full bank details
BRLA/USDC/USDT/EURC	BRL	INTERNAL	PIX-BRCODE	`outputBrCode` in quote
BRLA	BRL	INTERNAL	REFUND	`ticketRefundId` in quote
USDC/USDT	USD	INTERNAL	WIRE	`beneficiaryUsdBankAccountId`
USDC/USDT	USD	INTERNAL	ACH	`beneficiaryUsdBankAccountId`
EURC	EUR	INTERNAL	SEPA	`beneficiaryEurBankAccountId`
USDC	COP	INTERNAL	BANK-TRANSFER	`beneficiaryCopBankAccountId`
crypto	ARS	INTERNAL	BANK-TRANSFER	`beneficiaryArsBankAccountId`
crypto	MXN	INTERNAL	SPEI	`beneficiaryMxnBankAccountId`

Crypto → Crypto

Input	Output	Notes
Any crypto	Any crypto	INTERNAL ↔ INTERNAL, INTERNAL ↔ chain, chain ↔ INTERNAL

Internal Transfers (same currency)

Pair	Notes
BRLA ↔ BRLA	Between main/sub accounts
USDC ↔ USDC	Between main/sub accounts
USDT ↔ USDT	Between main/sub accounts
EURC ↔ EURC	Between main/sub accounts

4. ALL Endpoints — Complete Request/Response JSON

4.1 Auth

POST /v2/auth/login

// Request
{ "email": "string", "password": "string" }
// Response: empty (sends email token to user)

// Request
{ "email": "string", "emailToken": "string" }
// Response
{ "accessToken": "string (JWT)", "refreshToken": "string" }

Dev bypass: emailToken = "000000" (DEVELOPER env only)

POST /v2/auth/refresh

// Request
{ "refreshToken": "string" }
// Response
{ "accessToken": "string", "refreshToken": "string" }

POST /v2/auth/create

// Request
{ "email": "string", "password": "string", "confirmPassword": "string", "name": "string", "countryTaxResidence": "string (ISO alpha-3)", "countrySubdivisionTaxResidence": "string" }

PATCH /v2/auth/validate

// Request
{ "email": "string", "emailToken": "string" }

POST /v2/auth/forgot-password

// Request
{ "email": "string" }

PATCH /v2/auth/reset-password/{reset-token}

// Request
{ "password": "string", "confirmPassword": "string" }

Token Usage

Header: Authorization: Bearer {accessToken}
V2 uses 2-step login (login sends email, validate-login confirms)
4platforms uses 1-step login (returns tokens directly)

4.2 Account

GET /v2/account/account-info

// Response
{
  "id": "uuid",
  "email": "string",
  "name": "string",
  "wallets": [{ "id": "uuid", "chain": "string", "address": "string" }],
  "brCode": "string",
  "pixKey": "string"
}

GET /v2/account/balances

// Response
{
  "balances": {
    "BRLA": "518.00",
    "USDC": "1.753243",
    "USDT": "0",
    "EURC": "0",
    "USDM": "0"
  }
}

GET /v2/account/metadata

// Response
{
  "skipLiveness": false,
  "easierLevel1": false,
  "brlUnlocked": true,
  "usdUnlocked": false,
  "eurUnlocked": false,
  "arsUnlocked": false,
  "copUnlocked": false,
  "mxnUnlocked": false
}

GET /v2/account/limits

// Response
{
  "limits": [{
    "currency": "BRL",
    "maxFiatIn": "decimal",
    "maxFiatOut": "decimal",
    "maxChainIn": "decimal",
    "maxChainOut": "decimal",
    "usedLimit": { "fiatIn": "decimal", "fiatOut": "decimal", "chainIn": "decimal", "chainOut": "decimal" }
  }]
}

GET /v2/account/statement

Query: createdAfter, createdBefore, cursor, subAccountId

// Response
{
  "logs": [{
    "token": "string",
    "balanceChange": "decimal",
    "finalBalance": "decimal",
    "description": "string",
    "createdAt": "ISO8601"
  }],
  "cursor": "string"
}

GET /v2/account/access-info

// Response
{
  "id": "uuid",
  "email": "string",
  "permissions": { "admin": true, "payIn": true, "payOut": true, "convert": true, "onChain": true }
}

4.3 KYC

POST /v2/kyc/new-level-1/api

// Request
{
  "fullName": "string",
  "dateOfBirth": "YYYY-MM-DD",
  "countryOfTaxId": "string (ISO alpha-3)",
  "taxIdNumber": "string",
  "email": "string",
  "phone": "string (optional)",
  "country": "string (ISO alpha-3)",
  "state": "string",
  "city": "string",
  "zipCode": "string",
  "streetAddress": "string",
  "uploadedSelfieId": "string (from document upload)",
  "uploadedDocumentId": "string (from document upload)",
  "sandboxReject": false
}
// Response
{ "id": "uuid" }

POST /v2/kyc/new-level-1/web-sdk

// Request (optional)
{ "redirectUrl": "string" }
// Response
{
  "attemptId": "string",
  "authorizedRepresentativeUrl": "string",
  "basicCompanyDataUrl": "string"
}

POST /v2/documents/

// Request
{ "documentType": "ID|DRIVERS-LICENSE|PASSPORT|SELFIE|SELFIE-FROM-LIVENESS" }
// Response
{ "documentId": "string", "uploadUrl": "string (S3 presigned)" }

Then PUT the file to uploadUrl.

Currency-Specific KYC (all require Level 1 APPROVED first)

Endpoint	Request	Response
POST /v2/kyc/usd/api	`{ "sandboxReject": false }`	`{ "attemptId": "uuid" }`
POST /v2/kyc/eur/api	`{ "sandboxReject": false }`	`{ "attemptId": "uuid" }`
POST /v2/kyc/cop/api	(empty)	`{ "attemptId": "uuid" }`
POST /v2/kyc/mxn/api	(empty)	`{ "attemptId": "uuid" }`

POST /v2/kyc/import-token

// Request
{ "importToken": "string" }
// Response
{ "id": "string", "message": "string" }

GET /v2/kyc/attempts/

Query: createdAfter, createdBefore, levelName, status, result, cursor, subAccountId

// Response item
{
  "id": "uuid",
  "levelName": "string",
  "status": "PENDING|PROCESSING|COMPLETED|EXPIRED",
  "result": "APPROVED|REJECTED",
  "resultMessage": "string",
  "retryable": true,
  "createdAt": "ISO8601"
}

4.4 Quote

GET /v2/account/quote/fixed-rate

Query Parameters:

Param	Required	Type	Values
inputCurrency	Yes	string	BRL, USD, EUR, ARS, COP, MXN, BRLA, USDC, USDCe, USDT, USDM, EURC
inputPaymentMethod	Yes	string	PIX, WIRE, ACH, SEPA, BANK-TRANSFER, SPEI, INTERNAL, POLYGON, CELO, ETHEREUM, GNOSIS, MOONBEAM, BASE, TRON, AVALANCHE
outputCurrency	Yes	string	Same as inputCurrency
outputPaymentMethod	Yes	string	Same as inputPaymentMethod + PIX-BRCODE, REFUND, TED, ACH_SAME_DAY
inputAmount	One of	decimal	Amount in input currency
outputAmount	One of	decimal	Amount in output currency
inputThirdParty	Yes	bool	`false` (currently inactive)
outputThirdParty	Yes	bool	`false` (currently inactive)
blockchainSendMethod	Conditional	string	PERMIT or TRANSFER (required when input is blockchain)
markupFloatingFee	No	decimal	Platform markup % (0.01 = 1%)
markupInputFixedFee	No	decimal	Fixed fee on input
markupOutputFixedFee	No	decimal	Fixed fee on output
markupCurrency	No	string	BRLA, USDC, or USDT only
subAccountId	No	uuid	Operate on sub-account
outputBrCode	No	string	Required for PIX-BRCODE output
ticketRefundId	No	uuid	Required for REFUND output
settlementTerms	No	string	FAST (default) or D0

Response:

{
  "quoteToken": "string (JWT — pass to create ticket)",
  "inputCurrency": "string",
  "inputPaymentMethod": "string",
  "inputAmount": "decimal",
  "outputCurrency": "string",
  "outputPaymentMethod": "string",
  "outputAmount": "decimal",
  "markupAmount": "decimal",
  "markupCurrency": "string",
  "blockchainSendMethod": "string",
  "inputThirdParty": false,
  "outputThirdParty": false,
  "appliedFees": [
    { "type": "string", "description": "string", "amount": "decimal", "currency": "string", "rebatable": false }
  ],
  "basePrice": "decimal",
  "pairName": "string",
  "settlementTerms": "string",
  "settlementDate": "ISO8601"
}

Validation rules:

inputAmount XOR outputAmount — exactly one, never both, never zero
Max 6 decimal places for crypto, 2 for fiat
Quote validity: ~15 seconds (JWT expiration)

4.5 Ticket

POST /v2/account/tickets/

Base request (always required):

{
  "quoteToken": "string (REQUIRED — from quote endpoint)"
}

Optional base fields:

{
  "externalId": "string (max 68 chars, for tracking)",
  "customDuration": 600
}

Input-specific fields (include ONE based on inputPaymentMethod):

Input Method	Field	JSON
BRL-PIX	ticketBrlPixInput	`{ "remitterId": "string (if thirdParty)", "additionalData": "string (max 35)" }`
ARS-BANK-TRANSFER	ticketArsInput	`{ "senderCuit": "string (11 digits, REQUIRED)" }`
EUR-SEPA	ticketEurSepaInput	`{ "remitterId": "string (if thirdParty)", "additionalData": "string (max 140)" }`
USD-WIRE/ACH	ticketUsdInput	`{ "remitterId": "string (if thirdParty)", "additionalData": "string (max 140)" }`
Blockchain PERMIT	ticketBlockchainInput	`{ "walletAddress": "string", "permit": { "r": "string", "s": "string", "v": 0, "nonce": 0, "deadline": 0 } }`
Blockchain TRANSFER	ticketBlockchainInput	`{ "walletAddress": "string" }`
Blockchain Personal Sig	ticketBlockchainInput	`{ "walletAddress": "string", "personal": { "signature": "string", "deadline": 0 } }`
COP-BANK-TRANSFER	(none)	No user input needed
MXN-SPEI	(none)	No user input needed

Output-specific fields (include ONE based on outputPaymentMethod):

Output Method	Field	JSON
BRL-PIX	ticketBrlPixOutput	`{ "beneficiaryBrlBankAccountId": "uuid", "pixMessage": "string" }` OR `{ "pixKey": "string" }` OR full bank details
BRL-PIX-BRCODE	(none)	BR code was in quote params
BRL-REFUND	(none)	Refund ticket ID was in quote params
USD-WIRE	ticketUsdOutput	`{ "beneficiaryUsdBankAccountId": "uuid", "wireMessage": "string (max 256)" }`
USD-ACH	ticketUsdOutput	`{ "beneficiaryUsdBankAccountId": "uuid", "achReference": "string (max 10)" }`
EUR-SEPA	ticketEurSepaOutput	`{ "beneficiaryEurBankAccountId": "uuid", "sepaReference": "string (6-140 chars)" }`
COP-BANK-TRANSFER	ticketCopOutput	`{ "beneficiaryCopBankAccountId": "uuid" }`
ARS-BANK-TRANSFER	ticketArsOutput	`{ "beneficiaryArsBankAccountId": "uuid" }`
MXN-SPEI	ticketMxnOutput	`{ "beneficiaryMxnBankAccountId": "uuid" }`
Blockchain (INTERNAL)	ticketBlockchainOutput	`{ "beneficiaryWalletId": "uuid" }` OR `{ "walletAddress": "string", "walletChain": "string" }`
Blockchain (chain)	ticketBlockchainOutput	`{ "beneficiaryWalletId": "uuid" }` (REQUIRED — registered beneficiary)

Markup (optional):

{ "ticketMarkupInput": { "markupWalletAddress": "string" } }

Response varies by input payment method:

Input Method	Additional Response Fields
BRL-PIX	`{ "id": "uuid", "expiration": "ISO8601", "brCode": "string" }`
USD-WIRE/ACH	`{ "id": "uuid", "usdDepositInstructions": { "accountHolderName", "bankAccountNumber", "bankRoutingNumber", "accountType", "bankName", "bankAddress", "depositMessage", "paymentRail" } }`
EUR-SEPA	`{ "id": "uuid", "eurDepositInstructions": { "bankBeneficiaryName", "iban", "bic", "bankName", "depositMessage", "paymentRail", "currency", "amount" } }`
COP-BANK-TRANSFER	`{ "id": "uuid", "depositUrl": "string (PSE payment link)" }`
MXN-SPEI	`{ "id": "uuid", "speiClabe": "string", "speiBankName": "string", "speiBankCode": "string" }`
Blockchain	`{ "id": "uuid" }`
All outputs	`{ "id": "uuid" }`

Ticket expiration rules:

Same underlying currency: 72 hours
Cross-currency: 10 minutes
MXN-SPEI input: 35 minutes (override)
D0 settlement: expires at 19:30 UTC same day
customDuration: min 300s, cannot exceed default

GET /v2/account/tickets/{ticket-id}

// Response
{
  "id": "uuid",
  "externalId": "string",
  "status": "UNPAID|PROCESSING|PAID|FAILED|PARTIAL-FAILED|CANCELED",
  "reason": "string",
  "failureReason": "string",
  "createdAt": "ISO8601",
  "updatedAt": "ISO8601",
  "expiresAt": "ISO8601",
  "quote": {
    "inputCurrency": "string",
    "inputPaymentMethod": "string",
    "inputAmount": "decimal",
    "outputCurrency": "string",
    "outputPaymentMethod": "string",
    "outputAmount": "decimal",
    "markupCurrency": "string",
    "markupAmount": "decimal",
    "sendMethod": "string",
    "basePrice": "decimal",
    "appliedFees": [{ "type", "description", "amount", "currency" }],
    "pairName": "string"
  },
  "brazilianFiatSenderInfo": { "brCode", "endToEndId", "name", "taxId", "bankCode", "branchCode", "accountNumber", "accountType" },
  "brazilianFiatReceiverInfo": { "pixKey", "taxId", "userName", "bankCode", "branchCode", "accountNumber", "endToEndId", "brCode" },
  "blockchainSenderInfo": { "walletAddress", "txHash" },
  "blockchainReceiverInfo": { "walletAddress", "walletChain", "walletMemo", "txHash" },
  "americanFiatSenderInfo": { "accountHolderName", "bankAccountNumber", "bankRoutingNumber", "bankName", "depositMessage", "paymentRail" },
  "americanFiatReceiverInfo": { "same fields" },
  "europeanFiatSenderInfo": { "bankBeneficiaryName", "iban", "bic", "bankName", "depositMessage", "paymentRail" },
  "europeanFiatReceiverInfo": { "same fields" },
  "argentineFiatSenderInfo": { "cvu", "cuit", "name", "transactionId" },
  "argentineFiatReceiverInfo": { "cvu", "cuit", "accountHolder", "transactionId" },
  "markupInfo": { "markupWalletAddress", "txHash" }
}

GET /v2/account/tickets/

Query: createdAfter, createdBefore, cursor, status, inputCurrency, inputPaymentMethod, outputCurrency, outputPaymentMethod, endToEndId, externalId, subAccountId

PATCH /v2/account/tickets/{ticket-id}/cancel

No body needed.

GET /v2/account/tickets/{ticket-id}/receipt

Returns PDF binary (only for PAID tickets).

4.6 Beneficiaries

Wallet Beneficiary

POST /v2/account/beneficiaries/wallets/

// Request
{ "alias": "string", "description": "string", "walletAddress": "string", "walletChain": "string", "walletMemo": "string" }
// Response
{ "id": "uuid" }

Valid chains: POLYGON, CELO, ETHEREUM, GNOSIS, MOONBEAM, TRON, BASE, AVALANCHE

GET /v2/account/beneficiaries/wallets/ Query: createdAfter, createdBefore, cursor, alias, walletAddress, walletChain, subAccountId

// Response item
{ "id": "uuid", "alias": "string", "description": "string", "walletAddress": "string", "walletChain": "string", "walletMemo": "string", "createdAt": "ISO8601" }

BRL Bank Account

POST /v2/account/beneficiaries/bank-accounts/brl/

// Option 1: PIX key (auto-resolves bank details)
{ "alias": "string", "pixKey": "string" }
// Option 2: Full bank details
{ "alias": "string", "description": "string", "userName": "string", "bankCode": "string (3 or 8 digits)", "branchCode": "string", "accountNumber": "string", "accountType": "checking|payment|savings|salary", "taxId": "string (CPF or CNPJ)" }
// Response
{ "id": "uuid" }

USD Bank Account

POST /v2/account/beneficiaries/bank-accounts/usd/

// Request
{
  "alias": "string",
  "description": "string",
  "bankAccountNumber": "string",
  "bankRoutingNumber": "string (ABA)",
  "bankBeneficiaryName": "string",
  "bankName": "string",
  "beneficiaryAddress": {
    "streetLine1": "string", "streetLine2": "string",
    "city": "string", "state": "string",
    "postalCode": "string", "country": "string"
  },
  "bankAddress": { "streetLine1": "string", "city": "string", "state": "string", "postalCode": "string", "country": "string" }
}
// Response
{ "id": "uuid" }

EUR Bank Account

POST /v2/account/beneficiaries/bank-accounts/eur/

// Request
{
  "alias": "string",
  "description": "string",
  "iban": "string",
  "bic": "string (optional)",
  "country": "string (ISO alpha-3)",
  "bankBeneficiaryName": "string",
  "isBusiness": false
}
// Response
{ "id": "uuid" }

Note: SEPA only — SWIFT NOT supported.

COP Bank Account

POST /v2/account/beneficiaries/bank-accounts/cop/

// Request
{
  "alias": "string",
  "description": "string",
  "beneficiaryName": "string",
  "beneficiaryType": "string",
  "beneficiaryEmail": "string",
  "beneficiaryAddress": {},
  "phoneNumber": "string",
  "accountType": "string",
  "bankAccountNumber": "string",
  "documentNumber": "string (6-10 digits, Cedula)",
  "documentType": "string",
  "bankId": "string (bank_cop_XXX format)",
  "bankName": "string"
}
// Response
{ "id": "uuid" }

GET /v2/account/beneficiaries/bank-accounts/cop/supported-banks

// Response
{ "banks": [{ "bankId": "bank_cop_022", "bankName": "Bancolombia" }, ...] }

MXN Bank Account

POST /v2/account/beneficiaries/bank-accounts/mxn/

// Request
{
  "alias": "string",
  "description": "string",
  "beneficiaryName": "string",
  "beneficiaryType": "string",
  "beneficiaryEmail": "string",
  "beneficiaryAddress": {},
  "phoneNumber": "string",
  "clabe": "string",
  "bankId": "string",
  "bankName": "string"
}
// Response
{ "id": "uuid" }

GET /v2/account/beneficiaries/bank-accounts/mxn/supported-banks

// Response
{ "banks": [{ "bankId": "string", "bankName": "string" }, ...] }

ARS Bank Account

POST /v2/account/beneficiaries/bank-accounts/ars/

// Request
{ "alias": "string", "description": "string", "cvu": "string" }
// Response
{ "id": "uuid", "accountData": { "cvu": "string", "accountHolders": [{ "cuit": "string", "name": "string" }] } }

4.7 Subaccounts

POST /v2/account/sub-accounts/

// Request
{ "name": "string", "accountType": "INDIVIDUAL" }
// Response
{ "id": "uuid" }

GET /v2/account/sub-accounts/

// Response
{ "subAccounts": [{ "id": "uuid", "name": "string", "accountType": "string", "createdAt": "ISO8601" }] }

4.8 Webhooks

POST /v2/notifications/webhooks/

// Request
{ "url": "string", "subscriptions": ["TICKET", "KYC", "LIMIT-UPDATE"] }
// Response
{ "id": "uuid" }

Max 3 webhooks per account. Subscription "*" = all events.

Webhook Event Types

TICKET: TICKET-CREATED, DEPOSIT-PROCESSING, DEPOSIT-SUCCESS, DEPOSIT-FAILED, DELIVERY-PROCESSING, DELIVERY-SUCCESS, DELIVERY-FAILED, TICKET-COMPLETE, DELIVERY-PARTIAL-FAILED
KYC: KYC status changes
LIMIT-UPDATE: Limit changes

Signature Verification

Header: Signature (base64)
Verify with RSA public key from GET /v2/public-key (PSS padding, SHA256)

4.9 Banking

GET /v2/account/bank-accounts/brl/

Own BRL bank account info (Avenia's account for receiving PIX).

GET /v2/account/bank-accounts/brl/pix-info

Lookup PIX key owner info.

GET /v2/account/bank-accounts/brl/static-br-code

Query: amount (required), referenceLabel (required, max 19 chars), additionalData (max 35), subAccountId Returns a static BR code string.

4.10 MFA

POST /v2/auth/mfa/totp/create

// Response
{ "secret": "string", "qrCode": "string (base64 PNG)" }

POST /v2/auth/mfa/totp/validate

// Request
{ "otp": "string (6 digits)", "emailToken": "string" }

4.11 API Keys

POST /v2/auth/api-keys/

// Request
{ "otp": "string", "name": "string", "publicKey": "string (PEM)", "whitelistedIPs": ["CIDR"] }
// Response
{ "apiKey": "uuid" }

API Key auth headers:

X-API-Key: UUID
X-API-Timestamp: unix millis
X-API-Signature: base64(sign(sha256(idempotencyKey + timestamp + method + requestURI + body)))
X-API-IdempotencyKey: unique string

Supports RSA, ECDSA, Ed25519.

4.12 Payment Sessions (V2 only)

POST /v2/account/payment-session/

Creates a hosted payment page. This is a V2-specific feature (not in 4platforms).

GET /v2/payment-session/{id} (public, no auth)

Get payment session details for the hosted page.

4.13 Address & Proof of Address

GET /v2/account/address/

PUT /v2/account/address/

POST /v2/account/address/proof-of-address/api

5. Proxy Mapping (V2 → 4platforms)

V2: /v2/account/{feature}
4plat: /v2/workspaces/{workspaceId}/users/{userId}/{feature}

V2 resolves workspaceId + userId from JWT token subject → AccountInfo DB lookup
V2 replaces user's JWT with a service-to-service JWT for 4platforms calls
Most request/response bodies are passed through as raw JSON
Headers added: Content-Type: application/json, Authorization: Bearer {serviceJWT}

6. Documented Use Cases (Flow Templates for Builder)

Template 1: PIX → Stablecoin → PIX

Login → KYC → Create subaccount → Subaccount KYC → Webhook setup → PIX IN (BRL→BRLA) → Check balance → PIX OUT (BRLA→BRL)

Template 2: PIX → Stablecoin → On-Chain Transfer

Login → KYC → Create subaccount → Subaccount KYC → Webhook setup → PIX IN (BRL→BRLA) → Convert BRLA→USDC → Transfer to external wallet

Template 3: PayOut via BrCode

Template 4: Sandbox Mock Flow

Quote (BRL PIX → crypto) → Create ticket → Simulated payment → Balance credited

7. Things Missing from Current Builder (NEW blocks needed)

Feature	Current Builder	Needed in v2
ARS operations	No	Yes — BANK-TRANSFER in/out
COP operations	No	Yes — BANK-TRANSFER in/out, supported-banks
MXN operations	No	Yes — SPEI in/out, supported-banks
EUR operations	No	Yes — SEPA in/out
USD operations	Partial	Full — WIRE, ACH, ACH_SAME_DAY
Subaccounts	No	Yes — create, list, operate on behalf
Webhooks	No	Yes — register, manage, verify
MFA/TOTP	No	Yes — setup, validate
API Keys	No	Yes — register with public key
Payment Sessions	No	Yes — create hosted payment page
Document Upload	No	Yes — pre-signed URL flow for KYC
Currency-specific KYC	No	Yes — USD, EUR, COP, MXN KYC blocks
Account Creation	No	Yes — create + validate email
Static BR Code	No	Yes — generate for receiving
Ticket Receipt	No	Yes — download PDF
Ticket Cancel	No	Yes — cancel unpaid ticket
Address/PoA	No	Yes — address management
Email Notifications	No	Yes — configure email alerts
Supported Banks	No	Yes — COP, MXN bank lists

8. Key Source Files Reference

BRLAForPlatforms

Valid combinations: Lib/pkg/quoteUtils/quoteUtils.go
Ticket entity + all sub-structs: Lib/entities/ticket.go
TicketApi (GET response): Lib/entities/ticketApi.go
Quote entity: Lib/entities/quote.go
Chain constants: Lib/entities/blockchainInstruction.go
Create ticket usecase: UsersService/internal/usecases/createTicket.go
Quote validation: PricingService/internal/usecases/quote.go
Routes: ApiGateway/internal/infra/webServer/routes/*.go
DTOs: ApiGateway/internal/dtos/*.go

BRLAV2

Routes: ApiGateway/internal/infra/webServer/routes/*.go
DTOs: ApiGateway/internal/dtos/*.go
4platforms SDK (proxy): Lib/pkg/brlaForPlatformsSDK/brlaForPlatformsSDK.go
Config: Lib/configs/configs.go

Integration Guide

Combinations: docs/Operations/combinations.md
Use cases: docs/Usecases/*.md
KYC: docs/KYC/*.md
Auth: docs/Security/*.md

1. Environment URLs (NEW — must be selectable in builder)​

2. Runtime Combinations Endpoint (CRITICAL DISCOVERY)​

3. ALL Valid Combinations (Complete Matrix)​

Fiat Currencies​

Blockchain Currencies​

Underlying Currency Map​

Valid Input Payment Methods​

Valid Output Payment Methods​

Valid Blockchain Send Methods​

Combination Restrictions​

Documented Combination Flows​

Fiat On-Ramp (Fiat → Crypto)​

Fiat Off-Ramp (Crypto → Fiat)​

Crypto → Crypto​

Internal Transfers (same currency)​

4. ALL Endpoints — Complete Request/Response JSON​

4.1 Auth​

POST /v2/auth/login​

POST /v2/auth/validate-login​

POST /v2/auth/refresh​

POST /v2/auth/create​

PATCH /v2/auth/validate​

POST /v2/auth/forgot-password​

PATCH /v2/auth/reset-password/{reset-token}​

Token Usage​

4.2 Account​

GET /v2/account/account-info​

GET /v2/account/balances​

GET /v2/account/metadata​

GET /v2/account/limits​

GET /v2/account/statement​

GET /v2/account/access-info​

4.3 KYC​

POST /v2/kyc/new-level-1/api​

POST /v2/kyc/new-level-1/web-sdk​

POST /v2/documents/​

Currency-Specific KYC (all require Level 1 APPROVED first)​

POST /v2/kyc/import-token​

GET /v2/kyc/attempts/​

4.4 Quote​

GET /v2/account/quote/fixed-rate​

4.5 Ticket​

POST /v2/account/tickets/​

GET /v2/account/tickets/{ticket-id}​

GET /v2/account/tickets/​

PATCH /v2/account/tickets/{ticket-id}/cancel​

GET /v2/account/tickets/{ticket-id}/receipt​

4.6 Beneficiaries​

Wallet Beneficiary​

BRL Bank Account​

USD Bank Account​

EUR Bank Account​

COP Bank Account​

MXN Bank Account​

ARS Bank Account​

4.7 Subaccounts​

POST /v2/account/sub-accounts/​

GET /v2/account/sub-accounts/​

4.8 Webhooks​

POST /v2/notifications/webhooks/​

Webhook Event Types​

Signature Verification​

4.9 Banking​

GET /v2/account/bank-accounts/brl/​

GET /v2/account/bank-accounts/brl/pix-info​

GET /v2/account/bank-accounts/brl/static-br-code​

4.10 MFA​

POST /v2/auth/mfa/totp/create​

POST /v2/auth/mfa/totp/validate​

4.11 API Keys​

POST /v2/auth/api-keys/​

4.12 Payment Sessions (V2 only)​

POST /v2/account/payment-session/​

GET /v2/payment-session/{id} (public, no auth)​

4.13 Address & Proof of Address​

GET /v2/account/address/​

PUT /v2/account/address/​

POST /v2/account/address/proof-of-address/api​

5. Proxy Mapping (V2 → 4platforms)​

6. Documented Use Cases (Flow Templates for Builder)​