Линкове за плащане
Създавайте линкове за плащане за многократна употреба
Линковете за плащане са URL адреси за многократна употреба, които позволяват на клиентите да платят за поръчка. За разлика от стандартните поръчки, които изтичат след един неуспешен опит, линковете за плащане поддържат множество повторни опити, което ги прави идеални за фактури, плащания по имейл и сценарии, при които клиентът може да не плати веднага.
Основни характеристики
- За многократна употреба: Клиентите могат да опитат плащане до 25 пъти, ако предишните опити са неуспешни.
- Дълготрайни: Изтичането по подразбиране е 30 дни (конфигурируемо чрез
expiration_period). - За споделяне: Изпратете линка по имейл, SMS, чат или го вградете на уебсайта си.
Създаване на линк за плащане
Изпратете POST заявка към /v1/paymentlinks/:
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": 995,
"currency": "EUR",
"description": "Invoice #1234"
}'Отговорът включва payment_url за споделяне с клиента и уникален id за проследяване:
{
"id": "e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1",
"merchant_order_id": "invoice-1234",
"amount": 995,
"currency": "EUR",
"description": "Invoice #1234",
"expiration_period": "P30D",
"payment_url": "https://api.costplus.online/paymentlinks/e6eecc6a.../",
"status": "new",
"reason": "Payment Link was created, not yet visited",
"orders": {},
"created": "2026-01-15T12:00:00.000000Z"
}Запазете id — ще го използвате за проверка на статуса на линка за плащане по-късно.
Задължителни полета
| Поле | Описание |
|---|---|
merchant_order_id | Ваш собствен референтен идентификатор за линка за плащане |
amount | Сума в ISO 4217 второстепенна единица на валутата (напр. 9,95 EUR = 995) |
currency | ISO 4217 валутен код (напр. EUR, GBP) |
Незадължителни полета
| Поле | Описание |
|---|---|
description | Описание, показвано на клиента |
expiration_period | ISO 8601 продължителност. По подразбиране е P30D (30 дни) |
return_url | URL за пренасочване на клиента след успешно плащане |
failure_url | URL за пренасочване на клиента при отказ, изтичане или грешка |
webhook_url | URL за получаване на известия при промяна на статуса |
customer | Обект с данни за клиента (име, имейл и др.) |
Ако предоставите и return_url, и failure_url, клиентите се пренасочват към failure_url, когато статусът на поръчката е cancelled, expired или error. В противен случай всички пренасочвания отиват към return_url.
Извличане на линк за плащане
Изпратете GET заявка към /v1/paymentlinks/{id}/, като използвате id на линка за плащане от отговора при създаване:
curl -u YOUR_API_KEY: \
https://api.costplus.online/v1/paymentlinks/e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1/Отговорът включва текущия статус и препратки към всички поръчки, създадени от линка, групирани по статус:
{
"id": "e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1",
"merchant_order_id": "invoice-1234",
"amount": 995,
"currency": "EUR",
"description": "Invoice #1234",
"expiration_period": "P30D",
"payment_url": "https://api.costplus.online/paymentlinks/e6eecc6a.../",
"status": "completed",
"reason": "Completed",
"completed": "2026-01-15T12:05:30.123456+00:00",
"completed_order_id": "3bb663cc-2a20-400d-8bf6-18d9695d0c66",
"orders": {
"error": ["0d79014c-0aaa-4fd6-87c5-c8cfa5f5ac69"],
"completed": ["3bb663cc-2a20-400d-8bf6-18d9695d0c66"]
}
}В този пример клиентът е направил един неуспешен опит (поръчка 0d79014c... със статус error) преди успеха (поръчка 3bb663cc... със статус completed). Можете да извлечете пълните детайли на всяка поръчка чрез GET /v1/orders/{order_id}/.
Статуси на линкове за плащане
| Статус | Описание |
|---|---|
new | Линкът е създаден, но не е направен опит за плащане. |
processing | Опит за плащане е в ход. |
all_unsuccessful | Всички досегашни опити за плащане са неуспешни. Клиентът все още може да опита отново (до 25 опита). |
completed | Плащането е успешно. Линкът вече не е активен. |
expired | Линкът е изтекъл преди успешно плащане. |
Статусът all_unsuccessful не е финален. Клиентът все още може да опита да плати, докато плащането не успее, максималният брой опити (25) не бъде достигнат или линкът не изтече.
След като линк за плащане достигне статус completed или expired, той не може да се използва отново. Създайте нов линк за плащане, ако клиентът трябва да плати отново.
Примерен работен процес
- Създайте линк за плащане чрез
POST /v1/paymentlinks/. - Споделете върнатия
payment_urlс клиента си (напр. по имейл, SMS или фактура). - Клиентът отваря линка и завършва плащането.
- Cost+ изпраща уебхук към вашия
webhook_urlпри промяна на статуса. - Проверете статуса на линка за плащане чрез
GET /v1/paymentlinks/{id}/. - Изпълнете поръчката, когато статусът е
completed.
Свързани крайни точки
- Създаване на линк за плащане — създайте линк за плащане за многократна употреба
- Получаване на линк за плащане — извлечете текущия статус на линк за плащане