Splitting payment amount

General information

When payments are processed, there is a certain likelihood that the payment provider or the payment system may impose restrictions on the maximum payment amount. The 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.

Splitting payment amount is supported for one-time purchases made with cards in one or two steps as well as for payouts sent to cards and other payment methods. To learn more about methods for which splitting payout amount is supported, contact your ecommpay account manager.

Special characteristics

Splitting payment amount can be performed simultaneously with the cascade payment processing. This may require submitting additional payment information more than once.

When split purchases are processed, the 3‑D Secure authentication may also be necessary more than once. Therefore, the merchant's web service must display a warning to the customer that the purchase amount can be split, in which case passing the 3‑D Secure authentication may be required several times.

Restrictions

The following restrictions apply to the capability of splitting payment amount:

  • Splitting payment amount must be supported for the payment method used.

    If the payment amount exceeds the limit imposed by the payment provider or the payment system, but splitting payment amount is not supported for the payment method in question, the payment is declined. To learn more about supported methods, contact your ecommpay account manager.

  • The number of operations generated within the payment must not exceed the maximum limit.

    If the number of operations required for completing the payment exceeds the maximum limit, the payment is declined. The maximum number of such operations is set by the technical support specialists — support@ecommpay.com.

  • Simultaneous use of splitting payment amount and payout retries is not supported.

    If splitting payment amount was used and the payment was declined, an option to retry payout is not available for this payment.

Workflow

Splitting payment amount is performed after the request for processing the required payment is received by the ecommpay payment platform. The payment platform checks the payment amount passed in the request against the provider or payment system imposed restrictions. If the amount exceeds the imposed limit, then it is split and several operations are generated; if not, then the regular payment processing workflow is used. Keep in mind that if the payment amount requires currency conversion, then the amount is checked against restrictions after the conversion has been performed.

Operation amounts when the payment is split are calculated as follows:

  1. To determine the number of operations with the maximum limit amount, the payment amount is divided by the limit amount. An integer in the result is the number of operations with the maximum limit amount.

    For example, the amount limit of the provider is 1,800.00 EUR, and the payment amount is 5,000 EUR. The number of operations with the maximum limit amount is determined as follows: 5000 ÷ 1800 = 2.8. Hence, the payment is split into two operations with the maximum limit amount.

  2. To determine the remaining amount, the product of the limit amount by the number of operations with the maximum limit amount is deducted from the payment amount.

    For example, if the amount limit of the provider is 1,800.00 EUR, the payment amount is 5,000.00 EUR, and the number of operations with maximum limit amount equals two, the remainder is determined as follows: 5000 - (1800 × 2) = 1400. Hence, the amount of the third operation is 1,400 EUR.

After split amounts have been calculated, the payment platform generates and performs operations with the corresponding operation amounts. Information about successful completion of each operation is passed to the merchant's web service in callbacks. Their format is described below.

Information about split payments is also shown in the Payment flow type column of the payments list in Dashboard. Each of these payments is marked as split in this column.

Setup and configuration

To enable this capability, you need to coordinate its setup with your ecommpay account manager and then contact the technical support for assistance (support@ecommpay.com). Maximum allowed number of operations generated within a split payment is also set up by the ecommpay technical support specialists.

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...=="
        }

Callback format for delivering payout results

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

Callbacks contain information about the payment's final status, total payment amount and currency as well as the actual amount that was paid out and other data. Possible final payment statuses:

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

Information about the payment's currency, total amount and the actual amount that was paid out is passed in the payment object:

  • sum—an object with information about the payment's total amount and currency:
    • amount—the total amount of the payment
    • currency—the payment's currency code
  • actual_amount—the amount that was actually paid out to the customer

Figure: Callback example of a completed payout with split amount and without currency conversion

 {
  "project_id":51,
  "payment":{
    "id":"3_02022021",
    "type":"payout",
    "status":"success",
    "date":"2021-02-02T12:22:24+0000",
    "method":"card",
    "sum":{
      "amount":50,
      "currency":"EUR"
    },
    "actual_amount": 20,
    "description":""
  },
  "account":{
    "number":"431422******0056",
    "type":"visa",
    "card_holder":"JOHN DOE"
  },
  "customer":{
    "id":"0706"
  },
  "operation":{
    "id":99079010048031,
    "type":"payout",
    "status":"success",
    "date":"2021-02-02T12:22:24+0000",
    "created_date":"2021-02-02T12:22:22+0000",
    "request_id":"72dba48d05a-c80519e33ca93d-90",
    "sum_initial":{
      "amount":10,
      "currency":"EUR"
    },
    "sum_converted":{
      "amount":10,
      "currency":"EUR"
    },
    "code":"0",
    "message":"Success",
    "provider":{
      "id":414,
      "payment_id":"0020000025309274",
      "auth_code":"219705",
      "endpoint_id":414,
      "date":"2021-02-02T12:22:23+0000"
    }
  },
  "signature":"vVQBF25Pl+T4oYz0uYNKZXO/rSiEG4Ubeg=="
}

Figure: Callback example of a completed payout with split amount and currency conversion

{
  "project_id":51,
  "payment":{
    "id":"6_02022021",
    "type":"payout",
    "status":"success",
    "date":"2021-02-02T12:28:13+0000",
    "method":"card",
    "sum":{
      "amount":40,
      "currency":"USD"
    },
    "description":""
  },
  "account":{
    "number":"431422******0056",
    "type":"visa",
    "card_holder":"JOHN DOE"
  },
  "customer":{
    "id":"0706"
  },
  "operation":{
    "id":78330010048421,
    "type":"payout",
    "status":"success",
    "date":"2021-02-02T12:28:13+0000",
    "created_date":"2021-02-02T12:28:12+0000",
    "request_id":"8cf90a71b731b87d-ff50ef811046-031",
    "sum_initial":{
      "amount":16,
      "currency":"USD"
    },
    "sum_converted":{
      "amount":13,
      "currency":"EUR"
    },
    "code":"0",
    "message":"Success",
    "provider":{
      "id":414,
      "payment_id":"0010000025513643",
      "auth_code":"264443",
      "endpoint_id":414,
      "date":"2021-02-02T12:28:12+0000"
    }
  },
  "signature":"xoTV08v6S/owHnAPV=="
}

Figure: Callback example of a declined payout

 {
  "project_id":251,
  "payment":{
    "id":"02022021",
    "type":"payout",
    "status":"decline",
    "date":"2021-02-02T12:20:28+0000",
    "method":"card",
    "sum":{
      "amount":100,
      "currency":"EUR"
    },
    "description":""
  },
  "account":{
    "number":"431422******0056",
    "type":"visa",
    "card_holder":"JOHN DOE"
  },
  "customer":{
    "id":"0706"
  },
  "operation":{
    "id":75384010047551,
    "type":"payout",
    "status":"decline",
    "date":"2021-02-02T12:20:28+0000",
    "created_date":"2021-02-02T12:20:28+0000",
    "request_id":"14f0c88a0848998-00075385",
    "sum_initial":{
      "amount":100,
      "currency":"EUR"
    },
    "sum_converted":{
      "amount":100,
      "currency":"EUR"
    },
    "code":"3019",
    "message":"Exceeded count split operation",
    "provider":{
      "id":414,
      "payment_id":"",
      "endpoint_id":414
    }
  },
  "signature":"vrX0JIVGNEnqUJazUknfA6EaDtNZGmp=="
}