Кошелек

V 2.0

Накопительный и Форвардинг кошельки

Bitcoin QR code icon

Contents

Вы можете создавать сколь угодно кошельков для своего проекта, но каждый кошелек может быть только одного типа: Накопительный или Форвардинг.

Форвардинг кошелек принимает и сразу же пересылает платеж на указанный вами биткоин-адрес. Так же он имеет возможность разделять платеж на нескольких получателей.

Входящая оплата может быть разделена по списку до 255 получателей. Вы можете отправлять как фиксированные суммы так и процент от оплаты. Эта функция очень удобна для мгновенных рассчетов с рефералами, разделения выплат в многоуровневом маркетинге, выплата гонарара или разделение на горячий и холодный кошелек. Если после деления платежа, остается остаток, то он направляется на последний адрес из списка.

Каждый платеж делиться по очереди, в списке, пока не распределиться вся сумма до последнего Сатоши. Список выполняется от первого и до последнего значения. Поэтому порядок важен.

Накопительный кошелек аккумулирует все входящие транзакции и по запросу пересылает одному или нескольким получателям. Вы можете указать от 1 до 255 адресов получателей в списке.

Запрос:

{
"type": "saving|forwarding",
"callback":{                       #optional
      "url": "your_callback_URL",  #optional
      "data":{                     #optional
         "optional_key": "value"
      }
   },
	"destinations":[           #Адрес получателя указывается только для Форвардинг-кошельков
      {"amount": <amount|"percents">, "address": "<bitcoin_address>"},
		... #from 1 to 255 addresses
	]
}

Пример кода для wallet type

Обратный вызов URL КлючЗначение

+

АдресСумма

+


{
   "type": "forwarding",
   "callback":{
      "url" :  "http://example.com/callback"
   }
}
  
<?php
  $json_data = array (
    'type' => "forwarding",
    'callback' => array(
        'url'=> "http://example.com/callback"
    )
  );
  
  $api_endpoint = "https://apirone.com/api/v2/btc/wallet";
 
  $curl = curl_init($api_endpoint);
  curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
  curl_setopt($curl, CURLOPT_POST, 1);
  curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($json_data));
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
  $response = curl_exec($curl);
  $http_status_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
  curl_close($curl);
 
  if ($http_status_code==200){
	  $decoded = json_decode($response, true);
	  echo "Wallet: " . $decoded["wallet"] . "<BR>";
	  echo "Key: " . $decoded["transfer_key"];
  } else {
      var_dump($response);
  }
?>
Сделать запрос
Результат выполнения:

JSON Описание схемы

Используйте метод POST для отправки объектов в JSON формате

Ссылка на страницу колбэка

Колбэк это массив из URL и данных пользователя

Параметры Описание Обязательное поле
{callback:url}
string,
=< 1024 chars

Ссылка на страницу колбэка
URL-адрес колбэка для получения данных об оплате. URL-адрес должен быть валидным.

Обязательное поле
{callback:data}
массив

Данные
Ассоциативный массив состоящий из пар ключ-значение. Здесь вы можете использовать дополнительные идентификаторы или секретные поля для большей безопасности.

Для примера 'secret' = '7j0ap91o99cxj8k9' or 'invoice_id'='1234'

Опциональное поле

Биткоин-адрес получателя и сумма

Ваш биткоин-адрес для получения платежа. Можете указать минимум 1, максимум 255 различных биткоин-адресов. Тогда входящая оплата разделиться согласно этому списку.

Параметры Описание Обязательное поле Пример
{destinations}
string,
32 - 42 chars
Биткоин-адрес получателя

Биткоин-адрес Интернет-магазина, куда будет произведён форвардинг платежа.

Обязательное поле

1apiKcJM95jENZeom2dQo8ShK7dUQkRaS

bc1qggg2ys8duv4qvnfgzng2p75m6ehklcmfygr9m4

{amount}
(integer | "percent in string")

Сумма

Сумма в Сатоши или в процентах. Если этот параметр пустой, то вся оставшаяся сумма будет переведена на этот адрес.

Опциональное поле

253999

"20%"

"31.55%"

Успешное выполнение:

{
  "wallet": "8e9c53a62755bcc66e4d2aaae3a2af6d",
  "type": "saving",
  "transfer_key": "7j0ap91o99cxj8k97j0ap91o99cxj8k9",
  "currency": "btc",
  "callback":
  {
     "url": "http://example.com/callback",
     "data":
     {
        "invoice_id": "1234",
        "secret": "7j0ap91o99cxj8k9",
     }
  }
}

Сообщение об ошибке

Сообщение об ошибке возвращается в текстовом формате, как показано ниже:
Wrong parameters. — Неправильные параметры.
Destinations couldn't be empty. - Адрес получателя не может быть пустым.
All destinations should be unique. - Адреса получателей должны быть уникальными и не повторяться.
'destinations' attribute is required for forwarding wallet type. - Атрибут 'destinations' обязателен для форвардинг-кошельков.
Invalid wallet type. Valid wallet types are: saving,forwarding,forwarding-legacy. - Указан неправильный тип кошелька. Правильный тип кошелька: saving,forwarding,forwarding-legacy.
Invalid address: mqTZ5Lmt1rrgFPeGeTC8DFExAxV1U852G. - неверный формат адреса
Incorrect amount for address. - Неправильно указана сумма для адреса.

Cases of split payment

Пример разделения платежа с указанием точной суммы:

Магазин платить фиксированную сумму 0.2 BTC своему партнеру, 0.3 BTC за доставку, 1.5 BTC отправляет в холодное хранилище (Cold Storage) и остальное оставляем для бизнеса.

{
   "callback":{
      "url":"http://example.com/callback",
      "data":{
         "secret":"7j0ap91o99cxj8k9"
      }
   },
   "destinations":[
      {"address": "1apiKcJM95jENZeom2dQo8ShK7dUQkRaS", "amount":  20000000},
      {"address": "1apimr7q2cL3xPma8SfiDPyTdWSHXSEyB", "amount":  30000000},
      {"address": "1ApiwpetcWnBbkpU7cb7biPfc6Tiucasf8", "amount": 150000000},
      {"address": "1Api8ZyHPp4f1QNTsi3AGyXbaTnzzAuDez"}
   ]
}

Покупатель платит за заказ 10 BTC.

Случай оплаты меньшей суммы. Если покупатель оплатил всего 1 BTC, то сумма будет разделена на 0.2, 0.3 и оставшаяся часть 1 - 0.5 = 0.5 будет направлена в холодное хранилище. Адрес для Бизнеса не получит ничего, потому что входящей оплаты не достаточно.

Случай полной оплаты. Магазин получит уведомление об оплате и о разделении суммы на указанные биткоин-кошельки: 0.2, 0.3, 1.5 и 8 BTC.

Случай переплаты. Последний адрес, в списке, без указанной суммы, получит весь остаток от разделения.

Комиссия сети и комиссия сервиса будут вычтены из последней выплаты. В этом примере - из бизнес части.

Пример разделения в процентом соотношении:

Давайте представим что вы открываете Биржу. Вы хотите разделить 20% на Горячий кошелек, для быстрых выплат клиентам, 30% отправить на ваш счет, на другую биржу, для управления и арбитража, а оставшиеся 50% положить в безопасное место - Холодный кошелек.

{
   "callback":{
      "url":"http://example.com/callback",
      "data":{
         "secret":"7j0ap91o99cxj8k9"
      }
   },
   "destinations":[
      {"address": "1apiKcJM95jENZeom2dQo8ShK7dUQkRaS", "amount": "20%"},
      {"address": "1apimr7q2cL3xPma8SfiDPyTdWSHXSEyB", "amount": "30%"},
      {"address": "1ApiwpetcWnBbkpU7cb7biPfc6Tiucasf8"}
   ]
}

Порядок в списке важен.
Весь входящий платеж делится на три адреса пропорционально.
Первыми в списке, вычитаются комиссия сети и комиссия сервиса.