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.

../../_images/paygateway_1.png

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

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)

See also