Partner Integration Guide

This guide covers the complete integration lifecycle for the QASH Partner API: registering end-users, running identity verification, logging the user in, executing financial operations, and issuing a card — all from your own backend.

Current scope: partner integrations currently support users in Colombia (countryCode: "CO"), one asset (USDC), with amounts expressed in USD-equivalent terms. Other countries and assets are not yet available through the partner API.

Two credential types

The integration uses two distinct credentials, for two distinct phases:

End User → Your App → Your Backend → QASH Partner API
                             ↑
              Phase 1: X-Api-Key + X-Api-Secret
              Phase 2: Authorization: Bearer <user-access-token>

Phase	Credential	Used for
Onboarding (pre-login)	`X-Api-Key` + `X-Api-Secret`	Register users, manage profiles, run KYC — before the user has ever logged in
Everything else (post-login)	`Authorization: Bearer <user-access-token>`	Financial operations, card issuance, and card management — same token model as the QASH app itself

The access token is obtained through a two-step, backend-only email OTP login (Steps 5–6 below). There is no client-side SDK to integrate — your backend calls two endpoints and receives a standard QASH JWT.

1. Prerequisites

Before you start you need:

Partner API credentials — X-Api-Key + X-Api-Secret issued from the QASH Dashboard under Settings → API Keys. The secret is shown once at creation; store it securely in a secrets manager.
Server-side integration only — credentials must never be exposed to client-side code. Every call must originate from your backend.

Credential format

X-Api-Key:    qash_key_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Api-Secret: qash_secret_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Header	Notes
`X-Api-Key`	Identifies your partner account
`X-Api-Secret`	Authenticates your request — never log or expose

Base URL

Environment	URL
Production	`https://api.qash.ai`
Staging	`https://staging.qash.ai`

2. User lifecycle

Every end-user goes through the following states before they can log in and transact:

register → pending → kyc_required → [KYC approved] → active

Status	Meaning	Can log in / transact?
`pending`	Registered, KYC not yet initiated	No
`kyc_required`	KYC initiated, awaiting user verification	No
`active`	KYC approved — fully operational	Yes
`suspended`	Temporarily disabled	No
`banned`	Permanently blocked	No

Login is gated on active status — this is intentional. It’s what forces registration, profile, and KYC to run under partner API-key credentials rather than a user session: there is no user session yet at that point. Section numbers (§N) in the diagram match the numbered sections below.

3. Step 1 — Register a user

POST /api/v1/partner/users
X-Api-Key: <your-api-key>
X-Api-Secret: <your-api-secret>
Content-Type: application/json

{
  "email": "juan@example.com",
  "phone": "+573001234567",
  "countryCode": "CO"
}

Request fields

Field	Type	Required	Description
`email`	string	Yes	User email — must be unique within your partner scope
`phone`	string	No	E.164 format — e.g. `"+573001234567"`
`countryCode`	string	Yes	Currently only `"CO"` is supported

Response — 201 Created

{
  "success": true,
  "data": {
    "user": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "juan@example.com",
      "status": "pending",
      "createdAt": "2026-07-01T00:00:00.000Z"
    }
  },
  "message": "User created successfully"
}

Store the id immediately. This UUID is your permanent reference for the user across all subsequent calls until you have an access token.

Errors

Status	Error	Cause
`400`	Validation message	Missing field or invalid format
`409`	`A user with this email already exists`	Email already registered in your partner scope
`401`	`Invalid partner credentials`	Wrong `X-Api-Key` or `X-Api-Secret`

4. Step 2 — Create the user profile

Before starting KYC, the user must have a personal profile. Persona uses this data to pre-fill the identity verification form — without it the KYC call will fail.

POST /api/v1/user/profile
X-Api-Key: <your-api-key>
X-Api-Secret: <your-api-secret>
Content-Type: application/json

{
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "firstName": "Juan",
  "lastName": "García",
  "dateOfBirth": "1990-05-15",
  "nationality": "CO",
  "gender": "male",
  "governmentIdType": "national_id",
  "governmentIdNumber": "1234567890",
  "governmentIdCountry": "CO",
  "addressLine1": "Calle 100 # 15-20",
  "city": "Bogotá",
  "stateProvince": "Bogotá D.C.",
  "postalCode": "110111",
  "addressCountry": "CO",
  "occupation": "engineer",
  "annualSalary": "50000-100000",
  "accountPurpose": "personal_savings",
  "expectedMonthlyVolume": "5000-10000",
  "isPep": false,
  "usCitizen": false,
  "acceptedTerms": true
}

See Create user profile for the full field reference.

5. Step 3 — Verify profile completion

GET /api/v1/user/profile/check-completion?userId=a1b2c3d4-e5f6-7890-abcd-ef1234567890
X-Api-Key: <your-api-key>
X-Api-Secret: <your-api-secret>

{
  "success": true,
  "data": {
    "isComplete": true,
    "missingFields": []
  }
}

If isComplete is false, the missingFields array lists what’s still needed. Use PATCH /api/v1/user/profile to fill in the gaps before proceeding to KYC.

PATCH /api/v1/user/profile
X-Api-Key: <your-api-key>
X-Api-Secret: <your-api-secret>
Content-Type: application/json

{
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "occupation": "engineer",
  "annualSalary": "50000-100000",
  "accountPurpose": "personal_savings",
  "expectedMonthlyVolume": "5000-10000"
}

6. Step 4 — Initiate KYC

Once the profile is complete, initiate identity verification.

POST /api/v1/partner/kyc
X-Api-Key: <your-api-key>
X-Api-Secret: <your-api-secret>
Content-Type: application/json

{
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "firstName": "Juan",
  "lastName": "García",
  "email": "juan@example.com",
  "birthDate": "1990-05-15"
}

Response — 200 OK

{
  "success": true,
  "data": {
    "inquiryId": "inq_xxxxxxxxxxxxxxxxxxxxxxxx",
    "verificationUrl": "https://inquiry.withpersona.com/verify?inquiry-id=inq_xxxxxxxxxxxxxxxxxxxxxxxx",
    "isExisting": false,
    "message": "KYC verification started. Please complete the verification process."
  }
}

Redirect your user to verificationUrl. The form is pre-filled with the profile data you provided. Once the user finishes, QASH handles activation automatically — no webhook configuration required on your side.

Errors

Status	Error	Cause
`404`	`PersonalProfile not found`	Profile was not created (Step 2 missing)
`409`	`KYC already in progress`	Check status first with KYC status

7. Step 5 — Poll for activation

Poll until status is "active", using either endpoint:

GET /api/v1/partner/users/:userId
X-Api-Key: <your-api-key>
X-Api-Secret: <your-api-secret>

or check KYC status directly:

GET /api/v1/user/kyc/status?userId=a1b2c3d4-e5f6-7890-abcd-ef1234567890
X-Api-Key: <your-api-key>
X-Api-Secret: <your-api-secret>

Poll with exponential backoff. Start at 10 seconds, back off to 60 seconds max. Identity verification typically completes within 1–5 minutes in production.

8. Step 6 — Log the user in

This is the last pre-login call, and the bridge into everything else. See Send login code and Verify login code for full details.

POST /api/v1/partner/auth/send
X-Api-Key: <your-api-key>
X-Api-Secret: <your-api-secret>
Content-Type: application/json

{ "email": "juan@example.com" }

The user receives a 6-digit code by email. Once they provide it back to your app:

POST /api/v1/partner/auth/verify
X-Api-Key: <your-api-key>
X-Api-Secret: <your-api-secret>
Content-Type: application/json

{ "email": "juan@example.com", "code": "482913" }

{
  "success": true,
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "user": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "email": "juan@example.com", "status": "active" }
}

Store accessToken and refreshToken in your backend on behalf of the user. From this point forward, every financial and card endpoint uses Authorization: Bearer <accessToken> — no X-Api-Key, X-Api-Secret, or userId needed. The token already identifies the user and your partner account.

9. Financial operations

All financial endpoints below use Authorization: Bearer <accessToken> only.

Authorization: Bearer <accessToken>
Content-Type: application/json

Amount format

Ledger amounts (accounts, balance, deposit, transfer, transactions) are decimal USDC values, not smallest-unit integers — e.g. 100 means USDC 100.00. Never use floating point math when handling these values in your own backend; treat them as fixed-precision decimals. payout and exchange/calculate deal with external currencies (e.g. COP) and follow the unit conventions documented on their own pages — see Payout and Calculate exchange.

9.1 Get balance

GET /api/v1/user/balance

{
  "items": [
    { "id": 649, "asset": "USDC", "type": "LIABILITY", "credits": "0.00000000", "debits": "0.00000000" }
  ],
  "meta": { "totalItems": 1, "totalPages": 1, "currentPage": 1, "itemsPerPage": 20 }
}

The user’s USDC account is provisioned automatically — there is no separate “create account” call. Use the id from this response as accountId in deposits, transfers, and transaction queries. See Get balance.

9.2 Deposit funds

POST /api/v1/transactions/deposit

{
  "toAccountId": 649,
  "amount": 100,
  "currency": "USDC",
  "provider": "mock",
  "description": "USDC deposit"
}

See Deposit for the full field reference and response shape.

9.3 Transfer funds

POST /api/v1/transactions/transfer

{
  "fromAccountId": 649,
  "toAccountId": 650,
  "amount": 50,
  "description": "Service payment"
}

See Transfer.

9.4 List / get transactions

GET /api/v1/transactions?accountId=649&limit=20
GET /api/v1/transactions/:id

See List transactions and Get transaction.

9.5 Payout to bank account

POST /api/v1/user/payout

See Payout for the full request body — destination bank fields, idempotency via transactionId, and response shape.

9.6 Exchange rate quote

POST /api/v1/user/exchange/calculate

See Calculate exchange for request/response fields.

10. Card issuance and management

Once the user is logged in, issuing and managing their card uses the same access token — no separate credential.

10.1 Issue a card

POST /api/v1/auth/cards/setup

{
  "cardType": "virtual",
  "occupation": "engineer",
  "annualSalary": "50000-100000",
  "accountPurpose": "personal_savings",
  "expectedMonthlyVolume": "5000-10000"
}

This requires the user’s KYC to be approved and their profile complete — both are already satisfied at this point in the flow. See Issue a card for the full prerequisites and error cases.

10.2 Card management

Method	Endpoint	Description
`GET`	`/api/v1/cards/status`	Current card status
`GET`	`/api/v1/cards/details`	Masked card details
`GET`	`/api/v1/cards/balance`	Card balance
`GET`	`/api/v1/cards/transactions`	Card transaction history
`POST`	`/api/v1/cards/lock`	Lock the card
`POST`	`/api/v1/cards/unlock`	Unlock the card
`PATCH`	`/api/v1/cards/limit`	Update spending limit

See Cards overview for details on each.

11. User management

List your users

GET /api/v1/partner/users
X-Api-Key: <your-api-key>
X-Api-Secret: <your-api-secret>

Query param	Type	Description
`status`	string	`"pending"`, `"active"`, `"suspended"`, `"banned"`
`limit`	number	1–200, default 100
`offset`	number	Default 0

12. API key management

This is a separate credential from the end-user access token above — it authenticates you as the partner business, not an end user. Use it only to provision or revoke X-Api-Key/X-Api-Secret pairs from your own backend admin tooling.

Create a key pair

POST /api/v1/partner/api-keys
Authorization: Bearer <business-user-jwt>
Content-Type: application/json

{ "keyName": "Production key - July 2026" }

{
  "success": true,
  "apiKey": "qash_key_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "secretKey": "qash_secret_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx...",
  "keyName": "Production key - July 2026"
}

secretKey is returned once only. Store it immediately in a secrets manager.

Revoke a key

DELETE /api/v1/partner/api-keys/:keyId
Authorization: Bearer <business-user-jwt>

13. Security checklist

X-Api-Secret stored in a secrets manager — not in source code or environment files committed to git.
All API calls originate from your backend — no direct browser-to-QASH calls.
accessToken/refreshToken stored securely per user, not exposed to client-side code unless your integration is designed to hand sessions directly to a client app.
transactionId included on every payout request, unique per payout.
Your backend validates user.status === "active" before attempting login.
API key rotation plan in place — revoke and reissue on any suspected compromise.
Logs do not contain X-Api-Secret, accessToken, refreshToken, or raw API responses with sensitive fields.

14. Complete endpoint reference

Endpoint groups by auth model

Group	Auth	Notes
User management (`/partner/users`)	`X-Api-Key` + `X-Api-Secret`	Pre-login
Profile (`/user/profile*`)	`X-Api-Key` + `X-Api-Secret`	`userId` in body (POST/PATCH) or query (GET)
KYC start (`/partner/kyc`)	`X-Api-Key` + `X-Api-Secret`	`userId` in body
KYC status (`/user/kyc/status`)	`X-Api-Key` + `X-Api-Secret`	`userId` in query — pre-login variant
Login (`/partner/auth/send`, `/partner/auth/verify`)	`X-Api-Key` + `X-Api-Secret`	Issues the user access token
KYC document/history (`/auth/kyc/document/me`, `/auth/kyc/history`)	`Authorization: Bearer <accessToken>`	Post-login variant, no `userId` needed
Financial operations	`Authorization: Bearer <accessToken>`	Post-login
Card issuance and management	`Authorization: Bearer <accessToken>`	Post-login
API key management (`/partner/api-keys`)	`Authorization: Bearer <business-user-jwt>`	Your own business account, not an end user

Full endpoint map

User management — X-Api-Key + X-Api-Secret

Method	Path	Description
`POST`	`/api/v1/partner/users`	Register a new user
`GET`	`/api/v1/partner/users`	List your users
`GET`	`/api/v1/partner/users/:userId`	Get a specific user
`POST`	`/api/v1/partner/kyc`	Initiate identity verification

User profile and KYC status — X-Api-Key + X-Api-Secret + userId in body/query

Method	Path	Description
`POST`	`/api/v1/user/profile`	Create user profile — required before KYC
`GET`	`/api/v1/user/profile`	Get user profile
`PATCH`	`/api/v1/user/profile`	Update profile fields
`GET`	`/api/v1/user/profile/check-completion`	Check profile readiness for KYC
`GET`	`/api/v1/user/kyc/status`	KYC verification status

Login — X-Api-Key + X-Api-Secret

Method	Path	Description
`POST`	`/api/v1/partner/auth/send`	Send a 6-digit login code by email
`POST`	`/api/v1/partner/auth/verify`	Exchange the code for an access/refresh token

KYC document/history — Authorization: Bearer <accessToken>

Method	Path	Description
`GET`	`/api/v1/auth/kyc/document/me`	Extracted KYC document details
`GET`	`/api/v1/auth/kyc/history`	Full KYC verification history

Financial operations — Authorization: Bearer <accessToken>

Method	Path	Description
`GET`	`/api/v1/user/balance`	Get account balances
`GET`	`/api/v1/transactions`	List transactions (requires `accountId`)
`GET`	`/api/v1/transactions/:id`	Get a single transaction
`POST`	`/api/v1/transactions/deposit`	Create a deposit payment link
`POST`	`/api/v1/transactions/transfer`	Transfer between accounts
`POST`	`/api/v1/user/payout`	Send funds to a bank account
`POST`	`/api/v1/user/exchange/calculate`	Get an exchange rate quote

Cards — Authorization: Bearer <accessToken>

Method	Path	Description
`POST`	`/api/v1/auth/cards/setup`	Issue a card
`GET`	`/api/v1/cards/status`	Card status
`GET`	`/api/v1/cards/details`	Card details
`GET`	`/api/v1/cards/balance`	Card balance
`GET`	`/api/v1/cards/transactions`	Card transactions
`POST`	`/api/v1/cards/lock`	Lock card
`POST`	`/api/v1/cards/unlock`	Unlock card
`PATCH`	`/api/v1/cards/limit`	Update card limit

API key management — Authorization: Bearer <business-user-jwt>

Method	Path	Description
`POST`	`/api/v1/partner/api-keys`	Create API key pair
`DELETE`	`/api/v1/partner/api-keys/:id`	Revoke API key

Getting started

Integration guides

FAQs

Two credential types

1. Prerequisites

Credential format

Base URL

2. User lifecycle

3. Step 1 — Register a user

Request fields

Response — 201 Created

Errors

4. Step 2 — Create the user profile

5. Step 3 — Verify profile completion

6. Step 4 — Initiate KYC

Response — 200 OK

Errors

7. Step 5 — Poll for activation

8. Step 6 — Log the user in

9. Financial operations

Amount format

9.1 Get balance

9.2 Deposit funds

9.3 Transfer funds

9.4 List / get transactions

9.5 Payout to bank account

9.6 Exchange rate quote

10. Card issuance and management

10.1 Issue a card

10.2 Card management

11. User management

List your users

12. API key management

Create a key pair

Revoke a key

13. Security checklist

14. Complete endpoint reference

Endpoint groups by auth model

Full endpoint map

​Two credential types

​1. Prerequisites

​Credential format

​Base URL

​2. User lifecycle

​Onboarding and login sequence

​3. Step 1 — Register a user

​Request fields

​Response — 201 Created

​Errors

​4. Step 2 — Create the user profile

​5. Step 3 — Verify profile completion

​6. Step 4 — Initiate KYC

​Response — 200 OK

​Errors

​7. Step 5 — Poll for activation

​8. Step 6 — Log the user in

​9. Financial operations

​Amount format

​9.1 Get balance

​9.2 Deposit funds

​9.3 Transfer funds

​9.4 List / get transactions

​9.5 Payout to bank account

​9.6 Exchange rate quote

​10. Card issuance and management

​10.1 Issue a card

​10.2 Card management

​11. User management

​List your users

​12. API key management

​Create a key pair

​Revoke a key

​13. Security checklist

​14. Complete endpoint reference

​Endpoint groups by auth model

​Full endpoint map

Two credential types

1. Prerequisites

Credential format

Base URL

2. User lifecycle

Onboarding and login sequence

3. Step 1 — Register a user

Request fields

Response — 201 Created

Errors

4. Step 2 — Create the user profile

5. Step 3 — Verify profile completion

6. Step 4 — Initiate KYC

Response — 200 OK

Errors

7. Step 5 — Poll for activation

8. Step 6 — Log the user in

9. Financial operations

Amount format

9.1 Get balance

9.2 Deposit funds

9.3 Transfer funds

9.4 List / get transactions

9.5 Payout to bank account

9.6 Exchange rate quote

10. Card issuance and management

10.1 Issue a card

10.2 Card management

11. User management

List your users

12. API key management

Create a key pair

Revoke a key

13. Security checklist

14. Complete endpoint reference

Endpoint groups by auth model

Full endpoint map