Cost+Docs

Бързо начало

Приемете първото си плащане за 5 минути

Това ръководство ви води през създаването и завършването на тестово плащане чрез API на Cost+. В края ще имате работеща интеграция, върху която можете да надграждате.

Предварителни изисквания

Не сте сигурни как да получите вашия API ключ? Вижте Тестване на интеграцията за подробни инструкции за настройка.

Стъпка 1: Създаване на поръчка

Изпратете POST заявка за създаване на поръчка за плащане. Заменете YOUR_API_KEY с вашия sandbox API ключ:

Create an order
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 вътре в транзакцията:

Response
{
  "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: Завършване на тестовото плащане

  1. Отворете payment_url от отговора в браузъра си
  2. На страницата за плащане въведете данните на тестовата карта:
ПолеСтойност
Номер на карта4111 1111 1111 1111
ВалидностПроизволна бъдеща дата (напр. 12/28)
CVCПроизволни 3 цифри (напр. 123)
  1. Изпратете плащането
  2. Ще бъдете пренасочени обратно към вашия return_url

Не разчитайте само на пренасочването, за да потвърдите плащането. Клиентът може да затвори браузъра си преди пренасочването. Винаги проверявайте чрез API (Стъпка 3) или уебхукове (Стъпка 4).

Стъпка 3: Проверка на плащането

Извлечете поръчката, за да потвърдите, че е завършена:

Check order status
curl -u YOUR_API_KEY: \
  https://api.costplus.online/v1/orders/4851e31c-4137-4e91-95ef-1df945ee76a2/

Успешното плащане изглежда така:

Response (completed)
{
  "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:

Webhook payload
{
  "event": "status_changed",
  "order_id": "4851e31c-4137-4e91-95ef-1df945ee76a2"
}

Когато получите това:

  1. Извикайте GET /v1/orders/{order_id}/, за да проверите текущия статус (никога не се доверявайте само на данните от уебхука)
  2. Върнете HTTP 200, за да потвърдите получаването
  3. Изпълнете поръчката, ако статусът е "completed"

За локална разработка използвайте тунел като ngrok, за да изложите локалния си сървър и да получавате уебхукове.

Вижте ръководството за уебхукове за логика за повторни опити, добри практики и подробности за данните.

Алтернатива: Линкове за плащане

Ако не се нуждаете от сървърна логика за пренасочване, линковете за плащане предлагат по-прост начин. Създайте линк, споделете URL адреса с клиента си и проверете статуса по-късно.

Create a payment link
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 пъти), докато линкът изтече или плащането успее.

Вижте ръководството за линкове за плащане за пълния работен процес.

Какво следва?

Завършихте първото си плащане. Ето накъде да продължите:

Свързани крайни точки

On this page