Splitting payment amount

General information

When making a payment, it is likely to encounter restrictions imposed by payment providers on the purchase amounts to be processed. The ecommpay payment platform allows you to override these restrictions by splitting the payment with the amount that exceeds the limit into several operations with smaller amounts. To set the maximum number of operations that can be created for a payment with a split amount, contact the ecommpay technical support.

The number of operations and its amounts within a payment are calculated as follows:
  1. the payment amount is divided by the limit amount, an integer in the result is the number of operations with the maximum limit amount
  2. the limit amount and the resulting integer is deducted from the payment amount to know the remaining amount

For example, if the amount limit of the provider is 10,000.00 EUR, and the payment amount is 15,000.00 EUR, the payment is divided into two operations with the amounts of 10,000.00 EUR (maximum allowable amount) and 5,000.00 EUR (remaining amount) according to the formula 15000:10000=1.5, 15000-(10000*1)=5000. Or if the amount limit is 1,800.00 EUR and the payment amount is 5,000.00 EUR, then the payment is divided into three operations with the amounts of 1,800.00 EUR, 1,800.00 EUR (maximum allowable amounts) and 1,400.00 EUR (remaining amount) according to the formula: 5000:1800=2.8, 5000-(1800*2)=1400.

The functionality is supported for one-time purchase by using cards in one or two steps. When making a payment a customer is warned that the purchase amount can be split, and it is necessary to pass the 3‑D Secure authentication more than once.
Tip: To enable and configure the service contact technical support by email support@ecommpay.com.
On the final payment page with the result, a customer will see both the total requested amount and the real amount debited.


Callback format for delivering purchase results

The standard format for callbacks is used to deliver split purchase results. For more information, see Callbacks. A callback is sent for each processed operation within the payment.

Possible final payment statuses:

  • success—the entire amount of the payment has been paid
  • decline—the entire amount of the payment has not been paid and there are no cascading attempts left or set
  • partially paid—the amount of the payment has been partially paid and there are no cascading attempts left or set

The full payment amount and currency are passed in the payment.sum object:

  • amount—the total amount of the payment, always passed
  • currency—the currency of the payment, always passed

Depending on the operation type and payment status, the following parameters with amount information can be passed in the payment object:

  • actual_amount—the actual amount that was paid by the sale or capture operation, always passed
  • amount_authorized—the actual amount that was previously authorised by the auth operation, can either be confirmed by the capture operation or cancelled by the cancel operation, passed only if the two-step purchase is performed
  • amount_remaining_refund—the amount available for refund to the customer, passed only for payments with the status partially paid or success.

Below are examples of callbacks that are sent at different possible stages of processing a purchase with a split payment amount in one and two steps.

  • The example of a one-step purchase with payment amount of 10.01 EUR and with the provider's limit of 10.00 EUR.

    The following is the example of a callback that indicates that a one-step purchase from the customer has been initiated. The amount of the first operation to which the callback is sent and which was actually paid by the customer is 10.00 EUR.

    Figure: Callback example of a one-step purchase with split payment amount in progress

    {
    "project_id": 968,
    "payment": {
      "id": "ORDER_ID_762",
      "type": "purchase",
      "status": "processing",
      "date": "2019-11-14T05:36:19+0000",
      "method": "card",
      "sum": {
        "amount": 1001,
        "currency": "EUR"        
      },
      "actual_amount": 1000,
      "description": "2 operations"
    },
    "account": {
      "number": "541333******0019",
      "type": "mastercard",
      "card_holder": "PAUL LEE",
      "expiry_month": "01",
      "expiry_year": "2025"
    },
    "customer": {
      "id": "D_K"
    },
    "operation": {
      "id": 302103697,
      "type": "sale",
      "status": "success",
      "date": "2019-11-14T05:36:20+0000",
      "created_date": "2019-11-14T05:36:13+0000",
      "request_id": "00000001",
      "sum_initial": {
        "amount": 1000,
        "currency": "EUR"
      },
      "code": "0",
      "message": "Success",
      "provider": {
        "id": 3,
        "payment_id": "81206",
        "auth_code": "",
        "endpoint_id": "3",
        "date": "2019-11-14T05:36:18+0000"
      }
    },
    "signature": "h8WLEFVwUVnuL5X0szc0sVqDexKoe3UwumxXxLdn0...=="
  }

    In the following example, the callback indicates that both payment operations were performed with a total amount of 10.01 EUR, and the amount of the operation after which the callback is sent is 0.01 EUR. The amount available for refund is 10.01 EUR.

    Figure: Callback example of a one-step purchase with split payment amount fully processed

    {
    "project_id": 968,
    "payment": {
      "id": "ORDER_ID_762",
      "type": "purchase",
      "status": "success",
      "date": "2019-11-14T05:36:19+0000",
      "method": "card",
      "sum": {
        "amount": 1001,
        "currency": "EUR"        
      },
      "actual_amount": 1001,
      "amount_remaining_refund": 1001,
      "description": "2 operations"
    },
    "account": {
      "number": "541333******0019",
      "type": "mastercard",
      "card_holder": "PAUL LEE",
      "expiry_month": "01",
      "expiry_year": "2025"
    },
    "customer": {
      "id": "D_K"
    },
    "operation": {
      "id": 302103697,
      "type": "sale",
      "status": "success",
      "date": "2019-11-14T05:36:20+0000",
      "created_date": "2019-11-14T05:36:13+0000",
      "request_id": "00000001",
      "sum_initial": {
        "amount": 1,
        "currency": "EUR"
      },
      "code": "0",
      "message": "Success",
      "provider": {
        "id": 3,
        "payment_id": "81206",
        "auth_code": "",
        "endpoint_id": "3",
        "date": "2019-11-14T05:36:18+0000"
      }
    },
    "signature": "h8WLEFVwUVnuL5X0szc0sVqDexKoe3UwumxXxLdn0...=="
  }

  • The example of a two-step purchase with payment amount of 45.27 EUR and with the provider's limit of 25.00 EUR.

    The following is the example of a callback with the information about a two-step purchase with the amount 40.27 EUR partially paid by the customer, and the amount of the operation to which the callback was sent is 25.00 EUR. The payment status processing means that the amount of 20.27 EUR still remains to be confirmed.

    Figure: Callback example of a two-step purchase with split payment amount in progress

    {
    "project_id": 968,
    "payment": {
      "id": "ORDER_09519",
      "type": "purchase",
      "status": "processing",
      "date": "2019-11-14T05:32:27+0000",
      "method": "card",
      "sum": {
        "amount": 4527,
        "currency": "EUR"
        },   
      "actual_amount": 2500,
      "amount_authorized": 2027,
      "description": "2 operations"
    },
    "account": {
      "number": "541333******0019",
      "type": "mastercard",
      "card_holder": "PAUL LEE",
      "expiry_month": "01",
      "expiry_year": "2025"
    },
    "customer": {
      "id": "D_K"
    },
    "operation": {
      "id": 302103695,
      "type": "capture",
      "status": "success",
      "date": "2019-11-14T05:32:28+0000",
      "created_date": "2019-11-14T05:32:26+0000",
      "request_id": "00000001",
      "sum_initial": {
        "amount": 2500,
        "currency": "EUR"
      },
      "code": "0",
      "message": "success",
      "provider": {
        "id": 3,
        "payment_id": "",
        "auth_code": "",
        "endpoint_id": "3",
        "date": "2019-11-14T05:32:27+0000"
      }
    },
    "signature": "GvDHyki3OPkwbWzumbTYRBxNSgDFLF8Yg220hAud3r...=="
  }

    The following is the example of a callback indicating that the provider declined a part of the two-step purchase with the amount 45.27 EUR, and the amount of the operation to which the callback is sent is 20.27 EUR. The payment status awaiting capture means that there is an amount already confirmed and paid—25.00 EUR, and the amount of 20.27 EUR still remains to be confirmed or cancelled.

    Figure: Callback example of a declined two-step purchase with split payment amount

    {
    "project_id": 968,
    "payment": {
      "id": "ORDER_ID_C00024_0.63157000_1573709519",
      "type": "purchase",
      "status": "awaiting capture",
      "date": "2019-11-14T05:32:27+0000",
      "method": "card",
      "sum": {
        "amount": 4527,
        "currency": "EUR"
        }, 
      "actual_amount": 2500,
      "amount_authorized": 2027,     
      "description": "2 operations"
    },
    "account": {
      "number": "541333******0019",
      "type": "mastercard",
      "card_holder": "PAUL LEE",
      "expiry_month": "01",
      "expiry_year": "2025"
    },
    "customer": {
      "id": "D_K"
    },
    "operation": {
      "id": 302103695,
      "type": "capture",
      "status": "decline",
      "date": "2019-11-14T05:32:28+0000",
      "created_date": "2019-11-14T05:32:26+0000",
      "request_id": "00000001",
      "sum_initial": {
        "amount": 2027,
        "currency": "EUR"
      },
      "code": "10000",
      "message": "General decline",
      "provider": {
        "id": 3,
        "payment_id": "",
        "auth_code": "",
        "endpoint_id": "3",
        "date": "2019-11-14T05:32:27+0000"
      }
    },
    "signature": "GvDHyki3OPkwbWzumbTYRBxNSgDFLF8Yg220hAud3r...=="
  }

    The following is the example of a callback indicating that the merchant has cancelled a part of the two-step purchase with the amount 45.27 EUR, and the amount of the operation to which the callback is sent is 20.27 EUR. The payment status partially paid means that there is an amount already confirmed and paid—25.00 EUR, and this amount is available for refund to the customer.

    Figure: Callback example of a cancelled two-step purchase with split payment amount

    {
    "project_id": 968,
    "payment": {
      "id": "ORDER_ID_C00024_0.63157000_1573709519",
      "type": "purchase",
      "status": "partially paid",
      "date": "2019-11-14T05:32:27+0000",
      "method": "card",
      "sum": {
        "amount": 4527,
        "currency": "EUR"
        }, 
      "actual_amount": 2500,
      "amount_authorized": 0, 
      "amount_remaining_refund": 2500,     
      "description": "2 operations"
    },
    "account": {
      "number": "541333******0019",
      "type": "mastercard",
      "card_holder": "PAUL LEE",
      "expiry_month": "01",
      "expiry_year": "2025"
    },
    "customer": {
      "id": "D_K"
    },
    "operation": {
      "id": 302103695,
      "type": "cancel",
      "status": "success",
      "date": "2019-11-14T05:32:28+0000",
      "created_date": "2019-11-14T05:32:26+0000",
      "request_id": "00000001",
      "sum_initial": {
        "amount": 2027,
        "currency": "EUR"
      },
     "code": "10000",
      "message": "General decline",
      "provider": {
        "id": 3,
        "payment_id": "",
        "auth_code": "",
        "endpoint_id": "3",
        "date": "2019-11-14T05:32:27+0000"
      }
    },
    "signature": "GvDHyki3OPkwbWzumbTYRBxNSgDFLF8Yg220hAud3r...=="
  }

  • The example of a two-step purchase with payment amount of 45.00 EUR, with the provider's limit of 20.00 EUR, and with a set limit on the number of created operations per payment — 2.

    The following example of the callback indicates that the payment amount exceeds the established limit on the number of created operations with split payment amount.

    Figure: Callback example of a declined purchase with split payment amount

    {
        "customer": {
            "id": "customer_123"
        },
        "account": {
            "number": "431422******0056 ",
            "type": "visa",
            "card_holder": "PAUL LEE",
            "expiry_month": "07",
            "expiry_year": "2021"
        },
        "project_id": 260,
        "payment": {
            "id": "TEST_14-04-2020_0001",
            "type": "purchase",
            "status": "decline",
            "date": "2020-04-14T11:19:42+0000",
            "method": "card",
            "sum": {
                "amount": 4500,
                "currency": "EUR"
            },
            "description": "TEST_1586862995539"
        },
        "operation": {
            "id": 46523000020281,
            "type": "auth",
            "status": "decline",
            "date": "2020-04-14T11:19:42+0000",
            "created_date": "2020-04-14T11:19:42+0000",
            "request_id": "046524",
            "sum_initial": {
                "amount": 4500,
                "currency": "EUR"
            },
            "code": "3019",
            "message": "Exceeded count split operation",
            "provider": {
                "id": 414,
                "payment_id": "",
                "endpoint_id": 414
            }
        },
        "signature": "/dnQUd/uLStqBI4DU1j2+/X2Cua6cvH00...=="
    }