PaySystem¶

PaySystem enables payments usign following brokers:

Contents

Introduction¶

To integrate with TMS you need to have configured application in our system. To configure it you should contact with our support via email: USP@lst.onet.pl After succesful configuration you will recive following informations:

seller_id - Your ID in our system
list of ids of payment channels
secret_key for signing requests to pay-systems api
(optional) list of ids of paymet brokers

Requirements * Providing USP with list of products for sale with their sap material indexes * Setting up an API for notifications (which is described here - Notifications) and send to us an Endpoint Address - this is mandatory requirement. For details about notifications visit here.

Any product that the merchant wants to sell has to be registered by Accounting Department in order to receive the material index for the product. The product together with its material index has to be added in our system to enable the start of its sale.

Our API Endpoint paysystempub.tms.onetapi.pl

Generic transaction’s flow

Sandbox¶

It is possible that there will be prepared sandbox environment for testing development of the integration. On details about how to access the sandbox please contact USP team.

API method’s description¶

Interface: paysystem-public.tms.onetapi.pl

Methods available:

get_channels_list
set_transaction
get_action_and_data

get_channels_list¶

Optional method used to fetch available transparent payment channels and use to build dynamic payment options offered to the user

request params:

merchant_id	int	required	merchant identifier - PayPlatform configuration
agent_id	int	required	payment agent identifier - PayPlatform configuration
dist_channel_id	int	optional	distribution channel identifier - PayPlatform configuration. Default - WEB
secret	str	required	secret_key for signing requests to pay-systems api

response params:

status	boolean	states if the request was successful
channels	list	the available payments channels
agc_name	str	channel name
agc_desc	str	payment channels description
agc_img_url	str	url to image with payments logo (if available - configured by USP on merchant’s request)
aa_id	int	Payment channels identyfikator used within PaySystem (ex ‘channel_id’ from set_transaction)

get_channels_list request example¶

curl -X POST \
  http://paysystem.tms.onetapi.pl \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json-rpc' \
  -d '{
    "jsonrpc":"2.0",
    "id":"example",
    "method":"get_channels_list",
    "params":{
        "merchant_id":"181",
        "agent_id":"8083",
        "secret":"<secret-key>",
        "dist_channel_id":"1"
    }
}'

get_channels_list response example¶

{
   "id":"agc_app_get_by_id-1488289971788",
   "jsonrpc":"2.0",
   "result":{
      "channels":[
         {
            "agc_name":"PayU CARD (transparent)",
            "agc_desc":"Karta (transparent)",
            "agc_img_url":null,
            "aa_id":8505
         },
         {
            "agc_name":"PayU przelew mBank",
            "agc_desc":"Przelewy mTransfer",
            "agc_img_url":null,
            "aa_id":8489
         },
         {
            "agc_name":"PayU przelew PKO",
            "agc_desc":"Przelewy PKO",
            "agc_img_url":null,
            "aa_id":8491
         },
         {
            "agc_name":"PayU przelew Pekao",
            "agc_desc":"Przelewy Pekao",
            "agc_img_url":null,
            "aa_id":8490
         },
         {
            "agc_name":"PayU P\u0142atno\u015b\u0107 Testowa",
            "agc_desc":"P\u0142atno\u015b\u0107 testowa",
            "agc_img_url":null,
            "aa_id":8502
         }
      ],
      "status":1
   }
}

set_transaction¶

Method to request creation of a new transaction. Method operates in asynchronous manner, the response is given immediately and a positive status only means that the request has been accepted for farther processing.

To get the type of action and the parameters for it, one needs to call get_action_and_data method after calling set_transactions.

In case creating a transaction fails there will be no response on get_action_and_data and, if possible, there will be a notification delivered.

request params:

trans_ext_id	string	required	transaction external identifier, this ID is set by client’s system
seller_id	int	required	shop unique identifier - PayPlatform configuration, it is provided by USP
merchant_id	int	required	for some sellers their sale comes from various merchant, and in such case here can be provided id of the merchant. In other cases the value should be ‘1’
user_agreements	int	required	user agreements as binary sum. List of binary flags: 1 - Agreement with regulation, 2 - Agreement for data processing, 4 - Agreement for an immediate realization
invoice_series_id	int	required	invoice series identifier (1 receipt, 2 invoice, 0 non-fiscal)
payment	Payment object		payment details
articles	Articles object		articles details
customer	Customer object		customer details, (receipt / invoice)
next_url	string	optional	URL to redirect a user to after payment. If not set, a default from the PayPlatform configuration is used for redirection
secret	string	required	secret_key for signing requests to pay-systems api
shipping_address	Address object	optional	Optional address for shipping

Payment Object

channel_id	int	required	payment channel identification - PayPlatform configuration (aa_id from get_channel_list response)
amount	int	required	How much the product items is already payed. 0 if payment is to be started
currency	string	required	currency ISO code
validity_time	int	Optional	validity time (in seconds) of payments before it’s invalidated
config	Object	Optional	parameters specific for to a given payment method e.g. card_singleuse_token is required by card-registration payment type

Articles Object

prod_id	int	required	external product id
sap_index	int	required	SAP material index give to the product by Accounting Departament - PayPlatform configuration
vat_rate	float	required	VAT rate in percents
name	string	required	name of the product presented to the user
quantity	int	required	number of units
price	int	required	unit price gross, amount in decimal parts. e.g. 16 PLN - price: 1600
config	Object	optional	additional article configuration for farther use if required by the seller [ {"name": "conf_name1", "value": "conf_value1"}, {"name": "conf_name2", "value": "conf_value2"} ],

Customer Object

		receipt	invoice
ext_id	string	required	required	external user identification used by seller
company	string	optional	required	company name
firstname	string	optional	optional	first name
lastname	string	optional	optional	last name
email	string	required	required	email
street	string	optional	required	street
unit	string	optional	required	unit
flat	string	optional	optional	flat
city	string	optional	required	city
phone	string	optional	optional	phone number
country	string	optional	optional	country alpha 2 code
nip	string	optional	required	tax identification number

Address Object

		required
company	string	optional
firstname	string	optional	first name
lastname	string	optional	last name
email	string	optional	email
street	string	optional	street name
unit	string	optional	unit
flat	string	optional	flat no
city	string	optional	city
phone	string	optional	phone number

set_transaction example request¶

curl -X POST \
  http://paysystem.tms.onetapi.pl \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json-rpc' \
  -d '{
    "jsonrpc":"2.0",
    "id":"example",
    "method":"set_transaction",
    "params":{
        "trans_ext_id": "12345abwn",
        "seller_id": "34795",
        "merchant_id": "1",
        "user_agreements": "2",
        "invoice_series_id": "1",
        "payment":{
            "channel_id": "8089",
            "amount": "0",
            "currency": "PLN",
            "config": {
                "validity_time": 3600
            }
        },
        "articles":[
            {
                "prod_id": "1324",
                "sap_index": "1",
                "vat_rate": "23",
                "name": "test product",
                "quantity": "1",
                "price": "81",
                "config": [
                    {"name": "conf_name", "value": "conf_value"}
                ]
            }
        ],
        "customer":{
            "ext_id": "1234qwera",
            "company": "test",
            "firstname": "tester",
            "lastname": "testowski",
            "email": "test@test.pl",
            "street": "blotna",
            "city": "krakow",
            "phone": "48123456789",
            "postcode": "31-620",
            "country": "PL"
        },
        "client_ip": "127.0.0.1",
        "test": "True",
        "next_url": "http://onet.pl",
        "secret": "<secret-key>"
    }
}'

response:

status: boolean (the status only indicates that the request is accepted for the processing and it does not mean, that the order is created correctly. To find the status of order one needs to use get_action_and_data method or Notifications)

example: {“status”: “true”}

get_action_and_data¶

Method retrieving action to be performed to continue the payment transaction. The type of an action is determined by the selected payment channel (aa_id)

params:

order_ext_id	string	required	external transaction ID passed with a set_transaction call as trans_ext_id
secret	string	required	secret_key for signing requests to pay-systems api

response:

‘status’: boolean
‘action_type’: action to be performed to continue payment. supported types:
- TOKEN_PAYMENT
- CODE_PAYMENT
- CARD_REGISTERED
- REDIRECT_USER
- SMS_INVERTED

“data”: structure depending on action type

Example get_action_and_data request¶

curl -X POST \
  http://paysystem.tms.onetapi.pl \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json-rpc' \
  -d '{
    "jsonrpc":"2.0",
    "id":"example",
    "method":"get_action_and_data",
    "params":{
        "order_ext_id": "12345abwn",
        "secret":"<secret-key>"
    }
}'

Example get_action_and_data response with redirection¶

{
    "status": "true",
    "action": "REDIRECT_USER",
    "data": {
        "redirect_url": "<url-for-redirection>"
    }
}

for action REDIRECT_USER:

redirect_url - the url where the user has to be redirected to complete his payment

{
    "redirect_url": "<url-for-redirection>"
}

for action TOKEN_PAYMENT:

acces_key: card-access-key to be used for charging user’s card in the future

{
    "access_key": "<access-key>"
}

for action CARD_REGISTERED:

redirect_uri: thr URI where user has to be redirected to complete card registration status: the result of the registering of the user’s card eg. SUCESS if the card registration is complete, WARNING_CONTINUE_3DS if the user has to be redirected for 3ds verification

{
    "redirect_uri": "<url-for-redirection>",
    "status": "<agent-status ex:WARNING_CONTINUE_3DS>"
}

for action SMS_INVERTED:

sms_code: code the user has to send in SMS
sms_number: the number that the SMS has to be sent to

{
    "sms_code": "<sms-code>",
    "sms_number": "<sms-premium-number>"
}

Payments