External Account API

The External Account server is responsible for handling requests received from the MyQ server. These requests primarily involve session creation and termination, as well as facilitating payments within the active session. To authenticate the request the 'Basic' HTTP authentication scheme is used.

Payment session control

Start a payment session

In order to commence a payment session, the MyQ server transmits user identification parameters to the payment server, indicating the user to whom the session should be attributed.

These parameters are:

username
alias
card
personalNumber

The endpoint provides an identification number that represents the initiated session.

CODE

POST /sessions

Headers:
Content-Type: application/json
Authentication: Basic {login:pwd in base64}

Request body:
{
  "username": "string",
  "aliases": [
    "string"
  ],
  "cards": [
    "string"
  ],
  "personalnumber": "string"
}

Response body:
{
  "id": 0
}

Get balance for the session

The session balance refers to the amount of available credit allocated to the user. This endpoint returns the balance parameter that represents the available credit.

CODE

GET /sessions/{session id}

Headers:
Content-Type: application/json
Authentication: Basic {login:pwd in base64}

Response body:
{
  "balance": 0
}

Block credit for the session

Blocking of credit is a process to temporarily decrease the available balance until the session finishes. This prevents spending the same credit multiple times resulting in an negative balance.

CODE

POST /sessions/{session id}/block

Headers:
Content-Type: application/json
Authentication: Basic {login:pwd in base64}

Request body:
{
  "amount": 0
}

Response code:
  204 (Amount was blocked)

End the session

Ending the session and releasing the blocked credit.

CODE

DELETE /sessions/{session id}

Headers:
Authentication: Basic {login:pwd in base64}

Response codes:
  202 OK. Blockings will be released later.
  204 OK

Creating and committing payments

Create a payment

A payment transaction is generated within a session. The request must include an amount parameter indicating the payment size. In response, an id and the permitted amount of credit to be paid are returned.

CODE

POST /sessions/{session id}/payments

Headers:
Content-Type: application/json
Authentication: Basic {login:pwd in base64}

Request body:
{
  "amount": 0
}

Response body:
{
  "id": 0,
  "amount": 0
}

Update the payment

Updating the payment changes the amount to be paid after commiting the payment.

CODE

PATCH /sessions/{session id}/payments/{payment id}

Headers:
Content-Type: application/json
Authentication: Basic {login:pwd in base64}

Request body:
{
  "amount": 0
}

Response body:
{
  "id": 0,
  "amount": 0
}

Commit the payment

Commiting the payment, the available balance of the session is modified. Prior to utilizing this endpoint, it is necessary to call the endpoint for creating the payment.

CODE

POST /sessions/{session id}/payments/{payment id}/commit

Headers:
Content-Type: application/json
Authentication: Basic {login:pwd in base64}

Response code:
  204 OK

Rollback the payment

Payments have the capability to be rolled back, resulting in a restoration of the session amount to its previous state.

CODE

POST /sessions/{session id}/payments/{payment id}/rollback

Headers:
Content-Type: application/json
Authentication: Basic {login:pwd in base64}

Response code:
  204 OK

Error Message

All responses with status code >= 400 are considered as errors.

Example error response:

CODE

{
  "error": {
    "message": "Error description"
  }
}