Перейти к основному содержимому

Методы

При обработке запросов проверяется корректность входных параметров, наличие необходимых заголовков, права на выполнение действий.

Проведение операций​

recurrent/disable​

Отключение токена​

С помощью этого запроса можно отключить токен. Отправьте в запросе токен, в ответ придет token_active: false. Это значит, что с этим токеном больше нельзя проводить рекуррентные платежи.

После отключения токена в параметре даты окончания действия токена completed_date может появиться дата, относящаяся к 2000 году — она ни на что не влияет, можно не обращать на неё внимание.

Адрес для отправки запроса​

/api/v1/recurrent/disable

Параметры запроса​

НазваниеОбязательностьТипОписание
recurring_token_info+objectТокен, который нужно отключить
Пример запроса
curl -X POST \
  https://proxy-demo.zetplat.com/api/v1/recurrent/disable \
  -H 'Content-Type: application/json' \
  -H 'X-Project-Id: your_project_name' \
  -H 'X-Signature: signature' \
  -d '{
    "recurring_token_info": {
      "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427"
    }
  }'

Параметры ответа​

НазваниеОбязательностьТипОписание
transaction_status+stringСтатус. Возможные варианты: error, ok
recurring_token_info+objectИнформация о токене для рекуррентных платежей
error_info-objectОшибка
Пример успешного ответа
{
  "recurring_token_info": {
    "token": "97417d4a9a23da9c2401c510a3fc45c2d1752f68ac9fd2a366698d70293b6427",
    "created_date": "2020-07-14T13:17:11+03:00",
    "completed_date": "2020-07-31T16:05:42+03:00",
    "token_active": false,
    "type": "recurring_token"
  },
  "status": "ok"
}
Пример неуспешного ответа
{
  "error": {
    "error_code": "error code",
    "error_description": "error description"
  },
  "status": "error"
}

transaction/cancel​

Отмена операции​

Этот запрос можно отправлять, когда Zetplat готов провести операцию — выплату или платеж. Например, вы получили вебхук approve_pending или finalization_pending.

Если не хотите проводить эту операцию, можете ее отменить: отправьте запрос transaction/cancel.

Если всё в порядке, отправьте запрос на подтверждение операции (transaction/approve) или на списание замороженной суммы (transaction/finalize).

Адрес для отправки запроса​

/api/v1/transaction/cancel

Параметры запроса​

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор сессии
Пример запроса
curl -X POST \
  https://proxy-demo.zetplat.com/api/v1/transaction/cancel \
  -H 'Content-Type: application/json' \
  -H 'X-Project-Id: your_project_name' \
  -H 'X-Signature: signature' \
  -d '{
    "session_id": "ps_3230"
  }'

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session_info-objectПлатежная сессия
error_info-objectОшибка
Пример успешного ответа
{
  "status": "ok",
  "session_info": {
    "id": "ps_3230",
    "transaction_status": "active",
    "created_date": "2024-05-27T02:03:00.000000Z",
    "updated_at": "2024-05-27T02:03:00.000000Z",
    "payouts": [{
      "id": "po_1313",
      "transaction_status": "pending",
      "created_date": "2024-05-27T02:03:00.000000Z",
      "user_info": {
        "user_id": "user123",
        "contact_info": [{
          "email_address": "user@gmail.com"
        }]
      },
      "payout_info": {
        "type": "card_info",
        "card_info": {
          "card_last4": "4242",
          "card_network": "visa"
        }
      },
      "sum_info": {
        "sum": 10000,
        "currency_code": "rub"
      },
      "extra_info": "good"
    }]
  }
}
Пример неуспешного ответа
{
  "error": {
    "error_code": "error code",
    "error_description": "error description"
  },
  "status": "error"
}

transaction/finalize​

Списание захолдированной суммы​

Этот запрос можно использовать, если вы отправляете холдированные платежи. Такой платеж проходит в две стадии: сначала деньги замораживаются (например, на банковской карте пользователя), а потом списываются по вашей команде.

Запрос можно отправлять, когда Zetplat готов списать деньги и прислал вам вебхук finalization_pending.

Если вы хотите списать замороженную сумму, отправьте запрос transaction/finalize. Можно списать замороженную сумму полностью или частично.

Чтобы отменить списание, отправьте transaction/cancel.

Адрес для отправки запроса​

/api/v1/transaction/finalize

Параметры запроса​

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор сессии Zetplat
sum_info-objectСумма к списанию. Может быть меньше замороженной, но обязательно больше 0. Если параметр отсутствует, то замороженная сумма будет списана полностью
Пример запроса
curl -X POST \
  https://proxy-demo.zetplat.com/api/v1/transaction/finalize \
  -H 'Content-Type: application/json' \
  -H 'X-Project-Id: your_project_name' \
  -H 'X-Signature: signature' \
  -d '{
    "session_id": "ps_3230"
  }'

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session_info-objectПлатежная сессия
error_info-objectОшибка
Пример успешного ответа
{
  "status": "ok",
  "session_info": {
    "id": "ps_3230",
    "transaction_status": "active",
    "created_date": "2024-05-27T02:03:00.000000Z",
    "updated_at": "2024-05-27T02:03:00.000000Z",
    "payments": [{
      "id": "pm_1313",
      "transaction_status": "successful",
      "created_date": "2024-05-27T02:03:00.000000Z",
      "completed_date": "2024-05-27T02:03:00.000000Z",
      "user_info": {
        "user_id": "lucky"
      },
      "payment_info": {
        "type": "card_info",
        "card_info": {
          "card_network": "visa",
          "card_last4": "4242"
        }
      },
      "sum_info": {
        "sum": 10000,
        "currency_code": "usd"
      },
      "moneyback": [{
        "id": "rf_23",
        "transaction_status": "ongoing",
        "created_date": "2024-05-27T02:03:00.000000Z",
        "sum_info": {
          "sum": 10000,
          "currency_code": "usd"
        }
      }]
    }]
  }
}
Пример неуспешного ответа
{
  "error": {
    "error_code": "error code",
    "error_description": "error description"
  },
  "status": "error"
}

transaction/approve​

Подтверждение операции​

Этот запрос можно отправлять, когда Zetplat готов провести операцию — выплату или платеж. Например, вы получили вебхук approve_pending.

Вам нужно проверить параметры операции и принять решение. Если всё в порядке, подтвердите операцию: отправьте Zetplat transaction/approve. Если что-то не так, отмените операцию: отправьте запрос transaction/cancel.

Адрес для отправки запроса​

/api/v1/transaction/approve

Параметры запроса​

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор сессии
Пример запроса
curl -X POST \
  https://proxy-demo.zetplat.com/api/v1/transaction/approve \
  -H 'Content-Type: application/json' \
  -H 'X-Project-Id: your_project_name' \
  -H 'X-Signature: signature' \
  -d '{
    "session_id": "ps_3230"
  }'

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session_info-objectПлатежная сессия
error_info-objectОшибка
Пример успешного ответа
{
  "status": "ok",
  "session_info": {
    "id": "ps_3230",
    "transaction_status": "active",
    "created_date": "2024-05-27T02:03:00.000000Z",
    "updated_at": "2024-05-27T02:03:00.000000Z",
    "payouts": [{
      "id": "po_1313",
      "transaction_status": "pending",
      "created_date": "2024-05-27T02:03:00.000000Z",
      "user_info": {
        "user_id": "user123",
        "contact_info": [{
          "email_address": "user@gmail.com"
        }]
      },
      "payout_info": {
        "type": "card_info",
        "card_info": {
          "card_last4": "4242",
          "card_network": "visa"
        }
      },
      "sum_info": {
        "sum": 10000,
        "currency_code": "rub"
      },
      "extra_info": "good"
    }]
  }
}
Пример неуспешного ответа
{
  "error": {
    "error_code": "error code",
    "error_description": "error description"
  },
  "status": "error"
}

transaction/initiate​

Создание платежной сессии​

Этот запрос создает платежную сессию на стороне Zetplat.

Сессия необходима для проведения платежных операций. В рамках сессии может проходить одна или несколько операций одного или разных типов (например, несколько выплат, платеж и возврат, оплата с последующим разделением платежей).

Используйте этот запрос, если вам нужно запросить у пользователя данные для проведения выплаты или оплаты. Например, вызвать виджет для токенизации, показать пользователю и получить токенизированные данные карты и уже с этими данными отправить запрос на выплату.

Если вы готовы сразу передать параметры для платежа или выплаты, вы можете это сделать.
Для платежа передайте: payment_info, sum_info, user_info.
Для выплаты передайте: payout_info, sum_info.

В ответе возвращаются параметры созданной сессии.

Адрес для отправки запроса​

/api/v1/transaction/initiate

Параметры запроса​

НазваниеОбязательностьТипОписание
payout_info-objectПлатежные данные (карта, банковский счет и др.)
payment_info-objectПлатежные данные
sum_info-objectСумма. Передается в минорных единицах. Если отправляете 100 рублей, евро или долларов США, нужно передать 10000
participant_info-objectИнформация об участниках операции
user_info-objectДанные получателя в вашей системе
extra_info-*Дополнительная информация. Любые данные, которые вам необходимы для проведения операции
Пример запроса
curl -X POST \
  https://proxy-demo.zetplat.com/api/v1/transaction/initiate \
  -H 'Content-Type: application/json' \
  -H 'X-Project-Id: your_project_name' \
  -H 'X-Signature: signature' \
  -d '{
    "sum_info": {
      "sum": 10000,
      "currency_code": "rub"
    },
    "extra_info": "order123"
  }'

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session_info-objectПлатежная сессия
error_info-objectОшибка
Пример успешного ответа
{
  "status": "ok",
  "session_info": {
    "id": "ps_3230",
    "transaction_status": "created",
    "created_date": "2024-05-27T02:03:00.000000Z",
    "updated_at": "2024-05-27T02:03:00.000000Z",
  }
}
Пример неуспешного ответа
{
  "error": {
    "error_code": "invalid_request",
    "error_description": "customer.reference.not_blank"
  },
  "status": "error"
}

transaction/init/checkout​

Создание сессии с одновременным стартом платежа​

Можно использовать, если вы сразу готовы передать все параметры, необходимые для оплаты.

В ответе возвращаются параметры созданной сессии и объект с информацией о платеже (payments).

Адрес для отправки запроса​

/api/v1/transaction/init/checkout

Параметры запроса​

НазваниеОбязательностьТипОписание
payment_info+objectПлатежные данные
sum_info+objectСумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000
participant_info-objectИнформация об участниках операции
user_info+objectДанные клиента в вашей системе
payment_settings-objectДополнительные параметры платежа
extra_info-*Любая дополнительная информация. Если транзакция обрабатывается субпартнером, укажите сайт оплаты: "extra_info" {"merchant": leave_it_blank,"submerchant": "https://website"}
Пример запроса
curl -X POST \
  https://proxy-demo.zetplat.com/api/v1/transaction/init/checkout \
  -H 'Content-Type: application/json' \
  -H 'X-Project-Id: your_project_name' \
  -H 'X-Signature: signature' \
  -d '{
    "payment_info": {
      "type": "card_info",
      "card_info": {
        "type": "card_details",
        "card_details": {
          "card_number": "4242424242424242",
          "card_exp_month": "05",
          "card_exp_year": "22",
          "card_code": "123"
        }
      }
    },
    "sum_info": {
      "sum": 10000,
      "currency_code": "rub"
    },
    "user_info": {
      "user_id": "lucky"
    },
    "payment_settings": {
      "back_url": "https://zetplat.com"
    }
  }'

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session_info-objectПлатежная сессия
error_info-objectОшибка
Пример успешного ответа
{
  "status": "ok",
  "session_info": {
    "id": "ps_3230",
    "transaction_status": "active",
    "created_date": "2024-05-27T02:03:00.000000Z",
    "updated_at": "2024-05-27T02:03:00.000000Z",
    "payments": [{
      "id": "pm_1313",
      "transaction_status": "ongoing",
      "created_date": "2024-05-27T02:03:00.000000Z",
      "user_info": {
        "user_id": "lucky"
      },
      "payment_info": {
        "type": "card_info",
        "card_info": {
          "card_network": "visa",
          "card_last4": "4242"
        }
      },
      "sum_info": {
        "sum": 10000,
        "currency_code": "rub"
      },
      "payment_settings": {
        "back_url": "https://zetplat.com"
      }
    }]
  }
}
Пример неуспешного ответа
{
  "error": {
    "error_code": "invalid_request",
    "error_description": "customer.reference.not_blank"
  },
  "status": "error"
}

transaction/init/transfer​

Создание сессии с одновременным стартом выплаты​

Можно использовать этот запрос, если вы сразу готовы передать все параметры для создания выплаты на банковский счет или банковскую карту.

Также можно стартовать выплату с использованием токена, который был получен при создании рекуррентного платежа.

В ответе возвращаются параметры созданной сессии и объект с информацией о выплате (payouts).

Адрес для отправки запроса​

/api/v1/transaction/init/transfer

Параметры запроса​

НазваниеОбязательностьТипОписание
payout_info+objectПлатежные данные (карта, банковский счет и др.)
sum_info+objectСумма. Передается в копейках. Если отправляете 100 рублей, нужно передать 10000
participant_info-objectИнформация об участниках операции (отправителе и получателе)
user_info-objectДанные получателя в вашей системе
extra_info-*Любая дополнительная информация. Если транзакция обрабатывается субпартнером, укажите сайт оплаты: "extra_info" {"merchant": leave_it_blank,"submerchant": "https://website"}
Пример запроса
curl -X POST \
  https://proxy-demo.zetplat.com/api/v1/transaction/init/transfer \
  -H 'Content-Type: application/json' \
  -H 'X-Project-Id: your_project_name' \
  -H 'X-Signature: signature' \
  -d '{
    "payout_info": {
      "type": "card_info",
      "card_info": {
        "type": "card_details",
        "card_details": {
          "card_number": "4242424242424242"
        }
      }
    },
    "sum_info": {
      "sum": 1000,
      "currency_code": "rub"
    },
    "participant_info": {
      "payee_info": {
        "full_name": "Ivanov Ivan"
      }
    }
  }'

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session_info-objectПлатежная сессия
error_info-objectОшибка
Пример успешного ответа
{
  "status": "ok",
  "session_info": {
    "id": "ps_3230",
    "transaction_status": "active",
    "created_date": "2024-05-27T02:03:00.000000Z",
    "updated_at": "2024-05-27T02:03:00.000000Z",
    "payouts": [{
      "id": "po_1313",
      "transaction_status": "ongoing",
      "created_date": "2024-05-27T02:03:00.000000Z",
      "user_info": {
        "user_id": "user123",
        "contact_info": [{
          "email_address": "user@gmail.com"
        }]
      },
      "payout_info": {
        "type": "card_info",
        "card_info": {
          "card_last4": "4242",
          "card_network": "visa"
        }
      },
      "sum_info": {
        "sum": 10000,
        "currency_code": "rub"
      },
      "extra_info": "good"
    }]
  }
}
Пример неуспешного ответа
{
  "error": {
    "error_code": "error code",
    "error_description": "error description"
  },
  "status": "error"
}

transaction/refund​

Возврат​

С помощью этого запроса можно вернуть деньги пользователю после успешного платежа.

После проведения возврата Zetplat отправит вам вебхук checkout_refunded.

Адрес для отправки запроса​

/api/v1/transaction/refund

Параметры запроса​

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор успешной платежной сессии, по которой необходимо провести возврат.
sum_info-objectСумма возврата. Если не указывать, то возврат будет на полную сумму платежа
extra_info-*Дополнительная информация
Пример запроса
curl -X POST \
  https://proxy-demo.zetplat.com/api/v1/transaction/refund \
  -H 'Content-Type: application/json' \
  -H 'X-Project-Id: your_project_name' \
  -H 'X-Signature: signature' \
  -d '{
    "session_id":"ps_3230"
  }'

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session_info-objectПлатежная сессия
error_info-objectОшибка
Пример успешного ответа
{
  "status": "ok",
  "session_info": {
    "id": "ps_3230",
    "transaction_status": "active",
    "created_date": "2024-05-27T02:03:00.000000Z",
    "updated_at": "2024-05-27T02:03:00.000000Z",
    "payments": [{
      "id": "pm_1313",
      "transaction_status": "successful",
      "created_date": "2024-05-27T02:03:00.000000Z",
      "completed_date": "2024-05-27T02:03:00.000000Z",
      "user_info": {
        "user_id": "lucky"
      },
      "payment_info": {
        "type": "card_info",
        "card_info": {
          "card_network": "visa",
          "card_last4": "4242"
        }
      },
      "sum_info": {
        "sum": 10000,
        "currency_code": "rub"
      },
      "moneyback": [{
        "id": "rf_23",
        "transaction_status": "ongoing",
        "created_date": "2024-05-27T02:03:00.000000Z",
        "sum_info": {
          "sum": 10000,
          "currency_code": "rub"
        }
      }]
    }]
  }
}
Пример неуспешного ответа
{
  "error": {
    "error_code": "error code",
    "error_description": "error description"
  },
  "status": "error"
}

transaction/start/checkout​

Старт платежа​

Этот запрос можно использовать, чтобы начать платеж в рамках уже созданной сессии. В параметрах запроса можно передать недостающие данные для проведения оплаты или заменить уже переданные.

Адрес для отправки запроса​

/api/v1/transaction/start/checkout

Параметры запроса​

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор платежной сессии
payment_info- (обязательно, если не передано в transaction/initiate)objectПлатежные данные
sum_info- (обязательно, если не передано в transaction/initiate)objectСумма
participant_info-objectИнформация об участниках операции
user_info- (обязательно, если не передано в transaction/initiate)objectДанные отправителя в вашей системе
payment_settings-objectДополнительные параметры платежа
extra_info-*Любая дополнительная информация. Если транзакция обрабатывается субпартнером, укажите сайт оплаты: "extra_info" {"merchant": leave_it_blank,"submerchant": "https://website"}
Пример запроса
curl -X POST \
  https://proxy-demo.zetplat.com/api/v1/transaction/start/checkout \
  -H 'Content-Type: application/json' \
  -H 'X-Project-Id: your_project_name' \
  -H 'X-Signature: signature' \
  -d '{
    "session_id": "ps_3230",
    "payment_info": {
      "type": "card_info",
      "card_info": {
        "type": "card_details",
        "card_details": {
          "card_number": "4242424242424242",
          "card_exp_month": "01",
          "card_exp_year": "26",
          "card_code": "123"
        }
      }
    },
    "sum_info": {
      "sum": 10000,
      "currency_code": "rub"
    },
    "user_info": {
      "user_id": "lucky"
    },
    "payment_settings": {
      "back_url": "https://zetplat.com"
    },
    "extra_info": "good"
  }'

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session_info-objectПлатежная сессия
error_info-objectОшибка
Пример успешного ответа
{
  "status": "ok",
  "session_info": {
    "id": "ps_3230",
    "transaction_status": "active",
    "created_date": "2024-08-21T06:21:36.913863Z",
    "updated_at": "2024-08-21T06:21:56.832509Z",
    "payments": [{
      "id": "pm_3232",
      "transaction_status": "ongoing",
      "created_date": "2024-08-21T06:21:56.846204Z",
      "user_info": {
        "user_id": "lucky"
      },
      "payment_info": {
        "type": "card_info",
        "card_info": {
          "card_last4": "4242",
          "card_network": "visa",
          "country_code_alpha3": "RUS"
        }
      },
      "sum_info": {
        "sum": 10000,
        "currency_code": "rub"
      },
      "payment_settings": {
        "back_url": "https://zetplat.com"
      },
      "extra_info": "good"
    }]
  }
}
Пример неуспешного ответа
{
  "status": "error",
  "error": {
    "error_description": "internal error",
  "error_code": "repository_record_not_found"
  }
}

transaction/start/transfer​

Старт выплаты​

Этот запрос можно использовать, чтобы начать выплату в рамках уже созданной сессии. В параметрах запроса можно передать недостающие данные для проведения выплаты или заменить уже переданные.

Если вы используете выплатной виджет, чтобы получить токенизированные данные банковской карты пользователя, в этом запросе можно их передать.

Адрес для отправки запроса​

/api/v1/transaction/start/transfer

Параметры запроса​

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор платежной сессии
payout_info- (обязательно, если не передано в transaction/initiate)objectПлатежные данные (карта, банковский счёт и др.)
sum_info- (обязательно, если не передано в transaction/initiate)objectСумма
`participant_info -objectИнформация об участниках выплаты
user_info-objectДанные получателя в вашей системе
extra_info-*Любая дополнительная информация. Если транзакция обрабатывается субпартнером, укажите сайт оплаты: "extra_info" {"merchant": leave_it_blank,"submerchant": "https://website"}
Пример запроса
curl -X POST \
  https://proxy-demo.zetplat.com/api/v1/transaction/start/transfer \
  -H 'Content-Type: application/json' \
  -H 'X-Project-Id: your_project_name' \
  -H 'X-Signature: signature' \
  -d '{
    "session_id": "ps_3230"
  }'

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session_info-objectПлатежная сессия
error_info-objectОшибка
Пример успешного ответа
{
  "status": "ok",
  "session_info": {
    "id": "ps_3230",
    "transaction_status": "active",
    "created_date": "2024-05-27T02:03:00.000000Z",
    "updated_at": "2024-05-27T02:03:00.000000Z",
    "payouts": [{
      "id": "po_1313",
      "transaction_status": "ongoing",
      "created_date": "2024-05-27T02:03:00.000000Z",
      "user_info": {
        "user_id": "user123",
        "contact_info": [{
          "email_address": "user@gmail.com"
        }]
      },
      "payout_info": {
        "type": "card_info",
        "card_info": {
          "card_last4": "4242",
          "card_network": "visa"
        }
      },
      "sum_info": {
        "sum": 10000,
        "currency_code": "rub"
      },
      "extra_info": "good"
    }]
  }
}
Пример неуспешного ответа
{
  "error": {
    "error_code": "error code",
    "error_description": "error description"
  },
  "status": "error"
}

token​

Генерация публичного токена для работы с виджетами​

Токен нужен для доступа к JavaScript-библиотеке Zetplat. Вы можете сгенерировать его этим запросом и использовать для работы с виджетами.

Токен действителен 24 часа. Его можно использовать для одной операции. При отправке запроса следует передать параметры для работы с виджетами, которые вы собираетесь использовать с этим токеном.

Адрес для отправки запроса​

/api/v1/token

Параметры запроса​

НазваниеОбязательностьТипОписание
card_tokenize-objectДанные для работы виджета токенизации
payment_form_config-objectДанные для работы виджета платежной формы
fps_widget-objectДанные для платежной страницы
Пример запроса

Пример запроса на создание токена для проведения платежа с оплатой через платежную форму

curl -X POST \
  https://proxy-demo.zetplat.com/api/v1/token \
  -H 'Content-Type: application/json' \
  -H 'X-Project-Id: your_project_name' \
  -H 'X-Signature: signature' \
  -d '{
    "payment_form_config": {
      "session_id": "ps_3230"
    }
  }'

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
public_token-stringПубличный токен
error_info-objectОшибка
Пример успешного ответа
{
  "status": "ok",
  "public_token": "e065c2f1328e74156a883c00e210a4b1b1451782bbfdd18ae8d05715e05d8539"
}
Пример неуспешного ответа
{
  "status": "error",
  "error": {
    "error_description": "payment_form_config.session_id.not_unique",
  "error_code": "invalid_request"
  }
}

Информация​

fps/banks​

С помощью этого запроса вы можете получить список наименований и идентификаторов банков-участников Системы быстрых платежей.

Метод используется только для выплат.

Адрес для отправки запроса​

/api/v1/fps/banks

Пример запроса
curl -X GET \
  https://proxy-demo.zetplat.com/api/v1/fps/banks \
  -H 'Content-Type: application/json' \
  -H 'X-Project-Id: your_project_name' \
  -H 'X-Signature: signature' \
  -d '{}'
Пример ответа
{
  "banks": [{
    "id": "100000000243",
    "eng_name": "National Standard Bank",
    "ru_name": "Национальный стандарт"
  },
  {
    "id": "100000000056",
    "eng_name": "Khlynov",
    "ru_name": "Хлынов"
  },...]
}

fps/customer_verification​

С помощью этого запроса можно проверить зарегистрирован ли получатель в Системе Быстрых Платежей. Если пользователь найден в СБП, то сессия примет успешный статус, иначе сессия отменится. Эта операция не тарифицируется и подтверждается автоматически (вебхук approve_pending не отправляется).

Адрес для отправки запроса​

/api/v1/fps/customer_verification

Параметры запроса​

НазваниеОбязательностьТипОписание
payout_info+objectПлатежные данные (карта, банковский счёт и др.)
participant_info+objectИнформация об участниках выплаты
Пример запроса

curl -X POST \
  https://proxy-demo.zetplat.com/api/v1/fps/customer_verification \
  -H 'Content-Type: application/json' \
  -H 'X-Project-Id: your_project_name' \
  -H 'X-Signature: signature' \
  -d '{
    "payout_info": {
      "type": "account_info",
      "account_info": {
        "payment_system": "fps_info_verification",
        "fps_info_verification": {
          "phone_number": "79261234567",
          "bank_identifier": "100000000069"
        }
      }
    },
    "participant_info": {
      "payee_info": {
        "given_name": "Иван",
        "family_name": "Иванов",
        "patronymic": "Иванович"
      }
    }
  }'

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session_info-objectПлатежная сессия
error_info-objectОшибка
Пример успешного ответа
{
  "status": "ok",
  "session_info": {
    "id": "ps_3230",
    "transaction_status": "active",
    "created_date": "2022-03-01T11:57:31.652396Z",
    "updated_at": "2022-03-01T11:57:31.861329Z",
    "payouts": [{
      "id": "po_31668",
      "transaction_status": "ongoing",
      "created_date": "2022-03-01T11:57:31.895773Z",
      "payout_info": {
        "type": "account_info",
        "account_info": {
          "payment_system": "fps_info_verification",
          "fps_info_verification": {
            "phone_number": "79261234567",
            "bank_identifier": "100000000069"
          }
        }
      },
      "sum_info": {
        "sum": 100,
        "currency_code": "rub"
      },
      "participant_info": {
        "payee_info": {
          "given_name": "Иван",
          "family_name": "Иванов",
          "patronymic": "Иванович"
        }
      }
    }]
  }
}
Пример неуспешного ответа
{
  "error": {
    "error_code": "error code",
    "error_description": "error description"
  },
  "status": "error"
}

transaction/state​

Получение информации по сессии​

Вы можете отправить этот запрос, если хотите получить полную информацию о платежной сессии. Например, проверить, прошла выплата или нет. Или узнать, можно ли списывать сумму, захолдированную при оплате картой.

В ответ на запрос приходит платежная сессия с данными обо всех операциях, которые проводились в ее рамках.

Адрес для отправки запроса​

/api/v1/transaction/state

Параметры запроса​

НазваниеОбязательностьТипОписание
session_id+stringИдентификатор платежной сессии
Пример запроса
curl -X POST \
  https://proxy-demo.zetplat.com/api/v1/transaction/state \
  -H 'Content-Type: application/json' \
  -H 'X-Project-Id: your_project_name' \
  -H 'X-Signature: signature' \
  -d '{
    "session_id": "ps_3230"
  }'

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
session_info-objectПлатежная сессия
error_info-objectОшибка
Пример успешного ответа
{
  "status": "ok",
  "session_info": {
    "id": "ps_3230",
    "transaction_status": "active",
    "created_date": "2024-05-27T02:03:00.000000Z",
    "updated_at": "2024-05-27T02:03:00.000000Z",
    "next_step": "approve",
    "payouts": [{
      "id": "po_1313",
      "transaction_status": "ongoing",
      "created_date": "2024-05-27T02:03:00.000000Z",
      "user_info": {
        "user_id": "user123",
        "contact_info": [{
          "email_address": "user@gmail.com"
        }]
      },
      "payout_info": {
        "type": "card_info",
        "card_info": {
          "card_last4": "4242",
          "card_network": "visa",
          "card_bin":"444600"
        }
      },
      "sum_info": {
        "sum": 10000,
        "currency_code": "rub"
      },
      "transaction_info": {
        "retrieval_ref_number": "425307614918",
        "authorization_code": "057441"
      },
      "extra_info": "good"
    }]
  }
}
Пример неуспешного ответа
{
  "error": {
    "error_code": "error code",
    "error_description": "error description"
  },
  "status": "error"
}

token/state​

Получение информации по токену​

Операции с банковскими картами часто проводятся с токенизированными данными. При выплатах и платежах через виджеты создается публичный токен, при рекуррентных платежах — токен для рекуррентных платежей.

По любому платежному токену можно получить информацию:

  • о банковской карте, для которой создан этот токен — это будет маскированный номер карты и платежная система;
  • о самом токене — тип токена, время создания, срок действия, активен ли этот токен на момент запроса.

Этот метод можно использовать, чтобы, например, узнать маскированный номер карты и показать пользователю, с какой карты спишутся деньги по подписке. Или если понадобится проверить срок действия токена.

Адрес для отправки запроса​

/api/v1/token/state

Параметры запроса​

НазваниеОбязательностьТипОписание
type+stringТип запроса. Варианты: card_info, public_token, recurring_token
card_info- (обязателен для type = card_info)objectДанные токена банковской карты
public_token- (обязателен для type = public_token)objectДанные публичного токена
recurring_token- (обязателен для type = recurring_token)objectДанные токена для рекуррентных платежей
Примеры запросов

Вы отправляете токенизированные данные банковской карты и получаете маску карты и платежную систему.

curl -X POST \
  https://proxy-demo.zetplat.com/api/v1/token/state \
  -H 'Content-Type: application/json' \
  -H 'X-Project-Id: your_project_name' \
  -H 'X-Signature: signature' \
  -d '{
    "type": "card_info",
    "card_info": {
      "type": "hashed_card_details",
      "hashed_card_details": {
        "hashed_card_number": "card_number_hash (token)"
      }
    }
  }'

Параметры ответа​

НазваниеОбязательностьТипОписание
status+stringСтатус. Возможные варианты: error, ok
token_info-objectВ зависимости от типа запроса (type):
- информация о токенизированной банковской карте
- информация о публичном токене
- информация о токене для рекуррентных платежей
error_info-objectОшибка
Примеры успешных ответов
{
  "status": "ok",
  "token_info": {
    "hashed_card_number": "card_number_hash",
    "card_network": "visa",
    "card_last4": "4242",
    "type": "card_info"
  }
}
Пример неуспешного ответа
{
  "error": {
    "error_code": "error code",
    "error_description": "error description"
  },
  "status": "error"
}