Перейти к содержанию

Разделение платежа v2

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

Info

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

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

Обратитесь в службу технической поддержки для активации сплитования для вашего магазина.

Сценарии использования сплитования

  • оплата (payment) + массив split ИЛИ запрос на создание токена платежа с типом транзакции payment + массив split;
  • при необходимости одна или несколько транзакций возврата средств (refund)+ массив split.
  • авторизация (authorization) без массива split ИЛИ запрос на создание токена платежа с типом транзакции authorization без массива split;
  • при необходимости отмена авторизации (void) без массива split;
  • списание средств (capture) + массив split;
  • при необходимости возврат (refund) + массив split.

Info

Для сохранения данных карты в запросе на авторизацию, оплату или на создание токена платежа можно передать массив additional_data.contract со значением ["contract", "card_on_file"]. Токен карты будет отправлен в ответе на запрос или в автоматическом уведомлении в параметре credit_card.token.

Запрос

Для разделения платежа, отправьте данные получателей платежа в массиве additional_data.split.

Сплитование поддерживают следующие транзакции:

Пример запроса на оплату с массивом split 
{
  "request": {
    "amount": 1500,
    "currency": "USD",
    "test": true,
    "description": "Test transaction",
    "tracking_id": "tracking_id_000",
    "notification_url": "https://notification_url",
    "credit_card": {
      "number": "4242424242424242",
      "verification_value": "123",
      "holder": "John Doe",
      "exp_month": 10,
      "exp_year": 2030          
    },
    "customer": {
      "device_id": "",
      "birth_date": ""
    },
    "additional_data": {
      "split": [
        {
          "company_name": "Generic Company LLC",
          "bank_account": "IBAN000000000000000000000000",
          "bank_bic": "GENBANKXX",
          "tax_id": "171234567890",
          "amount": 500
        },
        {
          "company_name": "Best Restaurant Inc.",
          "bank_account": "IBAN111111111111111111111111",
          "bank_bic": "GENBANKYY",
          "tax_id": "222222222",
          "amount": 700
        },
        {
          "company_name": "Courier Services Ltd.",
          "bank_account": "IBAN222222222222222222222222",
          "bank_bic": "GENBANKZZ",
          "tax_id": "333333333",
          "amount": 300
        }
      ],
      "contract": [
        "recurring",
        "card_on_file"
      ]
    }
  }
}
Пример запроса на создание токена с массивом split 
{
    "checkout": {
        "test": true,
        "transaction_type": "payment",
        "settings": {
            "return_url": "http://127.0.0.1:4567/return",
            "success_url": "http://127.0.0.1:4567/success",
            "notification_url": "http://your_shop.com/notification"
        },
        "order": {
            "tracking_id": "your_uniq_number",
            "currency": "USD",
            "amount": 1400,
            "expired_at": "2025-11-29T05:33:38Z",
            "description": "description",
            "additional_data": {
              "split": [
                  {
                      "company_name": "Generic Company LLC",
                      "bank_account": "IBAN000000000000000000000000",
                      "bank_bic": "GENBANKXX",
                      "tax_id": "111111111",
                      "amount": 500
                  },
                  {
                      "company_name": "Best Restaurant Inc.",
                      "bank_account": "IBAN111111111111111111111111",
                      "bank_bic": "GENBANKYY",
                      "tax_id": "222222222",
                      "amount": 600
                  },
                  {
                      "company_name": "Courier Services Ltd.",
                      "bank_account": "IBAN222222222222222222222222",
                      "bank_bic": "GENBANKZZ",
                      "tax_id": "333333333",
                      "amount": 300
                  }
              ]
            }
        }            
    }
}
Пример запроса на списание средств с массивом split 
 {
  "request": {
    "parent_uid": "1-310b0da80b",
    "amount": 1500,
    "additional_data": {
      "split": [
        {
          "company_name": "Generic Company LLC",
          "bank_account": "IBAN000000000000000000000000",
          "bank_bic": "GENBANKXX",
          "tax_id": "111111111",
          "amount": 500
        },
        {
          "company_name": "Best Restaurant Inc.",
          "bank_account": "IBAN111111111111111111111111",
          "bank_bic": "GENBANKYY",
          "tax_id": "222222222",
          "amount": 700
        },
        {
          "company_name": "Courier Services Ltd.",
          "bank_account": "IBAN222222222222222222222222",
          "bank_bic": "GENBANKZZ",
          "tax_id": "333333333",
          "amount": 300
        }
      ]         
    }
  }
}
Пример запроса на возврат средств с массивом split 
{
    "request": {
        "parent_uid": "ef84f54b-a0d6-4bcb-813f-864a3cd9a44d",
        "amount": 1300,
        "reason": "Client request",
        "additional_data": {
            "split": [
                {
                    "tax_id": "171234567",
                    "amount": 500
                },
                {
                    "tax_id": "333333333",
                    "amount": 800
                }
            ]
        }
    }
}

Параметры массива split
object
array
Массив объектов, каждый из которых соответствует получателю платежа и включает в себя следующие параметры:
amount
обязательный
 bigInteger
Сумма для выплаты партнеру маркетплейса в минимальных денежных единицах. Сумма значений amount по всем объектам массива split должна быть равна сумме основного параметра amount в запросе финансовой транзакции.
company_name
 string
Наименование партнёра маркетплейса – юридического лица, ИП или самозанятого, который должен получить свою часть платежа.
bank_account
 string
IBAN расчётного счёта получателя платежа.
bank_bic
 string
BIC, код банка получателя платежа.
tax_id
обязательный
 string
УНП получателя платежа.
description
 string
Назначение платежа: текст может быть согласован с банком в процессе реализации проекта.
legal_address
 string
Юридический адрес получателя платежа.
mailing_address
 string
Почтовый адрес получателя платежа.
country
 string
Страна получателя платежа.
city
 string
Город получателя платежа.
postal_code
 string
Почтовый индекс получателя платежа.
contact_email
 string
Email-адрес получателя платежа.
contact_phone
 string
Номер телефона получателя платежа.
memo
 string
Параметр для заметок.

Ответ

Пример ответа на запрос оплаты с массивом split 
{
    "uid": "ef84f54b-a0d6-4bcb-813f-864a3cd9a44d",
    "code": "S.0000",
    "friendly_message": "The transaction is successfully processed.",
    "status": "successful",
    "amount": 1500,
    "currency": "USD",
    "description": "Test transaction",
    "type": "payment",
    "payment_method": {
        "payment_method_type": "credit_card",
        "holder": "John Doe",
        "stamp": "b3efde4d54bfda63f43c7bb5b1ca5bb93f9f16ed29590a70c190a7454f167679",
        "brand": "visa",
        "last_4": "4242",
        "first_1": "4",
        "bin": "424242",
        "bin_8": "42424242",
        "issuer_country": null,
        "issuer_name": null,
        "product": null,
        "exp_month": 10,
        "exp_year": 2030,
        "token_provider": null,
        "token": "657bb3ad-5f13-488d-bf9c-8305141dcd13"
    },
    "tracking_id": "tracking_id_000",
    "message": "Transaction is successful.",
    "test": true,
    "created_at": "2025-11-12T12:35:10.321Z",
    "updated_at": "2025-11-12T12:35:12.958Z",
    "paid_at": "2025-11-12T12:35:12.845Z",
    "expired_at": null,
    "recurring_type": "initial",
    "closed_at": null,
    "settled_at": null,
    "manually_corrected_at": null,
    "language": "en",
    "redirect_url": "https://gateway.pay-cross.com/process/ef84f54b-a0d6-4bcb-813f-864a3cd9a44d",
    "status_code": null,
    "links": {
        "receipt_url": "https://admin.pay-cross.com/customer/transactions/ef84f54b-a0d6-4bcb-813f-864a3cd9a44d/20e4a187c3dd9e18085a43fac9b7c7ab73a4c933bf9154ef2a3ef73f6ea9bfc2?language=en"
    },
    "gateway": {
        "iframe": true
    },
    "mute_notifications": null,
    "version": 4,
    "psp_settled_at": null,
    "registry_id": null,
    "three_ds_expired_at": null,
    "additional_data": {
        "split": [
            {
                "tax_id": "171234567",
                "amount": 500
            },
            {
                "tax_id": "222222222",
                "amount": 500
            },
            {
                "tax_id": "333333333",
                "amount": 500
            }
        ],
        "contract": [
            "recurring",
            "card_on_file"
        ]
    },
    "customer": {
        "ip": null,
        "email": null,
        "device_id": null,
        "birth_date": null,
        "external_id": null,
        "first_name": null,
        "last_name": null,
        "address": null,
        "country": null,
        "city": null,
        "zip": null,
        "state": null,
        "phone": null
    },    
    "transaction": {
        "auth_code": "654321",
        "bank_code": "05",
        "rrn": "999",
        "ref_id": "777888",
        "message": "Payment was approved",
        "amount": 1500,
        "currency": "USD",
        "billing_descriptor": "TEST GATEWAY BILLING DESCRIPTOR",
        "gateway_id": 3549,
        "status": "successful"
    },
    "avs_cvc_verification": {
        "avs_verification": {
            "result_code": "1"
        },
        "cvc_verification": {
            "result_code": "1"
        }
    }
}
Пример ответа с ошибкой валидации: сумма значений amount массива split не равна общей сумме транзакции 
{
    "code": "E.1025",
    "friendly_message": "Invalid request params",
    "message": "Split {:total_amount=>[\"Total amount in the 'split' section must equal the transaction amount.\"]}.",
    "errors": {
        "additional_data": {
            "split": {
                "total_amount": [
                    "Total amount in the 'split' section must equal the transaction amount."
                ]
            }
        }
    }
}