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

Общая информация

Повторяемая оплата со списаниями по запросам — это тип платежа, в рамках которого на основании одного исходного запроса осуществляется один (повторяемый) перевод денежных средств от пользователя к мерчанту с использованием сохранённых платёжных данных и без подтверждения подлинности платёжного инструмента пользователя (такого, как ввод кода проверки подлинности карты).

Повторяемые оплаты со списаниями по запросам могут проводиться при выполнении одного из следующих условий:

• если эти оплаты были изначально зарегистрированы на стороне платёжной платформы (подробнее);
• если информация об этих оплатах была перенесена в платформу от другого эквайера (подробнее);
• если информация об этих оплатах не была перенесена в платформу, но их проведение согласовано с курирующим менеджером Ecommpay и настроено в рамках используемого проекта.

Оплаты со списаниями по запросам проводятся в платёжной платформе Ecommpay в соответствии с моделью проведения платежей (подробнее) и представленной в этой статье схемой. При этом для оплат, зарегистрированных вне платформы Ecommpay, не актуальны условия и шаги, касающиеся регистрации. И, кроме того, для оплат, которые регистрировались вне платформы и информация о которых не была импортирована в платформу, актуально следующее:

• Если для какого-либо проекта подключена возможность проводить такие оплаты, в рамках этого же проекта исключается проведение других повторяемых оплат (зарегистрированных в платформе или перенесённых в неё).
• При использовании платёжных карт, выпущенных в Европейской экономической зоне, ответственность за регистрацию повторяемой оплаты с соблюдением требований второй директивы Европейского союза об оказании платёжных услуг (PSD2) к аутентификации покупателей (Strong Customer Authentication, SCA) возлагается на мерчанта.

Схема проведения

Для проведения повторяемой оплаты со списаниями по запросам необходимо:

1. Зарегистрировать повторяемую оплату.
2. Передать запрос на проведение повторяемой оплаты с идентификатором записи о серии списаний.
3. Принять от платёжной платформы оповещение о результате списания.

Для каждого последующего списания необходимо повторно передавать запросы на проведение повторяемой оплаты и принимать оповещения о результате.

Информация о форматах запросов и оповещений приведена далее; общая информация о работе с API — в разделе Организация взаимодействия. Информацию о возможных статусах такой оплаты можно найти в соответствующей статье.

Формат запроса

Формат запросов в этом разделе представлен для инициирования повторяемых оплат со списаниями по запросу с использованием платёжных карт. При формировании запросов необходимо учитывать следующее:

1. Должен использоваться POST-запрос к одной из следующих конечных точек:
   • /v2/payment/card/recurring — для всех категорий повторяемых оплат, которые были изначально зарегистрированы в платформе Ecommpay или информация о которых была перенесена в платформу, вне зависимости от места хранения платёжных данных (на стороне платёжной платформы или на стороне веб-сервиса);
   • /v2/payment/card/sale — для повторяемых оплат при хранении платёжных данных на стороне веб-сервиса, вне зависимости от того, где была зарегистрирована оплата;
   • /v2/payment/card/auth — только для автооплат и регулярных оплат при хранении платёжных данных на стороне веб-сервиса, вне зависимости от того, где была зарегистрирована оплата;
   • /v2/payment/card/account_verification/token — только для автооплат, которые были изначально зарегистрированы в платформе Ecommpay или информация о которых была перенесена в платформу, при хранении платёжных данных на стороне веб-сервиса.
2. В запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от Ecommpay при интеграции;
     • payment_id — идентификатор платежа, уникальный в рамках проекта;
     • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).
   • customer — объект, содержащий сведения о пользователе:
     • ip_address — IP-адрес пользователя, актуальный для инициируемой операции;
     • id — идентификатор пользователя, уникальный в рамках проекта и имеющий то же значение, которое было использовано при регистрации данной повторяемой оплаты;
       Внимание: Использование разных идентификаторов пользователя для операций в рамках одной повторяемой оплаты не допускается.
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;
     • currency — валюта платежа в формате ISO-4217 alpha-3.
     • cryptocurrency_type — указатель категории цифровой валюты, обязательный при выполнении операций, связанных с использованием криптовалют через платёжные системы Mastercard и Visa, и допускающий одно из следующих значений:
       • cbdc — цифровая валюта центрального банка или токенизированный депозит, выпущенные определённым государством;
       • stablecoins_fiat_backed — цифровая валюта (в виде стейблкоина), чья стабильность обеспечивается за счёт резервов в определённой фиатной валюте;
       • native_tokens — цифровая валюта определённого блокчейна, необходимая для выполнения операций в его сети, в том числе для оплаты комиссий;
       • other — нефиатная валюта, которая заведомо не относится ни к одной из других категорий либо не может быть отнесена ни к одной из категорий при инициировании операции.
3. В зависимости от конечной точки, к которой направляется запрос, в запросе также должны использоваться следующие объекты и параметры:
   • В запросах к конечной точке /v2/payment/card/recurring — идентификатор записи о серии списаний, полученный в оповещении с данными о регистрации, в параметре id объекта recurring.
   • В запросах к конечным точкам /v2/payment/card/sale и /v2/payment/card/auth — объект card со следующими параметрами:
     • pan — номер карты, который должен указываться в соответствии с написанием непосредственно на карте, без пробелов и других разделительных знаков.
     • year — порядковый номер года, в котором заканчивается срок действия карты (в четырёхзначном формате YYYY по григорианскому календарю).
     • month — порядковый номер месяца, в котором заканчивается срок действия карты (в виде числа, без ведущего нуля).
     • card_holder — имя держателя карты, которое должно указываться в соответствии с написанием непосредственно на карте и может быть исключено из числа обязательных параметров только по согласованию с курирующим менеджером Ecommpay после анализа и оценки рисков.
     • stored_card_type — указатель категории, к которой относится целевая повторяемая оплата (4 для автооплаты и 6 для регулярной оплаты).
     • scheme_id — специализированный идентификатор операции, в рамках которой была зарегистрирована целевая повторяемая оплата, на стороне международной платёжной системы. Этот идентификатор формируется непосредственно в платёжной системе и используется в ней для сквозного контроля действий по повторяемой оплате. Он обязателен для карт, которые выпущены в Европейской экономической зоне и относятся к платёжной системе Mastercard или Visa, но при его наличии может указываться и в других случаях.

       При регистрации и последующем проведении повторяемых оплат через платёжную платформу Ecommpay значения этого идентификатора автоматически сохраняются в платформе и используются во взаимодействиях с платёжными системами. В таких случаях scheme_id со стороны мерчанта можно не указывать. Вместе с тем, если повторяемая оплата была зарегистрирована через одного эквайера, а списание по ней инициируется через другого, этот идентификатор является обязательным для карт, выпущенных в Европейской экономической зоне. В таких случаях он должен указываться в запросах со стороны мерчанта — в полном соответствии со значением, полученным от эквайера при регистрации повторяемой оплаты.

     • transaction_link_id — специализированный идентификатор серии списаний, выполняемой в рамках повторяемой оплаты, на стороне международной платёжной системы. Этот идентификатор формируется непосредственно в платёжной системе и используется в ней для сквозного контроля действий по серии списаний. Он применим при проведении оплат с использованием карт платёжной системы Mastercard, для которых определяется как Transaction Link Identifier (TLID).

       При регистрации и последующем проведении повторяемых оплат через платёжную платформу Ecommpay значения этого идентификатора автоматически сохраняются в платформе и используются во взаимодействиях с платёжной системой Mastercard. Вместе с тем, если повторяемая оплата была зарегистрирована через одного эквайера, а списание по ней инициируется через другого, этот идентификатор должен указываться в запросах со стороны мерчанта — в полном соответствии со значением, полученным от эквайера. Начиная с 23 октября 2026 года это становится обязательным для всех карт платёжной системы Mastercard.

   • В запросах к конечной точке /v2/payment/card/account_verification/token — параметр stored_card_type объекта card со значением 4 (автооплата).
4. Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

Таким образом, корректный запрос должен содержать идентификаторы проекта и платежа, подпись, IP-адрес пользователя, валюту и сумму проведения платежа, идентификатор записи о серии списаний или данные платёжной карты и указатель категории повторяемой оплаты, а так же идентификатор связи операций при использовании платёжной системы Mastercard.

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

{  
  "general":{  
    "project_id":42,
    "payment_id":"456789",
    "signature":"v7KNMp5D/aZAeb0VMdeR+CqGSm...=="
  },
  "customer":{  
    "ip_address":"202.144.196.0",
    "id":"customer_12"
  },
  "payment":{  
    "amount":400,
    "currency":"USD"
  },
  "recurring":{
    "id":1079    // Идентификатор записи о серии списаний
  }
}

{  
  "general":{
    "project_id":42,
    "payment_id":"456789",
    "signature":"v7KftZ5D/aZAdeR+qGrNxY...=="
  },
  "customer":{
    "ip_address":"202.144.196.0",
    "id":"customer_12"
  },
  "payment":{
    "amount":400,
    "currency":"USD"
  },
  "card": {
    "pan": "4314220000000056",
    "year": 2025,
    "month": 8,
    "card_holder": "JOHN SMITH",
    "stored_card_type": 4,    // Проведение автооплаты
    "scheme_id": "MDS60JXCH0209",
    "transaction_link_id": "a7F9k3L2-Q8vB6pT1_WzYc"
  }
}

{  
  "general":{
    "project_id":42,
    "payment_id":"456789",
    "signature":"v7KftZ5D/aZAdeR+qGrNxY...=="
  },
  "customer":{
    "ip_address":"202.144.196.0",
    "id":"customer_12"
  },
  "payment":{
    "amount":400,
    "currency":"USD"
  },
  "token":"pkmawa3khb7wninntq8g8q3592fjjxwvzfebwbegqkl1c16akpgo6sgxac6wulz7",
  "card":{
    "stored_card_type": 4    // Проведение автооплаты
  }
}

Формат оповещений

Информация о результатах проведения повторяемых оплат передаётся от платёжной платформы к веб-сервису в виде оповещений о каждом выполняемом списании. Для оповещений в таких случаях используется типовой формат, описание которого представлено в статье Работа с оповещениями. При этом в состав оповещений можно включить соответствующие идентификаторы на стороне международных платёжных систем — в параметрах scheme_id и transaction_link_id. Для этого необходимо обратиться к специалистам технической поддержки Ecommpay.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 42 было выполнено списание в размере 4,00 USD с платёжной карты № 424242******4243.

{  
  "project_id":42,
  "payment":{  
    "id":"456789",
    "type":"recurring",
    "status":"success",
    "date":"2019-09-04T12:57:57+0000",
    "method":"card",
    "sum":{  
      "amount":400,
      "currency":"USD"
    },
    "description":""
  },
  "account":{  
    "number":"431422******0056",
    "type":"visa",
    "card_holder":"JUDY DOE",
    "id":45678,
    "expiry_month":"08",
    "expiry_year":"2025"
  },
  "recurring":{  
    "id":1079,
    "currency":"USD",
    "valid_thru":"2022-10-31T00:00:00+0000"
  },
  "operation":{  
    "id":39690002636,
    "type":"recurring",
    "status":"success",
    "date":"2019-09-04T12:57:57+0000",
    "created_date":"2019-09-04T12:57:53+0000",
    "request_id":"0b9f9e57a50-61da119c",
    "sum_initial":{  
      "amount":400,
      "currency":"USD"
    },
    "sum_converted":{  
      "amount":400,
      "currency":"USD"
    },
    "provider":{  
      "id":414,
      "payment_id":"0020000000072964",
      "date":"2019-09-04T12:58:03+0000",
      "auth_code":"634R",
      "endpoint_id":414
    },
    "code":"0",
    "message":"Success"
  },
  "scheme_id": "MCS38A0790706",
  "signature":"MpfogAxZ5D/b0VMdeR+xYyilUwSm...=="
}