Skip to main content

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
StatusCodeCodeCodeLiteralDescription
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:

  • 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
AttributesSource
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.