Cost+Docs

Линкове за плащане

Създавайте линкове за плащане за многократна употреба

Линковете за плащане са URL адреси за многократна употреба, които позволяват на клиентите да платят за поръчка. За разлика от стандартните поръчки, които изтичат след един неуспешен опит, линковете за плащане поддържат множество повторни опити, което ги прави идеални за фактури, плащания по имейл и сценарии, при които клиентът може да не плати веднага.

Основни характеристики

  • За многократна употреба: Клиентите могат да опитат плащане до 25 пъти, ако предишните опити са неуспешни.
  • Дълготрайни: Изтичането по подразбиране е 30 дни (конфигурируемо чрез expiration_period).
  • За споделяне: Изпратете линка по имейл, SMS, чат или го вградете на уебсайта си.

Създаване на линк за плащане

Изпратете POST заявка към /v1/paymentlinks/:

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 за проследяване:

Response (201 Created)
{
  "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)
currencyISO 4217 валутен код (напр. EUR, GBP)

Незадължителни полета

ПолеОписание
descriptionОписание, показвано на клиента
expiration_periodISO 8601 продължителност. По подразбиране е P30D (30 дни)
return_urlURL за пренасочване на клиента след успешно плащане
failure_urlURL за пренасочване на клиента при отказ, изтичане или грешка
webhook_urlURL за получаване на известия при промяна на статуса
customerОбект с данни за клиента (име, имейл и др.)

Ако предоставите и return_url, и failure_url, клиентите се пренасочват към failure_url, когато статусът на поръчката е cancelled, expired или error. В противен случай всички пренасочвания отиват към return_url.

Извличане на линк за плащане

Изпратете GET заявка към /v1/paymentlinks/{id}/, като използвате id на линка за плащане от отговора при създаване:

GET /v1/paymentlinks/{id}/
curl -u YOUR_API_KEY: \
  https://api.costplus.online/v1/paymentlinks/e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1/

Отговорът включва текущия статус и препратки към всички поръчки, създадени от линка, групирани по статус:

Response (completed example)
{
  "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, той не може да се използва отново. Създайте нов линк за плащане, ако клиентът трябва да плати отново.

Примерен работен процес

  1. Създайте линк за плащане чрез POST /v1/paymentlinks/.
  2. Споделете върнатия payment_url с клиента си (напр. по имейл, SMS или фактура).
  3. Клиентът отваря линка и завършва плащането.
  4. Cost+ изпраща уебхук към вашия webhook_url при промяна на статуса.
  5. Проверете статуса на линка за плащане чрез GET /v1/paymentlinks/{id}/.
  6. Изпълнете поръчката, когато статусът е completed.

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

On this page