Хоствана страница за плащане (HPP)
Приемайте плащания чрез хостваната страница за плащане на Cost+
Хостваната страница за плащане (HPP) е PCI DSS съвместимият формуляр за плащане на Cost+. Тя ви позволява да приемате плащания, без да обработвате чувствителни данни от карти на собствените си сървъри. Създавате поръчка чрез API-то, пренасочвате клиента към хостваната страница и той се връща на вашия сайт след плащането.
Как работи
- Вашият сървър създава поръчка, като извиква POST /v1/orders/.
- API-то връща URL, сочещ към хостваната страница за плащане.
- Вие пренасочвате клиента към страницата за плащане.
- Клиентът завършва плащането на хостваната страница на Cost+.
- Клиентът се пренасочва обратно към вашия
return_url(илиfailure_urlза неуспешни плащания). - Cost+ изпраща уебхук известие към вашия
webhook_urlсъс статуса на поръчката.
Хостваната страница за плащане е напълно PCI DSS съвместима. Никога не се налага да обработвате сурови номера на карти или чувствителни данни за плащане на вашите сървъри.
Създаване на поръчка
Има два подхода за използване на HPP:
Подход 1: Показване на всички методи на плащане (Най-простият)
Създайте поръчка без да посочвате transactions. Отговорът включва order_url — клиентът се пренасочва там и вижда всички активирани методи на плащане за вашия акаунт:
{
"currency": "EUR",
"amount": 1295,
"merchant_order_id": "my-order-id-1",
"description": "My amazing order",
"return_url": "https://www.example.com",
"webhook_url": "https://www.example.com/webhook"
}{
"id": "43114fde-da30-4115-8004-b7f808f9b25c",
"status": "new",
"currency": "EUR",
"amount": 1295,
"order_url": "https://api.costplus.online/pay/43114fde.../select-payment-method/",
"return_url": "https://www.example.com",
"webhook_url": "https://www.example.com/webhook"
}Пренасочете клиента към order_url. На хостваната страница се показват всички активирани методи на плащане.
Подход 2: Предварителен избор на методи на плащане
Създайте поръчка с масив transactions, за да контролирате кои методи на плащане се показват и в какъв ред. Всяка транзакция включва payment_method, а отговорът връща payment_url вътре в обекта на транзакцията:
{
"currency": "EUR",
"amount": 1295,
"merchant_order_id": "my-order-id-1",
"description": "My amazing order",
"return_url": "https://www.example.com",
"webhook_url": "https://www.example.com/webhook",
"transactions": [
{ "payment_method": "credit-card" }
]
}{
"id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
"status": "new",
"currency": "EUR",
"amount": 1295,
"transactions": [
{
"id": "d291f03f-a406-428a-967a-4895a46e03fd",
"payment_method": "credit-card",
"status": "new",
"payment_url": "https://api.costplus.online/pay/4851e31c.../select-payment-method/credit-card/d291f03f.../"
}
]
}Пренасочете клиента към payment_url от транзакцията.
Ако предоставите само един запис в масива transactions, клиентът се отвежда директно към този метод на плащане без да вижда екран за избор. Масивът flags съдържа "is-test" при използване на sandbox API ключ.
Полета на заявката
| Поле | Задължително | Описание |
|---|---|---|
currency | Да | ISO 4217 валутен код (напр. EUR, GBP, SEK) |
amount | да | Сума в ISO 4217 второстепенна единица на валутата. Например 12,95 EUR е представен като 1295 |
merchant_order_id | Не | Ваш собствен референтен идентификатор за поръчката |
return_url | Не | URL за пренасочване на клиента след плащане (по подразбиране за всички статуси) |
failure_url | Не | URL за пренасочване на клиента при статус cancelled, expired или error (вижте URL адреси за връщане по-долу) |
locale | Не | Език за страницата за плащане. Поддържани: en-GB, de-DE, nl-NL, nl-BE, fr-BE, sv-SE, no-NO, da-DK |
description | Не | Описание на поръчката, показвано на клиента |
payment_methods | не | Филтрирайте до един метод на плащане (напр. ["credit-card"]). Пропуснете, за да покажете всички разрешени методи. За множество специфични методи използвайте вместо това масива transactions |
webhook_url | Не | URL за получаване на известия при промяна на статуса |
expiration_period | Не | ISO 8601 продължителност за изтичане на поръчката. По подразбиране е PT30M (30 минути) |
Полето amount винаги е цяло число във второстепенната единица ISO 4217 на валутата. За EUR 1295 означава 12,95 EUR; валутите с нулева и три десетична запетая използват собствен експонент ISO 4217. Предаването на десетична стойност като 1295.00 или 12.95 ще доведе до грешка или неправилно таксуване.
Множество методи на плащане
Има два начина да контролирате кои методи на плащане да се показват на хостваната страница:
Опция A — payment_methods (единичен филтър). Предавайте едноелементен масив, за да ограничите поръчката до един метод на плащане. Пропуснете изцяло полето, за да покажете всички методи, активирани за вашия акаунт.
Опция B — масив transactions (препоръчва се за множество методи). Добавете по един запис за метод на плащане. Всяка транзакция получава свой собствен payment_url и методите се появяват в ред на масив на хостваната страница:
"transactions": [
{ "payment_method": "credit-card" },
{ "payment_method": "apple-pay" }
]Полето payment_methods на поръчки приема най-много една стойност. За да предложите множество специфични методи, винаги използвайте масива transactions. Ако имате нужда от връзка за многократна употреба с множество методи на плащане, помислете вместо това за Връзки за плащане, които поддържат истински масив payment_methods.
URL адреси за връщане
След плащането клиентът се пренасочва в зависимост от статуса на поръчката и кои URL адреси сте предоставили:
-
Когато и
return_url, иfailure_urlса зададени:cancelled,expiredилиerror→ клиентът се пренасочва къмfailure_url- Всички други статуси → клиентът се пренасочва към
return_url
-
Когато е зададен само
return_url:- Всички статуси → клиентът се пренасочва към
return_url
- Всички статуси → клиентът се пренасочва към
Използвайте failure_url, за да покажете страница за повторен опит или поддръжка при неуспешни плащания, докато return_url показва потвърждение на поръчката. Ако се нуждаете само от една дестинация, само return_url е достатъчен.
Поведение на бутона за отказ
Хостваната страница за плащане включва бутон за отказ. Когато клиентът кликне върху него, той се пренасочва към failure_url (ако е предоставен) или return_url. Статусът на поръчката ще се промени на cancelled. Винаги проверявайте статуса на поръчката чрез API-то или уебхукове, вместо да разчитате само на пренасочването.
Свързани крайни точки
- Създаване на поръчка — създайте поръчка за плащане и получете
payment_url - Получаване на поръчка — проверете статуса на поръчката след плащане