Introduction
This documentation is intended for current and future Partners of Simpay. Before implementation, it is necessary to first define the service in the Partner Panel and wait for its activation.
Other languages
Language | Link |
---|---|
Polski | https://docs.simpay.pl/pl/shell/#wstep |
English | https://docs.simpay.pl/en/shell/#wstep |
Pre-made libraries
Pagination
Pagination object
"pagination": {
"total": 1,
"count": 1,
"per_page": 15,
"current_page": 1,
"total_pages": 1,
"links": {
"next_page": null,
"prev_page": null
}
}
If pagination is available in the request it is possible to use the following URL Parameters
.
URL parameters
Name | Type | Description |
---|---|---|
page | integer | Page |
limit | integer | Limit of results. default: 15, maximum: 99 |
Object description
Name | Type | Description |
---|---|---|
Total | int | Number of all records in the object |
Count | int | Number of records on the current page |
PerPage | int | Number of records maximum per page |
CurrentPage | int | Current page |
TotalPages | int | Number of total pages |
links.NextPage | string | URL of the next page |
links.PrevPage | string | URL of previous page |
SMS
Downloading the list of services
curl --request GET 'https://api.simpay.pl/sms' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'
Example response
{
"success": true,
"data": [
{
"id": 1,
"type": "ONE_TIME_CODE",
"status": "service_rejected",
"name": "TEST",
"prefix": "SIM",
"suffix": "TEST",
"adult": false,
"created_at": "2021-05-21 10:28:04"
}
],
"pagination": {
"total": 1,
"count": 1,
"per_page": 15,
"current_page": 1,
"total_pages": 1,
"links": {
"next_page": null,
"prev_page": null
}
}
}
HTTPS Request
GET https://api.simpay.pl/sms
Response description
Name | Type | Description |
---|---|---|
id | integer | Id Services |
type | string | Service type |
status | string | Service status. service_active - means active status |
name | string | Service name |
prefix | string | SMS content prefix |
suffix | string | Suffix of SMS content |
adult | boolean | Is the service 18+ |
created_at | datetime | Date of service creation in the format: ISO 8601 |
Downloading service information
curl --location --request GET 'https://api.simpay.pl/sms/<id_service>' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'
Example response
{
"success": true,
"data": {
"id": 1,
"type": "ONE_TIME_CODE",
"status": "service_rejected",
"name": "TEST",
"prefix": "SIM",
"suffix": "TEST",
"description": "Example description",
"adult": false,
"numbers": [
"7055",
"7136",
"7255",
"7355",
"7455",
"7555",
"7636",
"77464",
"78464",
"7936",
"91055",
"91155",
"91455",
"91664",
"91955",
"92055",
"92555"
],
"created_at": "2021-02-16 21:00:30"
}
}
HTTPS Request
GET https://api.simpay.pl/sms/<id_service>
Response description
Name | Type | Description |
---|---|---|
id | integer | Id Services |
type | string | Service type |
status | string | Service status. service_active - means active status |
name | string | Service name |
prefix | string | SMS content prefix |
suffix | string | Suffix of SMS content |
description | string | Service description |
adult | boolean | Is the service 18+ |
numbers | array | List of SMS numbers available in the service |
created_at | datetime | Date of service creation in the format: ISO 8601 |
Downloading a list of transactions
curl --location --request GET 'https://api.simpay.pl/sms/<id_service>/transactions' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'
Example response
{
"success": true,
"data": [
{
"id": 1,
"from": 48123123123,
"code": "ABCDEF",
"used": false,
"send_at": "1970-01-01 00:00:00"
},
{
"id": 2,
"from": 48123123123,
"code": "ABCDEF",
"used": false,
"send_at": "1970-01-01 00:00:00"
},
{
"id": 3,
"from": 48123123123,
"code": "ABCDEF",
"used": false,
"send_at": "1970-01-01 00:00:00"
}
],
"pagination": {
"total": 3,
"count": 3,
"per_page": 15,
"current_page": 1,
"total_pages": 1,
"links": {
"next_page": null,
"prev_page": null
}
}
}
HTTPS Request
GET https://api.simpay.pl/sms/<id_service>/transactions
Response description
Name | Type | Description |
---|---|---|
id | integer | Transaction id |
from | integer | Number from which SMS was sent |
code | string | SMS return code |
used | boolean | Was the code used |
send_at | datetime | Date of sending the SMS in the format: ISO 8601 |
Downloading transaction information
curl --location --request GET 'https://api.simpay.pl/sms/<id_service>/transactions/<id_transaction>' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'
Example response
{
"success": true,
"data": {
"id": 1,
"from": 48123123123,
"code": "ABCDEF",
"used": false,
"send_number": 7636,
"value": 6,
"send_at": "1970-01-01 00:00:00"
}
}
HTTPS Request
GET https://api.simpay.pl/sms/<id_service>/transactions/<id_transaction>
Response description
Name | Type | Description |
---|---|---|
id | integer | Transaction id |
from | integer | Number from which SMS was sent |
code | string | SMS return code |
used | bolean | Was the code used |
send_number | integer | Number to which SMS was sent |
value | float | The net cost of a sent SMS |
send_at | datetime | Date of sending the SMS in the format: ISO 8601 |
Downloading available numbers for the service
curl --location --request GET 'https://api.simpay.pl/sms/<id_service>/numbers' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'
Example response
{
"success": true,
"data": [
{
"number": 70908,
"value": 0.5,
"value_gross": 0.62,
"adult": true
},
{
"number": 71908,
"value": 1,
"value_gross": 1.23,
"adult": true
},
{
"number": 72998,
"value": 2,
"value_gross": 2.46,
"adult": true
},
{
"number": 73908,
"value": 3,
"value_gross": 3.69,
"adult": true
},
{
"number": 75908,
"value": 5,
"value_gross": 6.15,
"adult": true
},
{
"number": 76908,
"value": 6,
"value_gross": 7.38,
"adult": true
},
{
"number": 79908,
"value": 9,
"value_gross": 11.07,
"adult": true
},
{
"number": 91998,
"value": 19,
"value_gross": 23.37,
"adult": true
},
{
"number": 92598,
"value": 25,
"value_gross": 30.75,
"adult": true
}
],
"pagination": {
"total": 9,
"count": 9,
"per_page": 15,
"current_page": 1,
"total_pages": 1,
"links": {
"next_page": null,
"prev_page": null
}
}
}
HTTPS Request
GET https://api.simpay.pl/sms/<id_service>/numbers
Response description
Name | Type | Description |
---|---|---|
number | integer | SMS number |
value | float | Net amount |
value_gross | float | Gross amount |
adult | boolean | Is it 18+ |
Downloading information about a single number
curl --location --request GET 'https://api.simpay.pl/sms/<id_service>/numbers/<numer>' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'
Example response
{
"success": true,
"data": {
"number": 70908,
"value": 0.5,
"value_gross": 0.62,
"adult": true
}
}
HTTPS Request
GET https://api.simpay.pl/sms/<id_service>/numbers/<numer>
Response description
Name | Type | Description |
---|---|---|
number | integer | SMS number |
value | float | Net amount |
value_gross | float | Gross amount |
adult | boolean | Is it 18+ |
Downloading all available numbers
curl --location --request GET 'https://api.simpay.pl/sms/numbers' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'
Example response
{
"success": true,
"data": [
{
"number": 7055,
"value": 0.5,
"value_gross": 0.62,
"adult": false
},
{
"number": 7255,
"value": 2,
"value_gross": 2.46,
"adult": false
},
{
"number": 7136,
"value": 1,
"value_gross": 1.23,
"adult": false
},
{
"number": 7355,
"value": 3,
"value_gross": 3.69,
"adult": false
},
{
"number": 7455,
"value": 4,
"value_gross": 4.92,
"adult": false
},
{
"number": 7555,
"value": 5,
"value_gross": 6.15,
"adult": false
},
{
"number": 7636,
"value": 6,
"value_gross": 7.38,
"adult": false
},
{
"number": 77464,
"value": 7,
"value_gross": 8.61,
"adult": false
},
{
"number": 78464,
"value": 8,
"value_gross": 9.84,
"adult": false
},
{
"number": 7936,
"value": 9,
"value_gross": 11.07,
"adult": false
},
{
"number": 91055,
"value": 10,
"value_gross": 12.3,
"adult": false
},
{
"number": 91155,
"value": 11,
"value_gross": 13.53,
"adult": false
},
{
"number": 91455,
"value": 14,
"value_gross": 17.22,
"adult": false
},
{
"number": 91664,
"value": 16,
"value_gross": 19.68,
"adult": false
},
{
"number": 91955,
"value": 19,
"value_gross": 23.37,
"adult": false
}
],
"pagination": {
"total": 26,
"count": 15,
"per_page": 15,
"current_page": 1,
"total_pages": 2,
"links": {
"next_page": "https://api.simpay.pl/sms/numbers?page=2",
"prev_page": null
}
}
}
HTTPS Request
GET https://api.simpay.pl/sms/numbers
Response description
Name | Type | Description |
---|---|---|
number | integer | SMS number |
value | float | Net amount |
value_gross | float | Gross amount |
adult | boolean | Is it 18+ |
Downloading a single sms number
curl --location --request GET 'https://api.simpay.pl/sms/numbers/7055' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'
Example response
{
"success": true,
"data": {
"number": 7055,
"value": 0.5,
"value_gross": 0.62,
"adult": false
}
}
HTTPS Request
GET https://api.simpay.pl/sms/numbers/<numer>
Response description
Name | Type | Description |
---|---|---|
number | integer | SMS number |
value | float | Net amount |
value_gross | float | Gross amount |
adult | boolean | Is it 18+ |
Code validation
Response in case of error
{
"success": false
}
Response in case of new code
{
"success": true,
"data": {
"used": false,
"code": "63D9C7",
"test": true,
"from": "123123123",
"number": 7055,
"value": 0.5
}
}
The response in the case of the code used
{
"success": true,
"data": {
"used": true,
"code": "63D9C7",
"test": true,
"from": "123123123",
"number": 7055,
"value": 0.5,
"used_at": "2021-11-08 00:56:00"
}
}
HTTPS Request
POST https://api.simpay.pl/sms/<id_service>
Input parameters
Name | Type | Required | Description |
---|---|---|---|
code | string | Yes | Return code from SMS |
number | integer | No | The number to which the SMS was to be sent |
Response description
Name | Type | Description |
---|---|---|
used | boolean | Was the SMS used |
code | string | Return code from SMS |
test | boolean | Is the test SMS |
from | integer | Number from which SMS was sent |
number | integer | Number to which SMS was sent |
value | integer | Net amount of SMS cost |
used_at | datetime | Date when SMS was used in the format: ISO 8601, only available if used is equal to true . |
Models
Here you will find models of types, statuses, etc. for SMS services
Service status
Name | Description |
---|---|
service_new | New (to be verified) |
service_active | Active |
service_blocked | Blocked |
service_deleted | Deleted |
service_second_verify | Re-verification |
service_rejected | Rejected |
service_verify | Verification |
service_ongoing_registration | In the course of registration |
Service type
Name | Description |
---|---|
ONE_TIME_CODE | One-time code |
CODE_PACK | Packet of codes |
API_URL | API |
SMSXML
SMS Api XML allows you to control the entire process of receiving the sms and sending the code on the partner’s side of the service. The partner prepares the URL link according to the described SimPay specification. When the user places an order (sends an SMS message), our system queries the URL provided by the partner and downloads the code directly.
Links to libraries
Language | Link |
---|---|
PHP | /en/php/?php#smsxml |
Java | /en/typescript/?php#smsxml |
TypeScript | /en/typescript/?php#smsxml |
Python | /en/python/?php#smsxml |
Kotlin | /en/kotlin/?php#smsxml |
GoLang | /en/go/?php#smsxml |
DirectBilling
Transaction flow
Downloading the list of services
curl --location --request GET 'https://api.simpay.pl/directbilling' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'
Example response
{
"success": true,
"data": [
{
"id": 1,
"name": "Testowa usługa",
"suffix": "TEST1",
"status": "service_db_rejected",
"created_at": "2021-10-01 12:57:18"
},
{
"id": 2,
"name": "Testowa usługa",
"suffix": "TEST2",
"status": "service_active",
"created_at": "2021-10-01 13:57:18"
},
{
"id": 3,
"name": "Testowa usługa",
"suffix": "TEST3",
"status": "service_active",
"created_at": "2021-10-01 14:57:18"
}
],
"pagination": {
"total": 3,
"count": 3,
"per_page": 15,
"current_page": 1,
"total_pages": 1,
"links": {
"next_page": null,
"prev_page": null
}
}
}
HTTPS Request
GET https://api.simpay.pl/directbilling
- There is pagination available in this query! Read about pagination
Response description
Name | Type | Description |
---|---|---|
id | integer | Service id |
name | string | Name of the service |
suffix | string | Service suffix |
status | string | Service status, for more information check Models |
created_at | datetime | Date of service creation in the format: ISO 8601 |
Downloading service information
curl --location --request GET 'https://api.simpay.pl/directbilling/139' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'
Example response
{
"success": true,
"data": {
"id": 139,
"name": "test.pl",
"suffix": "test",
"status": "service_active",
"api": {
"complete": "https://test.pl/wallet",
"failure": "https://test.pl/wallet"
},
"providers": {
"t-mobile": true,
"orange": true,
"play": true,
"plus": true
},
"commissions": {
"t-mobile": {
"commission_0": "60",
"commission_9": "60",
"commission_25": "60"
},
"orange": {
"commission_0": "67",
"commission_9": "67",
"commission_25": "70"
},
"play": {
"commission_0": "55",
"commission_9": "65",
"commission_25": "70"
},
"plus": {
"commission_0": "50",
"commission_9": "50",
"commission_25": "60"
}
},
"maxValues": {
"t-mobile": "250",
"orange": "300",
"play": "600",
"plus": "400"
},
"created_at": "2020-11-25 01:45:28"
}
}
HTTPS Request
GET https://api.simpay.pl/directbilling/<id_service>
Response description
Name | Type | Description |
---|---|---|
id | integer | Service id |
name | string | Name of the service |
suffix | string | Service suffix |
status | string | Service status, for more information check Models |
api[complete] | string | Redirection url in case of successful transaction |
api[failure] | string | Redirection url in case of transaction failure |
providers[t-mobile] | boolean | T-Mobile operator availability |
providers[orange] | boolean | Orange operator availability |
providers[play] | boolean | Play operator availability |
providers[plus] | boolean | Operator availability Plus |
commissions[t-mobile][commission_0] | string | Partner commission in % of T-Mobile operator from the amount of 0.01 PLN to 8.99 PLN |
commissions[t-mobile][commission_9] | string | Partner commission in % of T-Mobile operator from the amount of PLN 9.00 to PLN 24.99 |
commissions[t-mobile][commission_25] | string | Partner commission in % of T-Mobile operator from the amount of PLN 25.00 up to the maximum amount |
commissions[orange][commission_9] | string | Partner’s commission in % of Orange operator from the amount of 0.01 PLN to 8.99 PLN |
commissions[orange][commission_25] | string | Partner commission in % of Orange operator from the amount of PLN 9.00 to PLN 24.99 |
commissions[orange][commission_0] | string | Partner commission in % of Orange operator from the amount of PLN 25.00 up to the maximum amount |
commissions[play][commission_0] | string | Partner commission in % of Play operator from the amount of 0.01 PLN to 8.99 PLN |
commissions[play][commission_9] | string | Partner commission in % of Play operator from the amount of PLN 9.00 to PLN 24.99 |
commissions[play][commission_25] | string | Partner commission in % of Play operator from the amount of 25.00 PLN up to the maximum amount |
commissions[plus][commission_0] | string | Partner commission in % of Plus operator from the amount of 0.01 PLN to 8.99 PLN |
commissions[plus][commission_9] | string | Partner commission in % of Plus operator from the amount of PLN 9.00 to PLN 24.99 |
commissions[plus][commission_25] | string | Partner commission in % of Plus operator from the amount of 25.00 PLN up to the maximum amount |
maxValues[t-mobile] | string | Maximum amount of a single transaction for T-Mobile operator |
maxValues[orange] | string | Maximum amount of a single transaction for the operator Orange |
maxValues[play] | string | Maximum amount of a single transaction for Play operator |
maxValues[plus] | string | Maximum amount of a single transaction for Plus operator |
created_at | datetime | Date of service creation in the format: ISO 8601 |
Commission calculation
curl --location --request GET 'https://api.simpay.pl/directbilling/139/calculate?amount=200' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'
Example response
{
"success": true,
"data": {
"orange": {
"net": 285.72,
"gross": 351.44
},
"play": {
"net": 285.72,
"gross": 351.44
},
"t-mobile": {
"net": 333.34,
"gross": 410.01
},
"plus": {
"net": 333.34,
"gross": 410.01
}
}
}
Response in case any of the operators is not active or the amount is too high
{
"success": true,
"data": {
"orange": {
"net": 428.58,
"gross": 527.15
},
"play": {
"net": 428.58,
"gross": 527.15
},
"t-mobile": null,
"plus": null
}
}
HTTPS Request
GET https://api.simpay.pl/directbilling/<id_service>/calculate
URL parameters
Name | Type | Required | Description |
---|---|---|---|
amount | float | Yes | The amount we want to receive |
Response description
Name | Type | Description |
---|---|---|
orange[net] | float | Net amount |
orange[gross] | float | Gross amount |
play[net] | float | Net amount |
play[gross] | float | Gross amount |
t-mobile[net] | float | Net amount |
t-mobile[gross] | float | Gross amount |
plus[net] | float | Net amount |
plus[gross] | float | Gross amount |
- If the operator is not active or the amount is too large a
null
will be returned.
Downloading a list of transactions
curl --location --request GET 'https://api.simpay.pl/directbilling/139/transactions' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'
Example response
{
"success": true,
"data": [
{
"id": 552098,
"status": "transaction_db_generate_error",
"value": 0.34,
"value_netto": 0.24,
"operator": "orange",
"created_at": "2021-10-20 00:34:47",
"updated_at": "2021-10-19 22:34:47"
},
{
"id": 552097,
"status": "transaction_db_new",
"value": 0.34,
"value_netto": 0.24,
"operator": "orange",
"created_at": "2021-10-20 00:34:14",
"updated_at": "2021-10-19 22:34:14"
},
{
"id": 552096,
"status": "transaction_db_new",
"value": 0.34,
"value_netto": 0.24,
"operator": "orange",
"created_at": "2021-10-20 00:33:53",
"updated_at": "2021-10-19 22:33:53"
},
{
"id": 548852,
"status": "transaction_db_confirmed",
"value": 34.46,
"value_netto": 24.12,
"operator": "orange",
"created_at": "2021-10-05 20:50:25",
"updated_at": "2021-10-05 18:50:25"
},
{
"id": 548851,
"status": "transaction_db_confirmed",
"value": 34.46,
"value_netto": 24.12,
"operator": "orange",
"created_at": "2021-10-05 20:48:26",
"updated_at": "2021-10-05 18:48:26"
},
{
"id": 544659,
"status": "transaction_db_confirmed",
"value": 13.41,
"value_netto": 6.7,
"operator": "plus",
"created_at": "2021-09-17 20:55:52",
"updated_at": "2021-09-17 18:55:53"
},
{
"id": 544508,
"status": "transaction_db_confirmed",
"value": 13.41,
"value_netto": 8.04,
"operator": "t-mobile",
"created_at": "2021-09-17 10:31:17",
"updated_at": "2021-09-17 08:31:17"
},
{
"id": 448984,
"status": "transaction_db_rejected",
"value": 13.41,
"value_netto": 6.7,
"operator": "plus",
"created_at": "2021-01-19 21:08:56",
"updated_at": "2021-01-22 20:48:11"
},
{
"id": 448931,
"status": "transaction_db_rejected",
"value": 13.41,
"value_netto": 8.98,
"operator": "orange",
"created_at": "2021-01-19 19:14:35",
"updated_at": "2021-01-22 18:48:11"
}
],
"pagination": {
"total": 9,
"count": 9,
"per_page": 30,
"current_page": 1,
"total_pages": 1,
"links": {
"next_page": null,
"prev_page": null
}
}
}
HTTPS Request
GET https://api.simpay.pl/directbilling/<id_service>/transactions
- There is pagination available in this query! Read about pagination
- Filtering is available in this query via the
filter
parameter.
Response description
Name | Type | Description |
---|---|---|
id | integer | Transaction id |
status | string | Status of transaction, for more information check Models |
value | float | Transaction amount |
value_netto | float | Net transaction amount |
operator | string | Operator, see list of operators in Models |
created_at | datetime | The date the transaction was created in the format: ISO 8601 |
updated_at | datetime | Transaction update date in the format: ISO 8601 |
Filtration
Name | Description |
---|---|
status | Transaction status, for more information check Models |
phoneNumber | Phone number |
control | Control field |
If you want to filter by multiple values place them after a comma e.g. filter[status]=transaction_db_confirmed,transaction_db_rejected
.
Example of using filters
curl --location --request GET 'https://api.simpay.pl/directbilling/129/transactions?filter[phoneNumber]=48123456789,48987654321' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'
Downloading transaction information
curl --location --request GET 'https://api.simpay.pl/directbilling/129/transactions/544524' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'
Example response
{
"success": true,
"data": {
"id": 1,
"status": "transaction_db_confirmed",
"phoneNumber": null,
"control": "1111",
"value": 16.67,
"value_netto": 10,
"operator": "t-mobile",
"notify": {
"is_send": false,
"last_send_at": "1970-01-01 00:00:00",
"count": 0
},
"created_at": "2021-09-17 12:01:50",
"updated_at": "2021-09-17 10:01:50"
}
}
HTTPS Request
GET https://api.simpay.pl/directbilling/<id_service>/transactions/<transaction_id>
Response description
Name | Type | Description |
---|---|---|
id | integer | Transaction id |
status | string | Status of transaction, for more information check Models |
phoneNumber | string/null | The phone number that was forced when the transaction was generated |
control | string | Status of transaction, for more information check Models |
value | float | Transaction amount |
value_netto | float | Net transaction amount |
operator | string | Operator, see list of operators in Models |
notify | array | Server notification board, see below |
notify[is_send] | boolean | Information whether the notification has been sent |
notify[last_send_at] | datetime | Date the last notification was sent in the format: ISO 8601 |
notify[count] | integer | Number of notifications sent |
created_at | datetime | The date the transaction was created in the format: ISO 8601 |
updated_at | datetime | Transaction update date in the format: ISO 8601 |
Generating transaction
curl --location --request POST 'https://api.simpay.pl/directbilling/139/transactions' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783' \
--header 'Content-Type: application/json' \
--data-raw '{
"amount": 19.99,
"amountType": "gross",
"description": "Doładowanie portfela",
"control": "dcb1212e-0590-4992-a49c-4db3615cff58",
"returns": {
"success": "https://www.simpay.pl",
"failure": "https://www.simpay.pl/failure"
},
"phoneNumber": "123123123",
"signature": "af47e0f6f8571720fd7cbacf42e02616ce288b2c8999567bb9a4d5c10231b611"
}'
Example response
{
"success": true,
"data": {
"transactionId": "1d87a1b3-18f8-4146-bcb1-c0c9f293b04f",
"redirectUrl": "https://db.simpay.pl/1d87a1b3-18f8-4146-bcb1-c0c9f293b04f"
}
}
Sample response in case of error
{
"success": false,
"errors": {
"amount": [
"The amount field is required."
],
"signature": [
"The signature field is required."
]
}
}
HTTPS Request
POST https://api.simpay.pl/directbilling/<id_service>/transactions
Input parameters
Name | Type | Required | Description |
---|---|---|---|
amount | float | Yes | Transaction amount |
amountType | string | No | Transaction Amount Type. Available: required , net , gross . By default gross |
description | string | No | Description of the transaction |
control | string | No | Parameter to be used by partner to identify transaction |
returns[success] | string | No | URL to which the customer will be redirected after a successful transaction, if empty the URL from the service will be used |
returns[failure] | string | No | URL to which the customer will be redirected after a failed transaction, if empty the URL from the service will be used |
phoneNumber | string | No | Forced phone number |
signature | string | Yes | Transaction signature, see below |
steamid | string | No | Optional field ( steamid64 ) |
Signature generation method
The signature is generated by juxtaposing with each other all the parameters sent (except the signature) to the API in order from the table available above, separating them with the |
seperator.
and adding at the end the key
of the service available in the client panel. Hashing must be done using sha256. Example:
sha256(amount + | + amountType + | + description + | + control + | + returns[success] + | returns[failure] + | + phoneNumber + | + key)
In case we only use amount
and control
to generate our transaction, the signature generation should look like this:
sha256(amount + | + control + | + key)
Response description
Name | Type | Description |
---|---|---|
transactionId | string | UUID of the transaction |
redirectUrl | string | The address to which the customer should be redirected |
Error response description
Name | Type | Description |
---|---|---|
errors | object | Object with tables containing errors to be corrected |
errors[amount] | array | Table of amount field errors |
errors[signature] | array | Table of signature field errors |
Receiving transaction information
The object that will be sent to the partner service
{
"id": 1111,
"service_id": 1,
"status": "transaction_db_payed",
"values": {
"net": 11.07,
"gross": 13.61,
"partner": 5.00
},
"returns": {
"complete": "https://www.simpay.pl/complete",
"failure": "https://www.simpay.pl/failure"
},
"control": "test",
"number_from": "123123123",
"provider": 1,
"signature": "signature"
}
Description of the inquiry sent
Name | Type | Description |
---|---|---|
id | integer | Transaction id |
service_id | integer | Service id |
status | string | Status of transaction, for more information check Models |
values | object | Object with transaction amounts |
values[net] | float | Net transaction amount |
values[gross] | float | Gross transaction amount |
values[partner] | float | Partner’s commission |
returns | object | Post-transaction redirect URL object |
returns[complete] | string | The address to which the customer was to be redirected after a valid transaction |
returns[failure] | string | The address to which the customer was to be redirected after the transaction was not correct |
control | string | Control field to be used by partner |
number_from | string | The phone number from which the transaction was conducted |
provider | integer | Payment operator, see more at Models |
signature | string | The signature to be compared with the newly generated signature, see below |
Signature generation method
The signature is generated by juxtaposing all received parameters (except signature) to the API in order from the table available above, separating them with a |
seperator.
and adding at the end the key
of the service available in the partner panel. Hashing must be done using sha256. Example:
1111|1|transaction_db_payed|11.07|13.67|5.00|https://www.simpay.pl/complete|https://www.simpay.pl/failure|test|123123123|1|key
Models
Service status
Name | Description |
---|---|
service_db_new | New |
service_db_active | Active |
service_db_rejected | Rejected |
service_db_ongoing_registration | In the course of registration |
Transaction status
Name | Description |
---|---|
transaction_db_new | New |
transaction_db_confirmed | User redirected |
transaction_db_rejected | Rejected |
transaction_db_canceled | Cancelled |
transaction_db_payed | Paid |
transaction_db_generate_error | Error during generating |
Provider
Name | Description |
---|---|
1 | Orange |
2 | Plus |
3 | Play |
4 | T-Mobile |
Security
Verification of customer certificate
Notifications from SimPay servers are signed with a certificate.
Example of nginx configuration with client certificate verification on location /notify
# Tutaj wpisz fingerprint certyfikatu otrzymanego od SimPay
set $simpay_fingerprint "13d4313b94469038cdbab1839559ae381309a79d";
# Tutaj podmień ścieżkę na tą z certyfikatem otrzymanym od SimPay
ssl_client_certificate /opt/simpay/ssl/ipn.simpay.pem;
ssl_verify_client optional;
ssl_verify_depth 2;
location /notify {
if ($ssl_client_verify != "SUCCESS") { return 403; }
if ($ssl_client_fingerprint != $simpay_fingerprint) {
return 403;
}
}
SimPay IPN Certificate
-----BEGIN CERTIFICATE-----
MIICZjCCAe2gAwIBAgIUESmcYMAYfB5YTAGSqCyOay9OnZgwCgYIKoZIzj0EAwIw
czEmMCQGA1UEAwwdUGF5bWVudHMgU29sdXRpb25zIFJvb3QgQ0EgWDExJjAkBgNV
BAoMHVBheW1lbnRzIFNvbHV0aW9ucyBzcC4geiBvLm8uMRQwEgYDVQQHDAtLcmFz
bm9zaWVsYzELMAkGA1UEBhMCUEwwHhcNMjExMTExMTg0NzI5WhcNMzExMTA5MTg0
NzI5WjBzMSYwJAYDVQQDDB1QYXltZW50cyBTb2x1dGlvbnMgUm9vdCBDQSBYMTEm
MCQGA1UECgwdUGF5bWVudHMgU29sdXRpb25zIHNwLiB6IG8uby4xFDASBgNVBAcM
C0tyYXNub3NpZWxjMQswCQYDVQQGEwJQTDB2MBAGByqGSM49AgEGBSuBBAAiA2IA
BE371EkfU3OZJj6aUnv4JLfQ773ShbEooYxFc//DsWVi0rps0MUlpLuWpDN9tqdh
DJWQpdXq2Pam3nbzEr/klHeFRBBdI4ghWjs3GX+KxNUMMp0qVFNxZ+oBDdBkb7GD
s6NCMEAwDgYDVR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYE
FMplUBx3+kPIl5fkMLREXv5DwQyvMAoGCCqGSM49BAMCA2cAMGQCMGLV6BCrVb/W
RjsFkmho+qVUa9mdm54dPDI4JZ5rb98BnU0xxSGpPwXc+odSgPox7QIwXP1vJztU
qPn0D9ZdNFSIg7wpppLwIfhniv3gy4khuI9PAuWF76rjs90+Ij/pR67n
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIICWjCCAeGgAwIBAgIUcPa5Jqg71Be/IaLIlPy4XDLJJP8wCgYIKoZIzj0EAwIw
czEmMCQGA1UEAwwdUGF5bWVudHMgU29sdXRpb25zIFJvb3QgQ0EgWDExJjAkBgNV
BAoMHVBheW1lbnRzIFNvbHV0aW9ucyBzcC4geiBvLm8uMRQwEgYDVQQHDAtLcmFz
bm9zaWVsYzELMAkGA1UEBhMCUEwwHhcNMjExMTExMTk0OTUwWhcNMzExMTA5MTk0
OTUwWjBnMRowGAYDVQQDDBFTaW1wYXkgUm9vdCBDQSBYMTEmMCQGA1UECgwdUGF5
bWVudHMgU29sdXRpb25zIHNwLiB6IG8uby4xFDASBgNVBAcMC0tyYXNub3NpZWxj
MQswCQYDVQQGEwJQTDB2MBAGByqGSM49AgEGBSuBBAAiA2IABE9noXtjwMQ0IlDy
Anddos7JRYf3EcCbW8/ilHQcBxkE8828iTK+4bw1h8KYRzEfJRSZmZMlbH8AKPSC
oukSbSAnMMSu8vQ2QBQKwjjsxIttLv63HHBQ4c5k7C6WYm28C6NCMEAwDgYDVR0P
AQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFDPp5r7ojf5I/9pO
Z6uZKGAoJwS7MAoGCCqGSM49BAMCA2cAMGQCMCgFY0DWNkHPr1yV7inFuKPIKUBT
XzWc7F1vlcWszNuNJtyaxiSUsmysYxyxD0+QEwIwQ53zxnkppiw9+luTIZAxkchi
DoEV+E1e5GR8f4QaKCPIb4y9qp9dpWd9328sXvVP
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIICCDCCAY2gAwIBAgIUUGkJrAO+6V0xrOcbZ5szLAix4bIwCgYIKoZIzj0EAwIw
ZzEaMBgGA1UEAwwRU2ltcGF5IFJvb3QgQ0EgWDExJjAkBgNVBAoMHVBheW1lbnRz
IFNvbHV0aW9ucyBzcC4geiBvLm8uMRQwEgYDVQQHDAtLcmFzbm9zaWVsYzELMAkG
A1UEBhMCUEwwHhcNMjIwMjA3MTk0MTU3WhcNMzIwMjA1MTk0MTU3WjBjMRYwFAYD
VQQDDA1TaW1wYXkgSVBOIFgxMSYwJAYDVQQKDB1QYXltZW50cyBTb2x1dGlvbnMg
c3AuIHogby5vLjEUMBIGA1UEBwwLS3Jhc25vc2llbGMxCzAJBgNVBAYTAlBMMHYw
EAYHKoZIzj0CAQYFK4EEACIDYgAEmFd9ZEds0KBVKuRsi50sO+B+NUJM2MRbXnTh
7kkStVk8XFIzOHWEhbppttB1RaOrPpIT/Ys/+/YXWAGTAvubuWYH2rDYFv8h54gU
VI8HGK81aVbQmv8ln5tug7rKKmKtMAoGCCqGSM49BAMCA2kAMGYCMQC7sy+9bFAU
ZWUWgI0KRFWSYTwdhOC4V84+Ea4PCvVPha26hMe9NqB1A1Vf3tInBWUCMQD0x33e
8jDjlCiXN0jDf+5gKsREQs9Q2pF6r+P7uzX26dT+OvOz6IfJlYS+SEXYHjU=
-----END CERTIFICATE-----
Downloading the list of ips
curl --location 'https://api.simpay.pl/ip'
Example response
{
"success": true,
"data": [
"135.125.153.121"
]
}
HTTPS Request
GET https://api.simpay.pl/ip
IP addresses of servers
Notifications from SimPay servers are sent from the following IP addresses
LP | IP |
---|---|
1 | 135.125.153.121 |