Cost+Docs

Заявки за статус

Проверявайте статуса на поръчки и транзакции

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

Извличане на статус на поръчка

Изпратете GET заявка към /v1/orders/\{id\}/, за да извлечете пълния обект на поръчката, включително текущия статус и всички свързани транзакции.

GET /v1/orders/b9ae6.../

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

Статуси на поръчки

Поръчката преминава през следните статуси:

СтатусФиналенОписание
newНеПоръчката е току-що създадена. Не е направен опит за плащане.
processingНеОпит за плащане е в ход. Клиентът може да завършва 3D Secure или друга стъпка за верификация.
errorдаТехническа повреда прекрати поръчката. Създайте нова поръчка, ако клиентът трябва да опита отново.
completedДаПлащането е успешно. Можете да изпълните поръчката.
cancelledДаПоръчката е отменена — от клиента или чрез API-то.
expiredдаСрокът на поръчката е изтекъл преди да бъде направено успешно плащане. Периодът на изтичане по подразбиране е 30 минути.

Само статусите, маркирани като Финален = Да, са крайни. Поръчки със статус new, processing или error все още могат да преминат към completed.

Пример: Поръчка в обработка

Когато клиентът е инициирал плащане, но то все още не е завършено:

{
  "id": "b9ae6...",
  "project_id": "proj_abc123",
  "merchant_order_id": "my-order-id-1",
  "created": "2024-01-01T12:00:00.000000+00:00",
  "modified": "2024-01-01T12:01:30.000000+00:00",
  "completed": null,
  "expiration_period": "PT30M",
  "status": "processing",
  "currency": "EUR",
  "amount": 1295,
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "payment_url": "https://api.costplus.online/pay/...",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    {
      "id": "txn_001...",
      "payment_method": "credit-card",
      "payment_method_brand": "visa",
      "status": "processing",
      "amount": 1295,
      "currency": "EUR"
    }
  ],
  "flags": ["is-test"]
}

Пример: Завършена поръчка

Когато плащането е успешно, поръчката достига статус completed:

{
  "id": "b9ae6...",
  "project_id": "proj_abc123",
  "merchant_order_id": "my-order-id-1",
  "created": "2024-01-01T12:00:00.000000+00:00",
  "modified": "2024-01-01T12:02:15.000000+00:00",
  "completed": "2024-01-01T12:02:15.000000+00:00",
  "expiration_period": "PT30M",
  "status": "completed",
  "currency": "EUR",
  "amount": 1295,
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "payment_url": "https://api.costplus.online/pay/...",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    {
      "id": "txn_001...",
      "payment_method": "credit-card",
      "payment_method_brand": "visa",
      "payment_method_details": {
        "card_last_four": "4242",
        "card_expiry_month": 12,
        "card_expiry_year": 2026,
        "card_holder_name": "J. Smith"
      },
      "status": "completed",
      "amount": 1295,
      "currency": "EUR"
    }
  ],
  "flags": ["is-test"]
}

Детайли на транзакцията

Всяка транзакция в рамките на поръчка съдържа следните ключови полета:

ПолеОписание
payment_methodИзползваният метод на плащане (напр. credit-card, ideal, apple-pay)
payment_method_brandМарката или издателят (напр. visa, mastercard, amex)
payment_method_detailsОбект с детайли, специфични за метода — последни четири цифри на картата, валидност и име на картодържателя
statusСтатусът на тази конкретна транзакция
amountСумата на транзакцията във валутната единица ISO 4217
currencyВалутата на транзакцията

Не разчитайте единствено на пренасочването на клиента към вашия return_url като потвърждение за плащане. Винаги проверявайте статуса на поръчката чрез API-то или чрез уебхук, преди да изпълните поръчката.

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

On this page