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:
-
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 is5,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. -
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 is5,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 is1,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 paiddecline—the entire amount of the payment has not been paid and there are no cascading attempts left or setpartially 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 passedcurrency—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 thesaleorcaptureoperation, always passedamount_authorized—the actual amount that was previously authorised by theauthoperation, can either be confirmed by thecaptureoperation or cancelled by thecanceloperation, passed only if the two-step purchase is performedamount_remaining_refund—the amount available for refund to the customer, passed only for payments with the statuspartially paidorsuccess.
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 EURand with the provider's limit of10.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 is0.01 EUR. The amount available for refund is10.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 EURand with the provider's limit of25.00 EUR.The following is the example of a callback with the information about a two-step purchase with the amount
40.27 EURpartially paid by the customer, and the amount of the operation to which the callback was sent is25.00 EUR. The payment statusprocessingmeans that the amount of20.27 EURstill 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 is20.27 EUR. The payment statusawaiting capturemeans that there is an amount already confirmed and paid—25.00 EUR, and the amount of20.27 EURstill 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 is20.27 EUR. The payment statuspartially paidmeans 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 of20.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 outdecline—the entire amount of the payment has not been paid out and there are no available cascading attempts leftpartially 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 paymentcurrency—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=="
}