MyQ REST API documentation
MyQ REST API documentation
Breadcrumbs

Credit Recharge

Add credit to the user’s internal MyQ X credit account.

Get recharge providers

GET /v3/rechargeProviders

Get the current active Recharge providers.

Authentication

Grant_type: client_credentials, login_info
Scopes: [ credit ]

Headers

Content-Type: application/json
Authentication: Bearer %access_token%

Request Body

empty

Response Body

 
{
  "providers": [
    {
      "name": "string",
      "reference": "string",
      "description": "string",
      "params": [
        "string",
        0,
        true
      ]
    }
  ],
  "count": 0
}

  • name – Payment recharge provider name.

  • reference – Provider reference, use in requests to recharge credit using this provider; for integrations, use external.

  • description – Payment recharge provider description; optional.

  • params – Additional parameters; optional.

Examples:

Request Body

Response Body

empty

 
{
    "providers": [
        {
            "name": "External Payment Providers",
            "reference": "external",
            "description": "",
            "params": []
        },
        {
            "name": "PayPal",
            "reference": "paypal",
            "description": "",
            "params": []
        }
    ],
    "count": 2
}

REST API recharge does not support any standard built-in payment provider except for Voucher and External Payment Providers; use the recharge provider reference external in your requests. All payments will be visible in the logs with the source External Payment Provider.

Before you make recharges, ensure that External Payment Providers is enabled in MyQ X, in Settings > Credit.

image-20250310-204039.png

If it is not at the time of calling the endpoint to create a payment, you will receive a message: Invalid operation: The operation cannot be performed in the current state. Payment provider is disabled.

Create a payment

POST /v3/rechargeProviders/{reference}/payments

Create a payment. You must commit the payment to make it effective.

Logged user MUST have the right Manage payments.

Authentication

Grant_type: client_credentials, login_info
Scopes: [ credit ]

Headers

Content-Type: application/json
Authentication: Bearer %access_token%

Parameters

{reference} – Recharge provider reference.

Request Body
JSON
{
  "userId": 0,
  "description": "string",
  "params": {
	"amount": 0
  }
}

  • userId – ID of the user whose credit is recharged, get from the users endpoint.

  • description – Description of the payment; optional.

  • params – Additional parameters; required.

    • amount – Amount to be recharged.

Response Body
JSON
{
  "id": "string",
  "userId": 0,
  "amount": 0,
  "description": "string",
  "params": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

  • id – ID of the payment, must be referenced when committing or rolling back the payment.

  • userId – ID of the user whose credit is recharged.

  • amount – Requested amount to be recharged.

  • description – Description of the payment; optional.

  • params – Additional parameters provided when the payment was created; optional.

Examples:

Request Body

Response Body
JSON
{
	"userId": 34173,
	"params": {
      "amount": 10
	}
}
JSON
{
    "id": "34200",
    "userId": 34173,
    "amount": 10,
    "description": "",
    "params": {
      "amount": 10,
      "createdBy": -2
    }
}

Update a payment

PATCH /v3/rechargeProviders/{reference}/payments/{id}

Update the payment.

Logged user MUST have the right Manage payments.

Authentication

Grant_type: client_credentials, login_info
Scopes: [ credit ]

Headers

Content-Type: application/json
Authentication: Bearer %access_token%

Request Body

 
{
  "description": "string",
  "params": {
		"amount": 20
  }
}

  • description – Description of the payment; optional.

  • params – Additional parameters; required.

    • amount – Amount to be recharged.

Response Body

empty

Examples:

Request Body

Response Body

 
{
  "description": "Payment from Acme app",
  "params": {
		"amount": 20
  }
}

empty

1 if successful

Commit a payment

POST /v3/rechargeProviders/{reference}/payments/{id}/commit

Commit the payment to make it effective.

Logged user MUST have the right Manage payments.

Authentication

Grant_type: client_credentials, login_info
Scopes: [ credit ]

Headers

Content-Type: application/json
Authentication: Bearer %access_token%

Parameters

{reference} – Recharge provider reference.

{id} – Payment ID received when the payment was created.

Request Body

empty

Response Body

 
{
  "amount": 0
}

  • amount - The credit amount that was added to the account.

Examples:

Request Body

Response Body

empty

 
{
  "amount": 10
}

Rollback a payment

POST /v3/rechargeProviders/{reference}/payments/{id}/rollback

Roll back the payment.

Logged user MUST have the right Manage payments.

Authentication

Grant_type: client_credentials, login_info
Scopes: [ credit ]

Headers

Content-Type: application/json
Authentication: Bearer %access_token%

Parameters

{reference} – Recharge provider reference.

{id} – Payment ID received when the payment was created.

Request Body

empty

Response Body

 
{
  "reason": "string"
}

  • reason - Reason why the payment was rolled back

Examples:

Request

Response

 
{
  "reason": "Cancelled by user"
}

empty

1 if successful.

Get payments

GET /v3/rechargeProviders/{reference}/payments?userId={userid}

Get payments.

Logged user MUST have the right Manage payments.

Authentication

Grant_type: client_credentials, login_info
Scopes: [ credit ]

Headers

Content-Type: application/json
Authentication: Bearer %access_token%

Request Body

empty

Response Body

 
{
  "payments": [
    {
      "id": 0,
      "userId": 0,
      "amount": 0,
      "currency": "string",
      "state": "string",
      "created": "2021-10-21T09:24:43.122Z",
      "updated": "2021-10-21T09:24:43.122Z",
      "expires": "2021-10-21T09:24:43.122Z",
      "paymentNo": 0,
      "provider": "string",
      "description": "string"
    }
  ],
  "count": 0
}

  • id - ID of the payment.

  • userId - User whose credit was recharged.

  • amount - Credit amount recharged.

  • currency - Payment currency; optional.

  • state - Payment status.

    • state: created – payment created, not yet effective.

    • state: completed – payment was committed and made effective.

    • state: canceled – rolled back payment.

  • created - Creation timestamp.

  • updated - Update timestamp.

  • expires – Expiration timestamp.

  • paymentNo – Payment number.

  • provider – Reference of the payment provider that initiated the payment.

  • description - Payment description.

Examples:

Request

Response

empty

 
{
    "payments": [
        {
            "id": "34204",
            "userId": 34173,
            "amount": 15,
            "currency": null,
            "state": "created",
            "created": "2025-04-29T00:51:19+02:00",
            "updated": "2025-04-29T00:51:19+02:00",
            "expires": null,
            "paymentNo": "5",
            "provider": "external",
            "description": ""
        },
        {
            "id": "34203",
            "userId": 34173,
            "amount": 15,
            "currency": null,
            "state": "canceled",
            "created": "2025-04-29T00:46:48+02:00",
            "updated": "2025-04-29T00:50:58+02:00",
            "expires": null,
            "paymentNo": "4",
            "provider": "external",
            "description": "Cancelled by user"
        },
        {
            "id": "34200",
            "userId": 34173,
            "amount": 10,
            "currency": null,
            "state": "completed",
            "created": "2025-04-29T00:33:31+02:00",
            "updated": "2025-04-29T00:42:03+02:00",
            "expires": null,
            "paymentNo": "3",
            "provider": "external",
            "description": ""
        }
    ],
    "count": 3
}

Practical Example

To recharge credit, we usually need at least the scopes users and credit.

image-20230510-115508.png

Obtain the user ID:

GET {{baseUrl}}/v3/users/find?username={{username}} 

  • Required scope: users

Example response:

image-20250310-193330.png

POST request to create a payment:

POST {{baseUrl}}/v3/rechargeProviders/{{paymentproviderreference}}/payments

  • Required scope: credit

  • {{paymentproviderreference}} use external.

  • To successfully call this endpoint, make sure the Content-Type is application/json.

In the body of the request, provide the additional information about the user ID and the amount of money to recharge:

{
	"userId": {{userid}},
	"params": {
		"amount": 13
	}
}
image-20250310-192922.png

Example request:

POST {{baseUrl}}/v3/rechargeProviders/external/payments

{
	"userId": 1176,
	"params": {
		"amount": 13
	}
}

The answer then returns the ID of the payment (12532), which we will use to commit the payment.

Commit the payment:

POST {{baseUrl}}/v3/rechargeProviders/{{paymentproviderreference}}/payments/{{paymentid}}/commit

  • Required scope: credit

And finally, an answer is returned with the recharged amount, confirming the operation was successful.

image-20250310-193712.png

Example request:

POST {{baseUrl}}/v3/rechargeProviders/external/payments/12532/commit

And the user’s credit is topped up.

image-20250310-193830.png

You will see the payment in the Credit Statement.

image-20230510-115611.png