Generating a transaction

simpay-api (1.0.0)

Polish 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/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

simpay-api (1.0.0)

SMS

DirectBilling

Online Payments

Retrieving a list of services

Request

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Retrieving service details

Request

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Retrieving a list of channels for the service

Request

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Retrieving a list of transactions

Request

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Generating a transaction

RequestExpand all

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Retrieving transaction details

Request

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Retrieving a list of currencies for the service

Request

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Receiving information about online payment transactionsWebhook

RequestExpand all

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

Signature

Calculating the signature when receiving a notification

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Request

Request