Cost+Docs

Оторизации, улавяния и анулирания

Управлявайте потоците за оторизация, улавяне и анулиране на плащания

Някои методи на плащане поддържат двустъпков поток: първо оторизиране (резервиране на средства), след това улавяне (събиране на средствата) или анулиране (освобождаване на резервацията).

Режими на улавяне

Задайте capture_mode на поръчката, за да контролирате кога се улавят средствата:

РежимПоведение
manualВие изрично улавяте, когато сте готови (напр. след изпращане). Ако не уловите преди изтичане на поръчката, оторизацията е загубена и не може да бъде уловена.
delayedСредствата се улавят автоматично в момента на изтичане на expiration_period.
POST /v1/orders/ (manual capture)
{
  "currency": "EUR",
  "amount": 5000,
  "capture_mode": "manual",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    {
      "payment_method": "credit-card"
    }
  ]
}

При manual улавяне трябва да уловите преди изтичане на периода на валидност на поръчката. След изтичане оторизацията се освобождава и средствата не могат да бъдат уловени. Задайте подходящ expiration_period за вашата времева рамка за изпълнение.

Можете да зададете capture_mode на ниво поръчка без да посочвате transactions. Хостваната страница за плащане тогава ще показва само методи на плащане, които поддържат посочения режим на улавяне.

Проверка на суми за улавяне

Преди улавяне можете да проверите колко е налично за улавяне, като поискате amount_details:

curl -u YOUR_API_KEY: \
  "https://api.costplus.online/v1/orders/{order_id}/?fields[]=amount_details"

Отговорът включва обект amount_details:

{
  "amount": 5000,
  "amount_details": {
    "capturable": 5000,
    "captured": 0,
    "refundable": 0,
    "refunded": 0,
    "voidable": 5000,
    "voided": 0
  }
}

Редове на поръчката

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

ТипОписание
physicalФизически продукт
discountСума на отстъпка
shipping_feeРазходи за доставка
sales_taxДанък продажби
digitalДигитален продукт
gift_cardПодаръчна карта
store_creditКредит в магазина
surchargeДопълнителна такса

Улавяне на плащания

Улавяне по ред на поръчка

POST /v1/orders/{id}/transactions/{transaction_id}/captures/orderlines
Request body
{
  "description": "Shipping item #1",
  "order_line": {
    "merchant_order_line_id": "item-001",
    "quantity": 1
  }
}

Улавяне по сума

POST /v1/orders/{id}/transactions/{transaction_id}/captures/amount
Request body
{
  "description": "Partial capture",
  "amount": 2500
}

Анулиране на плащания

Анулирането освобождава оторизираните средства обратно на клиента.

Анулиране по ред на поръчка

POST /v1/orders/{id}/transactions/{transaction_id}/voids/orderlines
Request body
{
  "description": "Voiding item #2",
  "order_line": {
    "merchant_order_line_id": "item-002",
    "quantity": 1
  }
}

Анулиране по сума

POST /v1/orders/{id}/transactions/{transaction_id}/voids/amount
Request body
{
  "description": "Partial void",
  "amount": 1500
}

Параметри на заявката

Добавете параметри на заявката, за да включите допълнителни детайли в отговора:

ПараметърОписание
?fields[]=order_line_detailsВключете разбивка по редове на поръчката
?fields[]=amount_detailsВключете разбивка на сумите

Оптимистично заключване

Крайните точки за улавяне и анулиране поддържат оптимистично заключване на базата на ETag чрез хедъра if-match. Това предотвратява състезателни условия, когато множество системи се опитват да уловят една и съща транзакция.

Capture with optimistic locking
curl -X POST https://api.costplus.online/v1/orders/{id}/transactions/{tid}/captures/amount \
  -u {api_key}: \
  -H "Content-Type: application/json" \
  -H "if-match: \"etag-value\"" \
  -d '{"description": "Capture", "amount": 2500}'

Ако ETag-ът не съвпада (поръчката е била модифицирана, откакто последно сте я извлекли), ще получите отговор 412 Precondition Failed.

Cost+ поддържа едно улавяне на оторизация, а анулирания могат да се обработват само преди каквото и да е улавяне. Планирайте стратегията си за улавяне съответно.

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

On this page