Skip to main content
Base URL: https://your-domain.com/api
All endpoints on this page require Authorization: Bearer {token}.

​
Overview

The Doss platform supports two merchant types:
  • Standard merchant — The QR code encodes a fixed payment amount. The user reviews and confirms the pre-set amount.
  • Express merchant — The QR code does not include an amount. The user enters the payment amount at checkout.

​
Standard merchant flow

1

Scan QR code

Call POST /perform-qr-code-operation to decode the merchant QR code and get merchantId, merchantDefaultCurrencyCode, and merchantPaymentAmount.
2

Review payment

Call POST /perform-merchant-payment-qr-code-review to validate balance and calculate the merchant fee.
3

Submit payment

Call POST /perform-merchant-payment-qr-code-submit.

​
POST /perform-merchant-payment-qr-code-review

Validates a standard merchant QR payment. Checks merchant existence, currency availability, and user balance, and returns the calculated fee.

​
Request parameters

​
user_id
number
required
The authenticated payer’s user ID.
​
merchantId
number
required
Merchant ID decoded from the QR code.
​
merchantDefaultCurrencyCode
string
required
Currency code from the QR code (e.g. USD).
​
merchantPaymentAmount
number
required
Payment amount from the QR code.

​
Response fields

​
status
number
200 on success, 401 on validation failure.
​
message
string
Error description on failure.
​
merchantBusinessName
string
Merchant’s business name.
​
merchantPaymentCurrencySymbol
string
Currency symbol.
​
merchantPaymentAmount
number
Payment amount.
​
merchantCalculatedChargePercentageFee
number
Calculated merchant fee amount.
​
merchantActualFee
number
Merchant fee percentage rate. Pass to the submit endpoint.
​
merchantCurrencyId
number
Currency ID. Pass to the submit endpoint.
​
merchantUserId
number
Merchant user ID. Pass to the submit endpoint.

​
Error conditions

ReasonDescription
401Merchant does not exist
401Merchant cannot pay themselves
401Currency not found
401User does not have the required currency wallet
401Insufficient balance
curl --request POST \
  --url https://your-domain.com/api/perform-merchant-payment-qr-code-review \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_id": 42,
    "merchantId": 7,
    "merchantDefaultCurrencyCode": "USD",
    "merchantPaymentAmount": 25.00
  }'

​
POST /perform-merchant-payment-qr-code-submit

Executes a standard merchant QR payment. Creates merchant payment and transaction records, and updates both the payer’s and merchant’s wallets.

​
Request parameters

​
user_id
number
required
The authenticated payer’s user ID.
​
merchantId
number
required
Merchant ID.
​
merchantPaymentAmount
number
required
Total payment amount.
​
merchantActualFee
number
required
Merchant fee percentage from the review step.
​
merchantCurrencyId
number
required
Currency ID from the review step.
​
merchantUserId
number
required
Merchant user ID from the review step.

​
Response fields

​
status
number
200 on success, 401 on error.
​
message
string
Error description on failure.
curl --request POST \
  --url https://your-domain.com/api/perform-merchant-payment-qr-code-submit \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_id": 42,
    "merchantId": 7,
    "merchantPaymentAmount": 25.00,
    "merchantActualFee": 2.5,
    "merchantCurrencyId": 1,
    "merchantUserId": 15
  }'

​
Express merchant flow

1

Scan QR code

Call POST /perform-qr-code-operation to get expressMerchantId and expressMerchantPaymentCurrencyCode.
2

Review merchant and wallets

Call POST /perform-express-merchant-payment-qr-code-merchant-currency-user-wallets-review.
3

Enter and review amount

Call POST /perform-express-merchant-payment-qr-code-merchant-amount-review.
4

Submit payment

Call POST /perform-express-merchant-payment-qr-code-submit.

​
POST /perform-express-merchant-payment-qr-code-merchant-currency-user-wallets-review

Validates merchant and currency for an express merchant payment. Does not check the amount (entered in the next step).

​
Request parameters

​
user_id
number
required
The authenticated payer’s user ID.
​
expressMerchantId
number
required
Express merchant ID from the decoded QR code.
​
expressMerchantPaymentCurrencyCode
string
required
Currency code from the decoded QR code.

​
Response fields

​
status
number
200 on success, 401 on validation failure.
​
message
string
Error description on failure.
​
expressMerchantBusinessName
string
Merchant’s business name.
​
expressMerchantPaymentCurrencyId
number
Currency ID. Pass to subsequent steps.
​
expressMerchantPaymentCurrencySymbol
string
Currency symbol.
​
expressMerchantActualFee
number
Merchant fee percentage. Pass to subsequent steps.
​
expressMerchantUserId
number
Merchant user ID. Pass to the submit endpoint.
curl --request POST \
  --url https://your-domain.com/api/perform-express-merchant-payment-qr-code-merchant-currency-user-wallets-review \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_id": 42,
    "expressMerchantId": 8,
    "expressMerchantPaymentCurrencyCode": "USD"
  }'

​
POST /perform-express-merchant-payment-qr-code-merchant-amount-review

Validates the user-entered amount for an express merchant payment. Checks balance and calculates the fee.

​
Request parameters

​
user_id
number
required
The authenticated payer’s user ID.
​
expressMerchantPaymentAmount
number
required
The amount the user wants to pay.
​
expressMerchantPaymentCurrencyId
number
required
Currency ID from the wallet review step.
​
expressMerchantActualFee
number
required
Fee percentage from the wallet review step.

​
Response fields

​
status
number
200 on success, 401 on insufficient balance.
​
message
string
Error description on failure.
​
expressMerchantCalculatedChargePercentageFee
number
Calculated fee amount.
curl --request POST \
  --url https://your-domain.com/api/perform-express-merchant-payment-qr-code-merchant-amount-review \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_id": 42,
    "expressMerchantPaymentAmount": 50.00,
    "expressMerchantPaymentCurrencyId": 1,
    "expressMerchantActualFee": 2.5
  }'

​
POST /perform-express-merchant-payment-qr-code-submit

Executes an express merchant QR payment. Creates merchant payment and transaction records and updates both wallets. If the merchant does not yet have a wallet in the payment currency, one is created automatically.

​
Request parameters

​
user_id
number
required
The authenticated payer’s user ID.
​
expressMerchantId
number
required
Express merchant ID.
​
expressMerchantPaymentAmount
number
required
Total payment amount.
​
expressMerchantActualFee
number
required
Merchant fee percentage.
​
expressMerchantPaymentCurrencyId
number
required
Currency ID.
​
expressMerchantUserId
number
required
Merchant user ID.

​
Response fields

​
status
number
200 on success, 401 on error.
​
message
string
Error description on failure.
curl --request POST \
  --url https://your-domain.com/api/perform-express-merchant-payment-qr-code-submit \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_id": 42,
    "expressMerchantId": 8,
    "expressMerchantPaymentAmount": 50.00,
    "expressMerchantActualFee": 2.5,
    "expressMerchantPaymentCurrencyId": 1,
    "expressMerchantUserId": 16
  }'

Build docs developers (and LLMs) love

Get started for freeTalk to us