## Cryptom Pay API Integration

## Payment Flow

sequenceDiagram
Client ->> POS: Authenticate [POST /auth]
POS -->> Client: Access and refresh tokens
Client ->> POS: Create transaction [POST /api/transaction/create]
POS -->> Client: Wallet address
Client ->> POS: Create QR Code [GET /qr/:transactionID]
POS -->> Client: QR Code image in PNG format
loop until isTransferComplete == true
Note over Client,POS: After showing qrcode, poll this endpoint. Timeout is handled on your side (=Client).
    Client ->> POS: Get Transaction [GET /api/transaction/detail/:transactionID]
    POS -->> Client: Transaction detail and status
end
alt if user cancells manually
    Client ->> POS: Cancel Transaction [DELETE /api/transaction/cancel/:transactionID]
    POS ->> Client: Cancellation status
end

## Transaction Completion Criteria
- if `isTransferComplete == true` it means the transfer is complete and there's no need to check `status` field.
- if `status == CANCELLED`, it means the transaction is cancelled.
- the other terminal statuses `[DONE, MANUAL_CHECK, TIMEOUT]` are not needed on the client side.
- if `status == TRANSFERRED`, it doesn't necessarily mean that the tranfer is complete, in case of a partial transfer, `isTransferComplete !== true`, but `status == TRANSFERRED`. Always use `isTransferComplete` for checking successful transaction.

## Example responses

**POST** `/auth`
#### Request (Body)

{
    "email": "[e-mail]",
    "password": "password"
}

#### Response

{
    "status": true,
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiNjM4OWQyZTI1N2M4NTczOGFhYTAzNzQyIiwiZW1haWwiOiJ0ZXN0MUB0ZXN0LmNvbSIsInJvbGUiOiJ1c2VyIiwiaWF0IjoxNjczOTUzNTk5LCJleHAiOjE2Nzc1NTM1OTl9.epPEDrkCVOIGIkJFpTloYYzTQ2cQKNjx0cRcqRn77Q0",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiNjM4OWQyZTI1N2M4NTczOGFhYTAzNzQyIiwiZW1haWwiOiJ0ZXN0MUB0ZXN0LmNvbSIsInJvbGUiOiJ1c2VyIiwiaWF0IjoxNjczOTUzNTk5LCJleHAiOjE3NjAzNTM1OTl9.0g1gWi6_DdE2Tk7hPh9yk3c_RLQFjA70vNTJKsDdtdQ",
    "expires": {
        "accessToken": 3600000,
        "refreshToken": 86400000
    },
    "expiresIn": {
        "accessToken": 1673957199578,
        "refreshToken": 1674039999578
    }
}

**POST** `/api/transaction/create`
#### Request (Body)

{
    "currency": "TRY",
    "currencyAmount": 300,
    "coin": "TRX",
    "network": "TRX".
    "userMobile": "[phone]"
    "statusNote": "A sample description.",
}

#### Response

{
    "status": true,
    "data": {
        "_id": "6338cb9cd4cb3327e706ddb1",
        "currency": "TRY",
        "currencyAmount": "200",
        "conversionRate": "0.02",
        "exchangeFee": "1.474",
        "clientType": "GATEWAY",
        "coin": "TRX",
        "network": "TRX",
        "coinAmount": "148.874",
        "commission": "4",
        "cryptomUserId": "2",
        "assignedToMerchant": "6338caa212f17299558072a6",
        "cashierID": "9999",
        "status": "PENDING",
        "acceptableThreshold": 1000,
        "totalTransferAmount": "0",
        "isTransferComplete": false,
        "timestamps": "1664666524",
        "timeout": "1664726524",
        "deleted": false,
        "date": "2022-10-01T23:22:04.081Z",
        "createdAt": "2022-10-01T23:22:04.081Z",
        "updatedAt": "2022-10-01T23:22:05.640Z",
        "sequenceID": 10006,
        "__v": 0,
        "reservedFrom": "2022-10-01T23:22:06.521Z",
        "reservedUntil": "2022-10-15T23:22:06.521Z",
        "wallet": {
            "ID": 428048732580321540,
            "coin": "TRX",
            "network": "TRX",
            "address": "TXaxqXSZkZAsXmnFWYc6MPFdSXkUP1H3gq",
            "createdAt": "2022-10-01T23:22:06.522Z",
            "updatedAt": "2022-10-01T23:22:06.522Z"
        },
        "id": "6338cb9cd4cb3327e706ddb1"
    }
}

## Transaction History
**GET** `/api/transaction?p1=v1&...`

#### Request (Query Params)

{
    "id": <string>,
    "sequenceID": <number>,
    "currency": <string>,
    "currencyAmount": <number>,
    "clientType": <ClientType>,
    "coin": <string>,
    "network": <string>,
    "coinAmount": <number>,
    "status": <Status>,
    "userEmail": <string>,
    "userMobile": <string>,
    "reservedFrom": <string>,
    "reservedUntil": <string>,
    "walletAddress": <string>
}

type ClientType = OneOf['POS', 'GATEWAY']

type Status = Oneof['PENDING', 'TIMEOUT', 'TRANSFERRED', 'CONVERTING', 'CONVERTED', 'WALLET_CHARGED', 'DONE', 'MANUAL_CHECK', 'CANCELLED']

Note: These statuses are internal and subject to change.

#### Response

{
    "status": true,
    "data": {
        "results": [
            {
                "_id": "6333825a211f29425a7aca20",
                "currency": "TRY",
                "currencyAmount": "195.8",
                "conversionRate": "2.1",
                "clientType": "GATEWAY",
                "coin": "TRX",
                "network": "TRX",
                "coinAmount": "160.52",
                "commission": "4.2",
                "cryptomUserId": "1",
                "assignedToMerchant": {
                    "_id": "633370faa57f56e76dc8beaa",
                    "cryptomUserId": "1",
                    "merchantName": "abc2",
                    "assignedToUser": "6333707ba1b31559f9493d2f",
                    "contactEmail": "[e-mail]",
                    "website": "www.cryptom.com",
                    "callbackDomain": "pay.cryptom.com",
                    "defaultCallbackDomain": "pay.cryptom.com",
                    "countryCode": 90,
                    "contactNo": 5463925262,
                    "securityNo": 1,
                    "agentName": "Deniz Umut Dereli",
                    "status": "ACTIVE",
                    "accessType": "ALL",
                    "multipleLocation": "ALL",
                    "created_by": "63337059c9b7c79d371127b4",
                    "deleted": false,
                    "date": "2022-09-27T21:54:02.384Z",
                    "createdAt": "2022-09-27T21:54:02.391Z",
                    "updatedAt": "2022-09-27T22:14:25.488Z",
                    "updated_by": "63337059c9b7c79d371127b4"
                },
                "cashierID": "9999",
                "status": "PENDING",
                "statusNote": "A sample description.",
                "userMobile": "[phone]",
                "acceptableThreshold": 1000,
                "created_by": {
                    "_id": "6333707ba1b31559f9493d2f",
                    "email": "[e-mail]",
                    "role": "user",
                    "status": "ACTIVE",
                    "created_by": "63337059c9b7c79d371127b4",
                    "deleted": false,
                    "date": "2022-09-27T21:51:55.552Z",
                    "createdAt": "2022-09-27T21:51:55.558Z",
                    "updatedAt": "2022-09-27T21:51:55.558Z"
                },
                "timestamps": "1664320090",
                "deleted": false,
                "date": "2022-09-27T23:08:10.022Z",
                "createdAt": "2022-09-27T23:08:10.030Z",
                "updatedAt": "2022-09-27T23:08:11.555Z",
                "sequenceID": 10000,
                "__v": 0,
                "reservedFrom": "2022-09-27T23:08:12.554Z",
                "reservedUntil": "2022-10-11T23:08:12.554Z",
                "wallet": {
                    "ID": 427467512825878800,
                    "coin": "TRX",
                    "network": "TRX",
                    "address": "TBG1Wg3MdA3YwrVCbCmKqNkZ1fKyxhiuys",
                    "createdAt": "2022-09-27T23:08:12.555Z",
                    "updatedAt": "2022-09-27T23:08:12.555Z"
                }
            }
        ],
        "totalDocs": 1,
        "limit": 10,
        "page": 1,
        "totalPages": 1,
        "pagingCounter": 1,
        "hasPrevPage": false,
        "hasNextPage": false,
        "prevPage": null,
        "nextPage": null
    }
}