Receiving DirectBilling transaction information

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

Retrieving a list of services

Request

Security

bearerAuth

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

Responses

Bodyapplication/json

successbooleanrequired

Request status

Example: true

dataArray of objects(directbillingServiceItem)required

Example: [{"id":"d151e4f9","name":"Test service","suffix":"Test1","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[].suffixstringrequired

Title in the report

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 information

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/directbilling/{serviceId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Bodyapplication/json

successbooleanrequired

Request status

Example: true

dataobjectrequired

Example: {"id":"d151e4f9","name":"Test service","suffix":"Test1","status":"service_active","created_at":"2021-11-08T18:19:16+01:00"}

data.idstring(ServiceId)= 8 characters^[0-9a-f]{8}$

Service ID

data.namestring

Service name

Example: "Test service"

data.suffixstring

Title in the report

Example: "Test1"

data.statusstring(ServiceStatus)

Service Status

Enum"service_new""service_active""service_blocked""service_rejected""service_verify""service_ongoing_registration"

data.created_atstring(date-time)(DateTime)

Creation date in format: ISO 8601

Response

application/json

{
  "success": true,
  "data": {
    "id": "d151e4f9",
    "name": "Test service",
    "suffix": "Test1",
    "status": "service_active",
    "created_at": "2021-11-08T18:19:16+01:00"
  }
}

Commission calculation

Request

Security

bearerAuth

Path

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

Service ID

Query

amountnumber(float)required

The amount we want to receive “net”

curl -i -X GET \
  'https://docs.simpay.pl/_mock/en/apis/directbilling/{serviceId}/calculate?amount=0.1' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Bodyapplication/json

successbooleanrequired

Request status

Example: true

dataobjectrequired

Example: {"orange":{"net":285.72,"gross":351.44},"play":{"net":285.72,"gross":351.44},"t-mobile":null,"plus":null}

data.orangeobject or null(directbillingCalculationOperatorItem)required

data.orange.netnumber(float)

data.orange.grossnumber(float)

data.playobject or null(directbillingCalculationOperatorItem)required

data.play.netnumber(float)

data.play.grossnumber(float)

data.t-mobileobject or null(directbillingCalculationOperatorItem)required

data.t-mobile.netnumber(float)

data.t-mobile.grossnumber(float)

data.plusobject or null(directbillingCalculationOperatorItem)required

data.plus.netnumber(float)

data.plus.grossnumber(float)

Response

application/json

{
  "success": true,
  "data": {
    "orange": { … },
    "play": { … },
    "t-mobile": null,
    "plus": null
  }
}

Retrieving a list of transactions

Request

Security

bearerAuth

Path

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

Service ID

Query

filter[status]string(directbillingTransactionStatus)

Transaction status

Enum"transaction_db_new""transaction_db_confirmed""transaction_db_payed""transaction_db_rejected"

filter[phoneNumber]string

Phone number from which the transaction was made

Example: filter[phoneNumber]=48123123123

filter[control]string

Control field from the partner's system

curl -i -X GET \
  'https://docs.simpay.pl/_mock/en/apis/directbilling/{serviceId}/transactions?filter%5Bcontrol%5D=string&filter%5BphoneNumber%5D=48123123123&filter%5Bstatus%5D=transaction_db_new' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Bodyapplication/json

successbooleanrequired

Request status

Example: true

dataArray of objects(directbillingTransactionItem)required

Example: [{"id":"dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a","status":"transaction_db_payed","value":0.34,"value_netto":0.24,"created_at":"2023-02-16T14:52:11+01:00","updated_at":"2023-02-16T14:52:11+01:00"}]

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

Service ID

data[].statusstring(directbillingTransactionStatus)required

Transaction status

Enum"transaction_db_new""transaction_db_confirmed""transaction_db_payed""transaction_db_rejected"

data[].valuenumber(float)required

data[].value_nettonumber(float)required

data[].operatorstringrequired

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": 1,
    "count": 1,
    "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

One of:

amountnumber(float)required

Transaction amount

Example: 19.99

amountTypestring

Transaction amount type

required - a fixed amount that the partner wants to obtain, the final amount to be paid will be visible on the gateway and depends on the operator
net - net amount
gross - gross amount

Default "gross"

Enum"required""net""gross"

Example: "gross"

descriptionstring<= 128

Transaction description visible on the payment gateway

Example: "Payment for virtual products"

controlstring<= 128

Parameter for use by the partner for, e.g. transaction identification

Example: "96125f23-d549-4bfc-a845-b781b5f1ad03"

returnsobject

URLs to redirect the customer after the transaction

Example: {"success":"https://www.simpay.pl/success","failure":"https://www.simpay.pl/failure"}

phoneNumberstring

Forced phone number

Example: "48123123123"

steamidstring(steamId64)

Optional field (steamid64)

curl -i -X POST \
  'https://docs.simpay.pl/_mock/en/apis/directbilling/{serviceId}/transactions' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 19.99,
    "amountType": "gross",
    "description": "Payment for virtual products",
    "control": "96125f23-d549-4bfc-a845-b781b5f1ad03",
    "returns": {
      "success": "https://www.simpay.pl/success",
      "failure": "https://www.simpay.pl/failure"
    },
    "phoneNumber": "48123123123"
  }'

Responses

Bodyapplication/json

successbooleanrequired

Request status

Example: true

dataobjectrequired

Example: {"transactionId":"1d87a1b3-18f8-4146-bcb1-c0c9f293b04f","redirectUrl":"https://db.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://db.simpay.pl/1d87a1b3-18f8-4146-bcb1-c0c9f293b04f"

Response

application/json

{
  "success": true,
  "data": {
    "transactionId": "1d87a1b3-18f8-4146-bcb1-c0c9f293b04f",
    "redirectUrl": "https://db.simpay.pl/1d87a1b3-18f8-4146-bcb1-c0c9f293b04f"
  }
}

Retrieving transaction information

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/directbilling/{serviceId}/transactions/{transactionId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Bodyapplication/json

successbooleanrequired

Request status

Example: true

dataobjectrequired

Example: {"id":"dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a","status":"transaction_db_payed","phoneNumber":null,"control":"1d87a1b3-18f8-4146-bcb1-c0c9f293b04f","value":16.67,"value_netto":10,"operator":"t-mobile","notify":{"is_send":false,"last_send_at":"2023-02-16T14:52:11+01:00","count":1},"created_at":"2023-02-16T14:52:11+01:00","updated_at":"2023-02-16T14:52:11+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(directbillingTransactionStatus)required

Transaction status

Enum"transaction_db_new""transaction_db_confirmed""transaction_db_payed""transaction_db_rejected"

data.phoneNumberstring or null(phone)

data.controlstring or null

Example: "1d87a1b3-18f8-4146-bcb1-c0c9f293b04f"

data.valuenumber(float)required

Example: 16.67

data.value_nettonumber(float)required

Example: 10

data.operatorstring or null

Enum"orange""plus""play""t-mobile"

Example: "t-mobile"

data.notifyobjectrequired

Example: {"is_send":false,"last_send_at":"2023-02-16T14:52:11+01:00","count":1}

data.notify.is_sendbooleanrequired

data.notify.last_send_atstring(date-time)(DateTime)required

Creation date in format: ISO 8601

data.notify.countintegerrequired

Example: 1

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": "dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a",
    "status": "transaction_db_payed",
    "phoneNumber": null,
    "control": "1d87a1b3-18f8-4146-bcb1-c0c9f293b04f",
    "value": 16.67,
    "value_netto": 10,
    "operator": "t-mobile",
    "notify": { … },
    "created_at": "2023-02-16T14:52:11+01:00",
    "updated_at": "2023-02-16T14:52:11+01:00"
  }
}

Receiving DirectBilling transaction informationWebhook

Request

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:
dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a|e14f8074|transaction_db_payed|11.07|13.67|5.00|https://www.simpay.pl/complete|https://www.simpay.pl/failure|test|123123123|1|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

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

Service ID

statusstring(directbillingTransactionStatus)required

Transaction status

Enum"transaction_db_new""transaction_db_confirmed""transaction_db_payed""transaction_db_rejected"

valuesobjectrequired

Transaction amounts

Example: {"net":11.07,"gross":13.61,"partner":5}

values.netnumber(float)required

Net transaction amount

Example: 11.07

values.grossnumber(float)required

Gross transaction amount

Example: 13.61

values.partnernumber(float)required

Partner's commission from the transaction

Example: 5

returnsobject

Example: {"complete":"https://www.simpay.pl/complete","failure":"https://www.simpay.pl/failure"}

controlstring

number_fromstringrequired

Phone number from which the transaction was made

Example: "48123123123"

providerintegerrequired

Example: 1

signaturestringrequired

Signature of the notification Read how to generate the signature

Example: "a3116cf4f1e960223c2cc3088bf387278b6675255209bdeaf96a2f316a2fadc1"

application/json

{
  "id": "dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a",
  "serviceId": "e14f8074",
  "status": "transaction_db_payed",
  "values": {
    "net": 11.07,
    "gross": 13.61,
    "partner": 5
  },
  "returns": {
    "complete": "https://www.simpay.pl/complete",
    "failure": "https://www.simpay.pl/failure"
  },
  "number_from": "48123123123",
  "provider": 1,
  "signature": "a3116cf4f1e960223c2cc3088bf387278b6675255209bdeaf96a2f316a2fadc1"
}

Responses

Return a 200 status to indicate that the data was received successfully

Bodytext/plain

string

Default "OK"

Response

text/plain

OK

Online Payments

OperationsWebhooks

simpay-api (1.0.0)

SMS

DirectBilling

Retrieving a list of services

Request

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Retrieving service information

Request

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Commission calculation

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

Request

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Retrieving transaction information

Request

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Receiving DirectBilling transaction informationWebhook

RequestExpand all

Signature

Calculating the signature when receiving a notification

Responses

How would you rate this section?

Not helpful at all

Extremely helpful

Online Payments

Request