Przejdź do treści
Online Payments
/
Retrieving a list of channels for the service

simpay-api (1.0.0)

Polish version

Pobierz opis OpenAPI
index.json
index.yaml
Przegląd
URL

https://simpay.pl/kontakt

Support

kontakt@simpay.pl

Warunki świadczenia usług

Języki
Serwery
Mock server

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

https://api.simpay.pl/

SMS

Operacje

DirectBilling

OperacjeWebhooki

Online Payments

Operacje

Retrieving a list of services

Żądanie

Bezpieczeństwo
bearerAuth
curl -i -X GET \
  https://docs.simpay.pl/_mock/en/apis/payment \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Odpowiedzi

Treśćapplication/json
successbooleanwymagany

Request status

Przykład: true
dataArray of objectswymagany
Przykład: [{"id":"d151e4f9","name":"Test service","status":"service_active","created_at":"2021-11-08T18:19:16+01:00"}]
data[].​idstring(ServiceId)= 8 characters^[0-9a-f]{8}$wymagany

Service ID

data[].​namestringwymagany

Service name

data[].​statusstring(ServiceStatus)wymagany

Service Status

Enum"service_new""service_active""service_blocked""service_rejected""service_verify""service_ongoing_registration"
data[].​created_atstring(date-time)(DateTime)wymagany

Creation date in format: ISO 8601

paginationobject(Pagination)wymagany
pagination.​totalintegerwymagany

Total number of records

Przykład: 1
pagination.​countintegerwymagany

Number of records on the current page

Przykład: 1
pagination.​per_pageintegerwymagany

Maximum number of records per page

Przykład: 15
pagination.​current_pageintegerwymagany

Current page

Przykład: 1
pagination.​total_pagesintegerwymagany

Total number of pages

Przykład: 1
pagination.​linksobjectwymagany

URLs to pages

pagination.​links.​next_pagestring or null(url)wymagany

URL to the next page

Przykład: null
pagination.​links.​prev_pagestring or null(url)wymagany

URL to the previous page

Przykład: null
Odpowiedź
application/json
{
  "success": true,
  "data": [
    { … }
  ],
  "pagination": {
    "total": 1,
    "count": 1,
    "per_page": 15,
    "current_page": 1,
    "total_pages": 1,
    "links": { … }
  }
}

Retrieving service details

Żądanie

Bezpieczeństwo
bearerAuth
Ścieżka
serviceIdstring(ServiceId)= 8 characters^[0-9a-f]{8}$wymagany

Service ID

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

Odpowiedzi

Treśćapplication/json
successbooleanwymagany

Request status

Przykład: true
dataobjectwymagany
Przykład: {"id":"d151e4f9","name":"Test service","status":"service_active","created_at":"2021-11-08T18:19:16+01:00"}
data.​idstring(ServiceId)= 8 characters^[0-9a-f]{8}$wymagany

Service ID

data.​namestringwymagany

Service name

Przykład: "Test service"
data.​statusstring(ServiceStatus)wymagany

Service Status

Enum"service_new""service_active""service_blocked""service_rejected""service_verify""service_ongoing_registration"
data.​created_atstring(date-time)(DateTime)wymagany

Creation date in format: ISO 8601

Odpowiedź
application/json
{
  "success": true,
  "data": {
    "id": "d151e4f9",
    "name": "Test service",
    "status": "service_active",
    "created_at": "2021-11-08T18:19:16+01:00"
  }
}

Retrieving a list of channels for the service

Żądanie

Bezpieczeństwo
bearerAuth
Ścieżka
serviceIdstring(ServiceId)= 8 characters^[0-9a-f]{8}$wymagany

Service ID

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

Odpowiedzi

Treśćapplication/json
successbooleanwymagany

Request status

Przykład: true
dataArray of objectswymagany
Przykład: [{"id":"blik","name":"BLIK","type":"blik","img":"https://img.simpay.pl/transfer/banks/blik.png","commission":1.5,"currencies":["PLN"],"amount":{"min":1,"max":20000}},{"id":"mbank","name":"mBank","type":"transfer","img":"https://img.simpay.pl/transfer/banks/mbank.png","commission":1.5,"currencies":["PLN"],"amount":{"min":1,"max":20000}}]
data[].​idstringwymagany

Payment channel ID

data[].​namestringwymagany

Channel name

data[].​typestringwymagany

Channel type

data[].​imgstring(url)wymagany

URL to the payment channel graphic

data[].​commissionnumber(float)wymagany

Commission charged by SimPay from the payment

data[].​currenciesArray of stringswymagany

Array of available currencies

data[].​amountobjectwymagany

Amounts available for the channel

data[].​amount.​minnumber(float)

Minimum payment amount

data[].​amount.​maxnumber(float)

Maximum payment amount

Odpowiedź
application/json
{
  "success": true,
  "data": [
    { … },
    { … }
  ]
}

Retrieving a list of transactions

Żądanie

Bezpieczeństwo
bearerAuth
Ścieżka
serviceIdstring(ServiceId)= 8 characters^[0-9a-f]{8}$wymagany

Service ID

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

Odpowiedzi

Treśćapplication/json
successbooleanwymagany

Request status

Przykład: true
dataArray of objectswymagany
Przykład: [{"id":"528bd43f-d08a-43f5-9462-861e54db37bf","status":"transaction_paid","amount":24.99,"control":null,"channel":"nest","paid_at":"2023-12-07T05:21:50+01:00","created_at":"2023-12-07T05:20:30+01:00","updated_at":"2023-12-07T05:21:50+01:00"},{"id":"0238d92e-0dd9-469a-9aa9-0505974336a3","status":"transaction_paid","amount":24.99,"control":null,"channel":"blik","paid_at":"2023-12-07T06:21:50+01:00","created_at":"2023-12-07T06:20:30+01:00","updated_at":"2023-12-07T06: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]...wymagany

Transaction ID

data[].​statusstring(paymentTransactionStatus)wymagany

Transaction status

Enum"transaction_new""transaction_confirmed""transaction_generated""transaction_paid""transaction_failure""transaction_expired""transaction_canceled""transaction_refunded"
data[].​amountnumber(float)wymagany
data[].​controlstringwymagany
data[].​channelstringwymagany
data[].​paid_atstring(date-time)(DateTime)wymagany

Creation date in format: ISO 8601

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

Creation date in format: ISO 8601

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

Creation date in format: ISO 8601

paginationobject(Pagination)wymagany
pagination.​totalintegerwymagany

Total number of records

Przykład: 1
pagination.​countintegerwymagany

Number of records on the current page

Przykład: 1
pagination.​per_pageintegerwymagany

Maximum number of records per page

Przykład: 15
pagination.​current_pageintegerwymagany

Current page

Przykład: 1
pagination.​total_pagesintegerwymagany

Total number of pages

Przykład: 1
pagination.​linksobjectwymagany

URLs to pages

pagination.​links.​next_pagestring or null(url)wymagany

URL to the next page

Przykład: null
pagination.​links.​prev_pagestring or null(url)wymagany

URL to the previous page

Przykład: null
Odpowiedź
application/json
{
  "success": true,
  "data": [
    { … },
    { … }
  ],
  "pagination": {
    "total": 2,
    "count": 2,
    "per_page": 15,
    "current_page": 1,
    "total_pages": 1,
    "links": { … }
  }
}

Generating a transaction

Żądanie

Bezpieczeństwo
bearerAuth
Ścieżka
serviceIdstring(ServiceId)= 8 characters^[0-9a-f]{8}$wymagany

Service ID

Treśćapplication/json
amountnumber(float)>= 1wymagany

Transaction amount

currencystring

Transaction currency

Domyślny "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"
  }'

Odpowiedzi

Treśćapplication/json
successbooleanwymagany

Request status

Przykład: true
dataobjectwymagany
Przykład: {"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]...wymagany

Transaction ID

data.​redirectUrlstring(url)wymagany
Przykład: "https://pay.simpay.pl/1d87a1b3-18f8-4146-bcb1-c0c9f293b04f"
Odpowiedź
application/json
{
  "success": true,
  "data": {
    "transactionId": "1d87a1b3-18f8-4146-bcb1-c0c9f293b04f",
    "redirectUrl": "https://pay.simpay.pl/1d87a1b3-18f8-4146-bcb1-c0c9f293b04f"
  }
}

Retrieving transaction details

Żądanie

Bezpieczeństwo
bearerAuth
Ścieżka
serviceIdstring(ServiceId)= 8 characters^[0-9a-f]{8}$wymagany

Service ID

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

Transaction ID

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

Odpowiedzi

Treśćapplication/json
successbooleanwymagany

Request status

Przykład: true
dataobjectwymagany
Przykład: {"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]...wymagany

Transaction ID

data.​payer_transaction_idstringwymagany

Transaction identifier shared with the payer

Przykład: "477YDX14"
data.​statusstring(paymentTransactionStatus)wymagany

Transaction status

Enum"transaction_new""transaction_confirmed""transaction_generated""transaction_paid""transaction_failure""transaction_expired""transaction_canceled""transaction_refunded"
data.​amountobjectwymagany
Przykład: {"value":7.55,"currency":"BRL","commission":0.12,"commission_currency":"EUR","original":{"value":5,"currency":"PLN","pln_rate":1}}
data.​amount.​valuenumber(float)wymagany

Payment amount in the buyer's currency

Przykład: 7.55
data.​amount.​currencystring(ISO-4217)wymagany

Buyer's currency

Przykład: "BRL"
data.​amount.​commissionnumber or null(float)wymagany

SimPay's commission amount

Przykład: 0.12
data.​amount.​commission_currencystring(ISO-4217)wymagany

Commission currency (PLN/EUR)

Przykład: "EUR"
data.​amount.​originalobject

Original amounts declared at initiation

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

Postal code, format depends on the country field

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

Country

data.​billing.​companystring or null

Company name

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

Postal code, format depends on the country field

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

Country

data.​shipping.​companystring or null

Company name

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

Product name

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

Quantity of the product

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

Price of one product

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

Product brand

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

Product category

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

Product code

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

Creation date in format: ISO 8601

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

Creation date in format: ISO 8601

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

Creation date in format: ISO 8601

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

Creation date in format: ISO 8601

Odpowiedź
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"
  }
}

Retrieving a list of currencies for the service

Żądanie

Bezpieczeństwo
bearerAuth
Ścieżka
serviceIdstring(ServiceId)= 8 characters^[0-9a-f]{8}$wymagany

Service ID

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

Odpowiedzi

Treśćapplication/json
successbooleanwymagany

Request status

Przykład: true
dataArray of objectswymagany
Przykład: [{"iso":"PLN","pln_rate":"1.0000000000","nbp_table":"A","prefix":null,"suffix":" zł","updated_at":"2025-05-10T13:04:32+02:00"},{"iso":"EUR","pln_rate":"4.3238000000","nbp_table":"A","prefix":"€","suffix":null,"updated_at":"2025-05-10T13:04:32+02:00"},{"iso":"ARS","pln_rate":"0.0034150000","nbp_table":"B","prefix":"ARS$","suffix":null,"updated_at":"2025-05-10T13:04:32+02:00"}]
data[].​isostringwymagany

Currency ISO code (PLN, USD, EUR, BRL etc.)

data[].​pln_ratestringwymagany

Currency rate according to the NBP exchange rate

data[].​nbp_tablestringwymagany

NBP exchange rate table

data[].​prefixstring or null

Currency prefix

data[].​suffixstring or null

Currency suffix

data[].​updated_atstring(date)wymagany

Last currency update date

Odpowiedź
application/json
{
  "success": true,
  "data": [
    { … },
    { … },
    { … }
  ]
}

Provide BLIK code for Level 0 transaction

Żądanie

See https://docs.simpay.pl/payment/blik-level0 for more information.

Bezpieczeństwo
bearerAuth
Ścieżka
serviceIdstring(ServiceId)= 8 characters^[0-9a-f]{8}$wymagany

Service ID

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

Transaction ID

Treśćapplication/json
ticketobjectwymagany

BLIK code object

Przykład: {"T6":"123123"}
ticket.​T6string= 6 characterswymagany

6-digit BLIK code

Przykład: "123123"
curl -i -X POST \
  'https://docs.simpay.pl/_mock/en/apis/payment/{serviceId}/blik/level0/{transactionId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "ticket": {
      "T6": "123123"
    }
  }'

Odpowiedzi

Payment confirmation sent to the Payer’s Banking App

Odpowiedź
Brak zawartości

Receiving information about online payment transactionsWebhook

Żądanie

THE TEXT BELOW PRESENTS IPN V1, WHICH WILL BE REMOVED ON FEBRUARY 1, 2026. SEE IPN V2:

https://docs.simpay.pl/en/notifications/payment

Signature

Calculating the signature when receiving a notification

We generate the signature by combining all the parameters received (except for the signature) to the API in the order from the table above, separating them with a | separator and adding at the end the key available in the customer panel in the service.
Hashing must be done using sha256.
Example for a paid transaction using the declared currency:
dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a|e14f8074|transaction_paid|10|PLN|9.9|88643ada8857f25a1f391395f922f7db|blik|production|key

Example for a paid transaction using a different currency than declared:
dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a|e14f8074|transaction_paid|4.31|PLN|0.06|88643ada8857f25a1f391395f922f7db|blik|production|1.00|EUR|4.3123|key

The notification is sent using the POST method and requires you to respond in the body with OK and Http Code 200.

Treśćapplication/json
idstring(uuid)(TransactionId)= 36 characters^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]...wymagany

Transaction ID

service_idstring(ServiceId)= 8 characters^[0-9a-f]{8}$wymagany

Service ID

statusstring(paymentTransactionStatus)wymagany

Transaction status

Enum"transaction_new""transaction_confirmed""transaction_generated""transaction_paid""transaction_failure""transaction_expired""transaction_canceled""transaction_refunded"
amountobjectwymagany

Billing object

Przykład: {"value":10,"currency":"PLN","commission":9.9}
amount.​valuenumber(float)wymagany

Transaction amount (in paid currency)

Przykład: 10
amount.​currencystringwymagany

Transaction currency paid by the buyer

Przykład: "PLN"
amount.​commissionnumber(float)wymagany

SimPay's commission amount (in PLN or EUR)

Przykład: 9.9
controlstring

Field for use by the partner

Przykład: "88643ada8857f25a1f391395f922f7db"
channelstringwymagany

Payment channel

Przykład: "blik"
environmentstringwymagany
Enum"production""test"
Przykład: "production"
originalAmountobject

Information about the original currency and amount. Object sent only when the payer changed the currency on the payment gateway.

signaturestringwymagany

Notification signature. Signature calculation shown above.
The partner is obliged to verify the signature upon receiving the notification, you can also make a request to the endpoint Retrieving transaction details

Przykład: "a3116cf4f1e960223c2cc3088bf387278b6675255209bdeaf96a2f316a2fadc1"
application/json
{
  "id": "dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a",
  "service_id": "e14f8074",
  "status": "transaction_paid",
  "amount": {
    "value": 10,
    "currency": "PLN",
    "commission": 9.9
  },
  "control": "88643ada8857f25a1f391395f922f7db",
  "channel": "blik",
  "environment": "production",
  "signature": "a3116cf4f1e960223c2cc3088bf387278b6675255209bdeaf96a2f316a2fadc1"
}

Odpowiedzi

Return a 200 status to indicate that the data was received successfully

Treśćtext/plain
string
Domyślny "OK"
Odpowiedź
text/plain
OK
© 2025 Payments Solution Sp. z o.o. - All rights reserved.