simpay-api (1.0.0)

Download OpenAPI description
Languages
Servers
Mock server

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

https://api.simpay.pl/

SMS

Operations

DirectBilling

OperationsWebhooks

Online Payments

OperationsWebhooks

Retrieving a list of services

Request

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

Responses

Bodyapplication/json
successbooleanrequired

Request status

Example: true
dataArray of objectsrequired
Example: [{"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}$required

Service ID

data[].​namestringrequired

Service name

data[].​statusstring(ServiceStatus)required

Service Status

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

Creation date in format: ISO 8601

paginationobject(Pagination)required
pagination.​totalintegerrequired

Total number of records

Example: 1
pagination.​countintegerrequired

Number of records on the current page

Example: 1
pagination.​per_pageintegerrequired

Maximum number of records per page

Example: 15
pagination.​current_pageintegerrequired

Current page

Example: 1
pagination.​total_pagesintegerrequired

Total number of pages

Example: 1
pagination.​linksobjectrequired

URLs to pages

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

URL to the next page

Example: null
pagination.​links.​prev_pagestring or null(url)required

URL to the previous page

Example: null
Response
application/json
{ "success": true, "data": [ {} ], "pagination": { "total": 1, "count": 1, "per_page": 15, "current_page": 1, "total_pages": 1, "links": {} } }

Retrieving service details

Request

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

Service ID

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

Responses

Bodyapplication/json
successbooleanrequired

Request status

Example: true
dataobjectrequired
Example: {"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}$required

Service ID

data.​namestringrequired

Service name

Example: "Test service"
data.​statusstring(ServiceStatus)required

Service Status

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

Creation date in format: ISO 8601

Response
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

Request

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

Service ID

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

Payment channel ID

data[].​namestringrequired

Channel name

data[].​typestringrequired

Channel type

data[].​imgstring(url)required

URL to the payment channel graphic

data[].​commissionnumber(float)required

Commission charged by SimPay from the payment

data[].​currenciesArray of stringsrequired

Array of available currencies

data[].​amountobjectrequired

Amounts available for the channel

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

Minimum payment amount

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

Maximum payment amount

Response
application/json
{ "success": true, "data": [ {}, {} ] }

Retrieving a list of transactions

Request

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

Service ID

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

Transaction ID

data[].​statusstring(paymentTransactionStatus)required

Transaction status

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

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

paginationobject(Pagination)required
pagination.​totalintegerrequired

Total number of records

Example: 1
pagination.​countintegerrequired

Number of records on the current page

Example: 1
pagination.​per_pageintegerrequired

Maximum number of records per page

Example: 15
pagination.​current_pageintegerrequired

Current page

Example: 1
pagination.​total_pagesintegerrequired

Total number of pages

Example: 1
pagination.​linksobjectrequired

URLs to pages

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

URL to the next page

Example: null
pagination.​links.​prev_pagestring or null(url)required

URL to the previous page

Example: null
Response
application/json
{ "success": true, "data": [ {}, {} ], "pagination": { "total": 2, "count": 2, "per_page": 15, "current_page": 1, "total_pages": 1, "links": {} } }

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_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

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

Retrieving a list of currencies for the service

Request

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

Service ID

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

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

data[].​pln_ratestringrequired

Currency rate according to the NBP exchange rate

data[].​nbp_tablestring

NBP exchange rate table

data[].​prefixstring or null

Currency prefix

data[].​suffixstring or null

Currency suffix

data[].​updated_atstring(date)required

Last currency update date

Response
application/json
{ "success": true, "data": [ {}, {}, {} ] }

Receiving information about online payment transactionsWebhook

Request

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.

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

Transaction ID

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

Service ID

statusstring(paymentTransactionStatus)required

Transaction status

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

Billing object

Example: {"value":10,"currency":"PLN","commission":9.9}
amount.​valuenumber(float)required

Transaction amount (in paid currency)

Example: 10
amount.​currencystringrequired

Transaction currency paid by the buyer

Example: "PLN"
amount.​commissionnumber(float)required

SimPay's commission amount (in PLN or EUR)

Example: 9.9
controlstring

Field for use by the partner

Example: "88643ada8857f25a1f391395f922f7db"
channelstringrequired

Payment channel

Example: "blik"
environmentstringrequired
Enum"production""test"
Example: "production"
originalAmountobject

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

signaturestringrequired

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

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