Skrill Automated Payments Interface Merchant Integration Manual

www.skrill.com
Version <2.13>

Automated Payments Interface www.skrill.com

Version Date

<2.13> 28 Nov 2012

th

1 2

INTRODUCTION ............................................................................................................. 3 SECURITY .................................................................................................................... 4 2.1 2.2 2.3 2.4 IMPORTANT SECURITY REQUIREMENT FOR MAKING REQUESTS TO THE API .................................................... 4 SECURITY RESTRICTIONS .................................................................................................. 4 SEPARATE API/MQI PASSWORD .......................................................................................... 5 SECRET WORD ........................................................................................................... 6

SEND MONEY PER HTTPS REQUEST ....................................................................................... 7 3.1 3.2 3.3 SPECIFICATION OF THE SEND MONEY INTERFACE ........................................................................... 7 AUTHORISATION AND PREPARATION OF THE PAYMENT...................................................................... 7 EXECUTION OF THE TRANSFER ............................................................................................ 9

MERCHANT QUERY INTERFACE .......................................................................................... 11 4.1 4.2 ACTIONS .............................................................................................................. 11 ERROR MESSAGES...................................................................................................... 15

SKRILL 1-TAP PAYMENT INTERFACE ...................................................................................... 16 5.1 ACTIONS .............................................................................................................. 16

REFUNDS .................................................................................................................. 18 6.1 6.2 6.3 AUTHORISATION AND PREPARATION OF THE REFUND...................................................................... 18 EXECUTION OF THE REFUND ............................................................................................ 21 STATUS REPORT ....................................................................................................... 22

EMAIL CHECK TOOL ....................................................................................................... 23 7.1 SPECIFICATION OF THE EMAIL CHECK TOOL .............................................................................. 23

ANNEX I ERROR MESSAGES ................................................................................................. 26

Unclassified

www.skrill.com

Page 2

Automated Payments Interface www.skrill.com

Version Date

<2.13> 28 Nov 2012

th

Introduction
The Skrill Automated Payments Interface is a collection of tools where merchants can execute requests to the Skrill servers to:
Make send money transactions to their customers Make Skrill 1-Tap transactions Check the status of transactions, recurring payments, etc. Download account histories and repost status reports

These functionalities are described in detail in the following sections. We strongly advise that you call the Skrill URLs by hostname when making requests rather than hard-coding the static IP of our server since Skrill may need to change it. For all merchant support, please contact our Merchant Service Department: Email: merchantservices@skrill.com.com Phone: +44 870 383 0762 (Mon-Fri, 8am until 5pm UK time)

Unclassified

www.skrill.com

Page 3

Automated Payments Interface www.skrill.com

Version Date

<2.13> 28 Nov 2012

th

Security
2.1 Important security requirement for making requests to the API

All requests to the API are standard HTTPS requests. Although earlier versions of this manual do not mention this and the HTTP/1.1 specification states that the 'User-Agent' HTTP request header is not mandatory, it IS required by Skrill. It is a means of verification of the program on the client host and if the client does not send this string, we cannot verify nor log it and the response from our servers will be HTTP 404 Forbidden. Sending the 'User-Agent' is one of the principle rules of our network security and is usually a simple setting in client programs. If you are against sending the header for tracking reasons, you may be interested to know that this is used as a loophole by potential attackers.

2.2

Security restrictions

Enable Automated Payments Interface / Merchant Query Interface By default, the Automated Payments and Merchant Query Interfaces are disabled. To enable them login to www.moneybookers.com and enter the Merchant tools page in your My account section (See the screenshot below). Check the corresponding Enable service checkbox, enter the IP address from which you will make requests (see IP Restriction below) and press the confirm button. IP Restriction This Skrill feature aims to further increase the security level of the merchants account, protecting it from unauthorised login attempts. The merchant must specify at least one IP address from which requests to the API/MQI and Email Check interfaces will be made. All requests from other IP addresses are denied. Access to the API/MQI can be granted to: 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)

Unclassified

www.skrill.com

Page 4

Automated Payments Interface www.skrill.com

Version Date

<2.13> 28 Nov 2012

th

To enable IP restriction login to www.moneybookers.com and enter the Merchant tools page in your My account section. Enter a list of IPs or at least one IP address (or an IP range) in the text fields in the corresponding sections. (See the screenshot below). Click on the Confirm button in order to apply the changes.

2.3 Separate API/MQI password

Merchants must use a separate password from their account password for making API/MQI requests. This means that the password used for their account to login on the Skrill website can be changed without affecting the usage of the API/MQI. Before the API/MQI can be enabled, the merchant must: Check the Enable separate API/MQI password tick-box. Enter a new password and confirm it in the input box below (the password must be at least 8 characters long and must contain at least one alphabetic and one non-alphabetic character.) Click on the Submit button at the bottom of the page.

Unclassified

www.skrill.com

Page 5

Automated Payments Interface www.skrill.com Below is a screenshot of an account with successfully added API/MQI password:

Version Date

<2.13> 28 Nov 2012

th

To change the existing API/MQI password, the merchant must: 1. Enter a new password and confirm it in the input box below (the password is case sensitive, must be at least 8 characters long, maximum 50 characters long and must contain at least one alphabetic and one non-alphabetic character. The password cannot be the same as the email address and must be unique and not used for any other internet accounts. 2. Click on the Submit button at the bottom of the page. N.B. Before changing the API/MQI password, all instances of the old password used for existing API/MQI integrations should be changed to the new password value.

2.4 Secret word

This feature allows merchants to submit a secret word instead of their API/MQI password when making requests to the MQI and Email check interfaces. Additionally, the secret word is used when signing various status reports from Skrill to the merchant. The secret word can be submitted in the Merchant tools section of the website. The following restrictions apply: 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.

Unclassified

www.skrill.com

Page 6

Automated Payments Interface www.skrill.com

Version Date

<2.13> 28 Nov 2012

th

Send Money per HTTPS Request

Skrill transfers are usually performed by customers through the website www.moneybookers.com in the "Send Money" section. Merchants can execute the same kind of payments using Skrill' Automated Payments Interface (API) via simple HTTPS requests. The process is divided into two steps: 1. Authorisation and preparation of the payment 2. Execution of the transfer After each step the Skrill' servers return a XML response that contains the result of the performed action. You will probably require test accounts for which you need to open accounts online via our website and inform us of the email addresses used. The accounts will then be made test and funds uploaded. Test accounts operate in the production environment but funds cannot be sent from a test account to a normal account.

3.1
The

Specification of the Send Money Interface

merchant must provide the following parameters within HTTPS requests to this URL:

https://www.moneybookers.com/app/pay.pl. There are two interaction steps:

3.2

Authorisation and Preparation of the Payment

Request Parameters
Field Description Required? Example value

Unclassified

www.skrill.com

Page 7

Automated Payments Interface www.skrill.com

Version Date

<2.13> 28 Nov 2012

th

action email password amount currency bnf_email subject note frn_trn_id

define the first step of the iteration email address of the merchant MD5 of the merchants API/MQI password amount to be transferred currency of the amount beneficiary's email address subject of the notification email note to be included in the notification email reference id supplied by the merchant (must be unique if submitted)

Y Y Y Y Y Y Y Y N

action=prepare moneybookers@merchant.com 9f535b6ae672f627e4a5f79f2b7c63fe 10.95 EUR customer@host.com Your order is ready Details are available at our site... A1234

XML Server Response The resulting XML will contain a 'response' tag that has one of the following elements: If the authorisation and payment preparation were successful, a 'sid' element containing a session identifier is included that is to be submitted at the next step.

Example

If an error occurs, an 'error' element is included with a 'error_msg' child that contains the error message.

Successful Authorisation: Request:

GET https://www.moneybookers.com/app/pay.pl?action=prepare&email=merchant@host.com&passw ord=6b4c1ba48880bcd3341dbaeb68b2647f&amount=1.2&currency=EUR&bnf_email=beneficiary@d omain.com&subject=some_subject&note=some_note&frn_trn_id=111

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

Unclassified

www.skrill.com

Page 8

Automated Payments Interface www.skrill.com Incorrect request (missing 'amount'): Request:

GET

Version Date

<2.13> 28 Nov 2012

th

https://www.moneybookers.com/app/pay.pl?action=prepare&email=merchant@host.com&passw ord=6b4c1ba48880bcd3341dbaeb68b2647f&currency=EUR&bnf_email=beneficiary@domain.com&s ubject=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>

3.3 Execution of the Transfer

Request Parameters
Field
action sid

Description
define second step of interaction session identifier from the previous step

Required?
Y Y action=transfer

Example value

5e281d1376d92ba789ca7f0583e045d4

XML Server Response The correct XML will contain a 'response' tag that includes the following elements: If the payment was successful, the response contains a 'transaction' element with the following children:
Field
Amount Currency Id

Description
Amount paid in the currency of the merchant's account Currency of the merchant's account Transaction ID Numeric value of the transaction status:

Status

1 scheduled (if beneficiary is not yet registered at Skrill) 2 - processed (if beneficiary is registered)

status_msg

Text value of the transaction status

Unclassified

www.skrill.com

Page 9

Automated Payments Interface www.skrill.com Example Successful Execution of Payment: Request

GET

Version Date

<2.13> 28 Nov 2012

th

If an error occurs, an 'error' element is included with a 'error_msg' child.

https://www.moneybookers.com/app/pay.pl?action=transfer&sid=5e281d1376d92ba789ca7f0 583e045d4

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>

Reposting the 'transfer' HTTPS request In case of a communication error during the process of a transfer, merchants are advised to resend the 'transfer' payment request again within 15 minutes of the last 'transfer' request ('transfer' request sessions expire after 15 minutes). This will not cause a second transfer to be executed since one session identifier (sid) will be executed only once by Skrill. There are three possible results: 1. In case this 'transfer' request has been successful already as a result of an older request, Skrill will simply return the result of the previous payment. 2. If this 'transfer' request has not yet been executed but a request had already been received before, Skrill will respond with EXECUTION_PENDING. 3. If the 'transfer' request has been received for the first time, Skrill will respond as described above in section 4.3.

Unclassified

www.skrill.com

Page 10

Automated Payments Interface www.skrill.com

Version Date

<2.13> 28 Nov 2012

th

Merchant Query Interface

The Merchant Query Interface allows merchants to query the Skrill database for the current status of transactions performed by them. The Query interface is accessible by posting specific parameters at

https://www.moneybookers.com/app/query.pl. The interface requires three general parameters -- email, password, action -- and a number of parameters specific to the requested action (actions are explained below). General query parameters:
Field Name
email password action

Description
The email address of the merchants Skrill account. The hex MD5 of the merchants API/MQI password. The required action.

Required?
Yes Yes Yes

Example value
merchant@merchant.com 9f535b6ae672f627e4e5f79f2b7c63fe repost

4.1 Actions
The following actions are defined: Repost action=repost Repost allows merchants to request that a notification of the status of a given transaction be posted to their status_url. In response, the Skrill system posts a status report (the format is explained in 2.3.6 of the Merchant Gateway Manual). The following action-specific parameters are required
Field Name
trn_id mb_trn_id status_url

Description
Merchant transaction ID. Skrill transaction ID. Where to post the notification

Required?
Yes/No Yes/No No 500123

Example value

4585262 https://www.merchant.com/mb_ notifications.asp

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. Upon success, HTTP 200 with a body of "OK" is returned.

Unclassified

www.skrill.com

Page 11

Automated Payments Interface www.skrill.com Transaction status action=status_trn

Version Date

<2.13> 28 Nov 2012

th

This action allows merchants to request the details about a transaction received via the Merchant Gateway. The following parameters are expected:
Field Name
trn_id mb_trn_id

Description
Merchant transaction ID. Skrill transaction ID.

Required?
Yes/No Yes/No

Example value
500123 4585262

As with Repost, 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 contain the transaction details encoded as application/xwww-form-urlencoded. Examples:

API transaction
Request:
GET https://www.moneybookers.com/app/query.pl?action=status_trn&email=mb654@abv.bg&pass word=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%40 test.bg&mb_currency=EUR

Gateway transaction
Request:
GET https://www.moneybookers.com/app/query.pl?action=status_trn&email=merchant@host.com &password=53903d217504eb37f3fdb0ce77610558&mb_trn_id=104441110

Response:
200 OK status=2&Field1=TR234567&md5sig=6AB68D3465F57492B7412ED0EB013621&merchant_id=999998 1&pay_to_email=merchant%40host.com&mb_amount=33.24911&mb_transaction_id=101149910&c urrency=EUR&amount=17&transaction_id=49989810fa3ed45c&pay_from_email=payeremail%40h ost.bg&mb_currency=BGN

Unclassified

www.skrill.com

Page 12

Automated Payments Interface www.skrill.com Account history action=history

Version Date

<2.13> 28 Nov 2012

th

Through the 'Account history' action, the merchant may request a list with the details of all transactions performed by them during a given period. The following parameters are expected:
Field Name
start_date end_date

Description
The start date in DD-MM-YYYY format The end date in DD-MM-YYYY format

Required?
Yes No

Example value
29-05-2002 30-06-2002

Upon success, returns the complete account history for the specified period in CSV (comma separated values) form. If the end_date parameter is not specified, we use todays date. Example: Request:
GET https://www.moneybookers.com/app/query.pl?email=merchant@host.com&password=53903d21 7504eb37f3fdb0ce77610558&action=history&start_date=25-05-2008&end_date=25-06-2008

Response:
text/csv file: mb_history.csv

Cancel recurring payment action= cancel_rec This action allows merchants to cancel a recurring payment. The following action-specific parameters are required:
Field Name
trn_id

Description
Merchant transaction ID

Required?
Yes 500123

Example value

Upon success, HTTP 200 with a body of "OK" is returned.

Unclassified

www.skrill.com

Page 13

Automated Payments Interface www.skrill.com Recurring payment status action=status_rec

Version Date

<2.13> 28 Nov 2012

th

This action allows merchants to check the status of a recurring payment. The following action-specific parameters are required:
Field Name
trn_id

Description
Merchant transaction ID

Required?
Yes

Example value
500123

If a transaction with the given ID is found, the response will contain 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:
GET https://www.moneybookers.com/app/query.pl?action=status_rec&email=merchant@host.com &password=2813F1526CD435D296A2A8FEE37889AD&trn_id=yourtansID123

Response:
200 OK Status: 0 Next payment date: 26-10-2008, End date: 26-10-2009

Extending the end date of a recurring payment action= extend_rec This action allows merchants to extend the end date (rec_end_date) of a recurring payment. If you want to use this action, you have first to apply for it by contacting merchantservices@skrill.com.com. The following actionspecific parameters are required:
Field Name
trn_id rec_end_date

Description
Merchant transaction ID The recurrent end date in dd-mm-yyyy format

Required?
Yes Yes

Example value
500123 30-06-2007

Upon success, HTTP 200 with a body of "OK" is returned.

Unclassified

www.skrill.com

Page 14

Automated Payments Interface www.skrill.com Cancel Skrill 1-Tap payment action= cancel_od

Version Date

<2.13> 28 Nov 2012

th

This action allows the merchant to cancel a Skrill 1-Tap payment. The following action-specific parameter is required:
Field Name
trn_id

Description
Merchant transaction ID

Required?
Yes

Example value
500123

Upon success, HTTP 200 with a body of "OK" is returned.

Skrill 1-Tap payment status action= status_od This action allows the merchant to check the status of a Skrill 1-Tap payment. The following action-specific parameter is required:
Field Name
trn_id

Description
Merchant transaction ID

Required?
Yes

Example value
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.

4.2 Error messages

The following errors may be returned by the Query interface:
Code
401 402 403 404 405

Explanation
Authorisation declined. Unknown action. Transaction not found. Missing parameter. Illegal parameter value.

Reason
Wrong email and/or password. Password in wrong format. Action not one of 'repost', 'status_trn', 'history'. Wrong transaction ID. A required parameter was not found The value of a required parameter did not match the expected format.

Unclassified

www.skrill.com

Page 15

Automated Payments Interface www.skrill.com

Version Date

<2.13> 28 Nov 2012

th

Skrill 1-Tap Payment Interface

The Skrill 1-Tap Payment Request Interface allows merchants to debit the customers Skrill account once Skrill 1Tap payment has been authorised (refer to our Merchant Gateway Manual, section 3.5). The interface is accessible by posting specific parameters through HTTPS at https://www.moneybookers.com/app/ondemand_request.pl. You should contact merchantservices@skrill.com.com in order to be allowed to use this service. Skrill 1-Tap must be represented using the following button on the merchant checkout. The use-cases for this button are setup of Skrill 1-Tap mandates as well as any subsequent transactions performed through Skrill 1-Tap.

This button is available in different dimensions. Please contact merchantservices@skrill.com.com for more information. PLEASE NOTE: It is strongly advised to setup the Skrill and Skrill 1-Tap gateways using different merchant accounts.

5.1 Actions
The following actions are defined: Prepare action=prepare This action prepares the transaction to be executed later on with the request action. The following action specific parameters are required:
Field Name
email password action amount

Description
The email address of the merchants Skrill account The hex MD5 of the merchants API/MQI password The required action Amount of the request for a debit transaction 3-letter code of the currency of the maximum amount according to ISO 4217 (see Annex I for accepted currencies) Text that will be shown to the customer on the confirmation page as a reason for the Skrill 1-Tap payment

Required?
Yes Yes Yes Yes

Example value
merchant@merchant.com 9f535b6ae672f627e4e5f79f2b7c63fe prepare 10.50

currency

Yes

EUR

ondemand_note

No

Sample merchant will debit your account so that you can continue using our services

Unclassified

www.skrill.com

Page 16

Automated Payments Interface www.skrill.com

Merchant transaction ID used for the recurring payment Recurring payment ID as sent to the merchant on the status_url and rec_status_url upon creating the Skrill 1-Tap payment A comma-separated list of field names that should be passed back to the Merchants server when the Skrill 1-Tap payment is confirmed (maximum 5 fields). An example merchant field An example merchant field

Version Date

<2.13> 28 Nov 2012

th

frn_trn_id

Yes/No

A205220

rec_payment_id

Yes/No

200005

merchant_fields

Field1,Field2

Field 1 Field 2

N N

Value1 Value2

Either frn_trn_id or rec_payment_id must be provided. 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. Request action=request This action executes the actual transaction. The following action specific parameters are required:
Field Name
sid action Session identifier The required action.

Description

Required?
Yes Yes

Example value
7783bfa23641a627e4a5f79f2b7c6 request

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

Description
Amount of the transaction as requested by the merchant 3-letter code of the currency of the amount as requested by the merchant, according to ISO 4217 (see Annex I of Merchant Gateway Manual for accepted currencies) Transaction ID 10.50

Example value

currency

EUR

id

500123

Unclassified

www.skrill.com

Page 17

Automated Payments Interface www.skrill.com

Skrill 1-Tap payment status: status 2 processed 0 active -1 cancelled -2 failed 0

Version Date

<2.13> 28 Nov 2012

th

status_msg

Text description of the status.

processed

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

Refunds
The merchant must provide the parameters within HTTPS requests to the following URL:

https://www.moneybookers.com/app/refund.pl There are two interaction steps: Authorisation and preparation of the refund Execution of the refund

6.1 Authorisation and preparation of the refund

Request parameters
Field
action

Description
define first step of the iteration

Required
Y

Example
action=prepare

email password

email address of the merchant MD5 of merchant's API/MQI password. Please note that only lowercase of the MD5 value is accepted. The merchant transaction ID to be refunded The Skrill transaction ID to be refunded Amount to be refunded Explanation for the refund A comma-separated list of field names that should be passed back to the Merchants server when the refund payment is confirmed (maximum 5 fields).

Y Y

moneybookers@merchant.com 9f535b6ae672f627e4a5f79f2b7c63fe

transaction_id

Y/N

500123

mb_transaction_id amount refund_note

Y/N N N N

4585262 9.99 Product no longer in stock Field1,Field2

merchant_fields

Unclassified

www.skrill.com

Page 18

Automated Payments Interface www.skrill.com

Field 1 Field 2
refund_status_url An example merchant field An example merchant field URL or email address to which updated status should be sent N N N Value1 Value2

Version Date

<2.13> 28 Nov 2012

th

https://www.merchant.com/refund_update.cqi

Please note: The merchant 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 to the customer. XML Server Response The resulting XML will contain a 'response' tag that will contain one of the following elements, depending on the success of the operation: If the authorisation and refund preparation were successful, a 'sid' element containing a session identifier is included that is to be submitted at the next step:
<response> <sid>4504848cb1ed0d29f60458bf992399fd</sid> </response>

If an error occurs, an 'error' element is included with a 'error_msg' child that contains the error message:

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

Error messages
Error message
INVALID_OR_MISSING_ACTION REFUND_DENIED LOGIN_INVALID INVALID_EMAIL CANNOT_LOGIN

Reason
The action parameter is not supplied in the query Refund feature is not activated, refer to 2. Missing email or password parameters. An Invalid email parameter is supplied. Invalid combination of email and password is supplied.

Unclassified

www.skrill.com

Page 19

Automated Payments Interface www.skrill.com Examples Successful authorisation

Version Date

<2.13> 28 Nov 2012

th

Request: GET https://www.moneybookers.com/app/refund.pl?action=prepare&email=moneybookers @merchant.com&password=9f535b6ae672f627e4a5f79f2b7c63fe&transaction_id=50012 3&amount=9.99&refund_note=example_note&refund_status_url=https://www.merchan t.com/refund_update.cqi&merchant_fields=Field1,Field2&Field1=Value1&Field2=V alue2

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

Incorrect request (wrong merchant API/MQI password)

Request: GET

https://www.moneybookers.com/app/refund.pl?action=prepare&email=money bookers@merchant.com&password=9f535b6ae672f627e4a5f79f2b7c64fe&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> <error> <error_msg>CANNOT_LOGIN</error_msg> </error> </response>

Unclassified

www.skrill.com

Page 20

Automated Payments Interface www.skrill.com

Version Date

<2.13> 28 Nov 2012

th

6.2

Execution of the refund

Request parameters
Field
action sid

Description
define second step of the iteration session identifier from the previous step

Required
Y Y

Example
action=refund d831e9072e8b89c57a3654ddf5fcb907

XML Server Response The server will return XML containing a response tag containing some of the following elements, depending on the success of the operation:
Field
mb_amount mb_currency transaction_id mb_transaction_id Field1 Field2 status error

Description
amount refunded in the currency of the merchant's account currency of the merchant's account Merchant transaction ID for refund as submitted in the request The new Skrill transaction ID for refund The first additional field pre-defined in merchant_field_ parameter The second additional field pre-defined in merchant_field parameter If processed we will submit a 2, if pending a 0 and if failed a -2. BALANCE_NOT_ENOUGH CC_REFUND_FAILED RESERVE_EXCEEDED GENERIC_ERROR Refund amount exceeds account balance Refund to a credit/debit card failed Refund amount is blocked by rolling/fixed reserve All errors different from the described above

Example
9.99 EUR 500123 5585262 Value1 Value2 2 CC_REFUND_FAILED

Example Request: GET https://www.moneybookers.com/app/refund.pl?action=refund&sid=d831e9072e8b89c 57a3654ddf5fcb907 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>

Unclassified

www.skrill.com

Page 21

Automated Payments Interface www.skrill.com

Version Date

<2.13> 28 Nov 2012

th

6.3

Status report

If a merchants request for refund cannot be executed at the moment, Skrill will send a response with status 0 pending on the previous step. When Skrill receives an update on the status of the refund, a notification is sent to the refund_status_url submitted by the merchant. If you would like to receive notifications for every status of your refund request, please contact our Merchant Services team. This status report consists of:
Field
transaction_id

Description
Merchant transaction ID for refund as submitted in the request The new Skrill transaction ID for refund If processed we will submit a 2 and if failed a -2. Amount refunded in the currency of the merchant's account Currency of the merchant's account MD5 signature Sha2 signature

Required
Y/N

Example
500123

mb_transaction_id status mb_amount

Y Y Y

5585262 2 9.99

mb_currency md5sig sha2sig

Y Y N*

EUR 9f535b6ae672f627e4a5f79f2b7c63fe dbb7101322257a311f08d1c527053058fc7e464e30bc fb4613f09053c22dd1f8

*For more information, contact merchantservices@skrill.com.com. The md5sig parameter consists of an md5 sum on a string built by concatenating the following parameters:
Value
merchant_id mb_transaction_id MD5 of secret word

Description
The user ID of the merchant's Skrill account The new Skrill transaction ID for refund The uppercase MD5 value of the secret word submitted in the Merchant Tools section of the merchants online Skrill account Amount refunded in the currency of the merchant's account Currency of the merchant's account The defined fields that will be returned back to the Merchants server The first additional field pre-defined in merchant_field_ parameter The second additional field pre-defined in merchant_field parameter The status of the refund transaction

Example
4637827 5585262 327638C253A4637199CEBA6642371F20

mb_amount mb_currency merchant_fields

9.99 EUR Field1,Field2

Field1

Value 1

Field2

Value 2

status

Unclassified

www.skrill.com

Page 22

Automated Payments Interface www.skrill.com

Version Date

<2.13> 28 Nov 2012

th

Email Check Tool

This interface can be used by merchants to query Skrill database if the email of a mutual customer is already registered with Skrill. If registered, merchants can obtain additional information about the customer. If the email is registered and the merchant submits it via the pay_from_email parameter the user will not have to enter a Skrill email address. Using this functionality, merchants can offer Skrill as a preferred payment method for customers whose email addresses exist in Skrill database. The following information can be obtained about a user: Customer ID Account type First and last name Address Date of birth Lock level Verification level

By default the Email Check Tool is not enabled for all merchants. If you would like to use this functionality, please contact merchantservices@skrill.com.com.

7.1

Specification of the Email Check Tool

The merchant must provide the following parameters within HTTPS requests to the following URL: https://www.moneybookers.com/app/email_check.pl

Request Parameters
Field Name Description Required Example Value

Unclassified

www.skrill.com

Page 23

Automated Payments Interface www.skrill.com

Version Date

<2.13> 28 Nov 2012

th

email

The email address of the customer to be checked The customer ID of the merchant account MD5 of the lowercase value of the secret word submitted in the profile of the merchant account. Please note that the MD5 value should also be in lowercase.

Yes

email@host.com

cust_id password

Yes Yes

1234 202cb962ac59075b964b07152d234b70

Response
Response field
Email registration check

Description
Returns OK if the email is registered in Skrill database. If not registered, the system will return a NOK response. Returns the customer ID associated with the email address if registered. Provides information about the account type of the customer. Possible values are: N Normal account T Test account G Gateway account

Example
OK

Customer ID check Account type check

12345678 ACCOUNTTYPE=N

Customer name check

Provides information about the first and last names of the customer. Provides information about the address of the customer. The country of registration of the user is provided in 3-digit ISO Country Codes format. For a complete country codes list, please refer to our Gateway Integration Manual.

FNAME=John LNAME=Payer ADDRESS1=11 Payerstr St ADDRESS2=Payertown CITY=Payertown ZIPCODE=EC45MQ STATE=Central London COUNTRY=GBR DOB=01011976 LOCKLEVEL=NOT_LOCKED

Customer address check

Date of birth check Lock level check

Provides information about the date of birth of the customer in ddmmyyyy format. Provides information about the current lock level of the customer. Possible values are: NOT_LOCKED the customer account is not locked LOCKED the customer account is currently locked

Verification level check

Provides information about the verifications the customer has completed with Skrill. Possible values are: 0 - The customer is not verified 1 The customer has a verified payment method 2 The customer has passed verification checks

VERIFICATIONLEVEL=1

Example

Request:
Unclassified www.skrill.com Page 24

Automated Payments Interface www.skrill.com

Version Date

<2.13> 28 Nov 2012

th

GET:
https://www.moneybookers.com/app/email_check.pl?cust_id=3736166&password=4a46440b496 63212bdc2a9cce492a04f&email=test@skrill.com.com

Response:
OK,12345678,VERIFICATIONLEVEL=1,LOCKLEVEL=NOT ADDRESS2= LOCKED,ADDRESS1=11 Payerstr St, Payertown,CITY=Payertown,ZIPCODE=EC45MQ,STATE=Central London,COUNTRY=GBR,

FNAME=John,LNAME=Payer,ACCOUNTTYPE=N,DOB=01011976

Unclassified

www.skrill.com

Page 25

Automated Payments Interface www.skrill.com

Version Date

<2.13> 28 Nov 2012

th

ANNEX I Error Messages

Errors when validating parameters
Error
INVALID_OR_MISSING_ACTION LOGIN_INVALID INVALID_REC_PAYMENT_ID MISSING_EMAIL MISSING_PASSWORD MISSING_AMOUNT MISSING_CURRENCY MISSING_BNF_EMAIL MISSING_SUBJECT MISSING_NOTE

Resolution
Wrong action or no action is provided Email address and/or password were not provided Invalid recurring payment ID is submitted by the merchant Provide registered email address of merchant account Provide correct API/MQI password Provide amount you wish to send Provide currency you wish to send Provide email address of the beneficiary Provide subject of the payment Provide notes for the payment

Errors during log in

Error
CANNOT_LOGIN

Resolution
Email address and/or API/MQI password are incorrect Check in your account profile that the API is enabled and you are posting your requests from the IP address specified

PAYMENT_DENIED

Errors when validating payment details

Error
INVALID_BNF_EMAIL INVALID_SUBJECT INVALID_NOTE INVALID_FRN_TRN_ID INVALID_AMOUNT INVALID_CURRENCY

Resolution
Check the format of the beneficiary email address Check parameter length submitted Check parameter length submitted Check parameter length submitted Check amount format Check currency code

Unclassified

www.skrill.com

Page 26

Automated Payments Interface www.skrill.com

Version Date

<2.13> 28 Nov 2012

th

Error
EXECUTION_PENDING

Resolution
If you resend a transfer request with the same session identifier before the 'transfer' request was processed, this error will be returned 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 Sending amount exceeds account balance Maximum amount per transaction = EUR 10,000 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 Your account email address needs to be verified Your account is locked for security reasons. Please contact us

ALREADY_EXECUTED

BALANCE_NOT_ENOUGH SINGLE_TRN_LIMIT_VIOLATED

DISALLOWED_RECIPIENT

CHECK_FOR_VERIFIED_EMAIL LL_NO_PAYMENT

Errors when making Skrill 1-Tap payment requests

Error
CUSTOMER_IS_LOCKED BALANCE_NOT_ENOUGH RECIPIENT_LIMIT_EXCEEDED CARD_FAILED REQUEST_FAILED ONDEMAND_CANCELLED ONDEMAND_INVALID

Resolution
The customer's account is locked for outgoing payments The customer's account balance is insufficient The customer's account limits are not sufficient The customer's credit or debit card failed Generic response for transaction failing for any other reason The customer has cancelled this Skrill 1-Tap payment The Skrill 1-Tap payment requested does not exist 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

MAX_REQ_REACHED

Unclassified

www.skrill.com

Page 27