Deposit funds - QASH API Reference

Deposit funds

curl --request POST \
  --url https://api.example.com/api/v1/transactions/deposit

const options = {method: 'POST'};

fetch('https://api.example.com/api/v1/transactions/deposit', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

POST

/

api

/

v1

/

transactions

/

deposit

Deposit funds

curl --request POST \
  --url https://api.example.com/api/v1/transactions/deposit

const options = {method: 'POST'};

fetch('https://api.example.com/api/v1/transactions/deposit', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

Requires Authorization: Bearer <user-access-token> — the token from Verify login code. No X-Api-Key, X-Api-Secret, or userId — the token already identifies the user.

Creates a hosted payment link for a user deposit. Send the returned paymentLink to your user so they can complete the payment with the selected provider. The deposit is created with status: "PENDING". The user’s balance is updated after the payment is completed and confirmed by the provider.

Your backend calls POST /api/v1/transactions/deposit
    → Qash returns paymentLink
    → User completes payment
    → Deposit is confirmed asynchronously

Call GET /api/v1/user/accounts first to get the user’s toAccountId. The USDC account is provisioned automatically the first time the user logs in — you don’t need to create it manually.

Request

POST /api/v1/transactions/deposit
Authorization: Bearer <user-access-token>
Content-Type: application/json

Body

Field	Type	Required	Description
`toAccountId`	number	Yes	Account ID that will receive the deposit — use the `id` from List accounts
`amount`	number	Yes	Decimal amount in USDC (e.g. `100` = USDC 100.00) — not a smallest-unit integer
`currency`	string	Yes	Currency code matching the account’s asset — `"USDC"`
`provider`	string	Yes	Payment provider — e.g. `"mock"`, `"irisbank"`, `"cobre"`, `"stripe"`
`description`	string	Yes	Description of the deposit — e.g. `"USDC deposit"`
`metadata.payer.documentType`	string	Yes	Payer document type — e.g. `"CC"`, `"PASSPORT"`, `"RFC"`
`metadata.payer.documentNumber`	string	Yes	Payer document number

{
  "toAccountId": 659,
  "amount": 100,
  "currency": "USDC",
  "provider": "mock",
  "description": "USDC deposit",
  "metadata": {
    "payer": {
      "documentType": "passport",
      "documentNumber": "A1234567"
    }
  }
}

Response

201 Created

{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING",
  "inferredTransactionType": "DEPOSIT",
  "paymentLink": "/api/pay/1234?transactionId=550e8400-e29b-41d4-a716-446655440000&amount=100&currency=USDC",
  "message": "Transaction enqueued for processing"
}

Field	Type	Description
`transactionId`	string (UUID)	Deposit transaction identifier — use to poll status
`status`	string	`"PENDING"` while the user completes the payment
`paymentLink`	string	Hosted payment URL to share with the user

Amounts are decimal USDC values (e.g. 100 = USDC 100.00), not smallest-unit integers. Never use floating point arithmetic to compute the value before sending it.

Errors

HTTP status	Error	Cause
`400`	Validation message	Missing required field or invalid format
`400`	`description must be a string`	`description` field missing from body
`400`	`Payer information is required for deposits`	`metadata.payer` missing from body
`400`	`Payer document type and number are required for deposits`	`metadata.payer.documentType` or `documentNumber` missing
`401`	`Invalid or expired token`	Missing, expired, or malformed access token
`404`	`Account not found`	`toAccountId` does not exist or belongs to a different user