Mass Collect

When a customer intends to pay their utility bill, they access the utility's online platform. Within this system, they opt for PayU as their payment provider and proceed to make the payment using either a card or pay-by-link method. PayU facilitates the transfer of the payment to the individual account set up in the utility's system for the customer. Subsequently, the utility's billing system registers the received funds in the customer's designated individual account.

The scenario outlined above serves as an illustration of when enabling Mass Collect on your website becomes advantageous. PayU | Mass Collect empowers your customers to initiate payments directly to the designated individual account associated with the respective service. This solution proves particularly beneficial for various sectors including telecommunication companies, cable TV operators, internet providers, energy providers, as well as leasing and insurance companies.

Configuration

Configuring the Mass Collect service involves specific configuration that need to be set-up within the PayU system. To initiate this process, please get in touch with PayU through your account manager as you start the integration process.

Creating an Order

Single Payment Account

For Mass Collect transactions involving a single account, you should extend the standard request body to include the additional targetAccount field. Including this field in the request body will enable PayU to access the user's specific account for transferring the funds.

Request Example for Mass Collect Order - Single Account
curl -v -X POST https://secure.payu.com/api/v2_1/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 0089270b-5027-42f1-8f51-8a47fe99d9cd" \
-d '{
    "notifyUrl":"https://your.eshop.com/notify",
    "customerIp":"127.0.0.1",
    "merchantPosId":"199022",
    "description":"Invoice payment ",
    "additionalDescription":"1111/01/02/2017",
    "currencyCode":"PLN",
    "totalAmount":"15000",
    "extOrderId":"tlmnkfqdjc7irodvbs4gb6",
    "targetAccount":"PL23080049181648726886601824",
    "products":[
        {
            "name":"Invoice payment",
            "unitPrice":"15000",
            "quantity":"1"
        }
    ],
    "buyer": {
        "email": "john.doe@example.com",
        "phone": "654111654",
        "firstName": "John",
        "lastName": "Doe"
    }
}'

For details on parameters, please refer to the Create an Order section in our API Reference.

Multiple Payments Accounts

For Mass Collect transactions where a multiple accounts are specified, you should extend the standard request body to include the additional targetAccounts field. Including this field in the request body will enable PayU to access the users specific accounts for transferring the funds (maximum number of individual accounts in targetAccounts list is 50).

Sample Mass Collect Order - Multiple Accounts
curl -v -X POST https://secure.payu.com/api/v2_1/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 0089270b-5027-42f1-8f51-8a47fe99d9cd" \
-d '{
    "notifyUrl":"https://your.eshop.com/notify",
    "customerIp":"127.0.0.1",
    "merchantPosId":"199022",
    "description":"Payment for ",
    "additionalDescription":"gas, electricity",
    "currencyCode":"PLN",
    "totalAmount":"15000",
    "extOrderId":"2hqio1g5ruqpzwcbilogbu",
    "targetAccounts":[
        {
            "account":"PL23080049181648726886601824",
            "amount":"5000",
            "description":"Internal payment distribution AAA"
        },
        {
            "account":"PL83520640964843486631050632",
            "amount":"8000",
            "description":"Internal payment distribution BBB"
        },
        {
            "account":"PL42718382961584083942417177",
            "amount":"2000",
            "description":"Internal payment distribution CCC"
        }
    ],
    "products":[
        {
            "name":"Invoice payment XXX",
            "unitPrice":"10000",
            "quantity":"1"
        },
        {
            "name":"Invoice payment YYY",
            "unitPrice":"5000",
            "quantity":"1"
        }
    ],
    "buyer": {
        "email": "john.doe@example.com",
        "phone": "654111654",
        "firstName": "John",
        "lastName": "Doe"
    }
}'

For details on parameters, please refer to the Create an Order section in our API Reference.

Request Data Validation

Total payment (totalAmount) must be equal to sum of indicated amounts for target accounts.
All used accounts must be counted as permitted, i.e. they were listed by PayU on accounts whitelist.
The targetAccounts list cannot contain more than 50 accounts.
The number of accounts and products from products section doesn't have to be equal; this option allows to agregate payments from individual products or split user's payment into internal sub-accounts, as well as external accounts.

Payments are titled according to the specified template, details of which details can be found in the Payout Titles section. To distinguish different payments within the scope of a single request, a targetAccounts.description parameter is also added to the payment title.

Template for the Payout Title
description(<40characters),targetAccounts.description(<40characters),buyer's details(<40characters)

Based on the provided template, the operation titles for the aforementioned sample request body are:

Payment for gas, electricity, Internal payment distribution AAA, Jan Nowak ul.Polna 1 61-051 Opole
Payment for gas, electricity, Internal payment distribution BBB, Jan Nowak ul.Polna 1 61-051 Opole
Payment for gas, electricity, Internal payment distribution CCC, Jan Nowak ul.Polna 1 61-051 Opole

Notes

Since three bank accounts are used in this example, there will be three different bank statements.

Testing Mass Collect

You can test the Mass Collect service on a sandbox environment by using a dedicated POS:

Test POS with Mass Collect Service Enabled
POS ID (pos_id):                    478674
Second key (MD5):                   eaab0d1f51b99f77e4ebc6fe368c252e
OAuth protocol - client_id:         478674
OAuth protocol - client_secret:     3152a46e0d28ff0e3fa528c0fba48550

Error Codes

Error Codes Specific for Mass Collect

StatusCode	Code	CodeLiteral	Description
ERROR_VALUE_MISSING	MISSING_TARGET_ACCOUNT	8093	Target account is required for a POS with the Mass Collect functionality configured.
ERROR_VALUE_INVALID	TARGET_ACCOUNT_NOT_ON_WHITELIST	8308	Target account is not on the whitelist.
ERROR_VALUE_INVALID	TOO_MANY_ITEMS_IN_TARGET_ACCOUNTS	8312	Too many items in `targetAccounts` list.

Payout Titles

PayU can set the payout title using data derived from both the sent request and information obtained from the bank.

Examples of payout titles for:

pay-by-link
Cards and BLIK

Invoice payment 1111/01/02/2017,John Doe
Invoice payment 1111/01/02/2017,Sussana Doe ul. Ptasia 89 Opole

Notes

Actual data depends on bank used in payment process. Special characters can be substituted by PayU bank and target bank.

Above examples were created basing on defined at PayU side template: description(60 characters), separator(coma), Payer data(60 characters). Where:

Order.description(trimmed to 50 characters) + Order.additionalDescription(trimmed to 50 characters), then it is trimmed to 60 characters,
coma,
Payer's name and surname received from bank (sometimes also address), trimmed to 60 characters. Empty for cards and blik payments.

Attributes That an be Set in the Payout Template

Attributes	Source
description	OrderCreateRequest
name and surname of the payer	bank
address of the payer	bank
bank account number of the payer	bank
transaciton id	transaction
payout description for chosen account	`targetAccounts.description` field in OrderCreateRequest

Notes

Specific payout title needs configuration at PayU side.

Creating an Order​

Single Payment Account​

Multiple Payments Accounts​

Testing Mass Collect​

Error Codes​

Payout Titles​

On this page

Creating an Order

Single Payment Account

Multiple Payments Accounts

Testing Mass Collect

Error Codes

Payout Titles