Merchant Query Interface

The Merchant Query Interface allows you to query the Skrill database for the current status of your transactions as well as perform actions connected to Skrill 1-Tap and recurring payments. You can access the MQI by posting an HTTPS query to:

https://www.skrill.com/app/query.pl

Each MQI query requires the three general parameters email, password and action, and other parameters specific to the requested action (see MQI Actions).

Field Name	Description	Required	Example value
email	The email address of your Skrill account.	Yes	info@merchant.com
password	The lower-case hex MD5 of your API/MQI password.	Yes	9f535b6ae672f627e4e5f79f2b7c63fe
action	The required action.	Yes	repost

MQI Actions

The following MQI actions are supported:

• Repost transaction status
• View transaction status
• View account history
• Cancel a recurring payment
• View recurring payment status
• Extend the end date of a recurring payment
• Cancel a Skrill 1-Tap payment
• View Skrill 1-Tap payment status

Repost Transaction Status

This action allows you to request a repost of the status of a transaction to the Status URL provided.

note

This is a repost of the same status report that was posted when the payment was made, and is sent to the same status URL that was specified in the original payment.

In response, Skrill posts a status report (for details, refer to the Skrill Quick Checkout Integration Guide as appropriate). If no status report was posted initially, this action will return a 403 Transaction not found: TRN_ID error.

Parameters:

Field Name	Description	Required	Example Value
action	MQI action	Yes	repost
trn_id	Your transaction ID	Yes/No	500123
mb_trn_id	Skrill transaction ID	Yes/No	4585262
status_url	Where to post the notification	No	https://www.merchant.com/mb_notifications.asp

note

Either trn_id or mb_trn_id must be supplied. If both are given, trn_id will be used.
If status_url is not provided, the status_url given at the time the transaction was created will be used.
For a successful HTTP request, the HTTP response body 200\t\tOK\n\n is returned (using escape sequences to represent special characters).

View Transaction Status

This action gives a direct response with the status of the payment. It includes the same details as in the repost action, but sends a direct response to the request rather than to the old status URL. The following parameters are required:

Field Name	Description	Required	Example Value
action	MQI action	Yes	status_trn
trn_id	Your transaction ID	Yes/No	500123
mb_trn_id	Skrill transaction ID	Yes/No	4585262

note

Either trn_id or mb_trn_id must be supplied and if both are given, trn_id will be used.
If a transaction with the given ID is found, the response will be a query string that contains the transaction details. The string is encoded using the application/x-www-form-urlencoded format.

Example 1: API transaction

Request:

curl --location 'https://www.skrill.com/app/query.pl?action=status_trn&email=mb654%40abv.bg&password=53903d217504eb37f3fdb0ce77610558&mb_trn_id=104627261'

Response

200 OK

status=2&merchant_id=6999381&mb_transaction_id=104627261&mb_amount=1.2&pay_to_email=mb654%40abv.bg&currency=BGN&amount=2.346996&transaction_id=&pay_from_email=test%4test.bg&mb_currency=EU

Example 2: Checkout transaction

Request:

curl --location 'https://www.skrill.com/app/query.pl?action=status_trn&email=merchant%40host.com&password=53903d217504eb37f3fdb0ce77610558&mb_trn_id=104441110'

Response

200 OK

status=2&Field1=TR234567&md5sig=6AB68D3465F57492B7412ED0EB013621&merchant_id=9999981&pay_to_email=merchant%40host.com&mb_amount=33.24911&mb_transaction_id=101149910&currency=EUR&amount=17&transaction_id=49989810fa3ed45c&pay_from_email=payeremail%40host.bg&mb_currency=BGN&confirmed_by_provider=True

View Account History

You can obtain a list of all transactions for a specified period. The following parameters are required:

Field Name	Description	Required	Example value
action	MQI action	Yes	history
start_date	The start date in DD-MM-YYYY format.	Yes	29-05-2016
end_date	The end date in DD-MM-YYYY format.	No	30-06-2017
account_id	Your currency account ID. For more information, see Separating balances by fund origin.	Yes/No	1234567

note

Upon success, Skrill returns the complete account history for the specified period in CSV (comma separated values) format.
If the end_date parameter is not specified, Skrill uses today's date.

Extended transaction history feature: It is possible to request the extended currency account information for each transaction in the report. This information is presented in three additional columns: currency, region, and account_id.

By default, these features are not enabled for merchant accounts. If you would like to have them enabled for your account, please contact the Skrill Merchant Service Department at: merchantservices@skrill.com.

note

If you are using a multi-currency merchant account, we recommend that you enable the extended transaction history feature, otherwise, only the transaction history for the primary currency will be returned.

Example:

Request:

curl --location 'https://www.skrill.com/app/query.pl?email=merchant%40host.com&password=53903d217504eb37f3fdb0ce77610558&action=history&start_date=25-05-2017&end_date=25-06-2017'

Response:

CSV file containing account history.

Cancel a Recurring Payment

This action allows you to cancel a recurring payment. The following parameters are required:

Field Name	Description	Required	Example Value
action	MQI action	Yes	cancel_rec
trn_id	Your transaction ID	Yes	500123

View Recurring Payment Status

This action allows you to check the status of a recurring payment. The following parameters are required:

Field Name	Description	Required	Example Value
action	MQI action	Yes	status_rec
trn_id	Your transaction ID	Yes	500123

If a transaction with the given ID is found, the response contains the following parameters:

• Status: 0 = active, -1 = cancelled, -2 = failed, 1 = finished
• Next payment date in dd-mm-yyyy format. This parameter is returned only if status is active or failed
• End date in dd-mm-yyyy format. This parameter is returned only if status is active or failed

Example:

Request:

curl --location 'https://www.skrill.com/app/query.pl?action=status_rec&email=merchant%40host.com&password=2813F1526CD435D296A2A8FEE37889AD&trn_id=yourtansID123'

Response:

200 OK

Status: 0 Next payment date: 26-05-2017, End date: 26-12-2017

Extend the End Date of a Recurring Payment

This action allows you to extend the end date (rec_end_date) of a recurring payment. To enable this option, send a request to merchantservices@skrill.com.

The following parameters are required:

Field Name	Description	Required	Example value
action	MQI action	Yes	extend_rec
trn_id	Your transaction ID.	Yes	500123
rec_end_date	The recurrent end date in dd-mm-yyyy format.	Yes	30-06-2017

note

For PaysafeCard the validity of the token is limited to 364 days and it could not be extended further. The customer will need to again give his consent after the period in order to continue using the service.

Cancel Skrill 1-Tap Payment

This action allows you to cancel a Skrill 1-Tap payment. The following parameter is required:

Field Name	Description	Required	Example value
action	MQI action	Yes	cancel_od
trn_id	Your transaction ID.	Yes	500123

View Skrill 1-Tap Payment Status

This action allows you to check the status of a Skrill 1-Tap payment. The following parameter is required:

Field Name	Description	Required	Example value
action	MQI action	Yes	status_od
trn_id	Your transaction ID.	Yes	500123

If a transaction with the given ID is found, the response will contain following parameters:

• Status: 0 – active; -1 – cancelled; -2 – failed initial payment
• Last execution date in dd-mm-yyyy format. (-- is used instead if no subsequent 1-Tap payments have been taken)

Example:

Request:

curl --location 'https://www.skrill.com/app/query.pl?email=merchant%40host.com&action=status_od&password=2813F1526CD435D296A2A8FEE37889AD&trn_id=yourtansID123'

Response:

Status: -1 Last execution date: 08-01-2016

Obtaining Account Balance

Skrill offers two ways for merchants to retrieve their balance. The first way is to use the Account Balance API. The second option is via the Balance Notification Webhook, where we push the balance to a URL specified by you.

Get Account Balances

This action allows you to get the current balances of your accounts. The following parameters are optional:

Field Name	Description	Required	Example value
action	MQI action	Yes	balance
account_id	A single account id	No	131552

The server returns a JSON array containing objects of with the following structure:

Element	Type	Restrictions	Description	Example
account_id	number	64-bit positive signed integer	Account identifier	131552
currency	string	3 characters	ISO-4217 currency codes	USD
legalEntity	string	3 characters:EEA orROW	Legal entity region	ROW
balance	number	Floating-point numeric	Balance amount	12552.000000
availableBalance	number	Floating-point numeric	Available balance amount	12552.000000

note

If account_id is specified, then only the given account information is returned, if it belongs to the merchant. Otherwise, an empty array is returned.

legalEntity values:

• EEA – European Economic Area
• ROW – Rest of the world balance value contains total balance including reserves, not available balance, which excludes reserves.

Example:

Request:

curl --location 'https://www.skrill.com/app/query.pl?action=balance&email=merchant%40host.com&password=2813F1526CD435D296A2A8FEE37889AD&account_id=131552'

Response:

[
  {
    "accountId": 131552,
    "currency": "USD",
    "legalEntity": "ROW",
    "balance": 12552.000000,
    "availableBalance": 12552.000000
  }
]

Balance Notification Webhook

This webhook allows merchants to receive real-time push notifications whenever their account balance changes. It provides the same balance structure as the Get Account Balances MQI action but is delivered asynchronously to a merchant-defined endpoint.

Webhook Overview

When a balance update occurs, the system sends an HTTPS request to the merchant’s configured webhook URL.

Trigger Events

A balance update notification is sent when:

• Funds are added to an account
• Funds are withdrawn
• Transactions are processed
• Adjustments that modify the total account balance

How to Set It Up

In order to set the Balance Webhook URL, you will need to log in to the Skrill Merchant Portal and go to Settings > Developer Settings.

Security

Webhook requests are signed using the SHA256withRSA signing algorithm. The public key to verify the signature is the following:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw+mUjtHRvPtencmfgPwm
7mmHqKkCC7ar6nJn1pUfxSiWrdkoY445/YY9+G7tTDfJGnS7+zDeT6xpwjYR7kPX
uueePhkD0vXTMB12NK1oU2AdTWYQ5fJw2kv94INbp2wUGq08TQlp/MoHK9vLUf/A
vHbV7zvdUT6uD8zY6GKcMuar4fzWrWQkiHy6I5y5LYhU0JRWFHMTOCeyKDAlP6ZU
fRL0i5SNMLoRsH4hpItN63VSuoAi07AoJKtDDao8dAFKoKvHQzhWjbjBQGTrgmjc
urTIwPYhOohFFmW8J72E1ksLaDdGmvOLTapus82XAhXSC9O52o2hS/WTkmGQgWfx
kwIDAQAB
-----END PUBLIC KEY-----

The signature is passed as a request header X-Paysafe-Signature with a Base64 encoding (see the example below).

When you set up a balance webhook URL, our system will send balance-change notifications directly to the address you enter, which may result in balance information being shared with third parties. Please make sure it’s correct, secure, and managed by you. Any risks or consequences are your responsibility. To stop receiving the balance webhook notification, you can remove the set URL.

Verifying the Signature

The following example shows how to verify the webhook signature:

public class WebhookVerifier {

  private static final String PUBLIC_KEY_PEM = """
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw+mUjtHRvPtencmfgPwm
    7mmHqKkCC7ar6nJn1pUfxSiWrdkoY445/YY9+G7tTDfJGnS7+zDeT6xpwjYR7kPX
    uueePhkD0vXTMB12NK1oU2AdTWYQ5fJw2kv94INbp2wUGq08TQlp/MoHK9vLUf/A
    vHbV7zvdUT6uD8zY6GKcMuar4fzWrWQkiHy6I5y5LYhU0JRWFHMTOCeyKDAlP6ZU
    fRL0i5SNMLoRsH4hpItN63VSuoAi07AoJKtDDao8dAFKoKvHQzhWjbjBQGTrgmjc
    urTIwPYhOohFFmW8J72E1ksLaDdGmvOLTapus82XAhXSC9O52o2hS/WTkmGQgWfx
    kwIDAQAB
    -----END PUBLIC KEY-----
    """;

  public boolean verifyWebhook(String requestBody, String signatureHeader) throws Exception {
    String publicKeyContent = PUBLIC_KEY_PEM
      .replace("-----BEGIN PUBLIC KEY-----", "")
      .replace("-----END PUBLIC KEY-----", "")
      .replaceAll("\\s", "");
     
    byte[] keyBytes = Base64.getDecoder().decode(publicKeyContent);
    X509EncodedKeySpec keySpec = new X509EncodedKeySpec(keyBytes);
    PublicKey publicKey = KeyFactory.getInstance("RSA").generatePublic(keySpec);

    byte[] signatureBytes = Base64.getDecoder().decode(signatureHeader);

    Signature verifier = Signature.getInstance("SHA256withRSA");
    verifier.initVerify(publicKey);
    verifier.update(requestBody.getBytes("UTF-8"));
     
    return verifier.verify(signatureBytes);
  }

Example Webhook

Request:

POST {webhookUrl}
Content-Type: application/json
X-Paysafe-Signature: MGUCMQCxL2H8...base64-encoded-signature...==

Sample payload:

{
  "notificationId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1732617600,
  "data": {
    "accountId": 1001,
    "availableBalance": 123.45,
    "currency": "EUR"
  }
}

Error Messages

The following error messages can be returned by the Merchant Query Interface:

Error	Description	Reason for error
401	Unauthorised / Cannot log in	Authentication is required and has failed or has not yet been provided.
402	Payment Required	Reserved for future use.
403	Forbidden	The request was a valid request, but the server is refusing to respond to it. For example, the provided credentials were authenticated but lack access.
404	Not Found	The requested resource could not be found.
405	Method not Allowed	A request was made of a resource using a request method not supported. For example, using GET on a method which requires POST.