push.money API Guide

push-monei-api-guide.md

Гайд по использованию push.money API для front-end разработчиков

Flow со стороны отправителя

На главной странице после заполнения опциональной формы (sender, recipient, amount, password) вызываем /push/create, передаем в payload поля, которые были заполнены. получаем address, link_id и deeplink (если был указан amount).

Показываем юзеру address, даем возможность его скопировать. Если есть deeplink, даем возможность по нему перейти/отсканировать.

Далее проверяем баланс раз в ~5 сек. - /push/:link_id/balance. Если при создании был указан пароль, нужно передать его в payload После того как баланс стал ненулевым, можем показать отправителю ссылку https://yourproject.com/:link_id

Flow cо стороны получателя

При переходе на ссылку, вызываем /push/:link_id/info. Отображаем полученную доп. информацию (sender, recipient). Если is_protected: true - спрашиваем у получателя пароль. Вызываем /push/.../balance (с паролем, если надо). Если пароль верен, запомним его и будем передавать везде. Иначе запрашиваем пароль снова.

Эндпоинты GET /push/.../balance и POST /spend/... без пароля - недоступны. возможно auth-схему нужно будет пересмотреть, но пока так

Отображаем баланс одноразового кошелька (результат /push/:link_id/balance) и категории, куда можно потратить деньги (/spend/list). Некоторые из них реализованы, некоторые нет (за это отвечает флаг enabled)

На данный момент, тратить можем только всю сумму на одну категорию.

После того как пользователь выбрал способ траты, у нас появится categpry или option. Отправляем POST /spend/:link_id. В payload указываем:

• option: ставим option или category, если внутри категории нету вариантов выбора (mobile)
• params (о том какие они могут быть для каждого category/option, описано ниже в разделе с эндпоинтом)

После успещной траты баланса, Core Flow считаем завершенным.

Полная API-документация

BASE_URL = https://push.money/api/

• Create unique "push one-time wallet" id

  POST /push/create

  Payload:

  {
    // all params are optional
    "sender": string 
    "recipient": string
    "amount": number, 
    "password": string
  }
  

  Response:

  { 
      "address" : "Mx...",
      "link_id" : "Zegsm3HWhR3DELHc3Po9M3",
      
      // (optional, if amount specified)
      "deeplink": "https://bip.to/tx?d=f001aae98a424950..."
  }
  

• Get push-wallet info

  GET /push/:link_id/info

  Response:

  { 
      "sender": string|null,
      "recipient": string|null,
      "is_protected": boolean
  }
  

• Get push-wallet balance

  GET /push/:link_id/balance

  Payload:

  {
    "password": string  // needed, if was set when /push/create
  }
  

  Response:

  { 
      "address" : "Mx...",
      "balance" : {
          "BIP": {
              "value": 0.1234,  // coin amount
              "bip_value": 0.1234,  // bip equivalent
              "usd_value": 0.485  // usd equivalent
          },
          "COIN": {
              "value": 1.23,
              "bip_value": 579.2103,
              "usd_value": 2096.985
          },
          ...
      },
      "bip_value_total": 579.3337,
      "usd_value_total": 2097.470,
      
      // 1 USD to XXX. Local fiat value = fiat_rates[local_currency] * usd_value
      "fiat_rates": {
          "USD": 1.0,
          "RUB": 68.37,
          "UAH": 24.75,  
          ...
      }
  }
  

• Get all posible spend categories list with detailed options

  GET /spend/list

  Response:

  [
      "category": "transfer",
      "enabled": true  // false, if category is not available yet
      
      // "spend_options" list may be empty
      "spend_options": [
          // spend_option - payment target in scope of category
          // (service provider, product, payment system, etc.)
          {
              "option": "transfer-minter",
              "enabled": true
          },
          ...
      ]
  ]
  

  List of categories:

  transfer, mobile, invest, charity, taxi, lottery, bills, services, food, transport, offers, games, fuel, gifts, entertainment

• Perform spending

  POST /spend/:link_id

  Payload

  {
      "password": string,  // optional, only for protected push-wallets
      "option": "transfer-minter"
      "params": {
          ...
      }
  }
  

  valid value for "params" object is option-specific:

  • transfer-minter option - {"to": "Mx..."}
  • mobile option - {"phone": "+XXXXXXXXXXXX"}

  Fail Response:

  { 
      "error" : "Error message"
  }
  

  Success Response:

  { 
      "message" : "Success"
  }