Foreign USD KYC

Use this flow when your users are outside Brazil and need USD onramp (WIRE/ACH → USDC) or offramp (USDC → USD bank payout) through Avenia. Pods exposes foreign KYC separately from the Brazilian Pix flow documented in Set up Pods KYC. Brazilian profiles use cpf and brlaEnabled; foreign profiles use taxId / taxIdCountry and usdEnabled.

EUR capability is planned but not available yet. Poll eurEnabled on status responses only for forward compatibility — it stays false today.

Prerequisites

You need to understand these integration values:

Value	Source	Used for
`PODS_API_BASE_URL`	Pods	Base URL for API requests (`https://api.pods.finance`).
`PODS_API_KEY`	Pods	Server-to-server authentication. Get an API key.
`AVENIA_PARTNER_TOKEN`	Pods	Sumsub reusable-identity recipient setup. Pods provides for you.
`AVENIA_FOR_CLIENT_ID`	Pods	`forClientId` when generating Sumsub share tokens. Pods provides for you.

Send all requests from your backend with x-api-key. Never expose the API key in browser or mobile clients.

End-to-end flow

Complete Sumsub verification

The applicant finishes your Sumsub WebSDK level. Confirm reviewStatus: completed and reviewResult.reviewAnswer: GREEN before generating a share token.

Submit share token to Pods

POST /api/v1/kyc/foreign/sumsub-share-token with taxId, taxIdCountry, shareToken, sumsubApplicantId, email, and walletAddress.

Poll KYC status

GET /api/v1/kyc/status?kycUserId=… until status is approved. Level 1 approval does not enable USD ramps yet — usdEnabled stays false. Public Pix (BRL) and public USD are separate identities — a user typically has one or the other.

Unlock USD

For Avenia: POST /api/v1/kyc/currency-unlock with { "currency": "usd", "kycUserId": "…" }. Poll until usdEnabled is true. For UnblockPay, first provision an individual with POST /api/v1/kyc/sessions/:kycUserId/submit and rampProvider=unblockpay using taxId + taxIdCountry (and the home address). Finish UnblockPay KYC via hosted verificationLink or POST /api/v1/kyc/sessions/:kycUserId/documents — see UnblockPay KYC. Then POST /api/v1/kyc/currency-unlock with rampProvider=unblockpay refreshes rails and, when the bank fields in ramps.unblockpay.unlock.requiredBodyFields are sent, registers a wire External Account for offramp. That path never sets top-level usdEnabled. When the UnblockPay nest is non-terminal, GET /api/v1/kyc/status live-refreshes UnblockPay and may trigger /check after document uploads. capabilities.USD is the source of truth after review — LIGHT create alone is not enough.

Quote and settle onramp

See Move Money with Pods Ramp for quote examples and deposit instructions. GET /v2/swap/quote with originChain=fiat, destinationChain (ethereum | base | polygon), tokenIn=USD, USDC tokenOut, amountIn or amountOut, destinationAddress, and optional usdPaymentMethod=ACH or WIRE. With destinationAddress, the response includes ACH/WIRE deposit instructions — no EVM tx to sign. Poll GET /v2/swap/status/{quoteId} until fulfilled. Avenia (default) supports WIRE and ACH on ethereum, base, and polygon. Pin rampProvider=unblockpay only for USD WIRE on polygon or base — ACH and ethereum return RAMP_PROVIDER_NOT_ELIGIBLE. UnblockPay onramp is ready when ramps.unblockpay.capabilities.USD is true.

Quote and settle offramp

See Move Money with Pods Ramp for the full quote examples and execution details. GET /v2/swap/quote with originChain (ethereum | base | polygon), destinationChain=fiat, USDC tokenIn, tokenOut=USD, amountIn or amountOut, originAddress, USD bank fields, and optional usdPaymentMethod. Sign every item in transactionData using that item’s chainId. Poll status until fulfilled. UnblockPay offramp additionally requires ramps.unblockpay.unlock.offrampReady.

curl -sS -X POST \
  -H "x-api-key: $PODS_API_KEY" \
  -H "Content-Type: application/json" \
  "$PODS_API_BASE_URL/api/v1/kyc/foreign/sumsub-share-token" \
  -d '{
    "email": "[email protected]",
    "shareToken": "SUMSUB_SHARE_TOKEN",
    "sumsubApplicantId": "6a3502bf7fee2fab5377cb1e",
    "taxId": "123456789",
    "taxIdCountry": "USA",
    "walletAddress": "0xb794F5eA0ba39494cE839613fffBA74279579268"
  }'

Response:

{
  "kycUserId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "provider_pending"
}

Pods stores only a salted hash and last four digits of the tax id — never the full value. When the stored profile is already approved, retries with the same customer, applicant, tax ID, and an already linked wallet return the original kycUserId and status: approved without creating or changing a profile or importing another token. Legacy approvals, including copied approvals and profiles without import metadata, follow the same rule. The request still requires a share token, but Pods does not validate or consume it on this approved retry. Pods trusts the authenticated integration’s identifiers; your backend must authenticate the end user and authorize their use of that KYC profile. Changing the applicant while claiming a tax ID already approved for your customer returns 409 KYC_VERIFIED_BINDING_REQUIRED without creating a profile. Changing an existing profile’s wallet returns 409 SUMSUB_WALLET_MISMATCH; changing its tax ID returns 409 SUMSUB_TAX_ID_MISMATCH. An approved profile without a stored identity hash cannot be matched and returns 409 KYC_VERIFIED_BINDING_REQUIRED. A duplicate-tax-ID rejection does not establish approval for the current applicant.

2. Poll status (Level 1 approved, USD still locked)

curl -sS \
  -H "x-api-key: $PODS_API_KEY" \
  "$PODS_API_BASE_URL/api/v1/kyc/status?kycUserId=550e8400-e29b-41d4-a716-446655440000"

Example shape after Level 1 is approved but before currency unlock (live capture pattern):

{
  "kycUserId": "a0bfbe64-99fb-4823-902a-7187c67348bb",
  "provider": "bigdatacorp",
  "email": "[email protected]",
  "walletAddress": "0xb0b6234dCbB885409eF23fD5FD5E63eE33b1377f",
  "status": "approved",
  "brlaEnabled": true,
  "usdEnabled": false,
  "eurEnabled": false,
  "rejectReason": null,
  "providerStatus": "COMPLETED",
  "providerResult": "AVENIA_IDENTITY_REUSED",
  "providerMessage": "An approved Avenia identity is available for reuse",
  "livenessStatus": "passed",
  "documentStatus": "passed",
  "birthDate": "1991-03-11",
  "ageAtVerification": 35,
  "aveniaApprovedAt": "2026-07-25T11:51:11.377Z",
  "updatedAt": "2026-07-25T11:51:11.378Z",
  "reason": null
}

Wait until status is approved. For rejections, read the normalized reason object (not providerResult).

status: approved alone is not enough for USD ramps. You must unlock USD and wait until usdEnabled is true.

3. Unlock USD capability

curl -sS -X POST \
  -H "x-api-key: $PODS_API_KEY" \
  -H "Content-Type: application/json" \
  "$PODS_API_BASE_URL/api/v1/kyc/currency-unlock" \
  -d '{
    "currency": "usd",
    "kycUserId": "550e8400-e29b-41d4-a716-446655440000"
  }'

The success response is the full KYC status object. Immediately after a successful submit, usdEnabled is often still false while Avenia processes the USD KYC attempt:

{
  "kycUserId": "65a7197f-85d9-4e5f-a12f-702daf0995c7",
  "provider": "bigdatacorp",
  "email": "[email protected]",
  "walletAddress": "0xb0b6234dCbB885409eF23fD5FD5E63eE33b1377f",
  "status": "approved",
  "brlaEnabled": true,
  "usdEnabled": false,
  "eurEnabled": false,
  "providerStatus": "COMPLETED",
  "providerResult": "APPROVED",
  "providerMessage": "An approved Avenia identity is available for reuse",
  "livenessStatus": "passed",
  "documentStatus": "passed",
  "updatedAt": "2026-08-28T22:44:33.094Z"
}

Poll GET /api/v1/kyc/status until usdEnabled is true:

{
  "kycUserId": "65a7197f-85d9-4e5f-a12f-702daf0995c7",
  "status": "approved",
  "brlaEnabled": true,
  "usdEnabled": true,
  "eurEnabled": false,
  "updatedAt": "2026-08-28T22:49:05.042Z"
}

Currency-unlock errors

HTTP	`error.code`	When
`400`	`AVENIA_CURRENCY_KYC_SUBMIT_FAILED`	Avenia rejected the USD KYC (example: missing identification document on the subaccount)
`500`	`INTERNAL_SERVER_ERROR`	Avenia credentials not configured on the API (`Avenia API key not configured`)

Example — missing identification document:

{
  "error": {
    "code": "AVENIA_CURRENCY_KYC_SUBMIT_FAILED",
    "message": "missing required document: identification document",
    "details": {
      "provider": "avenia",
      "providerStatus": 400,
      "providerMessage": "missing required document: identification document"
    }
  }
}

Documents are collected during Level 1 / Sumsub — POST /currency-unlock does not accept document uploads in the body.

4. USD beneficiary

Offramp resolve-or-create

Pass bank account fields on GET /v2/swap/quote with originAddress. Pods lists existing Avenia beneficiaries for the KYC subaccount; if account number + routing match, it reuses that id, otherwise it creates one and stores it on the quote (rawQuote.beneficiaryUsdBankAccountId, internal). Required query fields:

Field	Notes
`bankAccountNumber`	Account number
`bankRoutingNumber`	ABA routing
`bankBeneficiaryName`	Legal name on the account. ASCII only — Avenia rejects accents (`ã`, `é`, …) with `bankBeneficiaryName is invalid` → `QUOTE_GENERATION_FAILED`.
`bankName`	Bank name
`beneficiaryStreetLine1`	Address line 1
`beneficiaryCity` / `beneficiaryState` / `beneficiaryPostalCode` / `beneficiaryCountry`	Address
`alias`	Optional; defaults to `bankBeneficiaryName`
`beneficiaryStreetLine2` / `description`	Optional

Inspect is not exposed as a separate KYC API — beneficiaries are created or reused automatically on offramp quote from the flat bank fields (Pix-style destination).

5. USD↔USDC ramps (summary)

Supported USDC networks for v1 follow Avenia’s USD→USDC allowlist: ethereum, base, and polygon. When Avenia supports the destination chain, it delivers USDC directly to the user’s wallet (no Pods inventory hop). For full quotes, deposit instructions, and execution examples, see the Move Money guide.

Direction	Chains	Payment rail	Fees
Onramp	`originChain=fiat`, `destinationChain=<evm>`	WIRE or ACH (`usdPaymentMethod`, default WIRE)	Avenia pass-through; no Pods/customer swap markup; In Fee is USD and appears as `kind: paymentRail`
Offramp	`originChain=<evm>`, `destinationChain=fiat`	WIRE or ACH to registered beneficiary	Avenia pass-through; Out Fee is USDC (live ACH ~1.0125 USDC, WIRE ~10.035 USDC). Already in the `tokenIn`/`tokenOut` spread and as `kind: paymentRail` on `tokenIn`

Token addresses (USDC)

Network	Chain id	Address
Ethereum	`1`	`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`
Base	`8453`	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
Polygon	`137`	`0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359`

Pass exactly one of amountIn or amountOut — same contract as the onramp, inverted:

Mode	Query	Fixes	Typical use
Exact USDC send	`amountIn`	USDC raw (6 decimals)	“User sends 5 USDC” — USD out varies after rail fee
Exact USD receive	`amountOut`	USD cents (`500` = USD 5.00)	“User receives $4.00” — Avenia returns the USDC the wallet must send

With amountOut, Pods asks Avenia once (outputAmount); tokenIn.amount is the USDC to transfer (Out Fee included). Optional usdPaymentMethod is WIRE (default) or ACH. Live quote smoke (2026-09-10, Polygon USDC, Picnic usdEnabled wallet — quotes only, nothing signed):

Mode	Request	Result	`quote.quoteId`
ACH `amountIn`	5 USDC (`5000000`)	USD 3.98 (`tokenOut=398`)	`7a6c2c6c-96b3-4fe0-866a-8ab32d076a22`
ACH `amountOut`	USD 4.00 (`400`)	5.012532 USDC (`tokenIn=5012532`)	`77fef6a2-358e-462a-8396-b9e2469f03d0`
WIRE `amountOut`	USD 4.00 (`400`)	14.035088 USDC	`d14a8e40-8689-4505-9f5e-7da67e329cc8`

A 5 USDC amountIn covers ACH but not WIRE (~10 USDC Out Fee). Prefer amountOut when the product promise is “receive $N”.

Sign using each transactionData[].chainId. Top-level chainId and quote.tokenIn.chainId must match the origin (polygon → 137).

Preferred offramp quote (bank fields → resolve-or-create, then executable payload). Use ASCII bankBeneficiaryName (example John Smith, not accented names):

curl -sS \
  -H "x-api-key: $PODS_API_KEY" \
  "$PODS_API_BASE_URL/v2/swap/quote?originChain=polygon&destinationChain=fiat&tokenIn=0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359&tokenOut=USD&amountOut=400&originAddress=0xb794F5eA0ba39494cE839613fffBA74279579268&bankAccountNumber=581984177591&bankRoutingNumber=721738952&bankBeneficiaryName=John%20Smith&bankName=JPMorgan%20Chase%20Bank%20N.A.&beneficiaryStreetLine1=123%20Main%20Street&beneficiaryCity=New%20York&beneficiaryState=NY&beneficiaryPostalCode=10001&beneficiaryCountry=USA&usdPaymentMethod=ACH"

Exact-input form: replace amountOut=400 with amountIn=5000000 (5 USDC). WIRE: keep amountOut=400 and set usdPaymentMethod=WIRE (expects ~14 USDC in). Track progress with GET /v2/swap/status/{quoteId} and GET /actions/{id}.

Offramp and onramp both require usdEnabled: true on the KYC profile tied to the wallet (destinationAddress on onramp, originAddress on offramp). Pods rejects quotes when the wallet has no unlocked USD capability.

Money movement and quotes

Onramp/offramp quote examples, deposit instructions, and executable transactionData live in the Move Money guide: Move Money with Pods Ramp. Use that guide for GET /v2/swap/quote, GET /v2/swap/status/{quoteId}, and execution details.

Status fields reference

Field	Meaning
`status`	Normalized Pods KYC state (`approved`, `provider_pending`, etc.)
`brlaEnabled`	Brazilian Pix capability
`usdEnabled`	USD WIRE/ACH ramps enabled after currency unlock
`eurEnabled`	Reserved; always `false` today

API reference

Open the Ramp group in the API Reference tab for full request/response schemas:

POST /api/v1/kyc/foreign/sumsub-share-token
POST /api/v1/kyc/currency-unlock
GET /api/v1/kyc/status
GET /v2/swap/quote
GET /v2/swap/status/{quoteId}
GET /actions/{id}

Captured examples

Internal live captures used to author this guide (do not ship secrets from local .env):

Fixture	Path
KYC status / unlock errors	`test/fixtures/kyc/usdCurrencyUnlockStatusCaptures.ts`
ACH onramp quote + deposit instructions	`test/fixtures/bridge/usdAchPolygonOnrampQuoteCapture.ts`
ACH/WIRE offramp live quotes (no bank PII)	Ramp quotes — USDC→USD (`7a6c2c6c-…`, `77fef6a2-…`, `d14a8e40-…`)

Overview

Guides

Integrations

Agents

Prerequisites

End-to-end flow

2. Poll status (Level 1 approved, USD still locked)

3. Unlock USD capability

Currency-unlock errors

4. USD beneficiary

Offramp resolve-or-create

5. USD↔USDC ramps (summary)

Token addresses (USDC)

Money movement and quotes

Status fields reference

API reference

Captured examples

​Prerequisites

​End-to-end flow

​1. Submit foreign share token

​2. Poll status (Level 1 approved, USD still locked)

​3. Unlock USD capability

​Currency-unlock errors

​4. USD beneficiary

​Offramp resolve-or-create

​5. USD↔USDC ramps (summary)

​Token addresses (USDC)

​Money movement and quotes

​Status fields reference

​API reference

​Captured examples

Prerequisites

End-to-end flow

1. Submit foreign share token

2. Poll status (Level 1 approved, USD still locked)

3. Unlock USD capability

Currency-unlock errors

4. USD beneficiary

Offramp resolve-or-create

5. USD↔USDC ramps (summary)

Token addresses (USDC)

Money movement and quotes

Status fields reference

API reference

Captured examples