Возврат средств после оплаты

Возвратом в рамках платежной платформы PSPHost считается перевод пользователю средств, ранее списанных при проведении оплаты. Если средства были не списаны, а, например заблокированы, то возвращение пользователю доступа к этим средствам выполняется в платформе через операцию отмены блокировки, а не операцию возврата (подробнее — Оплата в две стадии).

Платежная платформа поддерживает возвраты через Gate или через Dashboard. В этом разделе представлена информация о возврате через Gate. Общие сведения актуальны при использовании как платежных карт, так и других платежных инструментов, а техническая информация актуальна только для работы с картами. Техническая информация о возврате средств при использовании других платежных инструментов представлена в разделе Альтернативные платежные методы.

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

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

Чтобы инициировать возврат при работе через Gate, стороны веб-сервиса необходимо отправить запрос к конечной точке /v2/payment/{название метода}/refund. При этом следует учитывать особенности и ограничения, перечисленные далее в соответствующих разделах.

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

• reversal, если возврат инициируется до закрытия операционного дня и на всю сумму оплаты;
• refund, если возврат инициируется до закрытия операционного дня и на часть суммы оплаты или после закрытия операционного дня вне зависимости от суммы.

Исключением является возврат после оплаты, проведенной с использованием карты платежной системы Visa или American Express. Для выполнения такого возврата в зависимости от того, когда он инициируется, и вне зависимости от суммы формируется одна из следующих операций:

• reversal, если возврат инициируется до закрытия операционного дня;
• refund, если возврат инициируется после закрытия операционного дня.

Таким образом, возврат инициируется одним запросом и может выполняться для двух типов платежей — разовых и повторяемых оплат — с помощью одной из двух операций: refund или reversal.

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

• success — платеж проведен, возврат для платежа не выполнен;
• reversed — до закрытия операционного дня для платежа выполнен возврат всей суммы;
• refunded — после закрытия операционного дня для платежа выполнен возврат всей суммы;
• partially reversed — до закрытия операционного дня для платежа выполнен возврат части суммы (только для карт платежных систем Visa и American Express);
• partially refunded — для платежа выполнен возврат части суммы (для карт платежных систем Visa и American Express — после закрытия операционного дня);
• scheduled recurring processing — для повторяемой оплаты выполнен возврат всей суммы или части суммы, при этом ожидаются дальнейшие списания средств в рамках этой оплаты.

Особенности

Срок выполнения возврата, как правило, зависит от банка-эмитента или платежного провайдера, выполняющего операцию, и может занять длительное время.

При выполнении возврата изменяются данные о сумме платежа. В оповещении о результате возврата указывается актуальная сумма платежа, доступная для дальнейших возвратов. Актуальная сумма платежа рассчитывается как разница между исходной суммой платежа и суммой, возвращенной пользователю. Допустим, исходная сумма равна 13,70 долларов США. Тогда при возврате на сумму 10,00 долларов актуальная сумма платежа принимает значение 3,70 долларов, а при еще одном возврате на сумму 3,70 долларов — 0,00 долларов. Это правило справедливо в том числе для регулярных оплат, при которых актуальную сумму платежа составляют суммы всех списаний в рамках этого платежа за вычетом суммы всех выполненных возвратов.

В то же время для разовых оплат, в рамках которых выполнено несколько платежных операций, сумма платежа, доступная для дальнейших возвратов, может отличаться от суммы платежа, передаваемой в оповещении. Поэтому для оповещений о результатах таких оплат введен дополнительный параметр, в котором указывается сумма, доступная для дальнейших возвратов — remaining_refund. Подробная информация о таких оплатах представлена в разделе Разбиение суммы платежа.

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

Ограничения

Выполнение возвратов возможно с учетом следующих ограничений:

• В рамках оплаты, для которой выполняется возврат, должно быть выполнено хотя бы одно списание средств пользователя, при этом самой оплате должен соответствовать один из следующих статусов: success, partially paid, sсheduled recurring processing или partially refunded.

  Если в рамках оплаты не выполнено ни одного успешного списания или статус оплаты не соответствует ни одному из перечисленных, то запрос на возврат отклоняется и к веб-сервису направляется оповещение с кодом ошибки, например 3081.

• Валюта возврата должна соответствовать валюте оплаты, для которой выполняется возврат.

  Если в запросе передана валюта, не соответствующая валюте оплаты, то запрос на возврат отклоняется и к веб-сервису направляется оповещение с кодом ошибки 3284 (подробнее о таких кодах — в разделе Статусы операций и коды ответов).

• Должна соблюдаться допустимая частота отправки запросов.

  Если повторный запрос на возврат отправлен ранее, чем через две минуты, то этот запрос отклоняется и к веб-сервису направляется оповещение с кодом ошибки 3285.

• Остаток средств на счете мерчанта должен быть достаточным для выполнения возврата.

  Информацию об остатке средств можно получить с помощью запроса через Data API (Использование Data API) или в Dashboard (раздел Контроль балансов), а также при обращении к курирующему менеджеру PSPHost.

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

  Например, для одной оплаты, осуществляемой на территории Белоруссии или с использованием платежной карты этой страны, допускается только один возврат. Информацию о специфике выполнения возвратов в зависимости от используемого платежного метода можно получить в разделе Альтернативные платежные методы и при обращении к курирующему менеджеру PSPHost.

• Оплата, для которой выполняется возврат, не должна быть оспариваемой.

  Если для оплаты начался процесс опротестования, то запрос на возврат отклоняется и к веб-сервису направляется оповещение с кодом ошибки 3288.

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

• При проведении частичного возврата его сумма не должна превышать актуальную сумму платежа, иначе запрос на возврат отклоняется и к веб-сервису направляется оповещение с кодом ошибки 3283.
• Инициировать новый частичный возврат можно только после выполнения предыдущего, иначе запрос на возврат отклоняется и к веб-сервису направляется оповещение с кодом ошибки 3285.

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

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

Формат запроса на возврат соответствует описанному в разделе Общий порядок интеграции, конечной точкой API для этого запроса выступает /v2/payment/card/refund, а в теле запроса должны использоваться следующие объекты и параметры:

• general — объект, содержащий основные идентификационные сведения запроса:
  • project_id — идентификатор проекта, полученный от PSPHost при интеграции;
  • payment_id — идентификатор платежа, для которого необходимо выполнить возврат;
  • signature — подпись к данным запроса, составленная после указания целевых параметров (подробнее — в разделе Подписывание и проверка подписи).
• payment — объект, содержащий сведения о платеже:
  • description — описание причины возврата; относится только к операции возврата и не меняет описание оплаты, если оно было передано ранее.

Перечисленных параметров достаточно для возврата пользователю всей суммы платежа. Чтобы возвратить часть суммы, в объекте payment дополнительно необходимо использовать следующие параметры:

• amount — сумма возврата, не превышающая актуальную сумму платежа, в дробных единицах валюты;
• currency — код валюты возврата в формате ISO-4217 alpha-3; указываемая валюта должна быть той же, что и валюта платежа.

Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

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

{
  "general": {
    "project_id": 239,
    "payment_id": "payment2",
    "signature": "of8k9xeKJ7KLTZYO56lCv+f1M0Sf/7eg=="
  },
  "payment": {
    "description": "refund",
// При частичном возврате:
    "amount": 1000,
    "currency": "USD"
  }
}

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

Формат оповещения о результате возврата соответствует описанному в разделе Оповещения (callbacks) в Gate. Информация об актуальной сумме платежа содержится в объекте payment, а о сумме, возвращенной пользователю, — в объекте operation. Также оповещение может содержать описание причины возврата в объекте operation_description, если это было настроено специалистами технической поддержки по запросу мерчанта.

Далее представлены примеры информации из оповещений о полном и частичном возврате для разовой оплаты на исходную сумму 13,70 USD:

1. на сумму 10,00 USD, при этом актуальная сумма платежа равна 3,70 USD, а статус платежа соответствует partially refunded;
2. на сумму 13,70 USD, при этом актуальная сумма платежа равна 0,00 USD, а статус платежа соответствует refunded.

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

{ 
  "project_id":239,
  "payment":{ 
    "id":"payment2",
    "type":"purchase", // Тип платежа — разовая оплата
    "status":"partially refunded", // Статус платежа после частичного возврата
    "date":"2019-11-13T14:52:14+0000",
    "method":"card",
    "sum":{ 
      "amount":370, // Актуальная сумма платежа
      "currency":"USD" // Код валюты платежа
    },
    "description":"Tai massage session" // Описание оплаты
  },
  "account":{ 
    "number":"424242******4243",
    "type":"visa",
    "card_holder":"JUDY DOE",
    "expiry_month":"03",
    "expiry_year":"2023"
  },
  "operation_description":"Deficient service", // Описание причины возврата
  "operation":{ 
    "id":3862,
    "type":"refund", // Тип операции
    "status":"success", // Статус операции
    "date":"2019-11-13T14:52:15+0000",
    "created_date":"2019-11-13T14:52:12+0000",
    "request_id":"0c4457b5fe8dada59-e7b58eceb8aecfa791-00049391",
    "sum_initial":{ 
      "amount":1000, // Сумма возврата
      "currency":"USD" // Код валюты возврата (в соответствии с валютой платежа)
    },
    "sum_converted":{ 
      "amount":1000,
      "currency":"USD"
    },
    "code":"0",
    "message":"Success",
    "provider":{ 
      "id":414,
      "payment_id":"",
      "endpoint_id":414
    }
  },
  "signature":"of8k9xerKSK4XL1QFaDH3p9Mh0CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg=="
}

{ 
  "project_id":239,
  "payment":{
    "id":"payment2",
    "type":"purchase", // Тип платежа — разовая оплата
    "status":"refunded", // Статус платежа после полного возврата
    "date":"2019-11-13T13:52:09+0000",
    "method":"card",
    "sum":{ 
      "amount":0, // Актуальная сумма платежа
      "currency":"USD" // Валюта платежа
    },
    "description":"Tai massage session" // Описание оплаты
  },
  "account":{
    "number":"424242******4243",
    "token":"14c24c8a5384b413f11b2956a82ddaeea609ea49",
    "type":"visa",
    "card_holder":"JUDY DOE",
    "expiry_month":"03",
    "expiry_year":"2023"
  },
  "customer":{
    "id":"1478"
  },
  "operation_description":"Service cancellation", // Описание причины возврата
  "operation":{
    "id":3861,
    "type":"refund", // Тип операции
    "status":"success", // Статус операции
    "date":"2019-11-13T13:52:09+0000",
    "created_date":"2019-11-13T13:52:08+0000",
    "request_id":"67a97cd6b14f1aa0543c81e18cd270b66-aadc6e790206d5-00038611",
    "sum_initial":{ 
      "amount":1370, // Сумма возврата
      "currency":"USD" // Код валюты возврата (в соответствии с валютой платежа)
    },
    "sum_converted":{
      "amount":1370,
      "currency":"USD"
    },
    "code":"0",
    "message":"Success",
    "provider":{
      "id":414,
      "payment_id":"",
      "endpoint_id":414
    }
  },
  "signature":"of8k9xerKSK4XL1QFaDH3p9Mh0CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg=="
}

В следующем примере содержится информация о том, что для повторяемой оплаты с суммой всех списаний, равной 7,99 EUR, выполнен возврат на сумму 7,99 EUR и до выполнения следующего списания актуальная сумма платежа равна 0,00 EUR. Статус платежа в данном случае не изменился, так как в рамках этого платежа ожидаются дальнейшие списания (подробнее о статусах — в разделе Типы платежей, операции и платежи).

{ 
  "project_id":239,
  "payment":{ 
    "id":"payment3",
    "type":"recurring", // Тип платежа — повторяемая оплата
    "status":"scheduled recurring processing", // Статус платежа после возврата
    "date":"2019-11-13T17:23:26+0000",
    "method":"card",
    "sum":{ 
      "amount":0, // Актуальная сумма платежа
      "currency":"EUR" // Валюта платежа
    },
  },
  "account":{ 
    "number":"424242******4243",
    "token":"14c24c8a5384b413f11b2956a82ddaeea609ea49",
    "type":"visa",
    "card_holder":"JUDY DOE",
    "expiry_month":"03",
    "expiry_year":"2023"
  },
  "customer":{ 
    "id":"1478"
  },
  "recurring":{ 
    "id":1061,
    "currency":"EUR",
    "valid_thru":"2027-05-31T00:00:00+0000"
  },
  "operation_description":"Refund for payment3 order", // Описание причины возврата
  "operation":{ 
    "id":3861,
    "type":"refund", // Тип операции
    "status":"success", // Статус операции при успешном возврате
    "date":"2019-11-13T17:23:26+0000",
    "created_date":"2019-11-13T17:23:25+0000",
    "request_id":"bb36c8b4bce2c4-0198d59676189b0e344d1-00056689",
    "sum_initial":{ 
      "amount":799, // Сумма возврата
      "currency":"EUR" // Код валюты возврата (в соответствии с валютой платежа)
    },
    "sum_converted":{ 
      "amount":799,
      "currency":"EUR"
    },
    "code":"0",
    "message":"Success",
    "provider":{ 
      "id":414,
      "payment_id":"",
      "endpoint_id":6
    }
  },
  "signature":"of8k9xerKSK4XL1QFaDH3p9Mh0CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg=="
}

В следующем примере содержится информация о том, что для разовой оплаты отклонен возврат на сумму 60,00 USD в связи с нехваткой средств на счете мерчанта, о чем свидетельствует код ошибки 3028 (подробнее о таких кодах — в разделе Статусы операций и коды ответов). Сумма и статус платежа в данном случае не изменились.

{ 
  "project_id":239,
  "payment":{ 
    "id":"payment7",
    "type":"purchase", // Тип платежа — разовая оплата
    "status":"success", // Статус платежа при отказе в возврате
    "date":"2019-12-29T15:29:47+0000",
    "method":"card",
    "sum":{ 
      "amount":6000, // Сумма платежа
      "currency":"USD" // Валюта платежа
    },
  },
  "account":{ 
    "number":"424242******4243",
    "token":"14c24c8a5384b413f11b2956a82ddaeea609ea49",
    "type":"visa",
    "card_holder":"JUDY DOE",
    "expiry_month":"03",
    "expiry_year":"2023"
  },
  "operation_description":"Error", // Описание причины возврата
  "operation":{ 
    "id":3869,
    "type":"reversal", // Тип операции
    "status":"decline", // Статус операции при отказе в возврате
    "date":"2019-12-29T15:32:29+0000",
    "created_date":"2019-12-29T15:32:29+0000",
    "request_id":"713446e4b43-06bfc7eed42c4c854697846a-00059692",
    "sum_initial":{ 
      "amount":6000, // Сумма возврата
      "currency":"USD" // Код валюты возврата (в соответствии с валютой платежа)
    },
    "sum_converted":{ 
      "amount":6000,
      "currency":"USD"
    },
    "code":"3028", // Код ошибки
    "message":"Insufficient funds on merchant balance", // Описание ошибки
    "provider":{ 
      "id":120,
      "payment_id":"",
      "endpoint_id":120
    }
  },
  "signature":"of8k9xerKSK4XL1QFaDH3p9Mh0CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg=="
}

Дополнительные материалы

При работе с возвратами также могут быть полезны следующие материалы:

• Типы платежей, операции и платежи — раздел с общей информацией о типах поддерживаемых платежей и операций, а также об их возможных статусах.
• Альтернативные платежные методы — раздел с подробной информацией о проведении платежей с использованием различных платежных методов.
• Оповещения (callbacks) в Gate — раздел с информацией об оповещениях и работе с ними.
• Статусы операций и коды ответов— раздел с информацией о кодах ошибок, используемых в платежной платформе.
• Контроль и проведение платежей — раздел с информацией о проведении платежей и операций через Dashboard.