Foreign USD KYC

Use this flow when your users are outside Brazil and need USD onramp (WIRE → USDC) or offramp (USDC → USD bank payout). 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

Default path: 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 Wire to USDC (onramp) for quote examples and deposit instructions. GET /v2/swap/quote with originChain=fiat, destinationChain (base | polygon), tokenIn=USD, USDC tokenOut, amountIn or amountOut, and destinationAddress. With destinationAddress, the response includes the WIRE deposit instructions — no EVM tx to sign. Poll GET /v2/swap/status/{quoteId} until fulfilled. A default provider handles USD WIRE unless you pin one; pass rampProvider=unblockpay to route USD WIRE through UnblockPay on base or polygon. Requesting a chain outside base/polygon returns RAMP_PROVIDER_NOT_ELIGIBLE. UnblockPay onramp is ready when ramps.unblockpay.capabilities.USD is true.

Quote and settle offramp

See USDC to Wire (offramp) for the full quote examples and execution details. GET /v2/swap/quote with originChain (base | polygon), destinationChain=fiat, USDC tokenIn, tokenOut=USD, amountIn or amountOut, originAddress, and the USD bank fields. 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 the provider 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`	The ramp provider rejected the USD KYC (example: missing identification document on the subaccount)
`500`	`INTERNAL_SERVER_ERROR`	Ramp provider credentials not configured on the API

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.

UnblockPay: register the wire External Account

UnblockPay pays USD wire offramps only to a bank account registered beforehand (an External Account). Send the bank fields on POST /api/v1/kyc/currency-unlock with rampProvider=unblockpay to register it:

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",
    "rampProvider": "unblockpay",
    "kycUserId": "550e8400-e29b-41d4-a716-446655440000",
    "bankBeneficiaryName": "John Smith",
    "bankName": "Example Bank N.A.",
    "bankAccountNumber": "000000000000",
    "bankRoutingNumber": "000000000",
    "beneficiaryStreetLine1": "123 Main Street",
    "beneficiaryCity": "New York",
    "beneficiaryState": "NY",
    "beneficiaryPostalCode": "10001",
    "beneficiaryCountry": "USA",
    "isThirdParty": false
  }'

US beneficiary address only. UnblockPay’s wire provider rejects any other country, so Pods refuses it up front with UNBLOCKPAY_WIRE_BENEFICIARY_COUNTRY_UNSUPPORTED. Send beneficiaryCountry=USA (US is also accepted). The address does not need to match the KYC address.
isThirdParty (optional, default false) tells UnblockPay whether the bank account belongs to someone other than the KYC holder:
- Leave it out, or send false, when the account is the KYC holder’s own. That is the common case: the user withdraws to their own US account.
- Send true only when bankBeneficiaryName is a different person or company, for example a family member or the user’s employer.
- Send the real value: it is a compliance declaration to the provider. It does not block payouts, and it is fixed once the External Account exists.
Approval. UnblockPay reviews each External Account. Offramp quotes return UNBLOCKPAY_WIRE_EXTERNAL_ACCOUNT_NOT_APPROVED while the account is not approved.
One account per KYC profile. A second unlock with bank fields keeps the account already registered. Offramp quotes must send the same bankAccountNumber and bankRoutingNumber, or they fail with USD_WIRE_ACCOUNT_MISMATCH.

The response is the KYC status object. ramps.unblockpay.unlock.offrampReady becomes true once the External Account is registered.

HTTP	`error.code`	When
`409`	`UNBLOCKPAY_KYC_NOT_PROVISIONED`	The profile has no UnblockPay customer yet
`422`	`VALIDATION_ERROR`	Some, but not all, of the bank fields were sent; `error.details.requiredBodyFields` lists them
`422`	`UNBLOCKPAY_WIRE_BENEFICIARY_COUNTRY_UNSUPPORTED`	`beneficiaryCountry` is not the US
`502`	`UNBLOCKPAY_API_ERROR`	UnblockPay failed to register the account; retry, and contact support if it persists

4. USD beneficiary

Offramp resolve-or-create

Pass bank account fields on GET /v2/swap/quote with originAddress. Pods lists existing payout beneficiaries for the KYC subaccount; if account number + routing match, it reuses that id, otherwise it creates one and stores it on the quote. The id is internal and is not returned in the quote response. Required query fields:

Field	Notes
`bankAccountNumber`	Account number
`bankRoutingNumber`	ABA routing
`bankBeneficiaryName`	Legal name on the account. ASCII only — accented names (`ã`, `é`, …) are rejected 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 are base and polygon. The provider 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	Pass-through; no Pods/customer swap markup; In Fee is USD and appears as `kind: paymentRail`
Offramp	`originChain=<evm>`, `destinationChain=fiat`	WIRE to registered beneficiary	Pass-through; Out Fee is USDC (WIRE ~10.035 USDC). Already in the `tokenIn`/`tokenOut` spread and as `kind: paymentRail` on `tokenIn`

Token addresses (USDC)

Network	Chain id	Address
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” — the quote returns the USDC the wallet must send

With amountOut, Pods requests the price once (outputAmount); tokenIn.amount is the USDC to transfer (Out Fee included). The rail is WIRE (usdPaymentMethod defaults to WIRE). Example (quotes only, nothing signed):

Mode	Request	Result
WIRE `amountOut`	USD 4.00 (`400`)	~14.035088 USDC (Out Fee ~10.035 USDC)

Prefer amountOut when the product promise is “receive $N”. A small amountIn will not cover the WIRE Out Fee (~10 USDC), so use amountOut or an amountIn above ~10 USDC.

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=0x0000000000000000000000000000000000000001&bankAccountNumber=000000000000&bankRoutingNumber=000000000&bankBeneficiaryName=John%20Smith&bankName=Example%20Bank%20N.A.&beneficiaryStreetLine1=123%20Main%20Street&beneficiaryCity=New%20York&beneficiaryState=NY&beneficiaryPostalCode=10001&beneficiaryCountry=USA"

Exact-input form: replace amountOut=400 with amountIn=15000000 (15 USDC) — large enough to cover the ~10 USDC WIRE Out Fee. 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 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`
WIRE offramp live quotes (no bank PII)	Ramp quotes — USDC → Wire

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

UnblockPay: register the wire External Account

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

​UnblockPay: register the wire External Account

​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

UnblockPay: register the wire External Account

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