NAV Navigation
shell php java typescript python kotlin go

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

Language Link
PHP https://github.com/SimPaypl/SimPay-API-php
Java https://github.com/SimPaypl/SimPay-API-java
TypeScript https://github.com/SimPaypl/SimPay-API-TypeScript
Python https://github.com/SimPaypl/SimPay-API-Python
Kotlin https://github.com/SimPaypl/SimPay-API-Kotlin
Go https://github.com/SimPaypl/SimPay-API-go

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_uslugi>' \
--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_uslugi>

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_uslugi>/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_uslugi>/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_uslugi>/transactions/<id_transakcji>' \
--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_uslugi>/transactions/<id_transakcji>

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

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.

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

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

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

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

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_uslugi>/transactions

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

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

IP addresses of servers

Notifications from SimPay servers are sent from the following IP addresses

LP IP
1 135.125.153.121
shell php java typescript python kotlin go