PayGateway¶

Introduction¶

PayGateway module is a type of payment gateway that acts as an intermediary between the buyer and the seller, ensuring smooth payment for various services or products. This module adds a flexible frontend layer to TMS, which allows for:

selecting a payment method
collecting additional invoice data
tokenizing the card for recurring payments
collecting additional delivery address

Onet Konto supports the display of subscriptions and one-time payments made using the PayGateway service. You can also view and manage your subscriptions from one place. Additionally, in the future, you will be able to use the Onet Konto payment wallet integrated with multiple Onet portals.

The transaction flow begins when the user clicks ‘Pay’ in your store. Your service then generates a payload and sends it via POST to ‘init_transaction.’ In the next step, the user is redirected to the PayGateway page, where you can see a summary of their purchase, choose a payment method, and optionally provide invoice details etc. Then PayGateway creates a transaction in the TMS, and the user is redirected to the chosen payment operator’s page, where the payment can be completed. After the payment is completed, the user is redirected to the URL provided in the payload. In background, a notification containing payment status information is asynchronously sent to your store. [1]

Environments¶

PROD: https://payment.onet.pl

Live demo¶

https://demo-payment.ringieraxelspringer.dev/

Public methods¶

(POST) https://payment.onet.pl/api/v1/init_transaction/<merchant_id>¶

All requests will be sent in JWE format, encoding with A256KW + A256CBC-HS512 alghorithm. We deliver you secret_key and merchant_id which allow you to encrypt and send a request. An encrypted payload you must send as JSON object in encrypted_payload property as below:

JSON structure¶

{
    "encrypted_payload": "<your_encrypted_payload>"
}

More information about how to prepare a payload you can find in the FAQ section

The table below shows the structure of the object that allows you to set up a new transaction.

init_transaction payload structure:¶
Name	Type	Required	Description	Info
trans_ext_id	string	Y	transaction external identifier, this ID is set by client’s system
is_subscription	boolean	N	indicates whether transaction is subscription or one time payment
invoice_required	boolean	N	indicates that invoice should be generated
payment	object	Y	Object - payment details: channel_id: number \| number[] - payment channel identification: PayPlatform configuration (aa_id from get_channel_list response). It may be null, then PG will show a form to choose a payment method amount: number (required): how much the product items is already payed. 0 if payment is to be started currency: string (required): currency ISO code config: Object (optional): parameters specific for to a given payment method e.g. card_singleuse_token is required by card-registration payment type ext_id: string (optional): external id of payments	config may be empty
articles	list of objects	Y	Object - article details: prod_id: number (required): external product id sap_index: number (required): SAP material index give to the product by Accounting Departament - PayPlatform configuration vat_rate: number (required): VAT rate in percents name: string (required): name of the product presented to the user quantity: number (required): number of units price: number (required): unit price gross, amount in decimal parts. e.g. 16 PLN - price: 1600 config: list of dicts: (optional) - json - additional article configuration for farther use if required by the merchant base_price: number: (required) - base unit price gross, amount in decimal parts. e.g. 16 PLN - price: 1600
customer	object	Y	Object - customer details: ext_id: string (required / required): user identification for merchant company: string (optional / required): firstname: string (optional / required): lastname: string (optional / required): email: string (required / required): street: string (optional / required): unit: string (optional / required): flat: string (optional / required): city: string (optional / required): phone: string (optional / required): postcode: string (optional / required): country: string (optional): example {“country”: “PL”} nip: string (optional / required): tax identification number, (only digits without mask)	ext_id is required for all type of trans email is required for all type of tran country is required, PL by default
next_url	string	Y	URL to redirect a user to after payment. If not set, a default from the PayPlatform configuration is used for redirection
config	object	N	Additional configuration: “custom_notify_url”: “http://your.domain/order/notify” “piano_subscription_id”: (string) - id of subscription in Piano “shipping_address_required” (boolean) - indicates whether PG should gather delivery address data	config may be empty
locale	string	N	Language of messages	eg. pl
extras	object	N	If you want to pass any extra data to PG, please use this field

Response:

If SUCCESS (depending on parameters and configuration) redirect (http 302) to:

PayGateway page
direct to payment operator page

If FAILED api returns JSON with (http error code 400):

status (int) : 0 = success, !=0 if failure message (string)

Payments