PaySystem

PaySystem enables payments usign following brokers:

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

../../_images/pobrane.png

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

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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
   "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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
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
1
2
3
4
5
6
7
{
    "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>"
}