Збережені картки

Збережені картки дозволяють платникам здійснювати швидкі оплати без повторного введення карткових даних.

Способи збереження картки

На платіжній сторінці — користувач відмічає опцію “зберегти карту”
Через віджет — отримання токена та збереження в гаманець

Дані зберігаються по параметру customer.external_id — унікальному ідентифікатору користувача.

Додавання картки в гаманець

curl -X POST "https://api.rozetkapay.com/api/customers/v1/wallet?external_id=user_123" \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "hosted",
    "callback_url": "https://your-site.com/callback",
    "result_url": "https://your-site.com/result",
    "make_default": true,
    "payment_method": {
      "type": "cc_token",
      "cc_token": {
        "token": "tok_card_token",
        "mask": "424242******4242",
        "expires_at": "2027-12-01T00:00:00Z",
        "use_3ds_flow": true
      }
    }
  }'

Замість external_id можна передати заголовок X-CUSTOMER-AUTH з токеном користувача — потрібне одне з двох.

Отримання карток з гаманця

curl -X GET "https://api.rozetkapay.com/api/customers/v1/wallet?external_id=user_123" \
  -u "login:password"

Відповідь

{
  "external_id": "user_123",
  "wallet": [
    {
      "option_id": "opt_abc123",
      "type": "card",
      "name": "Моя картка",
      "is_default": true,
      "card": {
        "mask": "424242******4242",
        "payment_system": "VISA",
        "bank_short_name": "ПриватБанк",
        "expires_at": "2025-12-01T00:00:00Z"
      }
    },
    {
      "option_id": "opt_def456",
      "type": "card",
      "name": "Робоча картка",
      "is_default": false,
      "card": {
        "mask": "545454******5454",
        "payment_system": "MASTERCARD",
        "bank_short_name": "Monobank",
        "expires_at": "2026-06-01T00:00:00Z"
      }
    }
  ]
}

Оплата збереженою карткою

Через токен (cc_token)

curl -X POST https://api.rozetkapay.com/api/payments/v1/new \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "order_12345",
    "mode": "direct",
    "amount": 100,
    "currency": "UAH",
    "callback_url": "https://your-site.com/callback",
    "customer": {
      "external_id": "user_123",
      "payment_method": {
        "type": "cc_token",
        "cc_token": {
          "token": "tok_2df5e29f-7ace-4e1a-9153-7a95e5d6a503",
          "use_3ds_flow": true,
          "save_to_wallet": true
        }
      }
    }
  }'

Через гаманець (wallet)

curl -X POST https://api.rozetkapay.com/api/payments/v1/new \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "order_12345",
    "mode": "direct",
    "amount": 100,
    "currency": "UAH",
    "callback_url": "https://your-site.com/callback",
    "customer": {
      "external_id": "user_123",
      "payment_method": {
        "type": "wallet",
        "wallet": {
          "option_id": "opt_abc123",
          "use_3ds_flow": true
        }
      }
    }
  }'

Параметри платіжних методів

cc_token

Параметр	Обов’язковий	Опис
`token`	Так	Токен картки
`use_3ds_flow`	Так	Використовувати 3DS (за замовч. `true`)
`save_to_wallet`	Ні	Зберегти в гаманець після оплати

wallet

Параметр	Обов’язковий	Опис
`option_id`	Так	ID платіжного інструмента в гаманці
`use_3ds_flow`	Так	Використовувати 3DS

Видалення картки з гаманця

curl -X DELETE "https://api.rozetkapay.com/api/customers/v1/wallet?external_id=user_123" \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "option_id": "opt_abc123",
    "type": "card"
  }'

Токенізація через віджет

Для отримання токена картки використовуйте віджет:

let widget = RPayCardWidget.init({
  key: "your_widget_key",
  mode: "inline",
  selector: "widget-checkout",
  onToken: function (tokenData) {
    // tokenData.token — токен для збереження або оплати
    // tokenData.card_mask — маска картки
    // tokenData.expires_at — строк дії токена

    saveCardToWallet(tokenData.token);
  },
});

widget.open();

Діаграма процесу

flowchart TD
    U([Користувач])
    U --> W[Віджет<br/>токенізація]
    U --> C[Платіжна сторінка<br/>save card]
    W --> AW[Add to Wallet API]
    C --> AS[Автоматичне<br/>збереження]
    AW --> WL[(Гаманець<br/>користувача)]
    AS --> WL
    WL --> FP[Швидка оплата<br/>wallet / cc_token]