Skip to content
/
Retrieving transaction de...

simpay-api (1.0.0)

Polish version

Download OpenAPI description
index.json
index.yaml
Overview
URL

https://simpay.pl/kontakt

Support

kontakt@simpay.pl

Terms of Service

Languages
Servers
Mock server

https://docs.simpay.pl/_mock/en/apis/

https://api.simpay.pl/

SMS

Operations

DirectBilling

OperationsWebhooks

Online Payments

Operations

Generating a transaction

Request

Security
bearerAuth
Path
serviceIdstring(ServiceId)= 8 characters^[0-9a-f]{8}$required

Service ID

Bodyapplication/json
amountnumber(float)>= 1required

Transaction amount

currencystring

Transaction currency

Default "PLN"
descriptionstring<= 64 characters

Transaction description given by the partner, presented on the payment gateway

controlstring<= 255 characters

Field for use by the partner

customerobject or null

Basic information about the payer

antifraudobject or null

Information object for antifraud

billingobject or null(paymentCustomerFull)
shippingobject or null(paymentCustomerFull)
cartArray of objects or null(paymentCartItem)
returnsobject or null
directChannelstring

In this field you can send the channel ID, then the payer will be redirected directly to the page of the given channel For example, if you enter blik, you will be redirected directly to the BLIK payment gateway. In this case, it is necessary to send antifraud.useragent and customer.ip.

channelsArray of strings or null

Array with payment channel IDs that will be displayed to the payer on the gateway after redirection to the transaction url
A list of available channels along with their IDs can be obtained here Retrieving a list of channels for the service

channelTypesobject or null

Object in which we can define which channel types should be available on the payment gateway

refererstring[ 6 .. 64 ] characters
curl -i -X POST \
  'https://docs.simpay.pl/_mock/en/apis/payment/{serviceId}/transactions' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 1,
    "currency": "PLN",
    "description": "string",
    "control": "string",
    "customer": {
      "name": "string",
      "email": "user@example.com",
      "ip": "string",
      "countryCode": "PL"
    },
    "antifraud": {
      "useragent": "string",
      "steamid": 0,
      "mcusername": "string",
      "mcid": "string"
    },
    "billing": {
      "name": "string",
      "surname": "string",
      "street": "string",
      "building": "string",
      "flat": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "country": "string",
      "company": "string"
    },
    "shipping": {
      "name": "string",
      "surname": "string",
      "street": "string",
      "building": "string",
      "flat": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "country": "string",
      "company": "string"
    },
    "cart": [
      {
        "name": "string",
        "quantity": 1,
        "price": 0.01,
        "producer": "string",
        "category": "string",
        "code": "string"
      }
    ],
    "returns": {
      "success": "string",
      "failure": "string"
    },
    "directChannel": "string",
    "channels": [
      "string"
    ],
    "channelTypes": {
      "blik": true,
      "transfer": true,
      "cards": true,
      "ewallets": true,
      "paypal": true,
      "paysafe": true,
      "latam": true
    },
    "referer": "string"
  }'

Responses

Bodyapplication/json
successbooleanrequired

Request status

Example: true
dataobjectrequired
Example: {"transactionId":"1d87a1b3-18f8-4146-bcb1-c0c9f293b04f","redirectUrl":"https://pay.simpay.pl/1d87a1b3-18f8-4146-bcb1-c0c9f293b04f"}
data.​transactionIdstring(uuid)(TransactionId)= 36 characters^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...required

Transaction ID

data.​redirectUrlstring(url)required
Example: "https://pay.simpay.pl/1d87a1b3-18f8-4146-bcb1-c0c9f293b04f"
Response
application/json
{
  "success": true,
  "data": {
    "transactionId": "1d87a1b3-18f8-4146-bcb1-c0c9f293b04f",
    "redirectUrl": "https://pay.simpay.pl/1d87a1b3-18f8-4146-bcb1-c0c9f293b04f"
  }
}

Retrieving transaction details

Request

Security
bearerAuth
Path
serviceIdstring(ServiceId)= 8 characters^[0-9a-f]{8}$required

Service ID

transactionIdstring(uuid)(TransactionId)= 36 characters^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...required

Transaction ID

curl -i -X GET \
  'https://docs.simpay.pl/_mock/en/apis/payment/{serviceId}/transactions/{transactionId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Bodyapplication/json
successbooleanrequired

Request status

Example: true
dataobjectrequired
Example: {"id":"328bd42d-d08b-43f6-9463-869e5bd32b4","payer_transaction_id":"477YDX14","status":"transaction_paid","amount":{"value":7.55,"currency":"BRL","commission":0.12,"commission_currency":"EUR","original":{"value":5,"currency":"PLN","pln_rate":1}},"channel":"nest","control":null,"description":null,"redirect":{"success":null,"failure":null},"customer":{"name":null,"email":"kontakt@simpay.pl","ip":"192.168.0.1","country":"PL"},"billing":{"name":null,"surname":null,"street":null,"building":null,"flat":null,"city":null,"region":null,"postalCode":null,"country":null,"company":null},"shipping":{"name":null,"surname":null,"street":null,"building":null,"flat":null,"city":null,"region":null,"postalCode":null,"country":null,"company":null},"cart":null,"paid_at":"2023-12-07T05:21:50+01:00","expires_at":null,"created_at":"2023-12-07T05:20:30+01:00","updated_at":"2023-12-07T05:21:50+01:00"}
data.​idstring(uuid)(TransactionId)= 36 characters^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...required

Transaction ID

data.​payer_transaction_idstringrequired

Transaction identifier shared with the payer

Example: "477YDX14"
data.​statusstring(paymentTransactionStatus)required

Transaction status

Enum"transaction_new""transaction_confirmed""transaction_generated""transaction_paid""transaction_failure""transaction_expired""transaction_canceled""transaction_refunded""transaction_fraud""transaction_fraud_possibility"
data.​amountobjectrequired
Example: {"value":7.55,"currency":"BRL","commission":0.12,"commission_currency":"EUR","original":{"value":5,"currency":"PLN","pln_rate":1}}
data.​amount.​valuenumber(float)required

Payment amount in the buyer's currency

Example: 7.55
data.​amount.​currencystring(ISO-4217)required

Buyer's currency

Example: "BRL"
data.​amount.​commissionnumber or null(float)required

SimPay's commission amount

Example: 0.12
data.​amount.​commission_currencystring(ISO-4217)required

Commission currency (PLN/EUR)

Example: "EUR"
data.​amount.​originalobject

Original amounts declared at initiation

Example: {"value":5,"currency":"PLN","pln_rate":1}
data.​channelstring or nullrequired
Example: "nest"
data.​controlstring or nullrequired
data.​descriptionstring or nullrequired
data.​redirectobjectrequired
Example: {"success":null,"failure":null}
data.​redirect.​successstring or null(url)required
data.​redirect.​failurestring or null(url)required
data.​customerobjectrequired
Example: {"name":null,"email":"kontakt@simpay.pl","ip":"192.168.0.1","country":"PL"}
data.​customer.​namestring or nullrequired
data.​customer.​emailstring or null(email)required
Example: "kontakt@simpay.pl"
data.​customer.​ipstring or null(ip)
Example: "192.168.0.1"
data.​customer.​countrystring or null(CountryCode)
Example: "PL"
data.​billingobject or null(paymentCustomerFull)required
data.​billing.​namestring or null[ 5 .. 64 ] charactersrequired
data.​billing.​surnamestring or null<= 64 charactersrequired
data.​billing.​streetstring or null<= 64 charactersrequired
data.​billing.​buildingstring or null<= 16 characters
data.​billing.​flatstring or null<= 16 characters
data.​billing.​citystring or null<= 32 charactersrequired
data.​billing.​regionstring or null<= 32 characters
data.​billing.​postalCodestring or nullrequired

Postal code, format depends on the country field

data.​billing.​countrystring or null(ISO 3166-1 alpha-2)required

Country

data.​billing.​companystring or null

Company name

data.​shippingobject or null(paymentCustomerFull)required
data.​shipping.​namestring or null[ 5 .. 64 ] charactersrequired
data.​shipping.​surnamestring or null<= 64 charactersrequired
data.​shipping.​streetstring or null<= 64 charactersrequired
data.​shipping.​buildingstring or null<= 16 characters
data.​shipping.​flatstring or null<= 16 characters
data.​shipping.​citystring or null<= 32 charactersrequired
data.​shipping.​regionstring or null<= 32 characters
data.​shipping.​postalCodestring or nullrequired

Postal code, format depends on the country field

data.​shipping.​countrystring or null(ISO 3166-1 alpha-2)required

Country

data.​shipping.​companystring or null

Company name

data.​cartArray of objects or null(paymentCartItem)required
data.​cart[].​namestring[ 3 .. 64 ] charactersrequired

Product name

data.​cart[].​quantitynumber(integer)>= 1required

Quantity of the product

data.​cart[].​pricenumber(float)>= 0.01required

Price of one product

data.​cart[].​producerstring or null<= 64 charactersrequired

Product brand

data.​cart[].​categorystring or null<= 64 charactersrequired

Product category

data.​cart[].​codestring or null<= 64 charactersrequired

Product code

data.​paid_atstring(date-time)(DateTime)required

Creation date in format: ISO 8601

data.​expires_atstring(date-time)(DateTime)required

Creation date in format: ISO 8601

data.​created_atstring(date-time)(DateTime)required

Creation date in format: ISO 8601

data.​updated_atstring(date-time)(DateTime)required

Creation date in format: ISO 8601

Response
application/json
{
  "success": true,
  "data": {
    "id": "328bd42d-d08b-43f6-9463-869e5bd32b4",
    "payer_transaction_id": "477YDX14",
    "status": "transaction_paid",
    "amount": { … },
    "channel": "nest",
    "control": null,
    "description": null,
    "redirect": { … },
    "customer": { … },
    "billing": { … },
    "shipping": { … },
    "cart": null,
    "paid_at": "2023-12-07T05:21:50+01:00",
    "expires_at": null,
    "created_at": "2023-12-07T05:20:30+01:00",
    "updated_at": "2023-12-07T05:21:50+01:00"
  }
}

Retrieve a list of refunds for a transaction

Request

Security
bearerAuth
Path
serviceIdstring(ServiceId)= 8 characters^[0-9a-f]{8}$required

Service ID

transactionIdstring(uuid)(TransactionId)= 36 characters^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...required

Transaction ID

curl -i -X GET \
  'https://docs.simpay.pl/_mock/en/apis/payment/{serviceId}/transactions/{transactionId}/refunds' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Bodyapplication/json
successbooleanrequired

Request status

Example: true
dataArray of objectsrequired
Example: [{"id":"019483a5-885e-70f7-9b5b-94387a6690da","status":"refund_completed","amount":1,"currency":"PLN","wallet_amount":1,"wallet_currency":"PLN","created_at":"2025-01-20T13:17:31+01:00","updated_at":"2025-01-20T13:17:59+01:00"}]
data[].​idstring(uuid)(RefundId)= 36 characters^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...required

Refund ID

data[].​statusstring(paymentTransactionRefundStatus)required

Refund status

Enum"refund_new""refund_pending""refund_completed""refund_rejected""refund_failed"
data[].​amountnumber(float)required

Refund amount in the payer's currency

data[].​currencystring= 3 charactersrequired

Payer's currency

data[].​wallet_amountnumber(float)required

Refund amount deducted from the wallet

data[].​wallet_currencystring= 3 charactersrequired

Wallet currency

data[].​created_atstring(date-time)(DateTime)required

Creation date in format: ISO 8601

data[].​updated_atstring(date-time)(DateTime)required

Creation date in format: ISO 8601

Response
application/json
{
  "success": true,
  "data": [
    { … }
  ]
}
© 2025 Payments Solution Sp. z o.o. - All rights reserved.