Skip to content

invoice

Модель invoice предназначена для выставления счетов клиентам и пополнения мерчантом своих балансов собственными средствами.

Выбор способа оплаты совершается клиентом в рамках заданных мерчантом платежных систем.

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

  • is_multipay = true - зачисление средств на баланс мерчанта производится только при накоплении оплат в размере суммы, что указана в выставленном счете.

    Если сумма базового платежа меньше выставленной в счете, то клиент может выполнить доплату или вернуть себе уже перечисленные средства. А в случае переплаты - получить обратно сдачу.

  • is_multipay = false - не предусмотрена возможность доплаты или возврата. Сумма платежа сразу и в полном объеме, за вычетом комиссии, зачисляется на баланс мерчанта. В данном случае обязательно должна указываться платёжная система.

Доля общей суммы комиссии за поступления, которую оплачивает мерчант, определяется значением параметра merchant_payfee [0..1], остаток комиссии платят клиенты. А операционные расходы по возврату средств всегда несут клиенты.

Используя методы модели invoice мерчант может:

  1. Создать счет на оплату методом invoice.create;
  2. Рассчитать предварительные параметры счета - метод invoice.calc;
  3. Получить информацию по выбранному счету - метод invoice.get.

endpoint

Запросы на работу методов модели отправляются на endpoint https://api.any.money/.

invoice.create

Метод создания ордера входящего платежа, учитывающего суммы счета и оплаты.

Входящие параметры метода создания ордера invoice-платежа
Параметр Обязательный параметр Пример Описание
amount да "1000,25" сумма invoice-платежа
externalid да "123" уникальный идентификатор, заданный мерчантом
in_curr да "UAH" валюта пополнения invoice-платежа
callback_url нет "https://callback_example.com" url-адрес для уведомлений про изменения состояния ордера, формат уведомлений
client_email нет "[email protected]" email-адрес плательщика для нотификаций про изменения состояния invoice-платежа
comment нет "Счет по заказу 123" комментарий к invoice-платежу (не возвращается в репрезентации)
is_multipay нет false флаг, обеспечивающий возможность совершения доплаты и получения возврата (true = доплата и возврат возможны, false = блокированы). default=false
lifetime нет "1d12h" "время жизни" ордера, в секундах или в формате timedelta (строка формата "1w1d1h1m1s1ms"). Допустимый диапазон значений: "7d".."3600s". default="7d"
merchant_payfee нет "0,35" доля общей суммы комиссии за поступления, которую оплачивает мерчант (значение в интервале [0..1] c точностью до двух знаков после запятой. 0=0%..1=100%)
out_curr нет "USD" опциональная валюта зачисления invoice-платежа
payway нет "card" платежная система, через которую проводится пополнение (возможные варианты: "btc", "perfect", "qiwi"... и т.д.). Для мерчанта, имеющего привязку к ПС, доступна только ПС привязки. Является обязательным параметром при is_multipay = false.
redirect_url нет "https://example.com/order_page/" url-адрес для перенаправления пользователя после завершения работы или нажатия им кнопки "Назад"

Внимание!

Если в метод передаётся наименование платёжной системы, то обязательно с ним нужно передать приведенные ниже параметры соответствующей платёжной системы:

Обязательные параметры для используемых в методе платёжных систем

qiwi
  • payer - банковские реквизиты плательщика (номер кошелька в платежной системе) (e.g. +380123456789)
    • payoneer
  • payer - электронный адрес плательщика (e.g. [email protected]).
    • exmo, kuna, anycash
  • code - полный номер кода ПС. Обязательный параметр при is_multipay = false.
    • cash
  • contact - контактные данные получателя платежа: телефонный номер или телеграмм-аккаунт (e.g. "+380441232344")
  • country - наименование страны платежа (e.g. "ukraine")
  • region - наименование региона платежа (e.g. "kiev")
    • iban
  • payer - имя плательщика (должно соответствовать имени владельца счета, с которого будет выполнена оплата)

    • Если передано наименование валюты зачисления (out_curr), отличное от имени валюты пополнения (in_curr), то после удачной финализации ордера будет выполнена попытка конвертировать поступившую сумму в валюту зачисления по текущему курсу. При удачной попытке средства будут зачислены на баланс валюты зачисления, иначе - на баланс валюты пополнения.
    Если переданное наименование валюты зачисления равно наименованию валюты пополнения, то метод invoice.create в своей работе проигнорирует значение параметра out_curr.
    Если в запросе не передано значение out_curr, то будет произведено зачисление на баланс валюты с именем in_curr.
    Значения timedelta передаются в формате пар: <значение><ключ><значение><ключ>…<значение><ключ> без пробелов между парами. Возможна передача только секунд в виде значения без ключа. Но, если в строке timedelta применён хоть один ключ, то она обязана завершаться ключом, а не цифрой, иначе будет возвращена ошибка.

    Внимание!

    Для типизированных мерчантов передаваемая платежная система должна совпадать с типом мерчанта, иначе метод возвратит ошибку

    Данные ответа метода

    репрезентация ордера входящего платежа

    Возможные возвращаемые ошибки

    EParamAmountFormatInvalid
    неправильный формат параметра amount
    EParamAmountTooBig
    amount больше максимальной суммы операции
    EParamAmountTooSmall
    amount меньше минимальной суммы операции
    EParamCurrencyInvalid
    валюта отсутствует в системе
    EParamFieldInvalid
    передан невалидный параметр callback_url

    EParamInvalid
  • не передан обязательный параметр
  • переданное "время жизни" истекло
  • криптоадрес для принятия платежа не найден или не сгенерирован
  • переданный email или timedelta не соответствует формату
  • переданы одновременно merch_fee и merchant_payfee
  • переданы одновременно is_multipay и is_multypay
  • переданы одновременно expiry и lifetime
  • переданная ПС не соответствует типу мерчанта
    • EParamPaywayInvalid
    указана неверная платежная система
    EParamPeriodInvalid
    неправильный формат параметров expiry, lifetime, timedelta
    EParamPeriodTooLong
    значение lifetime больше максимально допустимого для системы
    EParamPeriodTooShort
    значение lifetime меньше минимально-допустимого для системы
    EParamUnique
    ордер с таким externalid уже существует
    EStateCurrencyInactive
    передана неактивная валюта пополнения
    EStateCurrencyUnavail
    передана недоступная валюта пополнения
    EStatePaywayInactive
    платежная система неактивна в данный момент
    EStatePaywayUnavail
    данная платежная система заблокирована административно
    EStatePwcurrencyUnavail
    данная валюта платежной системы недоступна
    EStatePwcurrencyInactive
    данная валюта платежной системы неактивна

    invoice.calc

    Метод расчета параметров входящего invoice-платежа с учётом суммы зачисления.

    Входящие параметры расчета ордера invoice-платежа
    Параметр Обязательный параметр Пример Описание
    amount да "500" сумма входящего платежа
    in_curr да "USD" валюта пополнения, т.е. валюта поступления средств в систему
    out_curr нет "USD" валюта списания
    payway нет "anycash" платежная система, через которую ожидается пополнение

    Внимание!

    Для типизированных мерчантов передаваемая платежная система должна совпадать с типом мерчанта, иначе метод возвратит ошибку

    Данные ответа метода

    account_amount
    сумма зачисления, за вычетом комиссии
    in_amount
    сумма пополнения
    orig_amount
    сумма, задаваемая при создании ордера
    out_amount
    сумма зачисления на баланс мерчанта
    rate
    курс конвертации входящей в исходящую валюты, если проводилась конвертация

    Возможные возвращаемые ошибки

    EParamAmountFormatInvalid
    неправильный формат параметра amount
    EParamAmountTooBig
    amount больше максимальной суммы операции
    EParamAmountTooSmall
    amount меньше минимальной суммы операции
    EParamCurrencyInvalid
    валюта отсутствует в системе
    EParamInvalid
  • передано неверное значение параметра
  • переданная ПС не соответствует типу мерчанта
    • EParamPaywayInvalid
    указана неверная платежная система
    EStateCurrencyInactive
    зачисления в валюте пополнения не могут быть совершены - она неактивна в переданной ПС или в Any.Money
    EStateCurrencyUnavail
    переданная валюта не валидна для переданной ПС (payway)
    EStatePaywayInactive
    платежная система неактивна в данный момент
    EStatePaywayUnavail
    данная ПС заблокирована административно
    EStatePwcurrencyUnavail
    данная валюта платежной системы недоступна
    EStatePwcurrencyInactive
    данная валюта платежной системы неактивна

    invoice.get

    Метод для запроса параметров invoice-платежа по его внешнему идентификатору.

    Входящие параметры запроса данных invoice-платежа
    Параметр Обязательный параметр Пример Описание
    externalid да "257" уникальный идентификатор платежа, заданный мерчантом

    Данные ответа метода

    репрезентация ордера операции входящего платежа

    Возможные возвращаемые ошибки

    EParamInvalid
    externalid передан пустой, неправильного типа или имеет недопустимое значение
    EParamNotFound
    не найден ордер c переданным externalid