VulCode

Tpay integration through the Open API

Tpay transfers, BLIK, cards and refunds in a store, app or multi-seller platform. With the JWS signature checked on every notification and statuses you can trust.

Payment gateway comparison
A platform panel: order 7731 from three sellers paid with one Tpay payment and split into child transactions

What a Tpay integration is made of

From the checkout form to booking the payment. Every layer has its job and its test.

Before we start

  • You open the Tpay account and sandbox access as the merchant.
  • If the store runs on a popular platform, Tpay has a ready plugin for it and we start there.
  • Marketplace needs the Tpay Partner Programme and a separate agreement, so we settle that first.
  • We keep the client_id and client_secret in environment variables, never in code.
No IP list

Tpay publishes no IP list, because the addresses are dynamic. The signature is the only safeguard, so checking it is mandatory.

  1. Checkout and form

    • method choice
    • BLIK code field
    • recurring consent

    The customer picks BLIK and types the code, or agrees to recurring payments.

  2. Your server

    • OAuth token
    • POST /transactions
    • transaction stored on the order

    The server creates the transaction and stores it on the order.

  3. Tpay

    • payment page or BLIK Level 0
    • bank authorisation
    • settlement

    The customer authorises in the bank, and Tpay settles it.

  4. Notifications

    • JWS signature in X-JWS-Signature
    • certificate checked against the Tpay root CA

    The JWS signature is checked before anything changes.

    This is where the status is decided

  5. The order

    • status paid
    • refunds
    • event log

    The status paid and an entry in the event log.

Three ways to take BLIK with Tpay

BLIK can redirect the customer, stay on your page or remember the store for next time.

  • With a redirect

    the eBLIK form
    Where the code is entered
    on the Tpay form
    Field in the request
    groupId 150
    Customer stays in the store
    No
    Later purchases without a code
    No
    Good for
    the simplest start
    Confirmation
    in the banking app, a BLIK code is valid for 2 minutes

  • Level 0

    code on your page
    Where the code is entered
    in your form
    Field in the request
    blikToken with the code
    Customer stays in the store
    Yes
    Later purchases without a code
    No
    Good for
    phone purchases
    Confirmation
    in the banking app, a BLIK code is valid for 2 minutes

  • One Click

    an alias instead of a code
    Where the code is entered
    only on the first payment
    Field in the request
    the user alias
    Customer stays in the store
    Yes
    Later purchases without a code
    Yes
    Good for
    stores and apps with accounts
    Confirmation
    in the banking app, a BLIK code is valid for 2 minutes

Refunds: the status trap

Full and partial refunds behave differently in Tpay. Your panel has to add refunds up itself, not just read the transaction status.

A refund for order 10533 in a store panel: a second partial refund reaches 100% of the amount, a warning about the status and the checked Tpay balance
  • A partial refund reaches 100%The first refund covered one plate, the second the rest of the order, the whole amount together. For Tpay both are partial refunds.
  • The transaction status staysPartial refunds never change the status in Tpay, even at 100%. Your system counts the refunded amount, and only a full refund gives the refund status.
  • The balance checked firstA refund only goes through when the account balance covers the amount and the fee. The panel shows this before you order it.

A payment in the Tpay marketplace

One customer payment for products from several sellers. This is the flow in the marketplace API.

  1. Customer 02217.00 PLN

    A cart from three sellers, one payment.

    Your platform

    Tpay does not compare child amounts with product prices, so the platform checks them against the cart before it creates the transaction.

    80.00 + 73.00 + 64.00 = 217.00 PLN
    POST /marketplace/v1/transaction
  2. Tpay: the parent transaction217.00 PLN

    The customer pays once, and Tpay splits the amount into the sellers' child transactions.

  3. child transactions
    • Seller 0180.00 PLN
      • Soy candle 180 g x 2: 68.00 PLN
      • Delivery: 12.00 PLN
      Tpay account 01J9W3K8QZ…C0MD
    • Seller 0273.00 PLN
      • Linen towel 50 x 90 cm: 59.00 PLN
      • Delivery: 14.00 PLN
      Tpay account 01J9X0D4TR…KZ3W
    • Seller 0364.00 PLN
      • A5 dotted notebook x 3: 54.00 PLN
      • Delivery: 10.00 PLN
      Tpay account 01JA1R9C3N…HB5Z
The precondition
The marketplace only works within the Tpay Partner Programme and after a separate agreement.
Identifiers
Sellers and points of sale have ULID ids encoded in base32. We store them with the seller accounts.
The paid notification
With the value the platform gave the transaction, such as the order number.

Checklist before going live

What we check on the Tpay sandbox before you take the first real payment.

  • The payment path3
  • Notifications and refunds3

The payment path

  • The OAuth token and its renewal

    By default a token lives 2 hours. The module renews it before it expires instead of waiting for an error.

  • Redirect to transactionPaymentUrl

    The payment address comes back when the transaction is created. We never build it ourselves.

  • BLIK after the time runs out

    A code lives 2 minutes. We check the customer message and the retry path.

Notifications and refunds

  • The JWS signature on every notification

    With no IP list, the signature is the only proof a notification came from Tpay.

  • A repeated notification

    A second notice about the same payment must not activate a service or ship a parcel twice.

  • The partial refund counter

    The Tpay status does not say how much was refunded, so the panel counts it.

Common questions about Tpay

Answers about BLIK, the marketplace and notifications.

Do you sell alone or with other sellers?

Tell us where Tpay payments should work and whether you need a marketplace. We will reply within an hour with questions and a quote.