Заявки за статус
Проверявайте статуса на поръчки и транзакции
Всяко плащане в 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-то или чрез уебхук, преди да изпълните поръчката.
Свързани крайни точки
- Получаване на поръчка — извлечете пълния обект на поръчката и текущия й статус
- Списък с поръчки — списък на поръчки с филтриране по дата