Skrill Automated

Payments Interface (API)

Guide
For use by Skrill merchants
This guide describes how to connect to the Automated
Payments Interface (API)

www.skrill.com
Version 2.19

Skrill Limited, 25 Canada Square, Canary Wharf, London, E14 5LQ, UK.

Skrill Automated Payments Interface (API) Guide 2.19

Copyright
2014. Skrill Ltd. All rights reserved.
The material contained in this guide is copyrighted and owned by Skrill Ltd together with any other
intellectual property in such material. Except for personal and non-commercial use, no part of this
guide may be copied, republished, performed in public, broadcast, uploaded, transmitted,
distributed, modified or dealt with in any manner at all, without the prior written permission of Skrill
Ltd, and, then, only in such a way that the source and intellectual property rights are acknowledged.
To the maximum extent permitted by law, Skrill Ltd shall not be liable to any person or organisation,
in any manner whatsoever from the use, construction or interpretation of, or the reliance upon, all
or any of the information or materials contained in this guide.
The information in these materials is subject to change without notice and Skrill Ltd. assumes no
responsibility for any errors.
Skrill Ltd.
Registered office: Skrill Limited, 25 Canada Square, Canary Wharf, London, E14 5LQ, UK.

Version Control Table

Date

Version

Description

13/09/2013

2.16

New guide template and updated content.

25/11/2013

2.1.7

Removal of Latvian currency.

21/02/2014

2.1.8

Changes to Skrill 1-Tap

14/03/2014

2.19

Updates to Skrill 1-Tap returned status codes.

Publication number: GW-API-REL-14/03/2014

Skrill 2014

Page 1

Skrill Automated Payments Interface (API) Guide 2.19

Contents
1

About this Guide................................................................................................................... 4

1.1

Objectives and target audience .............................................................................................. 4

1.2

Related documentation .......................................................................................................... 4

1.3

Conventions used in this guide ............................................................................................... 4

Introduction ......................................................................................................................... 5

Security ................................................................................................................................ 6

3.1

Security requirements............................................................................................................. 6

3.2

Security restrictions ................................................................................................................ 6

3.3

Separate API and MQI password ............................................................................................ 7

3.4

Secret word ............................................................................................................................. 7

Send Money using an HTTPs request ..................................................................................... 8

4.1.1

Sending a transfer prepare request ................................................................................ 9

4.1.2

Executing the transfer ................................................................................................... 10

4.1.3

Reposting the HTTPs transfer request .......................................................................... 11

Merchant Query Interface................................................................................................... 12

5.1

5.1.1

Repost transaction status ............................................................................................. 12

5.1.2

Transaction status ......................................................................................................... 13

5.1.3

View account history..................................................................................................... 14

5.1.4

Cancel a recurring payment .......................................................................................... 15

5.1.5

Recurring payment status ............................................................................................. 15

5.1.6

Extending the end date of a recurring payment ........................................................... 16

5.1.7

Cancel Skrill 1-Tap payment .......................................................................................... 16

5.1.8

Skrill 1-Tap payment status........................................................................................... 16

5.2
6

Error messages ...................................................................................................................... 17

Skrill 1-Tap Payment Interface ............................................................................................ 18

6.1

MQI Actions .......................................................................................................................... 12

Skrill 1-Tap actions ................................................................................................................ 18

6.1.1

Prepare .......................................................................................................................... 18

6.1.2

Request ......................................................................................................................... 19

Refunds .............................................................................................................................. 21
7.1

Preparation of the refund ..................................................................................................... 21

7.2

Execution of the refund ........................................................................................................ 23

7.3

Refund status report ............................................................................................................. 24

Appendices......................................................................................................................... 26

Skrill 2014

Page 2

Skrill Automated Payments Interface (API) Guide 2.19

8.1

ISO 4217 currencies .............................................................................................................. 26

8.2

Error Messages...................................................................................................................... 27

Glossary ............................................................................................................................. 29

10 Index .................................................................................................................................. 30

Skrill 2014

Page 3

Skrill Automated Payments Interface (API) Guide 2.19

1 ABOUT THIS GUIDE

1.1 Objectives and target audience
This guide describes how to use the Skrill Automated Payments Interface (API). The Skrill API provide
an alternative means of connecting to the Skrill Payment Gateway, and can be used to automate
transaction requests such as refunds, payments and queries.
This guide is intended for users who need to set up automated transaction queries, such as mass
payments and refunds. You will need a working knowledge of HTML and XML and an understanding
of how to send and receive information using these protocols.
The guide covers the different transaction request options and provides instructions on how to
implement them.

1.2 Related documentation

You should use this guide together with the additional Skrill documents described below.

Guide

Description

Skrill Payment Gateway

Integration Guide

Describes how to connect to and customise the Skrill Payment

Gateway.

1.3 Conventions used in this guide

The table below lists some of the conventions used in this guide.
Table 1: List of conventions

Convention

Description

Reference

Indicates a reference to another section in this guide. For

example, refer to the Introduction on page 5.

File path

Used to indicate a file path or folder structure.

Glossary

Glossary term

Skrill 2014

Page 4

Skrill Automated Payments Interface (API) Guide 2.19

2 INTRODUCTION
The Skrill Automated Payments Interface enables you to execute automated requests to Skrill,
including:

Send money transactions to you customers

Skrill 1-Tap transactions
Manage recurring payments
Checking the status of transactions and recurring payments
Downloading account histories and repost status reports

These options are described in detail in this guide.

Note: We strongly advise that you call the Skrill URLs by hostname when making requests rather
than hard-coding the static IP of the Skrill server, which is subject to change.

Contact for queries

For all merchant support, please contact the Skrill Merchant Service Department:
Email: [email protected]
Phone: +44 870 383 0762 (Mon-Fri, 8am until 5pm UK time).

Skrill 2014

Page 5

Skrill Automated Payments Interface (API) Guide 2.19

3 SECURITY
3.1 Security requirements
All requests to the API must be standard HTTPs requests. The HTTPs protocol provides a secure
means of verification of the program on the client host. Plain text HTTP requests are forbidden and if
the client sends an HTTP request to the server it will be denied.
Tip: If you currently do not send HTTPs headers for tracking reasons, you should be aware that this
can be used as a loophole by potential website hackers.

3.2 Security restrictions

By default, the Automated Payments Interface and Merchant Query Interface are disabled.

To enable the MQI and API:

1. Log in to your Skrill account at www.skrill.com.
2. Go to Settings > Developer Settings.
3. Check the Enable service checkbox next to the services you want to enable.

Figure 1: Enable API/MQI service

4. Specify at least one IP address from which requests will be made. All requests from other IP
addresses are denied. Access can be granted to:
o
o
o

A single IP address (e.g. 192.168.0.2)

Multiple IP addresses, separated by space (e.g. 192.168.0.2 10.0.0.2)
A subnet in CIDR notation (e.g. 192.168.0.0/24)

Enter a list of IPs or at least one IP address (or an IP range) in the text fields in the
corresponding sections.
5. To apply your changes, click Save.

Skrill 2014

Page 6

Skrill Automated Payments Interface (API) Guide 2.19

3.3 Separate API and MQI password

You must use a separate password for making API or MQI requests. This ensures that the password
you use to access your Skrill Digital Wallet account can be changed without affecting the API or MQI.

To enable a separate API/MQI password:

1. In the Settings > Developer Settings area, check the Enable separate API/MQI password
checkbox.
2. Enter a new password and confirm it in the Re-type password box below.

Figure 2: Change MQI/API password

Note: the password must be at least 8 characters long and must contain at least one alphabetic and
one non-alphabetic character.
3. Click Save.

3.4 Secret word

This feature allows you to submit a secret word instead of your API/MQI password when making
requests to the MQI. The secret word is also used when sending you Skrill status reports.

To insert a secret word:

1. Go to the Settings > Developer Settings section of your Skrill account.
2. In the Secret Word field, enter your secret word. The following restrictions apply:
o
o
o

All characters must be in lowercase

The length should not exceed 10 characters
Special characters are not permitted (e.g. @, %, $, etc.)

Note: If you insert any uppercase symbols, they will automatically be converted to lowercase.
3. To apply your changes, click Save.

Skrill 2014

Page 7

Skrill Automated Payments Interface (API) Guide 2.19

4 SEND MONEY USING AN HTTPS REQUEST

You can make mass payments using the Skrill Automated Payments Interface (API). This offers the
same functionality that is available on My Account, but enables you to automate the sending of
payment details from your servers to Skrill using an HTTPs request.
Automated payment transfers are implemented by sending an HTTPs request to the following URL:
https://www.moneybookers.com/app/pay.pl.
The process consists of two steps:

Sending a transfer prepare request

Executing the transfer

After each step Skrill returns a XML response that contains the result of the performed action. See
the example below.

Figure 3: Steps in the Transfer request

Note: we recommend you open a test account to test your mass payment transaction. You can open
a new Skrill digital wallet account online and send a request to the Merchant Service team to
enable this as a test account. Test accounts operate in the live environment, but funds cannot
be sent from a test account to a live account.

Skrill 2014

Page 8

Skrill Automated Payments Interface (API) Guide 2.19

4.1.1 Sending a transfer prepare request

Query parameter: action=prepare
You must include the parameters described below in your HTTPs request.
Table 2: Send money API prepare request parameters

Parameter

email

Description
The required action. In the first step,
this is prepare.
Your email address.

password

Your MD5 API/MQI password.

amount
currency
bnf_email
subject

Amount to be transferred.
Currency of the amount.
Recipients email address.
Subject of the notification email
Comment to be included in the
notification email.
Your reference ID (must be unique if
submitted).

action

note
frn_trn_id

Required?

Example value

Yes

action=prepare

Yes
Yes

[email protected]
9f535b6ae672f627e4a5f79f2b7c
63fe
10.95
EUR
[email protected]
Your order is ready
Details are available on our
website.

Yes
Yes
Yes
Yes
Yes
No

A1234

Skrill response
Skrill returns an XML response to your request, which contains a 'response' tag with one of the
following elements:

'sid' element - returned if the authorisation and payment preparation is successful. The SID
(Session Identifier) must be submitted in your transfer execution request (see section 4.1.2
on page 10).
'error' element included if an error occurs. It includes an 'error_msg' tag, which contains
the error message description.

Example 1: Successful prepare request

Below is an example of a successful prepare request:
Request:
POST
https://www.moneybookers.com/app/pay.pl?action=prepare&[email protected]&password=6b4c1b
a48880bcd3341dbaeb68b2647f&amount=1.2&currency=EUR&[email protected]&subject=s
ome_subject&note=some_note&frn_trn_id=111

Response:
<?xml version="1.0" encoding="UTF-8"?> <response>
<sid>5e281d1376d92ba789ca7f0583e045d4</sid> </response>

Skrill 2014

Page 9

Skrill Automated Payments Interface (API) Guide 2.19

Example 2: Failed prepare request

This example shows a request that failed, due to a missing amount.
Request:
POST
https://www.moneybookers.com/app/pay.pl?action=prepare&[email protected]&password=6b4c1b
a48880bcd3341dbaeb68b2647f&currency=EUR&[email protected]&subject=some_subject
&note=some_note&frn_trn_id=111

Response:
<?xml version="1.0" encoding="UTF-8"?> <response> <error>
<error_msg>MISSING_AMOUNT</error_msg> </error> </response>

4.1.2 Executing the transfer

Query parameter: action=transfer
Your web servers should include the SID information provided in the XML response from Skrill in the
transfer execution request, as described below.
Table 3: Execute transfer request parameters

Field

Description
The required action. In the second step,
this is transfer.
Session identifier returned in response
to the prepare request.

action
sid

Required?

Example value

Yes

action=transfer

Yes

5e281d1376d92ba789ca7f0583e04
5d4

Skrill response
The correct XML response contains a 'response' tag that includes the following elements:

'transaction' element - returned if the payment is successful; the response includes the
fields described in Table 4 below.
'error' element returned if an error occurs. The response includes the 'error_msg' field,
which provides details of the error.

Table 4: Successful response to transfer request

Field

Description

Amount
Currency
Id

Amount paid in the currency of your Skrill account.

Currency of your Skrill account.
Transaction ID.
Numeric value of the transaction status:
1 scheduled (if beneficiary is not yet registered at Skrill)
2 - processed (if beneficiary is registered)
Text value of the transaction status.

Status
status_msg

Skrill 2014

Page 10

Skrill Automated Payments Interface (API) Guide 2.19

Example of a successful transfer request

Request:
POST
https://www.moneybookers.com/app/pay.pl?action=transfer&sid=5e281d1376d92ba789ca7f0583e045d4

Response:
<?xml version="1.0" encoding="UTF-8"?> <response> <transaction>
<amount>1.20</amount> <currency>EUR</currency> <id>497029</id>
<status>2</status> <status_msg>processed</status_msg> </transaction>
</response>

4.1.3 Reposting the HTTPs transfer request

If there is a communication error during the transfer, you must resend the transfer request within 15
minutes of the previous request (since transfer request sessions expire after 15 minutes).
Note: The Skrill server executes only one transaction per session, so the request will not be
duplicated.
There are three possible outcomes to reposting the HTTPs request, depending on the transfer
execution status:

If a transaction has already been executed within this session, then you will need to
generate a new session ID, since only one transaction is allowed per session.
If there is a transaction in the process of execution, which is already associated with this
session, then Skrill responds with status EXECUTION_PENDING. In this case you do not need
to generate a new session ID and can wait for the response.
If the transfer request is new (i.e., not executed or pending) then it will either succeed or fail
and the result will be a response as described in the section Skrill Response on page 10
above.

Skrill 2014

Page 11

Skrill Automated Payments Interface (API) Guide 2.19

5 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 a query to:
https://www.moneybookers.com/app/query.pl
The MQI requires three general parameters to be included in your query (email, password and
action) and a number of parameters specific to the requested action (see section 5.1 below).
Table 5: General query parameters

Field Name

Description

Required?

Example value

email

The email address of your Skrill account.

Yes

[email protected]

password

The hex MD5 of your API/MQI password.

Yes

9f535b6ae672f627e4e5f79
f2b7c63fe

action

The required action.

Yes

repost

5.1 MQI Actions

The following MQI actions are supported:

Repost transaction status

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

Each of these is described in further details below.

5.1.1 Repost transaction status

Query parameter: action=repost
This action allows you to request a repost of the status of a transaction to your status_url page.
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, see section 2.2.5 in the Skrill Payment Gateway
Integration Guide). If no status report was posted initially, this action will return a 403 Transaction
not found: TRN_ID error.
The parameters listed below are required.

Skrill 2014

Page 12

Skrill Automated Payments Interface (API) Guide 2.19

Table 6: Repost parameters

Field Name

Description

Required?

Example value

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

Notes:

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 code 200 - OK is returned.

5.1.2 Transaction status

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

Description

Required?

Example value

trn_id

Your transaction ID.

Yes/No

500123

mb_trn_id

Skrill transaction ID.

Yes/No

4585262

Notes:

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-formurlencoded format.

5.1.2.1 Examples

API transaction
Request:
POST
https://www.moneybookers.com/app/query.pl?action=status_trn&[email protected]&password=53903d
217504eb37f3fdb0ce77610558&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_fr
om_email=test%40test.bg&mb_currency=EUR

Skrill 2014

Page 13

Skrill Automated Payments Interface (API) Guide 2.19

Gateway transaction
Request:
POST
https://www.moneybookers.com/app/query.pl?action=status_trn&[email protected]&password=53
903d217504eb37f3fdb0ce77610558&mb_trn_id=104441110

Response:
200 OK
status=2&Field1=TR234567&md5sig=6AB68D3465F57492B7412ED0EB013621&merchant_i
d=9999981&pay_to_email=merchant%40host.com&mb_amount=33.24911&mb_transactio
n_id=101149910&currency=EUR&amount=17&transaction_id=49989810fa3ed45c&pay_f
rom_email=payeremail%40host.bg&mb_currency=BGN

5.1.3 View account history

Query parameter: action=history
You can use the history action to request a list of all your transactions for a specified period. The
following parameters are required:
Table 7: History parameters

Field Name

Description

Required?

Example value

start_date

The start date in DD-MM-YYYY format.

Yes

29-05-2012

end_date

The end date in DD-MM-YYYY format.

No

30-06-2013

Notes:

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 todays date.

5.1.3.1 Example
Request:
POST
https://www.moneybookers.com/app/[email protected]&password=53903d217504eb37f3f
db0ce77610558&action=history&start_date=25-05-2013&end_date=25-06-2013

Response:
text/csv

Skrill 2014

file: mb_history.csv

Page 14

Skrill Automated Payments Interface (API) Guide 2.19

5.1.4 Cancel a recurring payment

Query parameter: action= cancel_rec
This action allows you to cancel a recurring payment. The following parameters are required:
Field Name

Description

Required?

Example value

trn_id

Your transaction ID.

Yes

500123

For a successful HTTP request, the HTTP response code 200 - OK is returned.

5.1.5 Recurring payment status

Query parameter: action=status_rec
This action allows you to check the status of a recurring payment. The following parameters are
required:
Field Name

Description

Required?

Example value

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

5.1.5.1 Recurring payment status example

Request:
POST
https://www.moneybookers.com/app/query.pl?action=status_rec&[email protected]&password=28
13F1526CD435D296A2A8FEE37889AD&trn_id=yourtansID123

Response:
200 OK Status: 0 Next payment date: 26-05-2013, End date: 26-12-2013

Skrill 2014

Page 15

Skrill Automated Payments Interface (API) Guide 2.19

5.1.6 Extending the end date of a recurring payment

Query parameter: action= extend_rec
This action allows you to extend the end date (rec_end_date) of a recurring payment. To enable this
option, send a request to [email protected].
The following parameters are required:
Field Name

Description

Required?

Example value

trn_id

Your transaction ID.

Yes

500123

rec_end_date

The recurrent end date in dd-mm-yyyy

format.

Yes

30-06-2013

For a successful HTTP request, the HTTP response code 200 - OK is returned.

5.1.7 Cancel Skrill 1-Tap payment

Query parameter: action= cancel_od
This action allows you to cancel a Skrill 1-Tap payment. The following parameter is required:
Field Name

Description

Required?

Example value

trn_id

Your transaction ID.

Yes

500123

For a successful HTTP request, the HTTP response code 200 - OK is returned.

5.1.8 Skrill 1-Tap payment status

Query parameter: action= status_od
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

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

Last execution date in dd-mm-yyyy format.

Skrill 2014

Page 16

Skrill Automated Payments Interface (API) Guide 2.19

5.2 Error messages

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

Description
Unauthorised/ Cannot log in

been provided.
Reserved for future use.

Forbidden

The request was a valid request, but the server is refusing to

respond to it. For example, the provided credentials were
successfully authenticated but do not grant the client
permission to access the resource.

Not Found

The requested resource could not be found.

Method not Allowed

A request was made of a resource using a request method

not supported. For example, using GET on a form which
requires data to be presented via POST.

405

Skrill 2014

Authentication is required and has failed or has not yet

Payment Required

403

404

Reason for error

Page 17

Skrill Automated Payments Interface (API) Guide 2.19

6 SKRILL 1-TAP PAYMENT INTERFACE

The Skrill 1-Tap Payment Request Interface allows you to debit your customers Skrill account once a
Skrill 1-Tap payment has been authorised (refer to section 3.5 in the Skrill Payment Gateway
Integration Guide). To enable this service, send a request to [email protected].
You can connect to the Skrill 1-Tap interface by sending an HTTPS request to:
https://www.moneybookers.com /app/ondemand_request.pl
You must use the following Skrill 1-Tap button on your website checkout page when setting up Skrill
1-Tap mandates as well as for any subsequent transactions performed through Skrill 1-Tap.

This button is available in different dimensions. For details, contact [email protected] .

Note: You are advised to set up a separate Skrill account for Skrill 1-Tap. For details, contact
Merchant services.

6.1 Skrill 1-Tap actions

The following actions are available:

Prepare prepare the Skrill 1-tap payment

Request execute the Skrill 1-tap payment

6.1.1 Prepare
Query parameter: action=prepare
This action prepares the transaction to be executed later on with the request action. The following
parameters are required:
Field Name

Description

Required?

Example value

email

The email address linked to your Skrill

account.

Yes

[email protected]

password

The hex MD5 of your API/MQI password.

Yes

9f535b6ae672f627e4e5f
79f2b7c63fe

action

The required action (i.e., prepare).

Yes

prepare

Yes

10.50

Yes

EUR

No

We will debit your

account so that you can
continue using our
services.

amount
currency

ondemand_note

Skrill 2014

Amount of the request for a debit

transaction.
3-letter code of the currency of the
maximum amount according to ISO 4217
(see section 8.1 on page 26).
Text to be shown to the customer in the
email confirmation.

Page 18

Skrill Automated Payments Interface (API) Guide 2.19

Field Name
frn_trn_id

rec_payment_id

merchant_fields

Field 1
Field 2

Description
Your transaction ID, used for the
recurring payment. This is your own
unique reference for this transaction
Recurring payment ID as sent to your
status_url and rec_status_url pages
upon creating the Skrill 1-Tap payment.
This should be the same as the original
Skrill transaction ID returned to your
systems with the original transaction
A comma-separated list of field names
that are passed back to your web server
when the Skrill 1-Tap payment is
confirmed (maximum 5 fields).
An additional field you can include,
containing your own unique parameters.
An additional field you can include,
containing your own unique parameters.

Required?

Example value

Yes

A205220

Yes

200005

Field1,Field2

Value1

Value2

Notes:

Both frn_trn_id and rec_payment_id should be provided. You should use the
rec_payment_id field to reference the original 1-tap transaction and provide a unique
frn_trn_id as the reference for the current transaction.
If ondemand_note is not provided, the one that is submitted when creating the Skrill 1-Tap
payment will be used.
A session identifier (SID) parameter is returned upon success.
You can track the status of any 1-tap transaction and perform refunds using the unique
frn_trn_id for that transaction.

6.1.2 Request
Query parameter: action=request
This action executes the actual transaction. The following parameters are required:
Field Name

Description

Required?

Example value

Sid

Session identifier returned in response to the

prepare request.

Yes

7783bfa23641a627
e4a5f79f2b7c6

Action

The required action. In this case request.

Yes

request

Upon success, returns the details of the transaction as an XML response. This response contains the
following fields:
Field Name

Description

Example value

Amount

Amount requested.

10.50

Currency

3-letter code of the currency of the amount, according to ISO

4217 (see section 8.1 on page 26).

EUR

Id

Transaction ID.

500123

Skrill 2014

Page 19

Skrill Automated Payments Interface (API) Guide 2.19

Field Name

Description

Example value

Skrill 1-Tap payment status:

Status

status_msg

2 processed
-2 failed

Text description of the status.

processed

Notes:

If a request fails, you are not allowed to make more than two requests for a debit of a
customers account using a Skrill 1-Tap payment per customer per 24 hours.
The customer is notified via email for every Skrill 1-Tap payment request executed.

Skrill 2014

Page 20

Skrill Automated Payments Interface (API) Guide 2.19

7 REFUNDS
You can use the Automated Payments Interface to make automated part or full refunds to
customers, up to the amount of the original payment.
You must send your refund request to the following URL:
https://www.moneybookers.com/app/refund.pl
The refund is made in two steps:

Preparation of the refund

Execution of the refund

7.1 Preparation of the refund

Query parameter: action=prepare
The following parameters must be included in the refund prepare request:
Table 8: Refund authorisation parameters

Field
action

Required
Yes

Example
action=prepare

Yes
Yes

[email protected]
9f535b6ae672f627e4a5f79
f2b7c63fe

transaction_id
mb_transaction_id
amount

Description
Defines the prepare step of the refund
request.
Your email address.
The MD5 of your API/MQI password.
Note: only lowercase of the MD5 value is
accepted.
Your transaction ID to be refunded.
The Skrill transaction ID to be refunded.
Amount to be refunded.

Yes /No
Yes / No
No

500123
4585262
9.99

refund_note

Description of the refund.

No

Product no longer in stock

merchant_fields

A comma-separated list of field names

that are passed back to your server
when the refund payment is confirmed
(maximum 5 fields).
An additional field you can include,
containing your own unique parameters.
An additional field you can include,
containing your own unique parameters.
URL or email address to which status
updates should be sent.

No

Field1, Field2

No

Value1

No

Value2

No

https://www.merchant.co
m/refund_update.cqi

email
password

Field 1
Field 2
refund_status_url

Notes:

You must submit either transaction_id or mb_transaction_id.

If no amount value is submitted, the refund will be for the full amount of the original
transaction.
If the refund_note value is submitted, it is shown in the body of the notification email sent
to the customer.

Skrill 2014

Page 21

Skrill Automated Payments Interface (API) Guide 2.19

XML server response

The resulting XML contains a 'response' tag with one of the following elements, depending on the
success of the operation:

'sid' (session identifier) element returned if the prepare request is successful. This must be
submitted with the refund action in the next step:

<response>
<sid>4504848cb1ed0d29f60458bf992399fd</sid>
</response>

'error' element returned if an error occurs. Contains an 'error_msg' tag with the error
message:

<response>
<error>
<error_msg>CANNOT_LOGIN</error_msg>
</error>
</response>

7.1.1.1 Error messages

See the table below for details of error messages.
Table 9: Refund authorisation error messages

Error message
INVALID_OR_MISSING_ACTION

Description
The action parameter is not supplied in the query.

REFUND_DENIED

Refund feature is not activated.

LOGIN_INVALID

Missing email or password parameters.

INVALID_EMAIL

An Invalid email parameter is supplied.

CANNOT_LOGIN

Invalid combination of email and password is supplied.

7.1.1.2 Prepare refund examples

Successful prepare request

Request:
POST
https://www.moneybookers.com/app/refund.pl?action=prepare&[email protected]&password=9f53
5b6ae672f627e4a5f79f2b7c63fe&transaction_id=500123&amount=9.99&refund_note=example_note&refund
_status_url=https://www.merchant.com/refund_update.cqi&merchant_fields=Field1,Field2&Field1=Value1&Fi
eld2=Value2

Response:
<response>
<sid>d831e9072e8b89c57a3654ddf5fcb907</sid>
</response>

Skrill 2014

Page 22

Skrill Automated Payments Interface (API) Guide 2.19

Incorrect request (invalid merchant API/MQI password)

Request:
POST
https://www.moneybookers.com/app/refund.pl?action=prepare&[email protected]&password=9f53
5b6ae672f627e4a5f79f2b7c64fe&amount=9.99&refund_note=example_note&refund_status_url=https://www
.merchant.com/refund_update.cqi&merchant_fields=Field1,Field2&Field1=Value1&Field2=Value2

Response:
<response>
<error>
<error_msg>CANNOT_LOGIN</error_msg>
</error>
</response>

7.2 Execution of the refund

Query parameter: action=refund
The following parameters must be included in the refund execution request:
Table 10: Refund execution parameters

Field
action
sid

Description
Defines the execution step of the refund
request.
Session identifier returned in response
to the prepare request.

Required
Yes

Example
action=refund

Yes

d831e9072e8b89c57a3654ddf
5fcb907

XML Server Response

The server returns XML containing a response tag, which includes some of the following elements,
depending on the success of the operation:
Table 11: Refund response

Field
mb_amount

Description
Amount refunded in the currency of your Skrill account.

Example
9.99

mb_currency

Currency of your Skrill account.

EUR

transaction_id

Your refund transaction ID as submitted in the request.

500123

mb_transaction_id

The Skrill transaction ID for the refund.

5585262

Field1

The first additional field pre-defined in merchant_field_

parameter
The second additional field pre-defined in merchant_field
parameter
2 - processed, 0 - pending and -2 - failed.
BALANCE_NOT_ENOUGH
Refund amount exceeds account
balance.
CC_REFUND_FAILED
Refund to a credit/debit card
failed.
RESERVE_EXCEEDED
Refund amount is blocked by
rolling/fixed reserve.
GENERIC_ERROR
Other errors, different from those
described above.

Value1

Field2
status
error

Skrill 2014

Value2
2
CC_REFUND_FAILED

Page 23

Skrill Automated Payments Interface (API) Guide 2.19

7.2.1.1 Refund execution example

Request:
POST
https://www.moneybookers.com/app/refund.pl?action=refund&sid=d831e9072e8b89c57a3654ddf5fcb907

Response:
<response>
<mb_amount>2</mb_amount>
<mb_currency>EUR</mb_currency>
<mb_transaction_id>381526883</mb_transaction_id>
<Field1>Value1</Field1>
<Field2>Value2</Field2>
<status>2</status>
<transaction_id/>
</response>

7.3 Refund status report

If a request for refund cannot be executed at the moment, Skrill sends a response with status 0
(pending) in the prepare step. When Skrill receives an update on the status of the refund, a
notification is sent to your refund_status_url page.
If you would like to receive notifications for every status of your refund request, contact the
Merchant Services team.
This status report consists of the following fields:
Table 12: Status report fields

Field
transaction_id
mb_transaction_id
status
mb_amount
mb_currency
md5sig
sha2sig

Skrill 2014

Description
Your transaction ID for the refund as
submitted in the request.
The Skrill transaction ID for the
refund.
2 processed and -2 - failed.

Required
Yes /No

Example
500123

Yes

5585262

Yes

Amount refunded in the currency of

your Skrill account
Currency of your Skrill account.
MD5 signature. See section 7.3.1.1
on page 25.
Sha2 signature.
For more information, contact
[email protected]

Yes

9.99

Yes
Yes

EUR
9f535b6ae672f627e4a5f79f2
b7c63fe
dbb7101322257a311f08d1c
527053058fc7e464e30bcfb4
613f09053c22dd1f8

No

Page 24

Skrill Automated Payments Interface (API) Guide 2.19

7.3.1.1 MD5 signature

The md5sig parameter consists of an MD5 sum on a string built by concatenating the following
parameters:
Table 13: MD5 Signature parameters

Value

Description

Example

merchant_id
mb_transaction_id
MD5 of secret word

4637827
5585262
327638C253A4637199CE
BA6642371F20

mb_amount
mb_currency

Your Skrill account user ID.

The new Skrill transaction ID for refund.
The uppercase MD5 value of the secret word
submitted in the Settings > Developer Settings
section of your Skrill account.
Amount refunded in the currency of your account.
Currency of your account.

status

The status of the refund transaction.

9.99
EUR

Example code
Concatenated fields in Ruby code:
fields = [merchant_id, mb_transaction_id,
Digest::MD5.hexdigest(secret).upcase, mb_amount, mb_currency, status].join
md5sig == Digest::MD5.hexdigest(fields).upcase

Using the example values in Table 13 above, the following MD5 code returned:
CF9DCA614656D19772ECAB978A56866D

Skrill 2014

Page 25

Skrill Automated Payments Interface (API) Guide 2.19

8 APPENDICES
8.1 ISO 4217 currencies
Table 14: ISO 4217 Currencies accepted by Skrill

EUR
USD
GBP
HKD
SGD
JPY
CAD
AUD
CHF
DKK
SEK
NOK
ILS
MYR
NZD
TRY
AED
MAD
QAR
SAR

Euro
U.S. Dollar
British Pound
Hong Kong Dollar
Singapore Dollar
Japanese Yen
Canadian Dollar
Australian Dollar
Swiss Franc
Danish Krone
Swedish Krona
Norwegian Krone
Israeli Shekel
Malaysian Ringgit
New Zealand Dollar
New Turkish Lira
Utd. Arab Emir. Dirham
Moroccan Dirham
Qatari Rial
Saudi Riyal

Skrill 2014

TWD
THB
CZK
HUF
SKK
EEK
BGN
PLN
ISK
INR
KRW
ZAR
RON
HRK
LTL
JOD
OMR
RSD
TND

Taiwan Dollar
Thailand Baht
Czech Koruna
Hungarian Forint
Slovakian Koruna
Estonian Kroon
Bulgarian Leva
Polish Zloty
Iceland Krona
Indian Rupee
South-Korean Won
South-African Rand
Romanian Leu New
Croatian Kuna
Lithuanian Litas
Jordanian Dinar
Omani Rial
Serbian dinar
Tunisian Dinar

Page 26

Skrill Automated Payments Interface (API) Guide 2.19

8.2 Error Messages

Table 15: Errors when validating parameters

Error

Resolution

INVALID_OR_MISSING_ACTION

Wrong action or no action is provided

LOGIN_INVALID

Email address and/or password were not provided

INVALID_REC_PAYMENT_ID

Invalid recurring payment ID is submitted by the merchant

MISSING_EMAIL

Provide registered email address of merchant account

MISSING_PASSWORD

Provide correct API/MQI password

MISSING_AMOUNT

Provide amount you wish to send

MISSING_CURRENCY

Provide currency you wish to send

MISSING_BNF_EMAIL

Provide email address of the beneficiary

MISSING_SUBJECT

Provide subject of the payment

MISSING_NOTE

Provide notes for the payment

Table 16: Errors during log in

Error

Resolution

CANNOT_LOGIN

Email address and/or API/MQI password are incorrect

PAYMENT_DENIED

Check in your account profile that the API is enabled and you are
posting your requests from the IP address specified

Table 17: Errors when validating payment details

Error

Resolution

INVALID_BNF_EMAIL

Check the format of the beneficiary email address

INVALID_SUBJECT

Check parameter length submitted

INVALID_NOTE

Check parameter length submitted

INVALID_FRN_TRN_ID

Check parameter length submitted

INVALID_AMOUNT

Check amount format

INVALID_CURRENCY

Check currency code

EXECUTION_PENDING

If you resend a transfer request with the same session identifier

before the 'transfer' request was processed, this error will be
returned

ALREADY_EXECUTED

If you have requested that the value for frn_trn_id must be unique
for each transfer, this error will be returned when you try to
submit the same value for more than one transfer

BALANCE_NOT_ENOUGH

Sending amount exceeds account balance

SINGLE_TRN_LIMIT_VIOLATED

Maximum amount per transaction = EUR 10,000

DISALLOWED_RECIPIENT

You are not permitted to send money to the recipient. E.g. Gaming
merchants are not permitted to send or receive payments to/from
US based customers

CHECK_FOR_VERIFIED_EMAIL

Your account email address needs to be verified

LL_NO_PAYMENT

Your account is locked for security reasons. Please contact us

Skrill 2014

Page 27

Skrill Automated Payments Interface (API) Guide 2.19

Table 18: Errors when making Skrill 1-Tap payment requests

Error

Resolution

CUSTOMER_IS_LOCKED

The customer's account is locked for outgoing payments

BALANCE_NOT_ENOUGH

The customer's account balance is insufficient

RECIPIENT_LIMIT_EXCEEDED

The customer's account limits are not sufficient

CARD_FAILED

The customer's credit or debit card failed

REQUEST_FAILED

Generic response for transaction failing for any other reason

ONDEMAND_CANCELLED

The customer has cancelled this Skrill 1-Tap payment

ONDEMAND_INVALID

The Skrill 1-Tap payment requested does not exist

MAX_REQ_REACHED

Too many failed Skrill 1-Tap payment requests to the API. For
security reasons, only two failed attempts per user per 24 hours
are allowed

Skrill 2014

Page 28

Skrill Automated Payments Interface (API) Guide 2.19

9 GLOSSARY
This section provides a description of key terms used in this guide.
Term
Automated Payments
Interface (API)

Browser

HTML POST

ISO currency codes

Merchant Services
team
My Account
Transaction
Skrill Digital Wallet

Skrill Payment
Gateway
Slim Gateway

Transaction
Transaction ID
Transaction status

Skrill 2014

Explanation
The API is a collection of tools that enables merchants to execute
requests to the Skrill Payment Gateway. For example: to send money,
make 1-tap payments, make refunds, check the status of transactions
and download reports.
Application that enables a customer or merchant to access web pages.
Examples include: Internet Explorer, Google Chrome and Mozilla
Firefox.
Integration method where the merchant sends details to the Skrill
Payment Gateway using a standard HTML form that posts this
information in the HTML header.
3-digit currency code of the International Standards Organisation (ISO)
that identifies the currency. For example, GBP for British Pound.
Skrill team responsible for providing technical and service support to
merchants.
Merchant and customer account administration portal that enables
viewing of transactions and transferring funds.
Each financial interaction on the system is referred to as a transaction.
Skrills Digital Wallet, enabling customers to link cards and pay directly
from their wallet account using cards or bank transfer. Up to 4
payment cards and 10 bank accounts can be linked to a wallet
account.
Skrills secure page for processing transactions. Merchants connect to
the Payment Gateway, which will then process transactions from their
website.
Option in which the Skrill account Login fields are hidden from the
customer, providing a simplified user experience. Note that on the
new Gateway payment page we hide the login fields by default.
Each financial interaction with the Skrill Payment Gateway is referred
to as a transaction. Transactions are linked to payments.
Unique ID assigned to a transaction by the Skrill Payment Gateway.
Each transaction on the Skrill Payment Gateway is given a status. This
includes: processed, pending, temporary, scheduled, cancelled, failed,
chargeback and successful.

Page 29

Skrill Automated Payments Interface (API) Guide 2.19

10 INDEX
Enable mass payments on My Account, 6
Example of a successful authorisation request,
10
Example of a successful transfer request, 11
Executing the Transfer, 10
ISO 4217 currencies, 12
Mass Payments option on My Account, 6

Skrill 2014

Preparing the payment file, 7

Reposting the transfer request, 11
Send Money option on My Account, 4
Skrill response, 9
Transfer authorisation request, 9
Transfers using an HTTPs request, 9
Uploading your payment file to My Account, 8

Page 30