Set Up Pods Ramp

Use Pods Ramp when your application owns the user experience, but wants Pods to handle local KYC/AML provider integration and expose one normalized approval status for fiat-to-crypto money movement. Pods Ramp uses Sumsub reusable KYC: you own a Sumsub account and generate reusable share tokens. Pods receives a tax id, a short-lived Sumsub share token, the Sumsub applicant id, email, and wallet address. Pods creates or reuses an internal subaccount with the local KYC/AML provider, tracks the attempt, and exposes one normalized status back to you.

Pods does not store Sumsub share tokens, full tax ids, raw document images, base64 payloads, or address data. Pods stores only a salted tax-id hash and its last four digits, plus the status fields and provider ids needed for audit and retry.

Supported countries

Pods Ramp is live today for Brazil and expanding to more countries in Latin America.

Country	Status	On-ramp methods	Off-ramp methods
Brazil (BRL)	Live	Pix	Pix
Argentina (ARS)	Live	Bank transfer (CVU), Mercado Pago	Bank transfer (CBU / CVU / alias)
Mexico (MXN)	Live	Bank transfer (CLABE / SPEI)	Bank transfer (CLABE)
Colombia (COP)	Live	Bank transfer (PSE), BRE-B, Request-to-Pay (Bancolombia, Nequi)	Bank transfer (PSE), BRE-B

Each country integrates with its own local KYC/AML provider behind the scenes (Avenia for Brazil) and its own Sumsub reusable-identity partner. Confirm with Pods which partner and required verification fields apply to your target country before configuring the Sumsub level below.

KYC requirements

Every Pods Ramp identity flow verifies the same four things before a user can be approved. Liveness, document, and address are enforced entirely inside Sumsub as part of the level configured in step 1; the tax id is the only one of the four that your backend also sends directly to Pods.

Requirement	Enforced by	Sent to Pods
Tax id (CPF for Brazil)	Sumsub applicant data (`TIN` field)	Yes — as `cpf` on `POST /api/v1/kyc/sumsub-share-token` (see step 6)
Liveness check	Sumsub level’s `Selfie` step, advanced liveness	No — folds into Sumsub’s `reviewAnswer`
Document check	Sumsub level’s `Identity document` step (ID card, passport, driver’s license, or residence permit)	No — folds into Sumsub’s `reviewAnswer`
Home address	Sumsub level’s `Applicant data` step (street, street line 2, country, city, state, building number, postcode)	No — held by Sumsub and the local KYC/AML provider, never received by Pods

Pods only receives the tax id, the share token, the Sumsub applicant id, email, and wallet address when you call POST /api/v1/kyc/sumsub-share-token. Liveness, document, and address data stay inside Sumsub and the local provider — your backend must confirm Sumsub reached reviewStatus: completed and reviewResult.reviewAnswer: GREEN (all four checks passed) before generating the share token and submitting it to Pods.

Architecture overview

Pods provisions your access

Pods sends your server-to-server API key, API base URL, a partner token for the local KYC/AML provider, and its recipient client id.

Configure Sumsub

Add the local provider as a reusable identity recipient in Sumsub and configure a verification level with the fields that provider requires.

Run Sumsub WebSDK

The user completes identity verification through Sumsub WebSDK in your app.

Submit to Pods

Your backend generates a fresh Sumsub share token and submits it to Pods.

Poll Ramp status

When the Pods status becomes approved, the user is approved for the Pods Ramp money movement routes enabled in your integration.

Before you start

Pods sends you these integration values:

Value	Source	Used for
`PODS_API_BASE_URL`	Pods	Base URL for Pods API requests.
`PODS_API_KEY`	Pods	Server-to-server authentication from your backend.
`PROVIDER_PARTNER_TOKEN`	Pods	Paste once in Sumsub Dashboard to add the local KYC/AML provider as a reusable identity recipient.
`PROVIDER_FOR_CLIENT_ID`	Pods	Send as `forClientId` when generating Sumsub share tokens for that provider.

The local KYC/AML provider (Avenia for Brazil) has no direct relationship with your company in this flow. Pods manages that relationship internally and gives you the values needed for Sumsub reusable identity sharing.

Authentication

Send your Pods API key from your backend. Do not expose it in browser or mobile clients.

x-api-key: PODS_API_KEY

1. Configure the Sumsub level

Create an individual Sumsub verification level named exactly:

pods-ramp-level

The fixed name keeps setup, monitoring, support, and runbooks consistent across integrations. Open Sumsub Individual levels, create a Standard level, and configure the required steps.

Required Sumsub steps

Step	Configuration
Identity document	Allow ID card, passport, driver’s license, and residence permit. The applicant submits one accepted document.
Selfie	Use advanced liveness check.
Applicant data	Require first name, last name, TIN, tax residence country, email, date of birth, street, street line 2, country, city, state, building number, and postcode.

Add the identity document and selfie steps first.

Then add the applicant data step.

Add each required applicant data field as a separate required field.

Create the level.

Country-specific requirements

The required tax id, applicant fields, and Sumsub reusable-identity partner differ per country. For Brazil, Avenia requires:

CPF in the Sumsub TIN field.
Country of Tax ID set to Brazil.
Full name.
Date of birth.
One identity document: ID_CARD, PASSPORT, DRIVERS, or RESIDENCE_PERMIT.
Sumsub review answer GREEN.

For Mexico, Colombia, and Argentina, confirm the equivalent tax-id field, required documents, and Sumsub partner with Pods before creating the level, since those routes are not live yet. Reference:

2. Add the local provider as a reusable identity recipient

Before generating reusable KYC share tokens, add the local KYC/AML provider as a recipient in Sumsub.

Go to Reusable identity -> Partners.
Open the Recipients tab.
Click Add recipient.
Enter the PROVIDER_PARTNER_TOKEN provided by Pods.
Save the recipient setup.

Open the Recipients tab and add a recipient

After the recipient is available, use the PROVIDER_FOR_CLIENT_ID from Pods when generating share tokens. This is the provider’s Sumsub recipient/client id. It is separate from the partner token and from your Pods API key. Reference: Sumsub partner management.

3. Create a Sumsub app token

Create the Sumsub app token after Reusable Identity is enabled and after the local provider is added as a recipient. This order matters because the token must include permission to share applicant data.

Open Sumsub Dashboard.
Go to Dev space -> App tokens.
Create a new app token.
Ensure Reusable Identity -> Share applicants data is selected.
Save the token and secret key securely. Sumsub only shows the secret once.

Enable Reusable Identity share applicants data permission

Save the generated Sumsub app token and secret key

Store them in your backend:

SUMSUB_API_BASE_URL="https://api.sumsub.com"
SUMSUB_APP_TOKEN="..."
SUMSUB_SECRET_KEY="..."
SUMSUB_LEVEL_NAME="pods-ramp-level"
PROVIDER_FOR_CLIENT_ID="..."

If Sumsub enables Reusable Identity after you already created an app token, create a new app token and make sure Reusable Identity -> Share applicants data is selected.

A valid app token still requires active Sumsub credits/license. If Sumsub returns license-key-exhausted or Not enough credit, ask Sumsub to enable credits for the target environment.

Reference: Sumsub app tokens.

4. Run WebSDK and confirm approval

Use your backend to create a Sumsub WebSDK access token for the applicant and mount WebSDK in your application. Use the same pods-ramp-level level name configured above. Your backend must only continue to Pods after Sumsub reaches:

reviewStatus = completed
reviewResult.reviewAnswer = GREEN

You can detect that result by receiving Sumsub webhooks or by polling Sumsub from your backend. If you use webhooks, the target must point to your backend, not to Pods. Required signal:

Signal	Required?	Purpose
`applicantReviewed` with `completed + GREEN`	Yes	Generate the share token and submit it to Pods.
`applicantReviewed` with `completed + RED`	Yes	Do not submit to Pods. Keep the user blocked or route them to retry/support.
`applicantPending`	Recommended	Useful for monitoring pending reviews.
`applicantAwaitingUser`	Recommended	Useful to prompt the user to complete missing steps.
`applicantAwaitingService` or `applicantOnHold`	Recommended	Useful for operations visibility.
`applicantCreated`	Optional	Logging only. Do not call Pods from this event.

Reference:

After Sumsub returns completed + GREEN, your backend calls Sumsub to generate a fresh share token for that applicant and the local provider’s recipient.

POST https://api.sumsub.com/resources/accessTokens/shareToken

Request:

{
  "applicantId": "SUMSUB_APPLICANT_ID",
  "forClientId": "PROVIDER_FOR_CLIENT_ID",
  "ttlInSecs": 600
}

Use the approved Sumsub applicant id and reuse the same PROVIDER_FOR_CLIENT_ID provided by Pods. Generate a fresh shareToken for each approved applicant import. Sumsub share tokens are short-lived and invalidated after usage. Response:

{
  "token": "SUMSUB_SHARE_TOKEN",
  "forClientId": "PROVIDER_FOR_CLIENT_ID"
}

Reference:

Send the fresh token from your backend to Pods. Pods does not store the share token. Pods validates the submitted tax id and searches its profiles for an approved identity with the same salted tax-id hash. When the local provider still reports the identity as approved, Pods creates a separate profile for your customer, reuses the approved identity, and returns approved without consuming the fresh token. Pods stores only the salted hash and the last four digits, never the raw tax id. If no approved identity can be revalidated, Pods creates or reuses the customer profile and internal subaccount with the local provider, then imports the fresh share token normally. If the provider reports that the token was already imported into that subaccount, Pods checks that subaccount for an existing approved attempt before adopting it.

POST /api/v1/kyc/sumsub-share-token

Request:

{
  "cpf": "52998224725",
  "shareToken": "SUMSUB_SHARE_TOKEN",
  "sumsubApplicantId": "SUMSUB_APPLICANT_ID",
  "email": "[email protected]",
  "walletAddress": "0x0000000000000000000000000000000000000001"
}

Field	Required	Description
`cpf`	Yes	Valid tax id used to match a previously approved identity. For Brazil this is a CPF. Send digits only or formatted; Pods does not store the raw value.
`shareToken`	Yes	The fresh Sumsub token generated for the local provider.
`sumsubApplicantId`	Yes	Unique Sumsub applicant id from the approved applicant. Pods uses it for customer-scoped idempotency.
`email`	Yes	User email stored on the Pods Ramp profile.
`walletAddress`	Yes	User wallet address stored on the Pods Ramp profile and used by money movement flows.

Pods generates the public kycUserId and returns it in the response. Store this id in your backend and use it for future status checks. Successful response:

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

If this request is retried with the same sumsubApplicantId, Pods returns the same customer-scoped profile instead of creating a duplicate. The tax id must remain the same; a conflicting tax id returns 409 SUMSUB_CPF_MISMATCH. An immediate approved response means the local provider revalidated an existing approved identity for the tax id. A provider_pending response means the provider accepted a new import for processing; approval is only final after the status endpoint returns approved. See Track Pods Ramp status to poll for that result, and Move money with Pods Ramp to use the resulting approval.

Overview

Guides

Integrations

Agents

Supported countries

KYC requirements

Architecture overview

Before you start

Authentication

1. Configure the Sumsub level

Required Sumsub steps

Country-specific requirements

2. Add the local provider as a reusable identity recipient

3. Create a Sumsub app token

4. Run WebSDK and confirm approval

​Supported countries

​KYC requirements

​Architecture overview

​Before you start

​Authentication

​1. Configure the Sumsub level

​Required Sumsub steps

​Country-specific requirements

​2. Add the local provider as a reusable identity recipient

​3. Create a Sumsub app token

​4. Run WebSDK and confirm approval

​5. Generate the Sumsub share token

​6. Submit the share token to Pods

Supported countries

KYC requirements

Architecture overview

Before you start

Authentication

1. Configure the Sumsub level

Required Sumsub steps

Country-specific requirements

2. Add the local provider as a reusable identity recipient

3. Create a Sumsub app token

4. Run WebSDK and confirm approval

5. Generate the Sumsub share token

6. Submit the share token to Pods