imsafu API

Authentication

If API requires authentication, it should use a Bearer Token.

Authorization: Bearer {SECRET}

Response example when auth failed:

{
  "error": "access denied"
}

Error Object

The standardized error object is:

{
  "error": "an error message"
}

API Prefix

• production: https://allowpay-api-mainnet.fly.dev/v1
• development: https://allowpay-api-devnet.fly.dev/v1

API Lists

Create Deposit Payment

AUTH: required

POST: /depositPay

Request

{
    "payment": {
        // unique orderID from the merchant.
        // error: if there is an existing payment with this orderID.
        "orderID": "0x1234",
        // address to receive this payment
        "receiver": "0x1F2C9c99361528F1E612F4378d52700d1aFDdC12",
        // solana address to receive this payment (token account owner)
        "solanaReceiver": "DEVWatx97Eg6W7oZi77Yt1oXzZsEypfFBDxpN1ySh7u8",
        // payment amount specified as decimal string(truncated 2 decimals).
        "amount": "123.12",
        // currency of the payment, optional, default to USD
        // if RMB is given, the amount (in RMB) will be converted to USD using exchange rate
        "currency": "RMB",
        // deadline for this payment, ISO-8601 Date, default to 6 hours after now
        // Optional
        "deadline": "2023-04-03T03:05:43.167Z"
    },
    // webhook for payment success or failure
    "notifyURL": "https://merchant.com/notify",
    // notifyData will include this in the webhook request body, and GET body
    // Optional
    "notifyData": "merchant-order-id: 123-4213"
}

Response:

{
  "status": "success",
  "payment": {
    "payID": "pay_01GZ8FYDR1E7VNM1J85EP4T0EG",
    "orderID": "0x1234",
    "receiver": "0x1F2C9c99361528F1E612F4378d52700d1aFDdC12",
    "amount": "123.12",
    "maxFeeAmount": "1.0",
    "deadline": "2023-04-03T03:05:43.167Z"
  },
  "solana": {
    "receiver": "DEVWatx97Eg6W7oZi77Yt1oXzZsEypfFBDxpN1ySh7u8",
  },
}

Error:

{
  // a string message
  "error": "invalid payment request"
}

Query payments by pay ID

GET: /depositPays/:payID

Response:

{
  "status": "success",
  "payment": {
    "payID": "pay_01GZ8FYDR1E7VNM1J85EP4T0EG",
    "orderID": "0x1234",
    "receiver": "0x1F2C9c99361528F1E612F4378d52700d1aFDdC12",
    "amount": "123.12",
    "originalAmount": "123.12",
    "maxFeeAmount": "1.0",
    "deadline": "2023-04-03T03:05:43.167Z"
  },
  "owner": "0x1F2C9c99361528F1E612F4378d52700d1aFDdC12",
  "depositAddress": "0x1F2C9c99361528F1E612F4378d52700d1aFDdC12",
  "callID": 1,
  "receiveTx": {
    "chain": {
      "id": 1,
      "symbol": "ETH",
      "name": "Ethereum"
    },
    "txID": "0xabc123",
    "confirmedAt": "2023-04-03T03:05:43.167Z",
    "amount": "123.12",
    "feeAmount": "0.1",
    "token": {
      "symbol": "ETH",
      "address": "0x123abc"
    }
  },
  "deposits": [
    {
      "chainID": 1,
      "token": "0x123"
    },
    {
      "chainID": 2,
      "token": "0x456"
    }
  ],
  "notifyData": "merchant-order-id: 123-4213",
  // if payment is made through solana, `solana.receiveTx` will be available
  "solana": {
    "receiver": "DEVWatx97Eg6W7oZi77Yt1oXzZsEypfFBDxpN1ySh7u8",
    "depositAddress": "7jVXXfMR4xW1dVho5ev5QPCiGXKTFqunWzdsnMVwaxxQ",
    "receiveTx": {
      "chain": {
          "name": "solana",
      },
      "txID": "3YuRCgZG96xduZaph6b8qNBLydftehU1QENrvnS7noVG3CYnsRiEKPjpJ1vx7FgZ19ARhHFRWbZ8bacQt5KhRMKV",
      "confirmedAt": "2023-05-22T08:34:30.001181Z",
      "amount": "2",
      "feeAmount": "0",
      "token": {
        "symbol": "USDT",
        "address": "USDTb1h66DadwB77q1Q94p23KYK96fHynTCrdive32d"
      }
    },
    "deposits": [{
      "token": "USDTb1h66DadwB77q1Q94p23KYK96fHynTCrdive32d",
      "tokenAccount": "7jVXXfMR4xW1dVho5ev5QPCiGXKTFqunWzdsnMVwaxxQ"
    }]
  }
}

Notify Hook

POST: ${notifyURL}

Post Body:

{
  "payment": {
    "payID": "pay_01GZ8FYDR1E7VNM1J85EP4T0EG"
  },
  "notifyData": "merchant-order-id: 123-4213"
}

Client should return 200 with any response type or body.

Appendix

Restrictions to merchant:

• Each key can have up to 10k pending payments.