Moca POS Third Party Wallet Integration Guide

This guide provides step-by-step instructions for integrating third-party wallets with Moca POS. The integration enables wallets to process cryptocurrency payments for merchants using Moca POS

Integration Flow

The integration follows a simple 4-step process: 0. Authentication: Generate a single-use token for every API call.

  1. QR Code Scanning - Wallet scans Moca POS QR code

  2. Order Data Retrieval - Fetch complete order information

  3. Payment Address Generation - Get payment address and memo

  4. Transaction Processing - Submit transaction for processing

0. Authentication: Generating a Single-Use Token

Before calling any other endpoint, you must obtain a fresh authentication token. This token is valid for exactly one API call and must be generated anew for every single request (e.g., for GET /api/orders/..., POST /api/txs/generate/memo, POST /api/txs/process).

  • Endpoint: POST /api/auth/token

  • Headers: Content-Type: application/json

  • Request Body:

    {
  "client_type": "wallet",
  "payment_key": "your_secret_payment_key_provided_by_moca"
}

Successful Response (200 OK)

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." // The single-use authentication token
}

Error Response (400 Bad Request)

{
  "error": {
    "message": "Invalid client_type or payment_key"
  }
}

Field Definitions

Field
Type
Description

client_type

String

For third-party wallets, this value must always be "wallet".

payment_key

String

The secret key provided to you by the Moca integration team. This must be kept confidential.

token

String (JWT)

The single-use token to be used in the Authorization header of the very next API request.

Implementation Note:

Your code must follow this pattern for every call to a Moca API endpoint:

  1. Call POST /api/auth/token with your credentials.

  2. Receive the token from the response.

  3. Immediately make your desired API call (e.g., GET /api/orders/...), adding the header Authorization: Bearer <token>.

  4. Discard the token. It cannot be used again. For the next API call, repeat steps 1-3.

Step 1: QR Code Scanning

When a wallet scans a Moca POS QR code, it receives initial transaction information in the following JSON format:

{
  "order_info": {
    "fiat": "USD",
    "amount": 50,
    "source": "POS",
    "reference_id": "35178fd8-861c-4198-88ab-3acbc259c495",
    "split_amount": 0,
    "business_name": "Moca Demo"
  },
  "expiration_date": "2025-09-12T14:42:28.617645"
}

QR Code Data Fields

Field
Type
Description

fiat

string

Currency abbreviation (e.g., "USD", "EUR")

amount

number

Amount to charge in fiat currency

source

string

Transaction source ("POS" or "ecommerce")

reference_id

string

Unique transaction/order identifier

split_amount

number

Split payment amount (if applicable)

business_name

string

Name of the merchant business

expiration_date

string

ISO 8601 formatted expiration timestamp

Step 2: Order Data Retrieval

Use the reference_id from the QR code to fetch complete order information.

Endpoint

GET /api/orders/{id}

Parameters:

  • id (path parameter): The reference_id from the QR code data

Response Examples

Success (200 OK)

{
  "business_id": "string",
  "cashier_identifier": "string", 
  "created_at": "string",
  "device_id": "string",
  "expiration_date": "string",
  "id": "string",
  "order_info": {
    "amount": 0,
    "business_name": "string",
    "fiat": "string",
    "reference_id": "string",
    "source": "string",
    "split_amount": 0
  },
  "paid": 0,
  "source": "string",
  "status": "string",
  "token_options": [
    {
      "method": "string",
      "token": "string"
    }
  ],
  "total": 0,
  "tx_list": [
    {
      "date": 0,
      "fiatAmount": 0,
      "fiatCode": "string",
      "hash": "string",
      "isValid": true,
      "notified": true,
      "status": "string",
      "toAddresses": ["string"],
      "tokenAmount": 0,
      "tokenCode": "string"
    }
  ],
  "version": 0
}

Error Responses

403 Forbidden

{
  "error": {
    "message": "string"
  }
}

404 Not Found

{
  "error": {
    "message": "string"
  }
}

Key Response Fields

Field
Description

token_options

Array of available payment tokens/methods

status

Current order status

paid

Amount already paid

total

Total amount due

tx_list

List of previous transactions (if any)

Step 3: Payment Address Generation

In this step the UI needs to show the user the available token options from token_options supported by the wallet. After the user selects a token from token_options, request the payment address and memo.

Endpoint

POST /api/txs/generate/memo

Request Body

{
  "chain": "string",
  "order_id": "string", 
  "token": "string",
  "referral": "string"
}

Request Parameters:

  • chain: Blockchain network identifier

  • order_id: The order reference ID

  • token: Selected token from token_options

  • referal: The wallet referal code

Response

Success (200 OK)

{
  "address": "string",
  "memo": "string",
  "amount_with_fees": 0
}

⚠️ Critical Requirements

  • DO NOT MODIFY THE MEMO - The memo contains referral information for both the wallet and business

  • Modifying the memo may result in the wallet being blocked from accessing Moca endpoints

  • Use the memo exactly as provided in all transactions

Step 4: Transaction Processing

After broadcasting the signed transaction to the blockchain, notify Moca POS to process the payment.

⚠️ The final amount paid by the user should be the amount_with_fees

Endpoint

POST /api/txs/process

Request Body

{
  "fiat_amount": 0,
  "fiat_code": "string",
  "hash": "string", 
  "order_id": "string",
  "to_address": "string"
}

Request Parameters:

  • fiat_amount: Amount paid in fiat currency

  • fiat_code: Fiat currency code (e.g., "USD")

  • hash: Transaction hash from the blockchain

  • order_id: Order reference ID

  • to_address: Payment address used

Response

Success (200 OK)

Transaction processed successfully.

Implementation Checklist

Prerequisites

  • [ ] Wallet can scan and parse QR codes

  • [ ] HTTP client capability for API requests

  • [ ] Blockchain transaction signing and broadcasting

  • [ ] User interface for token selection

  • [ ] Ability to sign transactions with memos

Integration Steps

  • [ ] Implement QR code scanning and parsing

  • [ ] Add order data retrieval functionality

  • [ ] Implement payment address generation

  • [ ] Add transaction broadcasting capability

  • [ ] Implement transaction processing notification

  • [ ] Handle error responses appropriately

  • [ ] Test with Moca POS test environment

Security Considerations

  • [ ] Validate QR code data format

  • [ ] Check order expiration dates

  • [ ] Verify transaction amounts match order total

  • [ ] Preserve memo integrity (DO NOT MODIFY)

  • [ ] Implement proper error handling

  • [ ] Use HTTPS for all API calls

Error Handling

Always implement proper error handling for:

  • Invalid QR code format

  • Expired orders

  • Network connectivity issues

  • API rate limiting

  • Transaction failures

  • Invalid token selections

Support

For technical support or integration questions, please contact the Moca development team.

API Base URL

Moca POS API base URL:

PreviousTechnical DocumentationNextTutorials

Last updated