API Reference

simpay-api (1.0.0)

English version

Download OpenAPI description

index.json

index.yaml

Overview

URL

https://simpay.pl/kontakt

Support

kontakt@simpay.pl

Servers

Mock server

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

https://api.simpay.pl/

SMS

Operations

DirectBilling

OperationsWebhooks

Płatności online

OperationsWebhooks

Pobieranie listy usług

Request

Security

bearerAuth

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

Responses

Bodyapplication/json

successbooleanrequired

Request status

Example: true

dataArray of objectsrequired

Example: [{"id":"d151e4f9","name":"Usługa testowa","status":"service_active","created_at":"2021-11-08T18:19:16+01:00"}]

data[].idstring(ServiceId)= 8 characters^[0-9a-f]{8}$required

Id usługi

data[].namestringrequired

Nazwa usługi

data[].statusstring(ServiceStatus)required

Status usługi

Enum"service_new""service_active""service_blocked""service_rejected""service_verify""service_ongoing_registration"

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

Data utworzenia w formacie: ISO 8601

paginationobject(Pagination)required

pagination.totalintegerrequired

Liczba wszystkich rekordów

Example: 1

pagination.countintegerrequired

Liczba rekordów na danej stronie

Example: 1

pagination.per_pageintegerrequired

Maksymalna ilość rekordów na strone

Example: 15

pagination.current_pageintegerrequired

Aktualna strona

Example: 1

pagination.total_pagesintegerrequired

Ilość stron

Example: 1

pagination.linksobjectrequired

Adresy URL do stron

pagination.links.next_pagestring or null(url)required

Adres URL do następnej strony

Example: null

pagination.links.prev_pagestring or null(url)required

Adres URL do poprzedniej strony

Example: null

Response

application/json

{
  "success": true,
  "data": [
    { … }
  ],
  "pagination": {
    "total": 1,
    "count": 1,
    "per_page": 15,
    "current_page": 1,
    "total_pages": 1,
    "links": { … }
  }
}

Pobieranie szczegółów usługi

Request

Security

bearerAuth

Path

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

Id usługi

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

Responses

Bodyapplication/json

successbooleanrequired

Request status

Example: true

dataobjectrequired

Example: {"id":"d151e4f9","name":"Usługa testowa","status":"service_active","created_at":"2021-11-08T18:19:16+01:00"}

data.idstring(ServiceId)= 8 characters^[0-9a-f]{8}$required

Id usługi

data.namestringrequired

Nazwa usługi

Example: "Usługa testowa"

data.statusstring(ServiceStatus)required

Status usługi

Enum"service_new""service_active""service_blocked""service_rejected""service_verify""service_ongoing_registration"

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

Data utworzenia w formacie: ISO 8601

Response

application/json

{
  "success": true,
  "data": {
    "id": "d151e4f9",
    "name": "Usługa testowa",
    "status": "service_active",
    "created_at": "2021-11-08T18:19:16+01:00"
  }
}

Pobieranie listy kanałów dla usługi

Request

Security

bearerAuth

Path

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

Id usługi

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

Responses

Bodyapplication/json

successbooleanrequired

Request status

Example: true

dataArray of objectsrequired

Example: [{"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[].idstringrequired

Id kanału płatności

data[].namestringrequired

Nazwa kanału

data[].typestringrequired

Typ kanału

data[].imgstring(url)required

Adres URL do grafiki kanału płatności

data[].commissionnumber(float)required

Prowizja pobierana przez SimPay z płatności

data[].currenciesArray of stringsrequired

Tablica z dostępnymi walutami

data[].amountobjectrequired

Kwoty dostępne dla kanłu

data[].amount.minnumber(float)

Kwota minimalna do płatności

data[].amount.maxnumber(float)

Kwota maksymalna do płatności

Response

application/json

{
  "success": true,
  "data": [
    { … },
    { … }
  ]
}

Pobieranie listy transakcji

Request

Security

bearerAuth

Path

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

Id usługi

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

Responses

Bodyapplication/json

successbooleanrequired

Request status

Example: true

dataArray of objectsrequired

Example: [{"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]...required

Id transakcji

data[].statusstring(paymentTransactionStatus)required

Status transakcji

Enum"transaction_new""transaction_confirmed""transaction_generated""transaction_paid""transaction_failed""transaction_expired""transaction_canceled""transaction_refunded"

data[].amountnumber(float)required

data[].controlstringrequired

data[].channelstringrequired

data[].paid_atstring(date-time)(DateTime)required

Data utworzenia w formacie: ISO 8601

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

Data utworzenia w formacie: ISO 8601

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

Data utworzenia w formacie: ISO 8601

paginationobject(Pagination)required

pagination.totalintegerrequired

Liczba wszystkich rekordów

Example: 1

pagination.countintegerrequired

Liczba rekordów na danej stronie

Example: 1

pagination.per_pageintegerrequired

Maksymalna ilość rekordów na strone

Example: 15

pagination.current_pageintegerrequired

Aktualna strona

Example: 1

pagination.total_pagesintegerrequired

Ilość stron

Example: 1

pagination.linksobjectrequired

Adresy URL do stron

pagination.links.next_pagestring or null(url)required

Adres URL do następnej strony

Example: null

pagination.links.prev_pagestring or null(url)required

Adres URL do poprzedniej strony

Example: null

Response

application/json

{
  "success": true,
  "data": [
    { … },
    { … }
  ],
  "pagination": {
    "total": 2,
    "count": 2,
    "per_page": 15,
    "current_page": 1,
    "total_pages": 1,
    "links": { … }
  }
}

Generowanie transakcji

Request

Security

bearerAuth

Path

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

Id usługi

Bodyapplication/json

amountnumber(float)>= 1required

Kwota transakcji

currencystring

Waluta transakcji

Default "PLN"

descriptionstring<= 64 characters

Opis transakcji nadany przez partnera, prezentowany na bramce płatności

controlstring<= 255 characters

Pole do wykorzystania przez partnera

customerobject or null

Obiekt podstawowych informacji o płacącym

antifraudobject or null

Obiekt informacji do antifrauda

billingobject or null(paymentCustomerFull)

shippingobject or null(paymentCustomerFull)

cartArray of objects or null(paymentCartItem)

returnsobject or null

directChannelstring

W tym polu można przesłać Id kanału, wtedy płacący zostanie przekierowany od razu na stronę podanego kanału np. przy podaniu blik zostanie przekierowany od razu na bramkę płatności BLIK. Wymagane jest wtedy przesłanie antifraud.useragent oraz customer.ip.

channelsArray of strings or null

Tablica z Id kanałów płatności, które zostaną wyświetlone płacącemu na bramce po przekierowaniu na url transakcji
Listę dostępnych kanałów wraz z ich Id możemy uzyskać tutaj Pobieranie listy kanałów dla usługi

channelTypesobject or null

Obiekt w którym możemy zdefiniować które typu kanłów mają być dostępne na bramce płatności

refererstring[ 6 .. 64 ] characters

curl -i -X POST \
  'https://docs.simpay.pl/_mock/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

Id transakcji

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

Pobieranie szczegółów transakcji

Request

Security

bearerAuth

Path

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

Id usługi

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

Id transakcji

curl -i -X GET \
  'https://docs.simpay.pl/_mock/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

Id transakcji

data.payer_transaction_idstringrequired

Identyfikator transakcji udostępniony płacącemu

Example: "477YDX14"

data.statusstring(paymentTransactionStatus)required

Status transakcji

Enum"transaction_new""transaction_confirmed""transaction_generated""transaction_paid""transaction_failed""transaction_expired""transaction_canceled""transaction_refunded"

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

Kwota płatności w walucie kupującego

Example: 7.55

data.amount.currencystring(ISO-4217)required

Waluta kupującego

Example: "BRL"

data.amount.commissionnumber or null(float)required

Kwota prowizji dla SimPay

Example: 0.12

data.amount.commission_currencystring(ISO-4217)required

Waluta prowizji (PLN/EUR)

Example: "EUR"

data.amount.originalobject

Oryginalne kwoty zadeklarowane przy inicjacji

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

Kod pocztowy, format zależny od pola country

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

Kraj

data.billing.companystring or null

Nazwa firmy

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

Kod pocztowy, format zależny od pola country

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

Kraj

data.shipping.companystring or null

Nazwa firmy

data.cartArray of objects or null(paymentCartItem)required

data.cart[].namestring[ 3 .. 64 ] charactersrequired

Nazwa produktu

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

Ilość danego produktu

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

Kwota jednego produktu

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

Marka producneta produktu

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

Kategoria produktu

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

Kod produktu

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

Data utworzenia w formacie: ISO 8601

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

Data utworzenia w formacie: ISO 8601

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

Data utworzenia w formacie: ISO 8601

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

Data utworzenia w formacie: 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"
  }
}

Pobieranie listy walut dla usługi

Request

Security

bearerAuth

Path

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

Id usługi

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

Responses

Bodyapplication/json

successbooleanrequired

Request status

Example: true

dataArray of objectsrequired

Example: [{"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[].isostringrequired

Kod ISO waluty (PLN, USD, EUR, BRL etc.)

data[].pln_ratestringrequired

Kurs waluty według kursu NBP

data[].nbp_tablestring

Tabela do kursu NBP

data[].prefixstring or null

Prefiks waluty

data[].suffixstring or null

Sufiks waluty

data[].updated_atstring(date)required

Data ostatniej aktualizacji waluty

Response

application/json

{
  "success": true,
  "data": [
    { … },
    { … },
    { … }
  ]
}

Odbieranie informacji o transakcji płatności onlineWebhook

Request

PONIŻSZY TEKST PRZEDSTAWIA IPN V1, KTÓRE ZOSTANIE USUNIĘTE 1 LUTEGO 2026. ZOBACZ IPN V2:

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

Sygnatura

Obliczanie sygnatury przy odbieraniu notyfikacji

Sygnature generujemy za pomocą zestawienia ze sobą wszystkich odebranych parametrów (oprócz signature) do API w kolejności z dostępnej powyżej tabli oddzielając je seperatorem | i dodając na końcu klucz dostępny w panelu klienta w usłudze.
Hashowanie musi odbyć się za pomocą sha256.
Przykład dla opłaconej transakcji przy pomocy zadeklarowanej waluty:
dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a|e14f8074|transaction_paid|10|PLN|9.9|88643ada8857f25a1f391395f922f7db|blik|production|klucz

Przykład dla opłaconej transakcji za pomocą innej waluty niż zadeklarowanej:
dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a|e14f8074|transaction_paid|4.31|PLN|0.06|88643ada8857f25a1f391395f922f7db|blik|production|1.00|EUR|4.3123|klucz

Notyfikacja wysyłana jest metodą POST i wymaga od Ciebie odpowiedzi w body OK oraz Http Code 200.

Bodyapplication/json

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

Id transakcji

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

Id usługi

statusstring(paymentTransactionStatus)required

Status transakcji

Enum"transaction_new""transaction_confirmed""transaction_generated""transaction_paid""transaction_failed""transaction_expired""transaction_canceled""transaction_refunded"

amountobjectrequired

Obiekt rozliczeniowy

Example: {"value":10,"currency":"PLN","commission":9.9}

amount.valuenumber(float)required

Kwota transakcji (w opłaconej walucie)

Example: 10

amount.currencystringrequired

Waluta transakcji, którą zapłacił kupujący

Example: "PLN"

amount.commissionnumber(float)required

Kwota prowizji pobranej przez simpay (w PLN lub EUR)

Example: 9.9

controlstring

Pole do wykorzystania przez partnera

Example: "88643ada8857f25a1f391395f922f7db"

channelstringrequired

Kanał płatności

Example: "blik"

environmentstringrequired

Enum"production""test"

Example: "production"

originalAmountobject

Informacje o oryginalnej walucie i kwocie. Obiekt wysyłany tylko wtedy, gdy płacący zmienił walutę na bramce płatności.

signaturestringrequired

Sygnatura notyfikacji. Wyliczanie sygnatury pokazane wyżej.
Partner ma obowiązek weryfikować sygnaturę przy otrzymaniu powiadomienia, można też wykonać request do endpointu Pobieranie szczegółów transakcji

Example: "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"
}

Responses

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

Bodytext/plain

string

Default "OK"

Response

text/plain

OK

simpay-api (1.0.0)

SMS

DirectBilling

Płatności online

Pobieranie listy usług

Request

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Pobieranie szczegółów usługi

Request

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Pobieranie listy kanałów dla usługi

Request

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Pobieranie listy transakcji

Request

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Generowanie transakcji

RequestExpand all

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Pobieranie szczegółów transakcji

Request

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Pobieranie listy walut dla usługi

Request

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Odbieranie informacji o transakcji płatności onlineWebhook

RequestExpand all

PONIŻSZY TEKST PRZEDSTAWIA IPN V1, KTÓRE ZOSTANIE USUNIĘTE 1 LUTEGO 2026. ZOBACZ IPN V2:

Sygnatura

Obliczanie sygnatury przy odbieraniu notyfikacji

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Request

Request