Mass Collect

1 Introduction

Joe Public would like to pay his electricity bill. He logs in to an online system of his electricity provider. He selects PayU payment provider to make the payment by card or pay-by-link. PayU transfers the payment to a Joe Public’s individual account created in the electricity provider’s system. Then the electricity provider’s billing system records the funds to the Joe Public’s individual account.

2 Service integration

2.1 Order with one payment account

Mass Collect is based on regular PayU integration involving REST API described in: Creating a new order. The targetAccount field serves as the extension. It is added to the OrderCreateRequest message that provides PayU with the user’s individual account to transfer the funds.

Sample order with basic buyer details, external identifier (extOrderId) and target account (targetAccount):

                    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":"[generateExtOrderId]",
                        "targetAccount":"PL23080049181648726886601824",
                        "products":[
                            {
                                "name":"Invoice payment",
                                "unitPrice":"15000",
                                "quantity":"1"
                            }
                        ],
                        "buyer": {
                            "email": "john.doe@example.com",
                            "phone": "654111654",
                            "firstName": "John",
                            "lastName": "Doe"
                        }
                    }'
                

Authentication methods are described in: Signing API calls parameters.

2.2 Order with many payment accounts

Mass Collect is based on regular PayU integration involving REST API described in: Creating a new order.. The targetAccounts list serves as the extension. It is added to the OrderCreateRequest message that provides PayU with the user’s individual accounts to transfer the funds (maximum number of individual accounts in targetAccounts list is 5).

Sample order with basic buyer details, external identifier (extOrderId) and three target accounts (targetAccounts):

                    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":"[generateExtOrderId]",
                        "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"
                        }
                    }'
                
Data validation:
  • total payment (totalAmount) is equal to sum of indicated amounts for target accounts,
  • all used accounts are counted as permitted, i.e. they were listed by PayU on accounts whitelist,
  • there are at most three accounts on targetAccounts list,
  • number of accounts and products from section products don’t have to be equal; such option enables possibility to agregate payments from individual products or split user's payment into internal subaccounts, as well as external accounts
Payments are titled in accordance to set template. Details can be found in the "Payout titles" point. Additionally attribute targetAccounts.description will be added to the defining payment title template. Thanks to this attribute every title can be named individually. Incoming operation titles (payments to the bank accounts given in the Order) for above specified Order, for template:
                    description(40characters),targetAccounts.description(40characters),buyer's details(40characters)
are presented as follows:
  • 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

It should be noted that three bank accounts are used in this example, because of this there will be three different bank statements.

Authentication methods can be found at: User's API authentication.

Specific error codes:

StatusCode Code CodeLiteral Opis
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.

2.3 Payout titles

PayU may set payout title basing on data received in Order or/and data received from bank.

Examples of payout titles for pay-by-links:
  • Invoice payment 1111/01/02/2017,John Doe
  • Invoice payment 1111/01/02/2017,Sussana Doe ul. Ptasia 89 Opole
Examples of payout titles for cards and blik payment:
  • Invoice payment 1111/01/02/2017

It must be clearly stated, that 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). Details:
  • 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 which can be set in payout template:
  • description (data source: Order),
  • name and surname of the payer (data source: Bank),
  • address of the payer (data source: Bank),
  • bank account number of the payer (data source: Bank),
  • transaciton id (data source: transaction),
  • payout description for chosen account (targetAccounts.description field).

Specific payout title needs configuration at PayU side.

2.4 PayU configuration

The Mass Collect service requires configuration operations to be performed at PayU. Therefore, when you start the integration process, please contact PayU via your account manager.