По всей базе знаний
Softline Payments
Наверх
По всей базе знаний
Softline PaymentsИнтеграцияPayments API
[POST] Создание платежа

[POST] Создание платежа

Описание запроса

POST /v1/payment

Запрос предназначен для создания платежа. В результате выполнения запроса создается объект Платеж в статусе not paid. Дальнейшие операции с платежом зависят от используемого сценария.

Сценарии использования:

Обратите внимание. Срок жизни платежа в статусе not paid - 90 дней. После этого происходит автоматическое изменение статуса на deleted.

Данные для отправки запроса

Параметры заголовка

content-type
string
required
MIME-тип данных в теле запроса
Должен быть равен "application/json".
AuthorizationJWT
required
Авторизационный токен
  • Формат значения: Bearer [token]
  • Вместо [token] подставьте значение token, полученное в ответ на запрос к Authentication API

Параметры в теле запроса

currency
string
required
Код валюты продажи платежа
Доступные валюты настраиваются при подключении в соответствии с вашим договором.
  • Формат: ISO 4217 alpha-3, 3 символа
  • Варианты значений см. в справочнике
amount
string
required
Сумма платежа
  • Формат: Число, до 2 десятичных знаков, разделитель - точка
  • Сумма платежа должна отвечать условию: [amount] > 0
return_success_url
string
required
URL для возврата после успешной оплаты
Это URL-адрес ресурса на вашей стороне, на который покупатель будет автоматически перенаправлен в случаях:
  • После успешной online оплаты через платежную форму Softline Payments
  • При обращении к странице платежной формы Softline Payments, если платеж имеет статус paid
В остальных случаях переданное значение не используется.

Не более 255 символов.
payment_method
string
required
Код платежного метода
  • Список доступных платежных методов зависит от валюты платежа, см. в справочнике
  • Если следующей операцией с платежом будет разовая оплата картой, то код платежного метода должен быть равен CreditCard
recurring_indicator
boolean
Признак родительского платежа
Используется для регистрации родительского заказа, с целью последующего проведения автоплатежей.
Варианты значения:
  • true - платеж является родительским для проведения автооплаты
  • false - платеж не является родительским
По умолчанию false.
payment_id
string
required
Идентификатор платежа на вашей стороне
Может отображаться покупателю при оплате, подробнее см. в описании параметра payment_description.
  • Информационное значение, уникальность идентификатора не проверяется
  • В случае, если будет сделан повторный запрос с одним и тем же идентификатором, то будет создан новый платеж
  • Допустимы только цифры, латинские буквы, символы "-" и "_"
payment_description
string
Описание платежа
В зависимости от платежного метода может отображаться покупателю в форме оплаты, на страницах ошибки оплаты. Отображаетcя не для всех платежных методов.
  • Не более 255 символов
  • Если не передано, то будет сгенерировано по шаблону: "Payment [payment_id]"
locale
string
Код языка интерфейса платежной формы
Например: ru_RU.
  • Варианты значений см. в справочнике
  • Список доступных языков определяется при подключении. Обратитесь в службу поддержки, если необходимо изменить список
Если параметр не передан, то платежная форма отображается на языке по умолчанию (определяется при подключении).
Полученный в запросе код языка сохраняется для платежа, если передан корректный код языка. Если код языка корректный, но не доступен для платежной формы, то он будет сохранен в платеже, но платежная форма открыта с использованием языка по умолчанию.
customer
object
required
Данные покупателя
Персональные данные покупателя используются для проведения оплаты в зависимости от выбранного платежного метода. Например, если платежный метод доступен только для юридических лиц, то требуется заполнить данные о компании покупателя.

Вы можете передавать фейковые данные в этих параметрах, но такой платеж может быть отклонен эквайером из-за подозрения во фроде.
customer
/
email
string
required
E-mail покупателя

Не более 80 символов.
customer
/
first_name
string
required
Имя покупателя

Не более 255 символов.
customer
/
last_name
string
required
Фамилия покупателя

Не более 255 символов.
customer
/
phone
string
Номер телефона покупателя

Не более 64 символов.
customer
/
company_name
string
required*
Наименование компании
  • * - При оплате юридическим лицом обязательно для заполнения
  • При оплате физическим лицом параметр не передается
  • Не более 255 символов
customer
/
vat_number
string
required*
ИНН компании (при оплате в российских рублях)
  • * - при оплате юридическим лицом требования к заполнению зависят от платежного метода, подробнее см. в справочнике
  • При оплате физическим лицом параметр не передается
  • Формат: только цифры, 10 или 12 символов
customer
/
company_billing_address
string
required*
Юридический адрес компании
  • * - при оплате юридическим лицом требования к заполнению зависят от платежного метода, подробнее см. в справочнике
  • При оплате физическим лицом параметр не передается
  • Не более 255 символов
customer
/
company_delivery_address
string
Фактический адрес компании
  • * - при оплате юридическим лицом требования к заполнению зависят от платежного метода, подробнее см. в справочнике
  • При оплате физическим лицом параметр не передается
  • Не более 255 символов
customer
/
kpp
string
КПП компании
  • * - при оплате юридическим лицом требования к заполнению зависят от платежного метода, подробнее см. в справочнике
  • При оплате физическим лицом параметр не передается
  • Формат: только цифры, 9 символов
additional_data
object
Дополнительные параметры
Не отображается покупателю. Переданные значения будут сохранены в платеж. Узнайте подробнее, как использовать дополнительные параметры. Обратите внимание, срок хранения дополнительных параметров ограничен.
additional_data
/
referer7
string
Значение referer7

Не более 255 символов.
additional_data
/
referer8
string
Значение referer8

Не более 255 символов.
additional_data
/
referer9
string
Значение referer9

Не более 255 символов.
additional_data
/
referer10
string
Значение referer10

Не более 255 символов.
additional_data
/
referer11
string
Значение referer11

Не более 255 символов.
additional_data
/
referer12
string
Значение referer12

Не более 255 символов.

Пример запроса (полный набор параметров)

{
  "currency": "RUB",
  "amount": "112.50",
  "return_success_url": "https://shop.com/successful_payment",
  "payment_method": "CreditCard",
  "recurring_indicator": false,
  "payment_id": "TEST12025",
  "payment_description": "Тестовая оплата",
  "locale": "ru_RU",
  "customer": {
    "email": "customer@gmail.com",
    "first_name": "Иван",
    "last_name": "Петров",
    "phone": "7999991111",
    "vat_number": "12345654321",
    "company_name": "ООО Компания",
    "company_billing_address": "Москва, Ломоновоский проспект, 12",
    "company_delivery_address": "Москва, Ломоновоский проспект, 12",
    "kpp": "123456789"
  },
  "additional_data": {
    "referer7": "test",
    "referer8": "testA",
    "referer9": "testB",
    "referer10": "testC",
    "referer11": "testD",
    "referer12": "testF"
  }
}

Пример запроса (минимальный набор параметров)

{
  "currency": "RUB",
  "amount": "112.50",
  "return_success_url": "https://shop.com/successful_payment",
  "payment_method": "CreditCard",
  "payment_id": "TEST12025",
  "customer": {
    "email": "customer@gmail.com",
    "first_name": "Иван",
    "last_name": "Петров"
  }
}

Ответ на запрос

В ответ на запрос вы получите код ответа сервера, соответствующий результату обработки.
В зависимости от кода в теле ответа могут присутствовать дополнительные параметры.

Положительный ответ

При успешной обработке запроса вы получите код ответа сервера HTTP/1.1 200 OK. В теле ответа будут переданные данные созданного платежа в формате JSON.

Обратите внимание. Платеж создается в статусе not paid. Срок жизни неоплаченного платежа - 90 дней.

Параметры в теле ответа

payment_url
string
required
Ссылка на платежную форму
. Включает в себя дополнительный GET-параметр:
  • lang - код языка интерфейса платежной формы, например, en_EN, es_MX. Если в запросе был передан корректный код языка в поле locale, то он будет сохранен в платеже и возвращен в этом параметре.
Обратите внимание, платежная форма может открыться на языке по умолчанию, если язык, код которого сохранен в платеже, не подключен. Обратитесь к службу поддержки для решения ситуации.

Ссылка действует в течение жизни платежа (90 дней) или до тех пор, пока платеж не будет оплачен. Если платеж оплачен - повторная оплата того же платежа невозможна.

При работе с тестовой средой в ответе будет возвращена ссылка на платежную форму для тестовой среды (ссылка будет иметь суффикс .demoslweb.com).
order_id
number
required
Уникальный идентификатор платежа на стороне Softline Payments.

Пример положительного ответа

{
  "payment_url": "https://.../order/status/[order_id]/[hash]?lang=[local]",
  "order_id": 123456
}

Ответ об ошибке

В случае ошибки при обработке запроса вы получите код ответа сервера, соответствующий результату обработки.
В зависимости от кода в теле ответа могут присутствовать дополнительные параметры.

Справочник HTTP-кодов ответа сервера при ошибке

Код ответа сервера Описание
HTTP/1.1 400 Bad Request Запрос не валиден (ошибка в параметрах; не переданы необходимые данные и т.п.).
В теле ответа будет передан дополнительный код ошибки (один или несколько).
HTTP/1.1 401 Unauthorized Неуспешная аутентификация.
В теле ответа будет передан дополнительный код ошибки (один или несколько). 
HTTP/1.1 404 Not found Неверный URL запроса. Проверьте адрес запроса.
HTTP/1.1 500 Request Error Ошибка на стороне сервера. Повторите запрос позднее или обратитесь в службу поддержки.

Справочник дополнительных кодов ошибок для HTTP 400

Error Message Описание
Если хотя бы одна ошибка из списка ниже найдена, то она возвращается в ответе на запрос, остальные ошибки не проверяются.
110 JSON is not valid. Платеж не может быть создан. Структура полей запроса не валидна. Проверьте поля в теле запроса на соответствие формату JSON.
111 Invalid data format (Content-type). Платеж не может быть создан. Неправильный заголовок запроса. Content-type должен быть равен application/json.
6000 Unable to generate payment. Please contact technical support. Платеж не может быть создан.
В том числе, если переданная валюта (currency) не доступна для использования.
Обратитесь в поддержку.
Если хотя бы одна ошибка из списка ниже найдена, то проверка запроса не прерывается. В ответе может быть возвращено несколько ошибок.
6010 Invalid field value: [наименование параметра] Запрос не валиден, например, не заполнен обязательный параметр, передано неверное название параметра, тип или формат значения параметра неверны.
В том числе ошибка будет возвращена, если в параметре передано null, и этот вариант значения не указан как допустимый.
6020 Locale not found. Платеж не может быть создан. Переданный язык интерфейса платежной формы (locale) не найден.
6030 Сreation of zero-amount payments is not available. Enable recurring_indicator = true or set the amount strictly greater than zero. Платеж не может быть создан. Переданная сумма платежа (amount) не соответствует требованиям. Вы можете передать сумму платежа равную нулю, только при регистрации родительского платежа ("recurring_indicator":true).
6060 Email field is filled out incorrectly. Expected format: [name]@[domain].[zone] Платеж не может быть создан. Передан некорректный email адрес (customer.email).
6080 This payment method is not available. Change payment method (payment_method). Платеж не может быть создан. Переданный метод оплаты (payment_method) не доступен. В том числе в ситуации, когда оплата выбранным платежным методом доступна только для юридических лиц, в запросе не передано название компании покупателя (customer.company_name).
6090 This payment method is not available for this payment amount. Change payment method (payment_method). Платеж не может быть создан.
Переданный метод оплаты (payment_method) не доступен для переданной суммы платежа (amount).
6100 This payment method does not support recurring payments. Change payment method (payment_method). Платеж не может быть создан. В запросе передан признак для регистрации родительского платежа ("recurring_indicator":true), но переданный метод оплаты (payment_method) не поддерживает автоплатежи. Измените код платежного метода.

Справочник дополнительных кодов ошибок для HTTP 401

Справочник этих ошибок одинаковый для всех API, которые используют авторизацию по токену.

Параметры в теле ответа

errors
array [objects]
required
Список ошибок.
errors / [error object]
/
error
number
required
Код ошибки.
errors / [error object]
/
message
string
Описание ошибки.

Пример ответа об ошибке

{
  "errors": [
    {
      "error": 63010,
      "message": "Invalid field value: currency." 
    },
    {
      "error": 6010,
      "message": "Invalid field value: amount." 
    }
  ]
}
Политика конфиденциальности
© 2024 Softline