Overview of the payment process

_images/paymentsapi.png

There are two versions of integration possible: basic integration with a redirect and iframe method which allows to embed payment interface as a part of the merchant’s own website.

With both methods:

  1. Amount is optional. If it’s not specified client will be asked to provide amount which (s)he would like to pay.

  2. Two charge modes are available: instant and delayed. With a latter transaction amount is locked on a client’s wallet and charged later on merchant’s demand (or voided if for some reason transaction should not be fulfilled).

Basic integration with a redirect

  1. Client selects Paymenticon as a payment method in the merchant’s checkout process.

  2. Payment session is created by a merchant system using Paymenticon REST API.

  3. Client browser is redirected to a unique address on a Paymenticon website. Access to that address is restricted to the IP address of a given client. On the Paymenticon’s payment page client:

    1. Authenticates himself as a Paymenticon wallet owner.

    2. Chooses payment amount (unless it was pre-defined by a merchant during session creation process).

    3. Verifies payment details and authorises transaction.

  4. Client is then redirected back to the merchant website.

  5. Merchant’s system either awaits notifications from Paymenticon or periodically polls session endpoint about session status changes.

  6. Optionally if „authorize” was selected as the charge_mode, merchant performs „capture” operation on a session to finalize payment and transfer money to his wallet.

Integration with an iframe

  1. Client selects Paymenticon as a payment method in the merchant’s checkout process.

  2. Payment session is created by a merchant system using Paymenticon REST API.

  3. Merchant’s system loads URL obtained from the API (while creating a session) into an iframe. Once the iframe contents is loaded client should:

    1. Authenticate himself as a Paymenticon wallet owner.

    2. Choose payment amount (unless it was pre-defined by a merchant during session creation process).

    3. Verify payment details and authorise transaction.

  4. While a client progresses through the payment process, a series of JavaScript "message"events is emitted from the iframe. It gives the ability to react to session events on an UI level (without waiting for API REST backend notifications). Important: these events are strictly complementary. In particular one cannot rely on it while designing financial flow of integrated systems. See below for a full list of possible events.

  5. Merchant’s system either awaits notifications from Paymenticon or periodically polls session endpoint about status changes.

  6. Optionally, if „authorize” was selected as the charge_mode, merchant performs „capture” operation on a session to finalize payment and transfer money to his wallet.

Iframe events

Example event sent from an iframe:

{
  "date": 1467380445, // date as an UNIX timestamp
  "session_id": "45158fcc-a33b-4439-b94e-4883f379633d", // session an event belongs to
  "event": "session_started" // name of an event
}

Currently available events:

  • session_started - payment session has just been started.

  • session_error - if payment session could not be initialized (eg. due to client_ip mismatch, session expired).

  • user_logged_in - client has been authenticated. His data can now be obtained via the /data/ endpoint.

  • session_succeeded - session completed successfully.

  • session_failed - session process failed to complete successfully.

  • user_left_session - user deliberately left session (eg. clicked on a close button).

  • user_redirected - client was redirected to external service (eg. bank) to complete payment process.

Feature policy of an iframe

Since a camera is used for authorization an appropriate feature policy has to be enabled for an iframe:

<iframe src="<ifame_url>" allow="camera"></iframe>

More information:

https://dev.chromium.org/Home/chromium-security/deprecating-permissions-in-cross-origin-iframes

Payment confirmation mode (charge_mode)

Capture - instant settlement

Capture mode results in an instant settlement of a transaction. Specified amount is transferred to merchant’s wallet immediately after client’s confirmation.

Authorize - delayed settlement

Authorize mode on the other hand results only in pre-authorization. This means that a transaction amount is locked on a client’s wallet. Merchant now has two options:

  1. Finish the transaction (capture) - locked amount will be transferred to the merchant’s wallet.

  2. Cancel and release the locked amount (void) - the payment session will be canceled and the amount will be unlocked on the client’s wallet.

If the transaction is not captured or voided before the session expiration time, it is automatically discarded - it equals to the void operation call by the system.

Payment without logging in (payment_without_login_enabled)

Irrespective of the chosen integration method (iframe / redirect), the partner can activate a payment without signing into Paymenticon (via an external payment provider). This allows clients to pay for merchant services without using a Paymenticon wallet.

Enabling this option for a session results with a „pay without logging in” section being shown. Within a list of payment methods is presented. After a client selects desired payment method, (s)he is redirected to the appropriate external provider to complete the payment there. After successful completion client is redirected back to a success/error URL provided by the merchant.

Transaction amount in this case is restricted to a currently valid limit for Paymenticon anonymous accounts.

Configuration data

Following authentication data will be provided to a Partner:

  1. wallet_ref - identifier of a Paymenticon wallet where payments will be collected. It acts as a „login” part when authorizing API requests.

  2. API KEY - a key to authenticate and verify the integrity of all requests.

Data mentioned above can be accessed after logging into a client panel. One can generate new API KEY there as well.

Communication guidelines

Communication with the service is performed via the HTTPS protocol. The API is based on the REST architecture and data is exchanged using the JSON format.

Requirements:

  • All communication has to be performed on top of the HTTPS protocol.

  • If the Partner chooses to subscribe to a payment session status change notifications, the receiving HTTPS endpoint must have a valid TLS certificate installed.

  • Each request must have an X-Paymenticon-Time HTTP header containing the UNIX timestamp (eg. 1470041886). If time from the query diverges from the present by more than 15 minutes, the query will be rejected.

  • Each request has to be signed with the appropriate Authorisation header (see Authorization section).

  • UTF-8 is used as a character encoding of the query contents.

Additional information:

  • Time-based data uses UTC time zone.

  • Amount values are described as 1/100 of a given currency (cents, pences etc.). Eg. for 10.00 EUR use 1000.

Additional transaction identification

The HTTP header X-Paymenticon-Device may be used to pass identifier of an entity (eg. a device or host) from which the actual payment requests are originating.

An example use case is a group of kiosk terminals connected to a single backend service which makes the actual Payment API calls. One could pass the serial number of given kiosk terminal to be able to correlate given transaction to specific user-facing hardware later.

Eg.:

X-Paymenticon-Device: D43D7EEB3422

Authorization of API calls

The HMAC-SHA256 checksum is used to authenticate API queries. It should be passed with the Authorization parameter of an HTTPS request as follows:

Authorization: hmac <wallet_ref>:<hmac_digest>

Base components of a checksum (the hmac_digest part below) are:

  1. HTTP method name in uppercase (eg. POST)

  2. Full API endpoint URL (eg. https://pay.paymenticon.com/session/)

  3. X-Paymenticon-Time header contents (eg. 1470041886)

If parameters are passed to an endpoint within the message body, all it’s values should be sorted by keys and glued together. The result forms another (fourth) component of a checksum.

For example:

{
    "ccc": "valueofCCC",
    "zzz": "valueofZZZ",
    "aaa": "valueofAAA"
}

the value to be added to base components will be:

valueofAAAvalueofCCCvalueofZZZ

In case a parameter list contains nested objects, every such object should be processed recursively in the same manner. The „flattened” values should fill the object’s place within the underlying, base object. For example with:

{
    "ccc": "valueofCCC",
    "zzz": {
    "222": "valueZZZ222",
    "111": "valueZZZ111"
    },
    "aaa": "valueofAAA"
}

we start with „zzz” key to obtain a string "valueZZZ111valueZZZ222", which we treat as a value of „zzz” while processing base object. Finally we end up with:

valueofAAAvalueofCCCvalueZZZ111valueZZZ222

Complete example

Authentication data:

wallet_ref: WLT-001
apikey: fb5e9519-0e2b-478d-9e04-15b31239c1cc

Query:

POST /session/45158fcc-a33b-4439-b94e-4883f379633d HTTP/1.1
Host: pay.paymenticon.com
X-Paymenticon-Time: 1470041886
{
    "client_ip": "127.0.0.1",
    "amount": 1000,
    "currency": "PLN",
    "success_url": "https://myshop.com/order/success.html",
    "error_url": "https://myshop.com/order/error.html",
    "description": "order 123"
}

Serialization process:

Join values in the following order:

  1. HTTP method name

  2. url address

  3. Value of a X-Paymenticon-Time header

  4. „Flattened” values of a query object. If the query body is empty (eg. for a GET type requests) we use an empty string here.

From the example data below we get the following string:

POSThttps://pay.paymenticon.com/session/45158fcc-a33b-4439-b94e-4883f379633d14700418861000127.0.0.1PLNorder 123https://myshop.com/order/error.htmlhttps://myshop.com/order/success.html

which in pair with an API KEY value is used to generate a HMAC-SHA256 digest:

818d3a296abcd9d2631156548442ee364efe72af7a986dc24b92d2beaa8da0c3

Finally the full Authorization header for this example is:

Authorization: hmac WLT-001: 818d3a296abcd9d2631156548442ee364efe72af7a986dc24b92d2beaa8da0c3`

REST API methods

Create payment session

http

POST /sessions/ HTTP/1.1
Host: pay.paymenticon.com
Accept: application/json
Content-Type: application/json
X-Paymenticon-Time: 1470041886
Authorization: hmac <wallet_ref>:<hmac_digest>

{
  "client_ip": "127.0.0.1",
  "charge_mode": "authorize",
  "amount": 1000,
  "currency": "PLN",
  "success_url": "https://myshop.com/order/success.html",
  "error_url": "https://myshop.com/order/error.html",
  "description": "myshop order 123",
  "payment_without_login_enabled": true
}

curl

curl -i -X POST https://pay.paymenticon.com/sessions/ -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Paymenticon-Time: 1470041886' -H 'Authorization: hmac <wallet_ref>:<hmac_digest>' --data-raw '{"amount": 1000, "charge_mode": "authorize", "client_ip": "127.0.0.1", "currency": "PLN", "description": "myshop order 123", "error_url": "https://myshop.com/order/error.html", "payment_without_login_enabled": true, "success_url": "https://myshop.com/order/success.html"}'

wget

wget -S -O- https://pay.paymenticon.com/sessions/ --header='Accept: application/json' --header='Content-Type: application/json' --header='X-Paymenticon-Time: 1470041886' --header='Authorization: hmac <wallet_ref>:<hmac_digest>' --post-data='{"amount": 1000, "charge_mode": "authorize", "client_ip": "127.0.0.1", "currency": "PLN", "description": "myshop order 123", "error_url": "https://myshop.com/order/error.html", "payment_without_login_enabled": true, "success_url": "https://myshop.com/order/success.html"}'

httpie

echo '{
  "amount": 1000,
  "charge_mode": "authorize",
  "client_ip": "127.0.0.1",
  "currency": "PLN",
  "description": "myshop order 123",
  "error_url": "https://myshop.com/order/error.html",
  "payment_without_login_enabled": true,
  "success_url": "https://myshop.com/order/success.html"
}' | http POST https://pay.paymenticon.com/sessions/ Accept:application/json Content-Type:application/json X-Paymenticon-Time:1470041886 Authorization:'hmac <wallet_ref>:<hmac_digest>'

python-requests

requests.post('https://pay.paymenticon.com/sessions/', headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Paymenticon-Time': '1470041886', 'Authorization': 'hmac <wallet_ref>:<hmac_digest>'}, json={'amount': 1000, 'charge_mode': 'authorize', 'client_ip': '127.0.0.1', 'currency': 'PLN', 'description': 'myshop order 123', 'error_url': 'https://myshop.com/order/error.html', 'payment_without_login_enabled': True, 'success_url': 'https://myshop.com/order/success.html'})

response

HTTP/1.1 201 OK
Content-Type: application/json
X-Paymenticon-Time: 1470041886

{
  "wallet_ref": "WLT-001",
  "charge_mode": "authorize",
  "session_id": "45158fcc-a33b-4439-b94e-4883f379633d",
  "status": "created",
  "url": "https://pay.paymenticon.com/process/835f664a-5140-4bb7-9c04-86c68da55484/",
  "created": 1467380445,
  "expires": 1467382245,
  "amount": 5,
  "authorized_amount": 0,
  "currency": "EUR",
  "is_closed": false,
  "_signature": "<hmac_digest>"
}
POST https://pay.paymenticon.com/sessions/
Response Headers
  • Accept – the response content type depends on Accept header

  • Authorization – required HMAC authorization

  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – call time as UNIX timestamp

Request Headers
  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – response time as UNIX timestamp

Request JSON Object
  • client_ip (string) – [required] IP address of a client; performing payment authorization will be possible from this IP address only .

  • currency (string) – [required] currency as an ISO 4217 3-letter code.

  • charge_mode (string) – [required] payment settlement mode - capture or authorize (available modes)

  • amount (int) – [optional] - payment amount as an integer value or null if it was not set. All amounts are described as a 1/100 of given currency (cents, pences etc.) eg. for 10.00 EUR use 1000.

  • success_url (string) – [optional] - URL where client will be redirected on successful payment.

  • error_url (string) – [optional] - URL where client will be redirected in case of an error.

  • description (string) – [optional] - string with a max length of 100. It can be used to associate a session with a particular transaction in the partner’s system. Content will be visible to customer as a transaction title within transaction history page.

  • voucher_id (string) – [optional] - customer’s voucher id (usually stored in QR code or on smartcard). Mainly to aid hardware (eg. card reader) integration. In case it is provided client will be asked to provide PIN straight away without scanning QR code.

  • payment_without_login_enabled (boolean) – [optional] - if set to true, payment without logging in option for this session will be available. Option is not available when parameter „only_registered” is set to „true”.

  • only_registered (boolean) – [optional] - if set to true, only registered wallet can proceed payment. Option is not available when parameter payment_without_login_enabled is set to true.

  • initial_gateway (string) – [optional] - If the value is provided, iframe will be initialized with the chosen gateway. Option is not available when parameter payment_without_login_enabled is set to false. It requires to enter the symbol defined below

Response JSON Object
  • wallet_ref (string) – Identifier of a merchant’s wallet.

  • charge_mode (string) – payment settlement mode.

  • session_id (string) – unique payment session identifier.

  • status (string) – payment session status (on this stage it will always be „created”)

  • url (string) – URL to display for a client in an iframe or redirect to; to initialize UI with specific language, append „lang” parameter at the end: „|lang=pl”.

  • created (string) – session creation time (as an UNIX timestamp).

  • expires (string) – session expiration time (as an UNIX timestamp).

  • amount (int) – payment amount as an integer value or null if it was not set.

  • authorized_amount (int) – amount authorized by a client as an integer value or null if it was not set yet. If the amount was not provided by a merchant, this field represents an amount entered by a client in the payment process.

  • currency (string) – currency for above amounts as an ISO 4217 3-letter code.

  • is_closed (boolean) – true if a session is closed (finalized).

  • _signature (string) – Response signature. Calculated in the same manner as a hmac*digest value used to sign the request (with the response’s X-Paymenticon-Time header and response body as a data source).

Status Codes
  • 201 Created – session created properly

  • 400 Bad Request – invalid request (missing parameters or invalid values)

  • 401 Unauthorized – could not authorize an API call (invalid data in Authorization header)

  • 403 Forbidden – access to given resource is not allowed

  • 404 Not Found – resource has not been found (eg. payment session or wallet)

Capture modes:

  • capture - instant settlement of a transaction.

  • authorize - settlement is delayed, amount is pre-authorized on a client’s wallet awaiting merchant decision to either void or capture.

Session statuses:

  • created - Newly created session.

  • loggedin - Client authorized himself during the session.

  • authorized - Client pre-authorized the payment (transaction amount is locked on a client’s wallet).

  • captured - payment amount was transferred to a merchant’s wallet.

  • cancelled - payment cancelled by a client (clicked on a cancel button during the payment process) or merchant (void called after the process on pre-authorized payment) or system (void called on a transaction after session expiration time).

  • declined - Payment declined by a system.

BLIK One Click configuration:

If you want to use the BLIK One Click function, the resulting url should be extended by two parameters „|blikUserUid=”string”|blikLabel=”string”:

  • blikUserUid - to initialize UI with info for BLIK One Click (this value is unique for each user. And it is necessary to define the user to pay BLIK One Click.)

  • blikLabel - to initialize UI with info for BLIK One Click (is the name by which the store will be remembered in the client’s mobile application).

Example: https://pay.paymenticon.com/v2/iframe#id=2d96402d-7229-40d6-957d-a90ee684cf8f|blikUserUid=TEST_ALIAS_UNIQUE|blikLabel=shoes shop NY?lang=pl"

Gateway symbols:

  • PAYMENTICON - Paymenticon

  • ALIOR - Alior Bank

  • BGZ - Bank BGŻ

  • BLIK - Blik

  • BANKISPOLDZIELCZE - Banki Spółdzielcze

  • MILLENNIUM - Bank Millennium

  • BOS - Bank Ochrony Środowiska

  • BANKPOCZTOWY - Bank Pocztowy

  • BGZPARIBAS - BGŻ BNP Paribas Polska

  • SANTANDER_BPH - BPH

  • CITI - Citi Handlowy

  • CREDITAGRICOLE - Credit Agricole

  • DEUTSCHEBANK - Deutsche Bank

  • DNBNORD - DnB Nord

  • PAYMENTFORM - Druczek płatności / Przelew z innego banku

  • ESKOK - E-SKOK

  • EUROBANK - Eurobank

  • EUROPAYMENT - Euro Payment

  • GETBANK - Get Bank

  • GETINONLINE - GetIn Online

  • GOOGLEPAY - Google Pay

  • IDEABANK - Idea Bank

  • IKO - IKO

  • ING - ING Bank Śląski

  • INTELIGO - Inteligo

  • CARD - Karta płatnicza

  • MASTERPASS - MasterPass

  • MBANK - mBank

  • NEOBANK - Neo Bank

  • NESTBANK - Nest Bank

  • NOBLEBANK - Noble Bank

  • ORANGE - Orange

  • PAYPAL - PayPal

  • PBS - PBS

  • PEKAO - PEKAO S.A.

  • PKOBP - PKO BP

  • PLUSBANK - Plus Bank

  • WALLET - Portfel

  • RAIFFEISEN - Raiffeisen Polbank

  • SANTANDER_WBK - Santander

  • TMOBILE - T-Mobile Usługi Bankowe

  • TOYOTABANK - Toyota Bank

  • VISACHECKOUT - Visa Checkout

  • VOLKSWAGENBANK - Volkswagen Bank

  • ALIORRDC - Zakupy Ratalne Alior

Create p2p transfer session

http

POST /sessions/ HTTP/1.1
Host: pay.paymenticon.com
Accept: application/json
Content-Type: application/json
X-Paymenticon-Time: 1470041886
Authorization: hmac <wallet_ref>:<hmac_digest>

{
  "type": "p2p_transfer",
  "receiver_wallet_ref": "WLT-052",
  "client_ip": "127.0.0.1",
  "charge_mode": "authorize",
  "amount": 1000,
  "currency": "PLN",
  "success_url": "https://myshop.com/order/success.html",
  "error_url": "https://myshop.com/order/error.html",
  "description": "myshop order 123"
}

curl

curl -i -X POST https://pay.paymenticon.com/sessions/ -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Paymenticon-Time: 1470041886' -H 'Authorization: hmac <wallet_ref>:<hmac_digest>' --data-raw '{"amount": 1000, "charge_mode": "authorize", "client_ip": "127.0.0.1", "currency": "PLN", "description": "myshop order 123", "error_url": "https://myshop.com/order/error.html", "receiver_wallet_ref": "WLT-052", "success_url": "https://myshop.com/order/success.html", "type": "p2p_transfer"}'

wget

wget -S -O- https://pay.paymenticon.com/sessions/ --header='Accept: application/json' --header='Content-Type: application/json' --header='X-Paymenticon-Time: 1470041886' --header='Authorization: hmac <wallet_ref>:<hmac_digest>' --post-data='{"amount": 1000, "charge_mode": "authorize", "client_ip": "127.0.0.1", "currency": "PLN", "description": "myshop order 123", "error_url": "https://myshop.com/order/error.html", "receiver_wallet_ref": "WLT-052", "success_url": "https://myshop.com/order/success.html", "type": "p2p_transfer"}'

httpie

echo '{
  "amount": 1000,
  "charge_mode": "authorize",
  "client_ip": "127.0.0.1",
  "currency": "PLN",
  "description": "myshop order 123",
  "error_url": "https://myshop.com/order/error.html",
  "receiver_wallet_ref": "WLT-052",
  "success_url": "https://myshop.com/order/success.html",
  "type": "p2p_transfer"
}' | http POST https://pay.paymenticon.com/sessions/ Accept:application/json Content-Type:application/json X-Paymenticon-Time:1470041886 Authorization:'hmac <wallet_ref>:<hmac_digest>'

python-requests

requests.post('https://pay.paymenticon.com/sessions/', headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Paymenticon-Time': '1470041886', 'Authorization': 'hmac <wallet_ref>:<hmac_digest>'}, json={'amount': 1000, 'charge_mode': 'authorize', 'client_ip': '127.0.0.1', 'currency': 'PLN', 'description': 'myshop order 123', 'error_url': 'https://myshop.com/order/error.html', 'receiver_wallet_ref': 'WLT-052', 'success_url': 'https://myshop.com/order/success.html', 'type': 'p2p_transfer'})

response

HTTP/1.1 201 OK
Content-Type: application/json
X-Paymenticon-Time: 1470041886

{
  "type": "p2p_transfer",
  "receiver_wallet_ref": "WLT-052",
  "wallet_ref": "WLT-001",
  "charge_mode": "authorize",
  "session_id": "45158fcc-a33b-4439-b94e-4883f379633d",
  "status": "created",
  "url": "https://pay.paymenticon.com/process/835f664a-5140-4bb7-9c04-86c68da55484/",
  "created": 1467380445,
  "expires": 1467382245,
  "amount": 5,
  "authorized_amount": 0,
  "currency": "EUR",
  "is_closed": false,
  "_signature": "<hmac_digest>"
}
POST https://pay.paymenticon.com/sessions/
Request Headers
  • Accept – the response content type depends on Accept header

  • Authorization – required HMAC authorization

  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – call time as UNIX timestamp

Response Headers
  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – response time as UNIX timestamp

Request JSON Object
  • type (string) – [required] „p2p_transfer”

  • receiver_wallet_ref (string) – [required] receiver wallet

  • client_ip (string) – [required] IP address of a client; performing payment authorization will be possible from this IP address only .

  • currency (string) – [required] currency as an ISO 4217 3-letter code.

  • charge_mode (string) – [required] payment settlement mode - capture or authorize (available modes)

  • amount (int) – [optional] - payment amount as an integer value or null if it was not set. All amounts are described as a 1/100 of given currency (cents, pences etc.) eg. for 10.00 EUR use 1000.

  • success_url (string) – [optional] - URL where client will be redirected on successful payment.

  • error_url (string) – [optional] - URL where client will be redirected in case of an error.

  • description (string) – [optional] - string with a max length of 100. It can be used to associate a session with a particular transaction in the partner’s system. Content will be visible to customer as a transaction title within transaction history page.

Response JSON Object
  • type (string) – session type

  • receiver_wallet_ref (string) – transfer receiver wallet

  • wallet_ref (string) – Identifier of a merchant’s wallet.

  • charge_mode (string) – payment settlement mode.

  • session_id (string) – unique payment session identifier.

  • status (string) – payment session status (on this stage it will always be „created”)

  • url (string) – URL to display for a client in an iframe or redirect to; to initialize UI with specific language, append „lang” parameter at the end: „|lang=pl”.

  • created (string) – session creation time (as an UNIX timestamp).

  • expires (string) – session expiration time (as an UNIX timestamp).

  • amount (int) – payment amount as an integer value or null if it was not set.

  • authorized_amount (int) – amount authorized by a client as an integer value or null if it was not set yet. If the amount was not provided by a merchant, this field represents an amount entered by a client in the payment process.

  • currency (string) – currency for above amounts as an ISO 4217 3-letter code.

  • is_closed (boolean) – true if a session is closed (finalized).

  • _signature (string) – Response signature. Calculated in the same manner as a hmac*digest value used to sign the request (with the response’s X-Paymenticon-Time header and response body as a data source).

Status Codes
  • 201 Created – session created properly

  • 400 Bad Request – invalid request (missing parameters or invalid values)

  • 401 Unauthorized – could not authorize an API call (invalid data in Authorization header)

  • 403 Forbidden – access to given resource is not allowed

  • 404 Not Found – resource has not been found (eg. payment session or wallet)

Capture modes:

  • capture - instant settlement of a transaction.

  • authorize - settlement is delayed, amount is pre-authorized on a client’s wallet awaiting merchant decision to either void or capture.

Session statuses:

  • created - Newly created session.

  • loggedin - Client authorized himself during the session.

  • authorized - Client pre-authorized the payment (transaction amount is locked on a client’s wallet).

  • captured - payment amount was transferred to a merchant’s wallet.

  • cancelled - payment cancelled by a client (clicked on a cancel button during the payment process) or merchant (void called after the process on pre-authorized payment) or system (void called on a transaction after session expiration time).

  • declined - Payment declined by a system.

Create data access session

http

POST /sessions/ HTTP/1.1
Host: pay.paymenticon.com
Accept: application/json
Content-Type: application/json
X-Paymenticon-Time: 1470041886
Authorization: hmac <wallet_ref>:<hmac_digest>

{
  "type": "data_access",
  "scopes": ["get_transactions", "get_confirmation_of_funds", "get_wallet_funds"],
  "client_ip": "127.0.0.1",
  "success_url": "https://myshop.com/order/success.html",
  "error_url": "https://myshop.com/order/error.html",
  "description": "optional description"
}

curl

curl -i -X POST https://pay.paymenticon.com/sessions/ -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Paymenticon-Time: 1470041886' -H 'Authorization: hmac <wallet_ref>:<hmac_digest>' --data-raw '{"client_ip": "127.0.0.1", "description": "optional description", "error_url": "https://myshop.com/order/error.html", "scopes": ["get_transactions", "get_confirmation_of_funds", "get_wallet_funds"], "success_url": "https://myshop.com/order/success.html", "type": "data_access"}'

wget

wget -S -O- https://pay.paymenticon.com/sessions/ --header='Accept: application/json' --header='Content-Type: application/json' --header='X-Paymenticon-Time: 1470041886' --header='Authorization: hmac <wallet_ref>:<hmac_digest>' --post-data='{"client_ip": "127.0.0.1", "description": "optional description", "error_url": "https://myshop.com/order/error.html", "scopes": ["get_transactions", "get_confirmation_of_funds", "get_wallet_funds"], "success_url": "https://myshop.com/order/success.html", "type": "data_access"}'

httpie

echo '{
  "client_ip": "127.0.0.1",
  "description": "optional description",
  "error_url": "https://myshop.com/order/error.html",
  "scopes": [
    "get_transactions",
    "get_confirmation_of_funds",
    "get_wallet_funds"
  ],
  "success_url": "https://myshop.com/order/success.html",
  "type": "data_access"
}' | http POST https://pay.paymenticon.com/sessions/ Accept:application/json Content-Type:application/json X-Paymenticon-Time:1470041886 Authorization:'hmac <wallet_ref>:<hmac_digest>'

python-requests

requests.post('https://pay.paymenticon.com/sessions/', headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Paymenticon-Time': '1470041886', 'Authorization': 'hmac <wallet_ref>:<hmac_digest>'}, json={'client_ip': '127.0.0.1', 'description': 'optional description', 'error_url': 'https://myshop.com/order/error.html', 'scopes': ['get_transactions', 'get_confirmation_of_funds', 'get_wallet_funds'], 'success_url': 'https://myshop.com/order/success.html', 'type': 'data_access'})

response

HTTP/1.1 201 OK
Content-Type: application/json
X-Paymenticon-Time: 1470041886

{
  "type": "data_access",
  "wallet_ref": "WLT-001",
  "session\_id": "45158fcc-a33b-4439-b94e-4883f379633d",
  "status": "created",
  "url": "https://pay.paymenticon.com/process/835f664a-5140-4bb7-9c04-86c68da55484/",
  "created": 1467380445,
  "expires": 1467382245,
  "is_closed": false,
  "voucher_id": "",
  "scopes": ["get_transactions", "get_confirmation_of_funds", "get_wallet_funds"],
  "_signature": "<hmac_digest>"
}
POST https://pay.paymenticon.com/sessions/
Request Headers
  • Accept – the response content type depends on Accept header

  • Authorization – required HMAC authorization

  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – call time as UNIX timestamp

Response Headers
  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – response time as UNIX timestamp

Request JSON Object
  • type (string) – [required] „data_access”

  • scopes (list) – [required] list of scopes to acquire from user

  • client_ip (string) – [required] IP address of a client; performing scopes acceptance authorization will be possible from this IP address only.

  • success_url (string) – [optional] URL where client will be redirected on successful confirmation.

  • error_url (string) – [optional] URL where client will be redirected in case of an error.

  • description (string) – [optional] string with a max length of 100. Optional description visible for user during scopes acceptance process.

Response JSON Object
  • type (string) – session type

  • wallet_ref (string) – Identifier of a merchant’s wallet.

  • session_id (string) – unique payment session identifier.

  • status (string) – payment session status (on this stage it will always be „created”)

  • url (string) – URL to display for a client in an iframe or redirect to; to initialize UI with specific language, append „lang” parameter at the end: „|lang=pl”.

  • created (string) – session creation time (as an UNIX timestamp).

  • expires (string) – session expiration time (as an UNIX timestamp).

  • is_closed (boolean) – true if a session is closed (finalized).

  • scopes (list) – list of authorized scopes.

  • _signature (string) – Response signature. Calculated in the same manner as a hmac*digest value used to sign the request (with the response’s X-Paymenticon-Time header and response body as a data source).

Status Codes
  • 201 Created – session created properly

  • 400 Bad Request – invalid request (missing parameters or invalid values)

  • 401 Unauthorized – could not authorize an API call (invalid data in Authorization header)

  • 403 Forbidden – access to given resource is not allowed

  • 404 Not Found – resource has not been found (eg. payment session or wallet)

Data access session statuses:

  • created - Newly created session.

  • canceled - Process canceled

  • data_access_accepted - user has accepted session

  • data_access_rejected - user has rejected session

Fetch session information

http

GET /sessions/(session_id:str) HTTP/1.1
Host: pay.paymenticon.com
Accept: application/json
Content-Type: application/json
X-Paymenticon-Time: 1470041886
Authorization: hmac <wallet_ref>:<hmac_digest>

curl

curl -i 'https://pay.paymenticon.com/sessions/(session_id:str)' -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Paymenticon-Time: 1470041886' -H 'Authorization: hmac <wallet_ref>:<hmac_digest>'

wget

wget -S -O- 'https://pay.paymenticon.com/sessions/(session_id:str)' --header='Accept: application/json' --header='Content-Type: application/json' --header='X-Paymenticon-Time: 1470041886' --header='Authorization: hmac <wallet_ref>:<hmac_digest>'

httpie

http 'https://pay.paymenticon.com/sessions/(session_id:str)' Accept:application/json Content-Type:application/json X-Paymenticon-Time:1470041886 Authorization:'hmac <wallet_ref>:<hmac_digest>'

python-requests

requests.get('https://pay.paymenticon.com/sessions/(session_id:str)', headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Paymenticon-Time': '1470041886', 'Authorization': 'hmac <wallet_ref>:<hmac_digest>'})

response

HTTP/1.1 200 OK
Content-Type: application/json
X-Paymenticon-Time: 1470041886

{
  "client_ip": "127.0.0.1",
  "charge_mode": "authorize",
  "amount": 1000,
  "currency": "PLN",
  "success_url": "https://myshop.com/order/success.html",
  "error_url": "https://myshop.com/order/error.html",
  "description": "myshop order 123",
  "payment_without_login_enabled": true
}
GET https://pay.paymenticon.com/sessions/(session_id: str)/
Request Headers
  • Accept – the response content type depends on Accept header

  • Authorization – required HMAC authorization

  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – call time as UNIX timestamp

Response Headers
  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – response time as UNIX timestamp

Query Parameters
  • session_id (string) – previously created session id

Status Codes

Notifications about session status changes

Granted that confirmation URL was set up in a client panel, notifications about session status changes will be sent to that URL. Queries will be sent as a HTTP POST request with JSON body. The notification will be sent repeatedly until either HTTP 200 status is received or a 12th try has been made.

The message is signed in the same manner as all Payments API requests (see Authorization session) so the authenticity and integrity can be verified. Although there is one difference: because notifications are sent asynchronously the X-Paymenticon-Time header is not included. In that case use empty string as it’s value during calculation of a signature.

Alternatively, instead of providing a return address, the partner’s system can retrieve information about the given session at specified intervals.

Data provided:

The exact same structure as in a „Create payment session” method.

Confirming delayed transaction (capture)

Captures previously locked amount from a client’s wallet and closes session.

http

POST /sessions/(session_id:str)/capture/ HTTP/1.1
Host: pay.paymenticon.com
Accept: application/json
Content-Type: application/json
X-Paymenticon-Time: 1470041886
Authorization: hmac <wallet_ref>:<hmac_digest>

curl

curl -i -X POST 'https://pay.paymenticon.com/sessions/(session_id:str)/capture/' -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Paymenticon-Time: 1470041886' -H 'Authorization: hmac <wallet_ref>:<hmac_digest>'

wget

wget -S -O- 'https://pay.paymenticon.com/sessions/(session_id:str)/capture/' --header='Accept: application/json' --header='Content-Type: application/json' --header='X-Paymenticon-Time: 1470041886' --header='Authorization: hmac <wallet_ref>:<hmac_digest>'

httpie

http POST 'https://pay.paymenticon.com/sessions/(session_id:str)/capture/' Accept:application/json Content-Type:application/json X-Paymenticon-Time:1470041886 Authorization:'hmac <wallet_ref>:<hmac_digest>'

python-requests

requests.post('https://pay.paymenticon.com/sessions/(session_id:str)/capture/', headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Paymenticon-Time': '1470041886', 'Authorization': 'hmac <wallet_ref>:<hmac_digest>'})

response

HTTP/1.1 202 OK
POST https://pay.paymenticon.com/sessions/(session_id: str)/capture/
Request Headers
  • Accept – the response content type depends on Accept header

  • Authorization – required HMAC authorization

  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – call time as UNIX timestamp

Response Headers
  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – response time as UNIX timestamp

Query Parameters
  • session_id (string) – previously created session id

Status Codes

Cancelling delayed transaction (void)

Cancels and closes the session, releases the amount locked on a client’s wallet.

http

POST /sessions/(session_id:str)/void/ HTTP/1.1
Host: pay.paymenticon.com
Accept: application/json
Content-Type: application/json
X-Paymenticon-Time: 1470041886
Authorization: hmac <wallet_ref>:<hmac_digest>

curl

curl -i -X POST 'https://pay.paymenticon.com/sessions/(session_id:str)/void/' -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Paymenticon-Time: 1470041886' -H 'Authorization: hmac <wallet_ref>:<hmac_digest>'

wget

wget -S -O- 'https://pay.paymenticon.com/sessions/(session_id:str)/void/' --header='Accept: application/json' --header='Content-Type: application/json' --header='X-Paymenticon-Time: 1470041886' --header='Authorization: hmac <wallet_ref>:<hmac_digest>'

httpie

http POST 'https://pay.paymenticon.com/sessions/(session_id:str)/void/' Accept:application/json Content-Type:application/json X-Paymenticon-Time:1470041886 Authorization:'hmac <wallet_ref>:<hmac_digest>'

python-requests

requests.post('https://pay.paymenticon.com/sessions/(session_id:str)/void/', headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Paymenticon-Time': '1470041886', 'Authorization': 'hmac <wallet_ref>:<hmac_digest>'})

response

HTTP/1.1 202 OK
POST https://pay.paymenticon.com/sessions/(session_id: str)/void/
Request Headers
  • Accept – the response content type depends on Accept header

  • Authorization – required HMAC authorization

  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – call time as UNIX timestamp

Response Headers
  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – response time as UNIX timestamp

Query Parameters
  • session_id (string) – previously created session id

Status Codes

Get personal data of a payer

http

GET /sessions/(session_id:str)/data/ HTTP/1.1
Host: pay.paymenticon.com
Accept: application/json
Content-Type: application/json
X-Paymenticon-Time: 1470041886
Authorization: hmac <wallet_ref>:<hmac_digest>

curl

curl -i 'https://pay.paymenticon.com/sessions/(session_id:str)/data/' -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Paymenticon-Time: 1470041886' -H 'Authorization: hmac <wallet_ref>:<hmac_digest>'

wget

wget -S -O- 'https://pay.paymenticon.com/sessions/(session_id:str)/data/' --header='Accept: application/json' --header='Content-Type: application/json' --header='X-Paymenticon-Time: 1470041886' --header='Authorization: hmac <wallet_ref>:<hmac_digest>'

httpie

http 'https://pay.paymenticon.com/sessions/(session_id:str)/data/' Accept:application/json Content-Type:application/json X-Paymenticon-Time:1470041886 Authorization:'hmac <wallet_ref>:<hmac_digest>'

python-requests

requests.get('https://pay.paymenticon.com/sessions/(session_id:str)/data/', headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Paymenticon-Time': '1470041886', 'Authorization': 'hmac <wallet_ref>:<hmac_digest>'})

response

HTTP/1.1 200 OK
Content-Type: application/json
X-Paymenticon-Time: 1470041886

{ "wallet_ref": "WLT-001",
  "category": "limited",
  "email": "[email protected]",
  "phone_number": "+48555555555",
  "personal": {
    "first_name": "John",
    "middle_name": null,
    "last_name": "Doe",
    "gender": "male",
    "date_of_birth": "1900-01-01",
    "address": "Memory Lane 9",
    "city": "Anytown",
    "postal": "40042",
    "country": "PL",
    "national_id": "90090515836",
    "nationality": "PL",
    "is_verified": true
  },
  "accounts": [{
    "iban": "PL36175015141120000000000002",
    "swift": "RCBWPLPW",
    "currency": "PLN"
  }],
  "_signature": "<hmac_digest>"
}
GET https://pay.paymenticon.com/sessions/(session_id: str)/data/
Request Headers
  • Accept – the response content type depends on Accept header

  • Authorization – required HMAC authorization

  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – call time as UNIX timestamp

Response Headers
  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – response time as UNIX timestamp

Query Parameters
  • session_id (string) – previously created session id

Response JSON Object
  • wallet_ref (string) – Identifier of a client’s wallet.

  • category (string) – wallet category: „anonymous”. „limited”, „standard”, „enhanced”, „gift”.

  • email (string) – Email address or null.

  • phone_number (string) – string with a client’s phone number.

  • personal (string) – personal data

  • -->first_name (string) – first name

  • -->middle_name (string) – middle name

  • -->last_name (string) – last name

  • -->gender (string) – „male” or „female”

  • -->date_of_birth (string) – date of birth in form: YYYY-MM-DD

  • -->address (string) – address line

  • -->city (string) – city name

  • -->postal (string) – postal code

  • -->country (string) – an ISO 3166-1 alpha-2 country code

  • -->national_id (string) – National identification number

  • -->nationality (string) – an ISO 3166-1 alpha-2 nationality code

  • -->is_verified (boolean) – true if the KYC procedure was performed on this set of data.

  • accounts (list) – dedicated bank account numbers for this wallet [{"iban": "", "swift": "", "currency": ""}]

  • _signature (string) – Response signature. Calculated in the same manner as a hmac*digest value used to sign the request (with the response’s X-Paymenticon-Time header and response body as a data source).

Status Codes

Get wallet stats for payer

http

GET /sessions/(session_id:str)/data/stats/ HTTP/1.1
Host: pay.paymenticon.com
Accept: application/json
Content-Type: application/json
X-Paymenticon-Time: 1470041886
Authorization: hmac <wallet_ref>:<hmac_digest>

curl

curl -i 'https://pay.paymenticon.com/sessions/(session_id:str)/data/stats/' -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Paymenticon-Time: 1470041886' -H 'Authorization: hmac <wallet_ref>:<hmac_digest>'

wget

wget -S -O- 'https://pay.paymenticon.com/sessions/(session_id:str)/data/stats/' --header='Accept: application/json' --header='Content-Type: application/json' --header='X-Paymenticon-Time: 1470041886' --header='Authorization: hmac <wallet_ref>:<hmac_digest>'

httpie

http 'https://pay.paymenticon.com/sessions/(session_id:str)/data/stats/' Accept:application/json Content-Type:application/json X-Paymenticon-Time:1470041886 Authorization:'hmac <wallet_ref>:<hmac_digest>'

python-requests

requests.get('https://pay.paymenticon.com/sessions/(session_id:str)/data/stats/', headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Paymenticon-Time': '1470041886', 'Authorization': 'hmac <wallet_ref>:<hmac_digest>'})

response

HTTP/1.1 200 OK
Content-Type: application/json
X-Paymenticon-Time: 1470041886

{
  "creation_source": "ONLINE",
  "registration_source": "ONLINE",
  "distributor_location": "SLR-001"
}
GET https://pay.paymenticon.com/sessions/(session_id: str)/data/stats/
Request Headers
  • Accept – the response content type depends on Accept header

  • Authorization – required HMAC authorization

  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – call time as UNIX timestamp

Response Headers
  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – response time as UNIX timestamp

Query Parameters
  • session_id (string) – previously created session id

Response JSON Object
  • creation_source (string) – Where wallet was created. Available values are: „DTM”, „POS”, „ONLINE”, „ADMIN_PANEL”.

  • registration_source (string) – Where wallet was registered with personal data of it’s user. For a list of possible values see above in creation_source description.

  • distributor_location (string) – Symbol of a Distributor location where the wallet was created.

Status Codes

Get identity documents of an authorized payer

http

GET /sessions/(session_id:str)/documents/ HTTP/1.1
Host: pay.paymenticon.com
Accept: application/json
Content-Type: application/json
X-Paymenticon-Time: 1470041886
Authorization: hmac <wallet_ref>:<hmac_digest>

curl

curl -i 'https://pay.paymenticon.com/sessions/(session_id:str)/documents/' -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Paymenticon-Time: 1470041886' -H 'Authorization: hmac <wallet_ref>:<hmac_digest>'

wget

wget -S -O- 'https://pay.paymenticon.com/sessions/(session_id:str)/documents/' --header='Accept: application/json' --header='Content-Type: application/json' --header='X-Paymenticon-Time: 1470041886' --header='Authorization: hmac <wallet_ref>:<hmac_digest>'

httpie

http 'https://pay.paymenticon.com/sessions/(session_id:str)/documents/' Accept:application/json Content-Type:application/json X-Paymenticon-Time:1470041886 Authorization:'hmac <wallet_ref>:<hmac_digest>'

python-requests

requests.get('https://pay.paymenticon.com/sessions/(session_id:str)/documents/', headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Paymenticon-Time': '1470041886', 'Authorization': 'hmac <wallet_ref>:<hmac_digest>'})

response

HTTP/1.1 200 OK
Content-Type: application/json
X-Paymenticon-Time: 1470041886

{
  "wallet_ref": "WLT-001",
  "category": "limited",
  "documents": [
    {
      "type": "id",
      "content_type": "image/png",
      "filename": "somefile.png",
      "expires": "2020-01-01",
      "checksum": "md5sum",
      "version": 3,
      "created": "2010-01-01 00:00:00",
      "modified": "2010-01-01 00:00:00",
      "file_url": "https://payments.../sessions/123/document/qwe123/"
    }
  ],
  "_signature": "<hmac_digest>"
}
GET https://pay.paymenticon.com/sessions/(session_id: str)/documents/
Request Headers
  • Accept – the response content type depends on Accept header

  • Authorization – required HMAC authorization

  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – call time as UNIX timestamp

Response Headers
  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – response time as UNIX timestamp

Query Parameters
  • session_id (string) – previously created session id

Response JSON Object
  • wallet_ref (string) – Indentifier of a client’s wallet.

  • category (string) – wallet category: „anonymous”, „limited”, „standard”, „enhanced”, „gift”

  • documents (list) – list of wallet’s documents

  • -->type (string) – document type, one of: „id”, „passport”, „driving”, „other”.

  • -->content_type (string) – mime type of a image file

  • -->filename (string) – name of a file

  • -->expires (string) – legal expiration date of a given document

  • -->checksum (string) – can be used to check whether document content has changed by compare checksums for both documents

  • -->version (int) – document version

  • -->created (string) – data when document was added to the system

  • -->modified (string) – modification date of a document record

  • -->file_url (string) – URL to fetch a full document file

  • _signature (string) – Response signature. Calculated in the same manner as a hmac*digest value used to sign the request (with the response’s X-Paymenticon-Time header and response body as a data source).

Status Codes

Get identity document of an authorized payer

http

GET /sessions/(session_id:str)/document/<token:str>/ HTTP/1.1
Host: pay.paymenticon.com
Accept: application/json
Content-Type: application/json
X-Paymenticon-Time: 1470041886
Authorization: hmac <wallet_ref>:<hmac_digest>

curl

curl -i 'https://pay.paymenticon.com/sessions/(session_id:str)/document/<token:str>/' -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Paymenticon-Time: 1470041886' -H 'Authorization: hmac <wallet_ref>:<hmac_digest>'

wget

wget -S -O- 'https://pay.paymenticon.com/sessions/(session_id:str)/document/<token:str>/' --header='Accept: application/json' --header='Content-Type: application/json' --header='X-Paymenticon-Time: 1470041886' --header='Authorization: hmac <wallet_ref>:<hmac_digest>'

httpie

http 'https://pay.paymenticon.com/sessions/(session_id:str)/document/<token:str>/' Accept:application/json Content-Type:application/json X-Paymenticon-Time:1470041886 Authorization:'hmac <wallet_ref>:<hmac_digest>'

python-requests

requests.get('https://pay.paymenticon.com/sessions/(session_id:str)/document/<token:str>/', headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Paymenticon-Time': '1470041886', 'Authorization': 'hmac <wallet_ref>:<hmac_digest>'})

response

HTTP/1.1 200 OK
Content-Type: image/png
X-Paymenticon-Time: 1470041886

.PNG...
GET https://pay.paymenticon.com/sessions/(session_id: str)/document/(token: str)/
Request Headers
  • Accept – the response content type depends on Accept header

  • Authorization – required HMAC authorization

  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – call time as UNIX timestamp

Response Headers
  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – response time as UNIX timestamp

Query Parameters
  • session_id (string) – previously created session id

  • token (string) – document checksum got from /sessions/<session_id>/document/ endpoint

Status Codes
  • 200 OK – session accessed properly

  • 401 Unauthorized – could not authorize an API call (invalid data in Authorization header)

  • 403 Forbidden – access to given resource is not allowed

Withdrawal

Withdraw given amount into a client’s wallet. Resulting transaction is performed as an internal transfer of funds from a merchant to a client. Therefore there have to be enough funds in the given currency available on a merchant’s wallet to cover this operation.

http

POST /withdraw/ HTTP/1.1
Host: pay.paymenticon.com
Accept: application/json
Content-Type: application/json
X-Paymenticon-Time: 1470041886
Authorization: hmac <wallet_ref>:<hmac_digest>

{
    "wallet_ref": "WLT-001",
    "amount": 1000,
    "currency": "PLN",
    "description": "refund order 123",
    "request_id": "3b573d51-eed3-4871-8480-19e0aef7125a"
}

curl

curl -i -X POST https://pay.paymenticon.com/withdraw/ -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Paymenticon-Time: 1470041886' -H 'Authorization: hmac <wallet_ref>:<hmac_digest>' --data-raw '{"amount": 1000, "currency": "PLN", "description": "refund order 123", "request_id": "3b573d51-eed3-4871-8480-19e0aef7125a", "wallet_ref": "WLT-001"}'

wget

wget -S -O- https://pay.paymenticon.com/withdraw/ --header='Accept: application/json' --header='Content-Type: application/json' --header='X-Paymenticon-Time: 1470041886' --header='Authorization: hmac <wallet_ref>:<hmac_digest>' --post-data='{"amount": 1000, "currency": "PLN", "description": "refund order 123", "request_id": "3b573d51-eed3-4871-8480-19e0aef7125a", "wallet_ref": "WLT-001"}'

httpie

echo '{
  "amount": 1000,
  "currency": "PLN",
  "description": "refund order 123",
  "request_id": "3b573d51-eed3-4871-8480-19e0aef7125a",
  "wallet_ref": "WLT-001"
}' | http POST https://pay.paymenticon.com/withdraw/ Accept:application/json Content-Type:application/json X-Paymenticon-Time:1470041886 Authorization:'hmac <wallet_ref>:<hmac_digest>'

python-requests

requests.post('https://pay.paymenticon.com/withdraw/', headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Paymenticon-Time': '1470041886', 'Authorization': 'hmac <wallet_ref>:<hmac_digest>'}, json={'amount': 1000, 'currency': 'PLN', 'description': 'refund order 123', 'request_id': '3b573d51-eed3-4871-8480-19e0aef7125a', 'wallet_ref': 'WLT-001'})

response

HTTP/1.1 202 OK
Content-Type: application/json
X-Paymenticon-Time: 1470041886

{
  "status": "success",
  "message": "Operation completed successfully",
  "request_id": "3b573d51-eed3-4871-8480-19e0aef7125a",
  "_signature": "<hmac_digest>"
}
POST https://pay.paymenticon.com/withdraw/
Request Headers
  • Accept – the response content type depends on Accept header

  • Authorization – required HMAC authorization

  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – call time as UNIX timestamp

Response Headers
  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – response time as UNIX timestamp

Request JSON Object
  • wallet_ref (string) – [required] Identifier of a client’s wallet.

  • amount (int) – [required] payment amount as an integer value.

  • currency (string) – [required] currency as an ISO 4217 3-letter code.

  • description (string) – [required] - string with a max length of 100. It can be used to associate a session with a particular transaction in the partner system. Content will be visible to customer as a transaction title within transaction history page.

  • request_id (string) – [required] Request identifier. Performing another query with the same request_id returns the cached result of a previous operation.

Response JSON Object
  • status (string) – operation status: „success”, „error”.

  • message (string) – success / error message

  • request_id (string) – Request identifier (copied from a query).

  • _signature (string) – Response signature. Calculated in the same manner as a hmac*digest value used to sign the request (with the response’s X-Paymenticon-Time header and response body as a data source).

Status Codes
  • 200 OK – operation ok

  • 400 Bad Request – invalid request (missing parameters or invalid values)

  • 401 Unauthorized – could not authorize an API call (invalid data in Authorization header)

  • 403 Forbidden – access to given resource is not allowed

Withdrawal session info

Retrieve information about withdrawal identified by given request_id.

http

GET /withdraw/(request_id:str)/ HTTP/1.1
Host: pay.paymenticon.com
Accept: application/json
Content-Type: application/json
X-Paymenticon-Time: 1470041886
Authorization: hmac <wallet_ref>:<hmac_digest>

curl

curl -i 'https://pay.paymenticon.com/withdraw/(request_id:str)/' -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Paymenticon-Time: 1470041886' -H 'Authorization: hmac <wallet_ref>:<hmac_digest>'

wget

wget -S -O- 'https://pay.paymenticon.com/withdraw/(request_id:str)/' --header='Accept: application/json' --header='Content-Type: application/json' --header='X-Paymenticon-Time: 1470041886' --header='Authorization: hmac <wallet_ref>:<hmac_digest>'

httpie

http 'https://pay.paymenticon.com/withdraw/(request_id:str)/' Accept:application/json Content-Type:application/json X-Paymenticon-Time:1470041886 Authorization:'hmac <wallet_ref>:<hmac_digest>'

python-requests

requests.get('https://pay.paymenticon.com/withdraw/(request_id:str)/', headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Paymenticon-Time': '1470041886', 'Authorization': 'hmac <wallet_ref>:<hmac_digest>'})

response

HTTP/1.1 202 OK
Content-Type: application/json
X-Paymenticon-Time: 1470041886

{
  "status": "success",
  "message": "Operation completed successfully",
  "request_id": "3b573d51-eed3-4871-8480-19e0aef7125a",
  "_signature": "<hmac_digest>"
}
GET https://pay.paymenticon.com/withdraw/(request_id: str)/
Request Headers
  • Accept – the response content type depends on Accept header

  • Authorization – required HMAC authorization

  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – call time as UNIX timestamp

Response Headers
  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – response time as UNIX timestamp

Query Parameters
  • request_id (string) – Request identifier.

Response JSON Object
  • status (string) – operation status: „success”, „error”.

  • message (string) – success / error message

  • request_id (string) – Request identifier (copied from a query).

  • _signature (string) – Response signature. Calculated in the same manner as a hmac*digest value used to sign the request (with the response’s X-Paymenticon-Time header and response body as a data source).

Status Codes

Withdrawal to new anonymous wallet

Method allows to create new anonymous wallet topped up with the specified amount. Response contains address of a voucher image of the specified width.

Resulting transaction is performed as an internal transfer of funds from merchant to client. Therefore there have to be enough funds in the given currency available on a merchant’s wallet to cover this operation. The transaction amount has to be lower than yearly limit of upload for an anonymous wallet.

http

POST /withdraw-anonymously/ HTTP/1.1
Host: pay.paymenticon.com
Accept: application/json
Content-Type: application/json
X-Paymenticon-Time: 1470041886
Authorization: hmac <wallet_ref>:<hmac_digest>

{
    "amount": 1000,
    "currency": "PLN",
    "description": "refund order 123",
    "voucher_width": 400,
    "set_pin": true,
    "request_id": "3b573d51-eed3-4871-8480-19e0aef7125a"
}

curl

curl -i -X POST https://pay.paymenticon.com/withdraw-anonymously/ -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Paymenticon-Time: 1470041886' -H 'Authorization: hmac <wallet_ref>:<hmac_digest>' --data-raw '{"amount": 1000, "currency": "PLN", "description": "refund order 123", "request_id": "3b573d51-eed3-4871-8480-19e0aef7125a", "set_pin": true, "voucher_width": 400}'

wget

wget -S -O- https://pay.paymenticon.com/withdraw-anonymously/ --header='Accept: application/json' --header='Content-Type: application/json' --header='X-Paymenticon-Time: 1470041886' --header='Authorization: hmac <wallet_ref>:<hmac_digest>' --post-data='{"amount": 1000, "currency": "PLN", "description": "refund order 123", "request_id": "3b573d51-eed3-4871-8480-19e0aef7125a", "set_pin": true, "voucher_width": 400}'

httpie

echo '{
  "amount": 1000,
  "currency": "PLN",
  "description": "refund order 123",
  "request_id": "3b573d51-eed3-4871-8480-19e0aef7125a",
  "set_pin": true,
  "voucher_width": 400
}' | http POST https://pay.paymenticon.com/withdraw-anonymously/ Accept:application/json Content-Type:application/json X-Paymenticon-Time:1470041886 Authorization:'hmac <wallet_ref>:<hmac_digest>'

python-requests

requests.post('https://pay.paymenticon.com/withdraw-anonymously/', headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Paymenticon-Time': '1470041886', 'Authorization': 'hmac <wallet_ref>:<hmac_digest>'}, json={'amount': 1000, 'currency': 'PLN', 'description': 'refund order 123', 'request_id': '3b573d51-eed3-4871-8480-19e0aef7125a', 'set_pin': True, 'voucher_width': 400})

response

HTTP/1.1 201 OK
Content-Type: application/json
X-Paymenticon-Time: 1470041886

{
    "wallet_ref": "WLT-01A",
    "voucher": {
      "label": "*123",
      "url": "https://pay.paymenticon.com/get-voucher/835f664a-5140-4bb7-9c04-86c68da55484.png",
      "url_expires": 1467382245,
      "pin": "1457"
    },
    "request_id": "3b573d51-eed3-4871-8480-19e0aef7125a",
    "_signature": "<hmac_digest>"
}
POST https://pay.paymenticon.com/withdraw-anonymously/
Request Headers
  • Accept – the response content type depends on Accept header

  • Authorization – required HMAC authorization

  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – call time as UNIX timestamp

Response Headers
  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – response time as UNIX timestamp

Request JSON Object
  • amount (int) – [optional] payment amount as an integer value.

  • currency (string) – [required] currency as an ISO 4217 3-letter code.

  • description (string) – [required] - string with a max length of 100. It can be used to associate a session with a particular transaction in the partner system. Content will be visible to customer as a transaction title within transaction history page.

  • voucher_width (int) – [required] desired width of a voucher image in pixels.

  • set_pin (boolean) – [required] if true a new PIN will be set up for newly created voucher.

  • request_id (string) – [required] Request identifier. Performing another query with the same request_id returns the cached result of a previous operation.

Response JSON Object
  • wallet_ref (string) – Identifier of a newly created anonymous wallet.

  • voucher (array) – section containing information about a voucher assigned to created wallet

  • -->label (string) – last three digits of a manual number printed on a voucher prefixed with a *.

  • -->url (string) – URL for an image file with a generated voucher. Ability to retrieve image is time constrained (see next parameter)

  • -->url_expires (string) – UNIX timestamp of a time until the image download is possible.

  • -->pin (string) – PIN for a voucher or empty string if PIN was not requested.

  • _signature (string) – Response signature. Calculated in the same manner as a hmac*digest value used to sign the request (with the response’s X-Paymenticon-Time header and response body as a data source).

Status Codes
  • 200 OK – returned on a second attempt with the same „request_id”

  • 201 Created – returned on a successful attempt.

  • 400 Bad Request – invalid request (missing parameters or invalid values)

  • 401 Unauthorized – could not authorize an API call (invalid data in Authorization header)

  • 403 Forbidden – access to given resource is not allowed

Create new anonymous wallet

Method allows to create new anonymous wallet. It can be later topped-up via the /wallet/withdraw/ operation.

http

POST /wallet/ HTTP/1.1
Host: pay.paymenticon.com
Accept: application/json
Content-Type: application/json
X-Paymenticon-Time: 1470041886
Authorization: hmac <wallet_ref>:<hmac_digest>

{
    "voucher_width": 400,
    "set_pin": true,
    "request_id": "3b573d51-eed3-4871-8480-19e0aef7125a"
}

curl

curl -i -X POST https://pay.paymenticon.com/wallet/ -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Paymenticon-Time: 1470041886' -H 'Authorization: hmac <wallet_ref>:<hmac_digest>' --data-raw '{"request_id": "3b573d51-eed3-4871-8480-19e0aef7125a", "set_pin": true, "voucher_width": 400}'

wget

wget -S -O- https://pay.paymenticon.com/wallet/ --header='Accept: application/json' --header='Content-Type: application/json' --header='X-Paymenticon-Time: 1470041886' --header='Authorization: hmac <wallet_ref>:<hmac_digest>' --post-data='{"request_id": "3b573d51-eed3-4871-8480-19e0aef7125a", "set_pin": true, "voucher_width": 400}'

httpie

echo '{
  "request_id": "3b573d51-eed3-4871-8480-19e0aef7125a",
  "set_pin": true,
  "voucher_width": 400
}' | http POST https://pay.paymenticon.com/wallet/ Accept:application/json Content-Type:application/json X-Paymenticon-Time:1470041886 Authorization:'hmac <wallet_ref>:<hmac_digest>'

python-requests

requests.post('https://pay.paymenticon.com/wallet/', headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Paymenticon-Time': '1470041886', 'Authorization': 'hmac <wallet_ref>:<hmac_digest>'}, json={'request_id': '3b573d51-eed3-4871-8480-19e0aef7125a', 'set_pin': True, 'voucher_width': 400})

response

HTTP/1.1 201 OK
Content-Type: application/json
X-Paymenticon-Time: 1470041886

{
    "wallet_ref": "WLT-01A",
    "voucher": {
      "label": "*123",
      "url": "https://pay.paymenticon.com/get-voucher/835f664a-5140-4bb7-9c04-86c68da55484.png",
      "url_expires": 1467382245,
      "pin": "1457"
    },
    "request_id": "3b573d51-eed3-4871-8480-19e0aef7125a",
    "_signature": "<hmac_digest>"
}
POST https://pay.paymenticon.com/wallet/
Request Headers
  • Accept – the response content type depends on Accept header

  • Authorization – required HMAC authorization

  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – call time as UNIX timestamp

Response Headers
  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – response time as UNIX timestamp

Request JSON Object
  • voucher_width (int) – [required] desired width of a voucher image in pixels.

  • set_pin (boolean) – [required] if true a new PIN will be set up for newly created voucher.

  • request_id (string) – [required] Request identifier. Performing another query with the same request_id returns the cached result of a previous operation.

Response JSON Object
  • wallet_ref (string) – Identifier of a newly created anonymous wallet.

  • voucher (array) – section containing information about a voucher assigned to created wallet

  • -->label (string) – last three digits of a manual number printed on a voucher prefixed with a *.

  • -->url (string) – URL for an image file with a generated voucher. Ability to retrieve image is time constrained (see next parameter)

  • -->url_expires (string) – UNIX timestamp of a time until the image download is possible.

  • -->pin (string) – PIN for a voucher or empty string if PIN was not requested.

  • request_id (string) – Request identifier (copied from a query).

  • _signature (string) – Response signature. Calculated in the same manner as a hmac*digest value used to sign the request (with the response’s X-Paymenticon-Time header and response body as a data source).

Status Codes
  • 200 OK – returned on a second attempt with the same „request_id”

  • 201 Created – returned on a successful attempt.

  • 400 Bad Request – invalid request (missing parameters or invalid values)

  • 401 Unauthorized – could not authorize an API call (invalid data in Authorization header)

  • 403 Forbidden – access to given resource is not allowed

Fetch basic voucher/smartcard data

Allows to fetch basic voucher/smartcard data using either voucher_id` or manual_number`. As voucherid and manual number are considered sensitive payment data they must not be carried openly (e.g. in logfiles or urls, hence the POST method here).

http

POST /wallet/voucher/get/ HTTP/1.1
Host: pay.paymenticon.com
Accept: application/json
Content-Type: application/json
X-Paymenticon-Time: 1470041886
Authorization: hmac <wallet_ref>:<hmac_digest>

{
    "id_type": "voucher_id",
    "id": "dcf411c480d740ce729f3f2e"
}

curl

curl -i -X POST https://pay.paymenticon.com/wallet/voucher/get/ -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Paymenticon-Time: 1470041886' -H 'Authorization: hmac <wallet_ref>:<hmac_digest>' --data-raw '{"id": "dcf411c480d740ce729f3f2e", "id_type": "voucher_id"}'

wget

wget -S -O- https://pay.paymenticon.com/wallet/voucher/get/ --header='Accept: application/json' --header='Content-Type: application/json' --header='X-Paymenticon-Time: 1470041886' --header='Authorization: hmac <wallet_ref>:<hmac_digest>' --post-data='{"id": "dcf411c480d740ce729f3f2e", "id_type": "voucher_id"}'

httpie

echo '{
  "id": "dcf411c480d740ce729f3f2e",
  "id_type": "voucher_id"
}' | http POST https://pay.paymenticon.com/wallet/voucher/get/ Accept:application/json Content-Type:application/json X-Paymenticon-Time:1470041886 Authorization:'hmac <wallet_ref>:<hmac_digest>'

python-requests

requests.post('https://pay.paymenticon.com/wallet/voucher/get/', headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Paymenticon-Time': '1470041886', 'Authorization': 'hmac <wallet_ref>:<hmac_digest>'}, json={'id': 'dcf411c480d740ce729f3f2e', 'id_type': 'voucher_id'})

response

HTTP/1.1 201 OK
Content-Type: application/json
X-Paymenticon-Time: 1470041886

{
  "label": "*123",
  "voucher_type": "voucher"
  "is_active": true,
  "wallet_ref": "WLT-01A",
  "_signature": "<hmac_digest>"
}
POST https://pay.paymenticon.com/wallet/voucher/get/
Request Headers
  • Accept – the response content type depends on Accept header

  • Authorization – required HMAC authorization

  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – call time as UNIX timestamp

Response Headers
  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – response time as UNIX timestamp

Request JSON Object
  • id_type (string) – [required] Identifier type. Either „manual_number” or „voucher_id”.

  • id (string) – [required] identifier of an entity.

Response JSON Object
  • label (string) – last three digits of a manual number printed on a voucher prefixed with a *.

  • voucher_type (string) – type of voucher. Either „voucher” or „smartcard”

  • is_active (boolean) – activity status of a given voucher/smartcard. Either true or false.

  • wallet_ref (string) – Identifier of a wallet this voucher is attached to.

  • _signature (string) – Response signature. Calculated in the same manner as a hmac*digest value used to sign the request (with the response’s X-Paymenticon-Time header and response body as a data source).

Status Codes
  • 200 OK – returned on a successful attempt

  • 400 Bad Request – invalid request (missing parameters or invalid values)

  • 401 Unauthorized – could not authorize an API call (invalid data in Authorization header)

  • 403 Forbidden – access to given resource is not allowed

Get confirmation of funds

Allows to confirm that users has required amount of funds on his account in given currency.

Informacja

Requires get_confirmation_of_funds scope.

http

POST /session/(session_id:str)/get_confirmation_of_funds/ HTTP/1.1
Host: pay.paymenticon.com
Accept: application/json
Content-Type: application/json
X-Paymenticon-Time: 1470041886
Authorization: hmac <wallet_ref>:<hmac_digest>

{
  "amount": 10000,
  "currency": "PLN"
}

curl

curl -i -X POST 'https://pay.paymenticon.com/session/(session_id:str)/get_confirmation_of_funds/' -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Paymenticon-Time: 1470041886' -H 'Authorization: hmac <wallet_ref>:<hmac_digest>' --data-raw '{"amount": 10000, "currency": "PLN"}'

wget

wget -S -O- 'https://pay.paymenticon.com/session/(session_id:str)/get_confirmation_of_funds/' --header='Accept: application/json' --header='Content-Type: application/json' --header='X-Paymenticon-Time: 1470041886' --header='Authorization: hmac <wallet_ref>:<hmac_digest>' --post-data='{"amount": 10000, "currency": "PLN"}'

httpie

echo '{
  "amount": 10000,
  "currency": "PLN"
}' | http POST 'https://pay.paymenticon.com/session/(session_id:str)/get_confirmation_of_funds/' Accept:application/json Content-Type:application/json X-Paymenticon-Time:1470041886 Authorization:'hmac <wallet_ref>:<hmac_digest>'

python-requests

requests.post('https://pay.paymenticon.com/session/(session_id:str)/get_confirmation_of_funds/', headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Paymenticon-Time': '1470041886', 'Authorization': 'hmac <wallet_ref>:<hmac_digest>'}, json={'amount': 10000, 'currency': 'PLN'})

response

HTTP/1.1 200 OK
Content-Type: application/json
X-Paymenticon-Time: 1470041886

{
  "wallet_ref": "WLT-001",
  "funds_available": true
}
POST https://pay.paymenticon.com/session/(session_id: str)/get_confirmation_of_funds/
Request Headers
  • Accept – the response content type depends on Accept header

  • Authorization – required HMAC authorization

  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – call time as UNIX timestamp

Response Headers
  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – response time as UNIX timestamp

Query Parameters
  • session_id (string) – previously created session id

Request JSON Object
  • amount (int) – [required] required amount in cents

  • currency (string) – [required] target currency

Response JSON Object
  • wallet_ref (string) – logged in user wallet ref

  • funds_available (boolean) – true if available funds are greater or equal to requested amount; otherwise false

  • _signature (string) – Response signature. Calculated in the same manner as a hmac*digest value used to sign the request (with the response’s X-Paymenticon-Time header and response body as a data source).

Status Codes
  • 200 OK – returned on a successful attempt

  • 400 Bad Request – invalid request (missing parameters or invalid values)

  • 401 Unauthorized – could not authorize an API call (invalid data in Authorization header)

  • 403 Forbidden – access to given resource is not allowed

Get wallet funds

Fetch available funds and balance for all currencies on given wallet.

Informacja

Requires get_wallet_funds scope.

http

POST /session/(session_id:str)/get_wallet_funds/ HTTP/1.1
Host: pay.paymenticon.com
Accept: application/json
Content-Type: application/json
X-Paymenticon-Time: 1470041886
Authorization: hmac <wallet_ref>:<hmac_digest>

curl

curl -i -X POST 'https://pay.paymenticon.com/session/(session_id:str)/get_wallet_funds/' -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Paymenticon-Time: 1470041886' -H 'Authorization: hmac <wallet_ref>:<hmac_digest>'

wget

wget -S -O- 'https://pay.paymenticon.com/session/(session_id:str)/get_wallet_funds/' --header='Accept: application/json' --header='Content-Type: application/json' --header='X-Paymenticon-Time: 1470041886' --header='Authorization: hmac <wallet_ref>:<hmac_digest>'

httpie

http POST 'https://pay.paymenticon.com/session/(session_id:str)/get_wallet_funds/' Accept:application/json Content-Type:application/json X-Paymenticon-Time:1470041886 Authorization:'hmac <wallet_ref>:<hmac_digest>'

python-requests

requests.post('https://pay.paymenticon.com/session/(session_id:str)/get_wallet_funds/', headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Paymenticon-Time': '1470041886', 'Authorization': 'hmac <wallet_ref>:<hmac_digest>'})

response

HTTP/1.1 200 OK
Content-Type: application/json
X-Paymenticon-Time: 1470041886

{
  "wallet_ref": "WLT-001",
  "available_funds": {
      "PLN": 1200,
      "EUR": 0,
      "GBP": 2000
  },
  "balance": {
      "PLN": 1200,
      "EUR": 0,
      "GBP": 2000
  }
}
POST https://pay.paymenticon.com/session/(session_id: str)/get_wallet_funds/
Request Headers
  • Accept – the response content type depends on Accept header

  • Authorization – required HMAC authorization

  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – call time as UNIX timestamp

Response Headers
  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – response time as UNIX timestamp

Query Parameters
  • session_id (string) – previously created session id

Response JSON Object
  • wallet_ref (string) – logged in user wallet ref

  • available_funds (array) – available funds per currency as cents

  • balance (array) – balance per currency as cents

  • _signature (string) – Response signature. Calculated in the same manner as a hmac*digest value used to sign the request (with the response’s X-Paymenticon-Time header and response body as a data source).

Status Codes
  • 200 OK – returned on a successful attempt

  • 400 Bad Request – invalid request (missing parameters or invalid values)

  • 401 Unauthorized – could not authorize an API call (invalid data in Authorization header)

  • 403 Forbidden – access to given resource is not allowed

Get transactions

Fetch transactions list for a given wallet.

Informacja

Requires get_transactions scope.

http

POST /session/(session_id:str)/get_transactions/ HTTP/1.1
Host: pay.paymenticon.com
Accept: application/json
Content-Type: application/json
X-Paymenticon-Time: 1470041886
Authorization: hmac <wallet_ref>:<hmac_digest>

{
  "page": 1,
  "paginate_by": 10,
  "order_by": "-date",
  "filters": {
      "currency": "PLN",
      "direction": "incoming",
      "date_from": "2019-08-11T21:20:11",
      "date_to": "2020-01-02T11:11:11"
  }
}

curl

curl -i -X POST 'https://pay.paymenticon.com/session/(session_id:str)/get_transactions/' -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'X-Paymenticon-Time: 1470041886' -H 'Authorization: hmac <wallet_ref>:<hmac_digest>' --data-raw '{"filters": {"currency": "PLN", "date_from": "2019-08-11T21:20:11", "date_to": "2020-01-02T11:11:11", "direction": "incoming"}, "order_by": "-date", "page": 1, "paginate_by": 10}'

wget

wget -S -O- 'https://pay.paymenticon.com/session/(session_id:str)/get_transactions/' --header='Accept: application/json' --header='Content-Type: application/json' --header='X-Paymenticon-Time: 1470041886' --header='Authorization: hmac <wallet_ref>:<hmac_digest>' --post-data='{"filters": {"currency": "PLN", "date_from": "2019-08-11T21:20:11", "date_to": "2020-01-02T11:11:11", "direction": "incoming"}, "order_by": "-date", "page": 1, "paginate_by": 10}'

httpie

echo '{
  "filters": {
    "currency": "PLN",
    "date_from": "2019-08-11T21:20:11",
    "date_to": "2020-01-02T11:11:11",
    "direction": "incoming"
  },
  "order_by": "-date",
  "page": 1,
  "paginate_by": 10
}' | http POST 'https://pay.paymenticon.com/session/(session_id:str)/get_transactions/' Accept:application/json Content-Type:application/json X-Paymenticon-Time:1470041886 Authorization:'hmac <wallet_ref>:<hmac_digest>'

python-requests

requests.post('https://pay.paymenticon.com/session/(session_id:str)/get_transactions/', headers={'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Paymenticon-Time': '1470041886', 'Authorization': 'hmac <wallet_ref>:<hmac_digest>'}, json={'filters': {'currency': 'PLN', 'date_from': '2019-08-11T21:20:11', 'date_to': '2020-01-02T11:11:11', 'direction': 'incoming'}, 'order_by': '-date', 'page': 1, 'paginate_by': 10})

response

HTTP/1.1 200 OK
Content-Type: application/json
X-Paymenticon-Time: 1470041886

{
  "wallet_ref": "WLT-001",
  "transactions": [
    {
      "amount": 1200,
      "currency": "PLN",
      "date": "2019-08-11T21:20:11",
      "direction": "outgoing",
      "opposite": "Asdfasd\nasdfasdf\nAccount number: PL53013425766858704781265328",
      "resource": "payout",
      "title": "Some transaction",
      "trnId": "d9d93250338b4501a24ff75f9959a260"
      "walletRef": "WLT-333"
    },
  ],
  "pagination" {
      "paginate_by": 10,
      "page": 2,
      "total": 40,
      "previous_page": 1,
      "next_page": 3
  }
}
POST https://pay.paymenticon.com/session/(session_id: str)/get_transactions/
Request Headers
  • Accept – the response content type depends on Accept header

  • Authorization – required HMAC authorization

  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – call time as UNIX timestamp

Response Headers
  • Content-Type – this depends on Accept header of request

  • X-Paymenticon-Time – response time as UNIX timestamp

Query Parameters
  • session_id (string) – previously created session id

Request JSON Object
  • page (int) – [optional] page result (default 1)

  • paginate_by (int) – [optional] results per page (default 10)

  • order_by (string) – [optional] ordering field, you can change ordering direction by „-” prefix (default „-date”); available values: currency, date, title, amount

  • filters (array) – [optional] directory with list filters

  • -->currency (string) – [optional] currency symbol

  • -->direction (string) – [optional] incoming or outgoing

  • -->date_from (string) – [optional] ISO8601 format starting date

  • -->date_to [optional] (string) – ISO8601 format end date

Response JSON Object
  • wallet_ref (string) – logged in user wallet ref

  • pagination (array) – pagination data

  • -->paginateby (int) – current records per page

  • -->page (int) – current page

  • -->total (int) – total records in query

  • previous_page (int) – [optional] previous page number if exists

  • next_page (int) – [optional] next page number if exists

  • transactions (list(array)) – list of transactions

  • amount (int) – transaction amount in cents

  • currency (string) – transactions currency

  • date (string) – transaction ISO8601 date

  • direction (string) – transaction direction

  • opposite (string) – description of opposite side of transaction

  • resource (string) – transaction resource

  • title (string) – transaction title

  • id (string) – transaction id

  • _signature (string) – Response signature. Calculated in the same manner as a hmac*digest value used to sign the request (with the response’s X-Paymenticon-Time header and response body as a data source).

>Json string wallet_ref

transaction wallet ref

Status Codes
  • 200 OK – returned on a successful attempt

  • 400 Bad Request – invalid request (missing parameters or invalid values)

  • 401 Unauthorized – could not authorize an API call (invalid data in Authorization header)

  • 403 Forbidden – access to given resource is not allowed