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
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) |
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" } }' |
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 details |
||
articles |
articles details |
||
customer |
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 |
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 |
string |
required |
required |
||
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 |
string |
optional |
||
street |
string |
optional |
street name |
unit |
string |
optional |
unit |
flat |
string |
optional |
flat no |
city |
string |
optional |
city |
phone |
string |
optional |
phone number |
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
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>" } }' |
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>"
}