Moca POS: Third-Party Wallet Integration Guide

This guide details the integration process for third-party wallets to accept payments via Moca POS. The

Version: 3.2 Last Updated: 2024-09-12 Audience: Third-Party Wallet Development Teams Base URL: https://api.payment-moca.com

Introduction

This guide details the integration process for third-party wallets to accept payments via Moca POS. The flow involves HMAC authentication, order fetching, and transaction processing.

Integration Flow Summary

---

35KB

POS_flow.svg

image

1. Authentication

All API calls (except the auth endpoint itself) require a JWT obtained via HMAC authentication.

Endpoint: POST /api/auth/token

Generates a short-lived JWT for authenticating subsequent API calls.

Headers:

Header	Description	Example
X-Moca-Api-Key	Your public API key provided by Moca.	pk_live_12345
X-Moca-Timestamp	Current Unix timestamp (seconds).	1726184430
X-Moca-Nonce	Unique random nonce (UUIDv4).	f47ac10b-58cc-4372-a567-0e02b2c3d479
X-Moca-Signature	HMAC-SHA256(secret, "timestamp:nonce") as hex.	a1b2c3d4e5f67890...

Request Body: None

Response (200 OK):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." // JWT valid for 1 minute
}

Response (401 Unauthorized):

{
  "error": {
    "message": "Invalid or missing HMAC headers"
  }
}

---

2. QR Code Data

When a user scans a Moca POS QR code, your wallet will receive the following data:

QR Code Content:

{
  "reference_id": "35178fd8-861c-4198-88ab-3acbc259c495",
  "fiat": "USD",
  "amount": 50,
  "business_name": "Moca Demo",
  "expiration_date": "2025-09-12T14:42:28.617Z"
}

Field Description:

Field	Type	Description
reference_id	String	Unique order identifier for API calls.
fiat	String	Fiat currency code (e.g., USD, EUR).
amount	Number	Order amount in fiat currency.
business_name	String	Display name of the business.
expiration_date	String	ISO 8601 timestamp when order expires.

---

3. API Endpoints

All endpoints below require the JWT in the header: Authorization: Bearer <your_jwt_token>

3.1. Get Order Details

Endpoint: GET /api/orders/{id}

Retrieves complete order information including available payment tokens.

Path Parameter:

Parameter	Description
id	The reference_id from the QR code.

Response (200 OK):

{
  "business_id": "string",
  "business_name": "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",
    "split_amount": 0
  },
  "paid": 0,
  "qr_payload": {
    "amount": 0,
    "business_name": "string",
    "expiration_date": "string",
    "fiat": "string",
    "reference_id": "string"
  },
  "source": "string",
  "status": "string",
  "token_options": [
    {
      "method": "string",
      "token": "string"
    }
  ],
  "total": 0,
  "tx_list": [
    {
      "date": 0,
      "fiatAmount": 0,
      "fiatCode": "string",
      "finalOutAddress": "string",
      "from_address": "string",
      "hash": "string",
      "inboundMemo": "string",
      "isValid": true,
      "method": "string",
      "notified": true,
      "status": "string",
      "toAddress": "string",
      "tokenAmount": 0,
      "tokenCode": "string"
    }
  ],
  "usd_total": 0,
  "version": 0
}

Field Description:

Field	Type	Description
id	String	Order identifier.
status	String	Order status (pending, paid, canceled).
order_info.amount	Number	Order amount in fiat.
order_info.fiat	String	Fiat currency code.
order_info.business_name	String	Business display name.
token_options	Array	Available payment options.
token_options[].method	String	send or swap
token_options[].token	String	Token symbol.

---

3.2. Generate Payment Instructions

Endpoint: POST /api/txs/generate/memo

Generates payment address, final amount (with fees), and mandatory memo.

Request Body:

{
  "order_id": "35178fd8-861c-4198-88ab-3acbc259c495",
  "token_id": "solana",
  "referral": "wallet_ref_code"
}

Field Description:

Field	Type	Description
order_id	String	The order reference_id.
token_id	String	Selected token identifier.
referral	String	Optional wallet referral code.

Response (200 OK):

{
  "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
  "memo": "REFID:35178fd8-861c-4198-88ab-3acbc259c495",
  "amount_with_fees": "50.25",
  "bps": 50,
  "provider_notes": "Sandbox transaction"
}

Field Description:

Field	Type	Description
address	String	Deposit address to send funds to.
memo	String	Mandatory memo to include in transaction.
amount_with_fees	String	Final amount to send (including fees).
bps	Number	Basis points in fees (e.g., 50 = 0.5%).
provider_notes	String	Additional notes from payment provider.

---

3.3. Process Transaction

Endpoint: POST /api/txs/process

Notifies Moca POS of a completed transaction.

Request Body:

{
  "order_id": "35178fd8-861c-4198-88ab-3acbc259c495",
  "hash": "5dzx...Xy12",
  "fiat_amount": 50,
  "fiat_code": "USD",
  "to_address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
  "from_address": "UserWalletAddress123..."
}

Field Description:

Field	Type	Description
order_id	String	The order reference_id.
hash	String	Blockchain transaction hash.
fiat_amount	Number	Order amount in fiat.
fiat_code	String	Fiat currency code.
to_address	String	Receiving address from generate/memo.
from_address	String	User's wallet address.

Response: 200 OK (empty) on success.

Response (400 Bad Request):

{
  "error": {
    "message": "Error description"
  }
}

---

4. Sandbox Testing (Optional)

Endpoint: POST /api/orders/sandbox

Generates test order data for development.

Headers: Authorization: Bearer <jwt_token>, Content-Type: application/json

Request Body:

{
  "amount": 10,
  "fiat": "USD",
  "payment_addresses": [
    {
      "address": "YourTestAddress123...",
      "chain": "solana",
      "token": "usdc"
    }
  ]
}

Response (200 OK):

{
  "reference_id": "test-uuid-1234",
  "fiat": "USD",
  "amount": 10,
  "business_name": "Sandbox Business",
  "expiration_date": "2025-09-12T14:42:28.617Z"
}

Use this response to simulate a scanned QR code.

---

5. Best Practices

1. Authentication: Generate a new JWT for each API call sequence

2. Amount Handling: Always use the amount_with_fees from the generate/memo response

3. Memo Field: Never modify or omit the memo - it contains critical tracking information

4. Error Handling: Implement retry logic for network errors, but not for auth errors (401)

5. Security: Store API keys securely using platform-specific secure storage solutions

6. Expiration: Check order expiration before processing payments

6. Support

For integration support, provide:

• Your API key

• Order reference_id

• Transaction hash (if applicable)

• Error messages and response bodies

• Steps to reproduce the issue

Support Contact: [email protected]