Бързо начало
Приемете първото си плащане за 5 минути
Това ръководство ви води през създаването и завършването на тестово плащане чрез API на Cost+. В края ще имате работеща интеграция, върху която можете да надграждате.
Предварителни изисквания
- Акаунт в Cost+ със sandbox уебсайт — създайте го в портала на търговеца
- Вашият sandbox API ключ (намира се в Уебсайтове → вашият sandbox уебсайт → Интеграция)
Не сте сигурни как да получите вашия API ключ? Вижте Тестване на интеграцията за подробни инструкции за настройка.
Стъпка 1: Създаване на поръчка
Изпратете POST заявка за създаване на поръчка за плащане. Заменете YOUR_API_KEY с вашия sandbox API ключ:
curl -X POST https://api.costplus.online/v1/orders/ \
-u YOUR_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"currency": "EUR",
"amount": 1295,
"merchant_order_id": "my-first-order",
"description": "Test order",
"return_url": "https://example.com/return",
"webhook_url": "https://example.com/webhook",
"transactions": [
{
"payment_method": "credit-card"
}
]
}'amount е цяло число във второстепенната единица ISO 4217 на валутата. За EUR 1295 означава 12,95 EUR.
API-то връща пълния обект на поръчката. Ключовите полета са id, status и payment_url вътре в транзакцията:
{
"id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
"status": "new",
"currency": "EUR",
"amount": 1295,
"merchant_order_id": "my-first-order",
"description": "Test order",
"return_url": "https://example.com/return",
"webhook_url": "https://example.com/webhook",
"created": "2026-01-15T12:00:05.433502+00:00",
"modified": "2026-01-15T12:00:05.553125+00:00",
"expiration_period": "PT1H",
"transactions": [
{
"id": "d291f03f-a406-428a-967a-4895a46e03fd",
"payment_method": "credit-card",
"status": "new",
"amount": 1295,
"currency": "EUR",
"payment_url": "https://api.costplus.online/pay/4851e31c.../select-payment-method/credit-card/d291f03f...",
"is_capturable": false,
"expiration_period": "PT30M"
}
]
}Формата на отговора зависи от това какво изпращате:
- С масив
transactions(тази бърза справка): всеки обект transaction съдържа собственpayment_url. Пренасочете клиента към него. - Без
transactions: поръчката имаorder_urlна горно ниво, а клиентът избира метод за плащане на хоствана страница на Cost+. Вижте ръководството за хостванa страница за плащане за този поток.
Запазете id — ще ви трябва в Стъпка 3.
Стъпка 2: Завършване на тестовото плащане
- Отворете
payment_urlот отговора в браузъра си - На страницата за плащане въведете данните на тестовата карта:
| Поле | Стойност |
|---|---|
| Номер на карта | 4111 1111 1111 1111 |
| Валидност | Произволна бъдеща дата (напр. 12/28) |
| CVC | Произволни 3 цифри (напр. 123) |
- Изпратете плащането
- Ще бъдете пренасочени обратно към вашия
return_url
Не разчитайте само на пренасочването, за да потвърдите плащането. Клиентът може да затвори браузъра си преди пренасочването. Винаги проверявайте чрез API (Стъпка 3) или уебхукове (Стъпка 4).
Стъпка 3: Проверка на плащането
Извлечете поръчката, за да потвърдите, че е завършена:
curl -u YOUR_API_KEY: \
https://api.costplus.online/v1/orders/4851e31c-4137-4e91-95ef-1df945ee76a2/Успешното плащане изглежда така:
{
"id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
"status": "completed",
"currency": "EUR",
"amount": 1295,
"merchant_order_id": "my-first-order",
"completed": "2026-01-15T12:02:30.123456+00:00",
"transactions": [
{
"id": "d291f03f-a406-428a-967a-4895a46e03fd",
"payment_method": "credit-card",
"status": "completed",
"amount": 1295,
"currency": "EUR",
"payment_method_details": {
"truncated_pan": "1111",
"card_expiry": "122028"
}
}
]
}Статусът на поръчката е "completed" — плащането е успешно.
Стъпка 4: Обработка на уебхука (Препоръчително)
Когато статусът на плащането се промени, Cost+ изпраща POST заявка към вашия webhook_url:
{
"event": "status_changed",
"order_id": "4851e31c-4137-4e91-95ef-1df945ee76a2"
}Когато получите това:
- Извикайте
GET /v1/orders/{order_id}/, за да проверите текущия статус (никога не се доверявайте само на данните от уебхука) - Върнете HTTP
200, за да потвърдите получаването - Изпълнете поръчката, ако статусът е
"completed"
За локална разработка използвайте тунел като ngrok, за да изложите локалния си сървър и да получавате уебхукове.
Вижте ръководството за уебхукове за логика за повторни опити, добри практики и подробности за данните.
Алтернатива: Линкове за плащане
Ако не се нуждаете от сървърна логика за пренасочване, линковете за плащане предлагат по-прост начин. Създайте линк, споделете URL адреса с клиента си и проверете статуса по-късно.
curl -X POST https://api.costplus.online/v1/paymentlinks/ \
-u YOUR_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"merchant_order_id": "invoice-1234",
"amount": 2500,
"currency": "EUR",
"description": "Invoice #1234"
}'Отговорът включва payment_url, който можете да споделите по имейл, SMS или чат. Клиентът може да опита плащане многократно (до 25 пъти), докато линкът изтече или плащането успее.
Вижте ръководството за линкове за плащане за пълния работен процес.
Какво следва?
Завършихте първото си плащане. Ето накъде да продължите:
- Хоствана страница за плащане — пълна HPP референция с всички полета и опции на заявката
- Периодични плащания — настройте абонаменти и планирано таксуване
- Плащания с един клик — бързо плащане за завръщащи се клиенти
- Оторизация / Улавяне / Анулиране — първо оторизирайте, уловете по-късно (напр. при доставка)
- Възстановявания — обработвайте пълни и частични възстановявания
- SDK библиотеки — официални библиотеки за Node.js, Python, PHP, Java/Kotlin, C#/.NET и Ruby
- Плъгини — готови интеграции за Shopify, WooCommerce, Magento и други
Свързани крайни точки
- Създаване на поръчка — пълна API референция за създаване на поръчки
- Получаване на поръчка — извличане на детайли и статус на поръчка
- Създаване на линк за плащане — създаване на линкове за плащане за многократна употреба