Cost+Docs

Карти (Visa и Mastercard)

Приемайте плащания с кредитни и дебитни карти

Преглед

Приемайте плащания с кредитни и дебитни карти чрез API на Cost+, като използвате метода на плащане credit-card.

{
  "transactions": [
    {
      "payment_method": "credit-card"
    }
  ]
}

Поддържани марки карти

МаркаТип
AmexКредитна
MastercardКредитна / Дебитна
MaestroДебитна
VisaКредитна / Дебитна
V PayДебитна

Опции за конфигурация

Динамичен дескриптор

Използвайте полето dynamic_descriptor, за да зададете персонализиран текст, който се появява в банковото извлечение на клиента.

{
  "transactions": [
    {
      "payment_method": "credit-card",
      "payment_method_details": {
        "dynamic_descriptor": "My Store Order 123"
      }
    }
  ]
}

Използване на името на клиента като име на картодържателя

Задайте use_customer_name_as_cardholder_name на true, за да използвате автоматично името на клиента от поръчката като име на картодържателя.

{
  "transactions": [
    {
      "payment_method": "credit-card",
      "payment_method_details": {
        "use_customer_name_as_cardholder_name": true
      }
    }
  ]
}

Персонализиран формуляр за въвеждане на карта

Ако искате да създадете собствен формуляр за въвеждане на карта вместо да използвате хостваната страница за плащане, следвайте тези четири стъпки.

Стъпка 1: Създаване на поръчка с Setup Token

Създайте поръчка и включете setup_token: true в payment_method_details на транзакцията. Това казва на Cost+ да генерира setup token, който можете да използвате за сигурна токенизация на данните от картата.

curl -X POST https://api.costplus.online/v1/orders \
  -u your-api-key: \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "amount": 5000,
    "merchant_order_id": "order-001",
    "transactions": [
      {
        "payment_method": "credit-card",
        "payment_method_details": {
          "setup_token": true
        }
      }
    ],
    "return_url": "https://example.com/return",
    "webhook_url": "https://example.com/webhook"
  }'

Отговорът ще включва стойност setup_token в payment_method_details на транзакцията:

{
  "id": "order-uuid",
  "transactions": [
    {
      "id": "txn-uuid",
      "payment_method": "credit-card",
      "payment_method_details": {
        "setup_token": "st_abc123..."
      }
    }
  ]
}

Стъпка 2: Токенизация на данните от картата

Изпратете PAN на картата, дата на валидност и setup token към крайната точка за токени. Това сигурно съхранява картата и връща vault_token.

curl -X POST https://api.costplus.online/v1/tokens/ \
  -H "Content-Type: application/json" \
  -d '{
    "pan": "4111111111111111",
    "expiry_date": "1228",
    "setup_token": "st_abc123..."
  }'

Отговор:

{
  "vault_token": "vt_xyz789..."
}

Стъпка 3: Удостоверяване на транзакцията

Подайте vault_token и cvc към крайната точка за удостоверяване. Ако е необходим 3D Secure, ще получите redirect_url за пренасочване на клиента към страницата за удостоверяване на банката му.

curl -X POST https://api.costplus.online/v1/orders/{order_id}/transactions/{transaction_id}/authenticate/ \
  -u your-api-key: \
  -H "Content-Type: application/json" \
  -d '{
    "vault_token": "vt_xyz789...",
    "cvc": "123"
  }'

Отговор:

{
  "redirect_url": "https://3ds.bank.example.com/auth?id=..."
}

Пренасочете клиента към redirect_url, за да завърши 3D Secure удостоверяването. След като клиентът завърши (или откаже) удостоверяването, ще бъде пренасочен обратно към вашия return_url.

Стъпка 4: Проверка на статуса на поръчката

След като клиентът се върне от 3D Secure, направете polling на поръчката, за да проверите крайния статус.

curl -X GET https://api.costplus.online/v1/orders/{order_id} \
  -u your-api-key:

Статусът на поръчката ще се промени на един от:

СтатусЗначение
completedПлащането е успешно
cancelledКлиентът е отказал или удостоверяването е неуспешно
errorВъзникна грешка при обработката
expiredПоръчката е изтекла преди завършване

За потоци с ръчна оторизация и улавяне при плащания с карти вижте ръководството Оторизация / Улавяне / Анулиране.

On this page