# SoftPOS – MyPinPad Merchant ID Integration

## Overview

This document describes the implementation of the `POST /api/softpos/register` endpoint, which accepts a SoftPOS registration payload, authenticates with the MyPinPad backend using Azure AD OAuth2, generates a new MyPinPad Merchant ID, and returns it to the caller.

---

## Files Added / Modified

| File | Action |
|------|--------|
| `lib/da_product_app_web/router.ex` | Added route `POST /api/softpos/register` |
| `lib/da_product_app_web/controllers/softpos_controller.ex` | Created — handles request and builds response |
| `lib/da_product_app/mypinpad/mypinpad_client.ex` | Created — OAuth2 token fetch + MyPinPad API call |
| `config/dev.exs` | Added `:mypinpad` config block with credentials |

---

## Request

**Endpoint:** `POST /api/softpos/register`

**Headers:**
```
Content-Type: application/json
```

**Sample Payload:**
```json
{
  "softpos_uuid": "c630b50d-afa9-4aea-a6a9-6dca814c526d",
  "merchantRefId": "392390770000000",
  "device_type": "SoftPOS",
  "store_id": 375
}
```

**Required field:** `softpos_uuid` — your internal reference identifier. It is logged but not forwarded to MyPinPad.

---

## Response

**Success (`200 OK`):**
```json
{
  "success": true,
  "softpos_uuid": "44fba95e-259c-434d-97cc-f694ff619d8d",
  "message": "UUID registered successfully"
}
```

> The `softpos_uuid` in the response is the **newly generated Merchant ID from MyPinPad**, not the UUID sent in the request.

**Missing field (`400 Bad Request`):**
```json
{
  "error": "Missing or invalid required field: softpos_uuid"
}
```

**MyPinPad API error (passes through MyPinPad's status code):**
```json
{
  "success": false,
  ...
}
```

**Network/service failure (`502 Bad Gateway`):**
```json
{
  "success": false,
  "error": "Failed to reach MyPinPad service"
}
```

---

## Internal Flow

```
POST /api/softpos/register
  └─ SoftposController.register/2
       └─ extract softpos_uuid (logged as internal reference)
            └─ MypinpadClient.generate_merchant_id/0
                 ├─ Step 1: POST to Azure AD token endpoint
                 │          → returns Bearer access_token
                 └─ Step 2: GET https://sandbox.mypinpad.io/merchant/id
                            Authorization: Bearer <token>
                            → returns plain UUID string (new merchantId)
  └─ Response: { success, softpos_uuid: <merchantId>, message }
```

---

## Authentication

MyPinPad uses **Azure AD OAuth2 Client Credentials** flow.

| Parameter | Value |
|-----------|-------|
| Token URL | `https://login.microsoftonline.com/mpptestce.onmicrosoft.com/oauth2/v2.0/token` |
| Grant type | `client_credentials` |
| Client ID | configured in `config/dev.exs` |
| Client Secret | configured in `config/dev.exs` |
| Scope | `https://mpptestce.onmicrosoft.com/9c64e445-d90c-4438-91cf-9fe1468ab905/.default` |

A fresh token is fetched on every request. If token caching is needed in future, consider using an Agent or ETS table.

---

## MyPinPad API Reference

| Field | Value |
|-------|-------|
| Sandbox base URL | `https://sandbox.mypinpad.io` |
| Production base URL | `https://api-na1.mypinpad.io` (confirm with MyPinPad before go-live) |
| Endpoint | `GET /merchant/id` |
| Response | Plain UUID string — the new Merchant ID |

> **Note:** The endpoint generates a **new** Merchant ID on every call. It does not accept or look up an existing ID.

---

## Configuration (`config/dev.exs`)

```elixir
config :da_product_app, :mypinpad,
  base_url: "https://sandbox.mypinpad.io",
  token_url: "https://login.microsoftonline.com/mpptestce.onmicrosoft.com/oauth2/v2.0/token",
  client_id: "<client_id>",
  client_secret: "<client_secret>",
  scope: "https://mpptestce.onmicrosoft.com/9c64e445-d90c-4438-91cf-9fe1468ab905/.default"
```

For production, move credentials to environment variables in `config/runtime.exs`.

---

## Sample cURL

```bash
curl -X POST http://localhost:4000/api/softpos/register \
  -H "Content-Type: application/json" \
  -d '{
    "softpos_uuid": "c630b50d-afa9-4aea-a6a9-6dca814c526d",
    "merchantRefId": "392390770000000",
    "device_type": "SoftPOS",
    "store_id": 375
  }'
```