Welcome to the SimPay API documentation! Before you move on to integrating specific services (Online Payments, DirectBilling, or SMS), you need to learn the basic principles of communication with our servers.
Our API is designed with REST architecture, and data exchange is done exclusively in JSON format.
Access to the API is protected. To send requests to us, you need a unique access key (Bearer Token).
- Log in to the SimPay Client Panel.
- Go to the My Account > API Keys tab.
- Generate a new key and copy its value.
The generated token must be included with every request sent to our API using the Authorization header. Also remember to include the appropriate headers specifying the data format.
Example HTTP request skeleton:
POST /api/endpoint HTTP/1.1
Host: api.simpay.pl
Authorization: Bearer YOUR_API_KEY
Accept: application/json
Content-Type: application/jsonYour API key is the virtual equivalent of your company keys – it grants access to generating transactions and even initiating refunds. Treat it with the utmost care.
- Never expose the API key on the client side (Frontend). The key must not appear in JavaScript code (React, Vue, Angular) or in mobile applications. Communication with SimPay must always be done from your server (Backend).
- Do not commit the key to a code repository. Use environment variables (e.g.,
.envfiles) that are ignored by version control systems (Git).
SimPay offers powerful access granulation tools that help minimize risk in case of a key leak. We strongly recommend using them when generating tokens in the Client Panel:
Instead of creating a single key for everything ("God Mode"), create keys dedicated to specific tasks. If a key is only meant for generating new online payments on your store's website, uncheck its permissions for handling refunds or viewing transaction history.
This is the strongest security measure. In the key settings, you can define the exact IP addresses of your servers. If someone steals your API key and tries to use it from a different computer, our API will immediately reject such a request (error 403).
Our API uses standard HTTP status codes to inform you about the result of an operation. Codes in the 2xx group indicate success, while 4xx indicate an error on your request's side.
Every error response contains a JSON object with an errorCode field to facilitate debugging. In case of validation errors (422), we additionally return an errors object with a list of invalid fields.
| HTTP Code | Error Type | Description | Example errorCode |
|---|---|---|---|
200 OK | Success | The request was processed successfully. | - |
401 Unauthorized | No authorization | No API token was provided in the header, or it is invalid/expired. | UNAUTHORIZED |
403 Forbidden | Access denied | Your token does not have the appropriate permissions (Abilities) to perform this action, or the request came from an IP address not on the whitelist. | INVALID_ABILITY_PROVIDED, IP_ADDRESS_NOT_WHITELISTED |
404 Not Found | Not found | You are trying to query a non-existent endpoint, or an incorrect service/transaction ID was provided in the URL. | ROUTE_NOT_FOUND, SERVICE_NOT_FOUND, TRANSACTION_NOT_FOUND |
422 Unprocessable Entity | Validation error | The submitted data is incomplete or has an incorrect format (e.g., missing required amount or invalid currency). | VALIDATION_ERROR |
Example response for error 422 (VALIDATION_ERROR):
{
"success": false,
"errorCode": "VALIDATION_ERROR",
"errors": {
"amount": [
"The amount field is required."
],
"currency": [
"The selected currency is invalid."
]
}
}You now know the communication rules and how to properly authorize your requests. Time to start generating real transactions!
Choose the module you want to integrate with: