Skip to content

Payment split v2

Split payment is a method of accepting payments when the payment amount is distributed among multiple recipients. For example, in the case of a marketplace, the transaction request is initiated by the marketplace operator. The transaction parameters include the information about the payment recipients: marketplace partners and stores, as well as the corresponding bank account details (optional).

Info

If payment split v2 is used, the customer is charged once and the payment amount is split when the payment is settled with the payment recipients.

To split the payment during the transaction (the number of charges from the customer's card will equal the number of the payment recipients), use payment split v1.

Contact the Tech Support Team to activate split payments for your shop.

Split payment flows

  • payment + split array OR payment token request with transaction_type set to payment + split array;
  • if necessary, one or more refund transactions + split array.
  • authorization without split array OR payment token request with transaction_type set to authorization without split array;
  • if necessary, void without split array;
  • capture + split array;
  • if necessary, refund + split array.

Info

To save the card data, send additional_data.contract array with the value ["contract", "card_on_file"] in the payment, authorization or a payment token request. The card token will be sent in the response or in the webhook notification in the credit_card.token parameter.

Request

To split the payment, send the information about the recipients in the additional_data.split array.

The following card transactions support split payments:

Payment request example with the split array 
{
  "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"
      ]
    }
  }
}
Payment token request example with the split array 
{
    "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
                  }
              ]
            }
        }            
    }
}
Capture request example with the split array 
 {
  "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
        }
      ]         
    }
  }
}
Refund request example with the split array 
{
    "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 parameters
object
array
Array of objects where each object corresponds to the payment recipient and includes the following parameters:
amount
required
 bigInteger
Amount to be paid to the marketplace partner. The sum of amount values in the split array must equal the transaction amount.
company_name
 string
Name of the marketplace partner to receive the share of the payment – a legal entity, individual entrepreneur, or self-employed person.
bank_account
 string
IBAN of the bank account of the payment recipient.
bank_bic
 string
The BIC number of the bank account of the payment recipient.
tax_id
required
 string
Taxpayer identification number of the payment recipient.
description
 string
Purpose of the payment: the text can be agreed upon with the bank.
legal_address
 string
Payment recipient's legal address.
mailing_address
 string
Payment recipient's mailing address.
country
 string
Payment recipient's country.
city
 string
Payment recipient's city.
postal_code
 string
Payment recipient's postal code.
contact_email
 string
Payment recipient's contact email.
contact_phone
 string
Payment recipient's contact phone number.
memo
 string
Notes about the transaction.

Response

Response example with the split array 
{
    "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://demo-gateway.begateway.com/process/ef84f54b-a0d6-4bcb-813f-864a3cd9a44d",
    "status_code": null,
    "links": {
        "receipt_url": "https://demo-backoffice.begateway.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"
        }
    }
}
Response example with a validation error: the sum of amount values in the split array does not equal the overall transaction amount 
{
    "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."
                ]
            }
        }
    }
}