Skrill 1-Tap Payment

Skrill offers a single-click payment service which enables you to automatically debit transactions from your customer's Skrill account without the customer having to authorise the payment each time. Customers are sent an email notification after each 1-Tap payment and they can view the status of all their Skrill 1-Tap payments in the History section of their Skrill Wallet account. Customers can pay using Skrill 1-Tap with any of the following payment methods linked to their Skrill account:

• Credit/debit card (Visa and Mastercard)
• Skrill Balance

Enable the MQI and API

You will need to enable the MQI (Merchant Query Interface) and API (Automated Payment Interface) and set up an MQI/API password to use 1-Tap. You can also change the MQI/API password from the Skrill Business Portal.

To enable the MQI and/or API:

1. Log in to your Skrill account.
2. Go to Settings > Developer Settings > API / MQI / GSR / CVT Management.
3. Set the API / MQI Password, and click Save to confirm.
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:

• A single IP address (e.g. 192.168.0.2)
• Multiple IP addresses, separated by a space (e.g. 192.168.0.2 10.0.0.2)
• A subnet in CIDR notation (e.g. 175.10.10.252/30).

warning

CIDR ranges should be no longer than 256 IP addresses.

note

If the Settings > Developer Settings section is not displayed in your account, contact Skrill Merchant Services.

5. To apply your changes, click Save.

You must use a separate password for 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.

note

The password must be at least 8 characters long and must contain at least one alphabetic and one non-alphabetic character.

The MQI is used for the following functions:

• Repost transaction status information for payment transactions (Wallet Checkout, Quick Checkout, and 1-Tap subsequent payments)
• View transaction status(payment and send money transactions)
• View account history
• Cancel a recurring payment
• View the status of a recurring payment
• Extend the end date of a recurring payment
• Cancel a 1-Tap payment
• View the status of a 1-Tap payment

The API is used for the following functions:

• Refund Quick Checkout, Wallet Checkout, or 1-Tap payments(Note: This functionality is not available for Gambling and FOREX Merchants)
• Transfer money to another Skrill Account
• Take subsequent 1-Tap payments after the initial setup payment

Skrill 1-Tap Button

The Skrill 1-Tap button must be displayed on your website when setting up Skrill 1-Tap mandates and with any subsequent transactions performed through Skrill 1-Tap.

This button is available in different sizes. For details, see:

https://www.skrill.com/en/business/merchants/brand-centre

Call Flows

Initial Payment Request

The following figure provides an overview of the 1-Tap payment set-up process.

1. When the customer is ready to pay for goods or services on your website, they select the payment button on your website.
2. You request a session identifier (SID) by passing customer and transaction details (e.g., amount, currency, and language) to the Skrill Quick Checkout. You also include the required 1-Tap parameters.
3. Skrill returns the generated SID.
4. Redirect the customer to the Skrill Quick Checkout and include the session identifier in the redirect URL. Skrill displays the payment page.

note

We do not support iFrames.

5. The customer pays using the preferred payment method and confirms the transaction.
6. Skrill requests authorisation for the payment from the customer's bank, third party provider, or card issuer.
7. The bank/provider approves or rejects the transaction.
8. Skrill displays the confirmation page, containing the transaction result, on the Skrill Quick Checkout.
9. Skrill provides you with an asynchronous notification, sent to your status URL or IPN (instant Payment Notification), confirming the transaction details and status. These details include the rec_payment_id of the 1-Tap payment, which can be used for future 1-Tap debits from the customer's account.

note

You should keep track of the status of 1-Tap payment and update your records if notified of a status change at the ondemand_status_url you submitted for the 1-Tap payment

Subsequent Payments

The following figure provides an overview of the 1-Tap payment process after the initial setup is complete.

1. The customer clicks the Skrill 1‐Tap button.
2. The merchant checks the status of the 1-Tap mandate using their records or the Merchant Query Interface (MQI).
3. If the customer is already set up for 1-Tap, the merchant makes the prepare request. Both frn_trn_id and rec_payment_id should be provided.

note

If the customer is not set up for 1-Tap, then the merchant makes a normal Quick Checkout payment request and optionally submits 1-Tap payment details to set up the 1-Tap service, as described previously in Initial Skrill 1-Tap payment flow.

4. The Skrill 1-Tap Payment Interface returns the session identifier (SID).
5. The merchant sends the execution request with the returned SID.
6. The Skrill 1-Tap Payment Interface validates the request.
7. Skrill requests authorisation for the payment from the customer's bank, third party provider, or card issuer (if required).
8. The bank/provider approves or rejects the transaction.
9. The Skrill 1-Tap Payment interface sends a response with the transaction status.
10. The transaction status notification is also posted to the merchant's status URL.
11. The merchant notifies the customer of the status of the 1-Tap payment.

In addition to the standard parameters described in Skrill Quick Checkout parameters, you can supply the following parameters to set up a Skrill 1-Tap payment via the Skrill Wallet Checkout:

Field name	Description	Required	Max length	Example value
ondemand_max_amount	Maximum amount for future payments that will be debited from the customer's account	Yes	9	11.50
ondemand_max_currency	3-letter code of the currency of the maximum amount according to ISO 4217 (see ISO 4217 currencies)	Yes/No	3	EUR
ondemand_note	Text shown to the customer in the payment confirmation email as the reason for the Skrill 1-Tap payment.	Yes	1000	credit topped up
ondemand_status_url	URL to which Skrill notifies you that the Skrill 1-Tap payment is cancelled. This URL is restricted to the same ports as the status_url	No	400	http://www.example.com/od_payment_cancelled.html
ondemand_status_url2	URL to which Skrill notifies you that the Skrill 1-Tap payment is cancelled. This URL is restricted to the same ports as the status_url	No	400	http://www.example.com/od_payment_cancelled2.html

note

• If ondemand_max_currency is not provided, the currency value will be the one provided as the currency in the standard HTML form (see Skrill Quick Checkout parameters).
• A session identifier (SID) parameter is returned upon success.
• The Skrill response includes a rec_payment_id. You should store the rec_payment_id field so that you can reference the original 1-Tap transaction.
• You can track the status of any 1-Tap transaction and perform refunds using your own unique transaction_id for that transaction.

Example of a Skrill 1‐Tap payment form

See the example below. The included 1-Tap payment fields are highlighted.

<form action="https://pay.skrill.com" method="post" target="_blank">
  <input type="hidden" name="pay_to_email" value="demowallet@sun-fish.com" />
  <input type="hidden" name="status_url" value="https://www.example.com/status" />
  <input type="hidden" name="language" value="EN" />
  <input type="hidden" name="amount" value="39.60" />
  <input type="hidden" name="currency" value="GBP" />
  <input type="hidden" name="detail1_description" value="Description:" />
  <input type="hidden" name="detail1_text" value="Romeo and Juliet" />
  <input type="hidden" name="recipient_description" value="ACME Solutions" />
  <input type="hidden" name="ondemand_max_amount" value="150.00" />
  <input type="hidden" name="ondemand_max_currency" value="EUR" />
  <input type="hidden" name="ondemand_note" value="Your 1-Tap Payment" />
  <input type="hidden" name="ondemand_status_url" value="www.example.com/ondemandstatus1" />
  <input type="hidden" name="ondemand_status_url2" value="www.example.com/ondemandstatus2" />
  <input type="submit" value="Pay!" />
</form>

Taking Subsequent 1‐Tap Payments

Once a Skrill 1-Tap payment has been set up, you must use the Skrill 1-Tap Payment Interface (part of Skrill's Automated Payment Interface) to make individual requests to debit the customer's Skrill account. If you have provided a status_url value in your HTML form, Skrill will post the transaction details of each payment to that URL.

Connecting to the 1‐Tap interface

You can connect to the Skrill 1-Tap interface by sending HTTPS GET/POST requests to:

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

note

• You must enable the Skrill Automated Payment Interface (API) and setup an MQI/API password
• Skrill recommend using POST for maximum security.
• Do not mix GET and POST requests. Choose which method to use and apply consistently.
• POST parameters are encoded using Content-Type: application/x-www-form-urlencoded
• GET parameters are encoded in the URI query string using & delimiters(e.g. GET parameters are sent as part of the URL query string https://www.skrill.com/app/query.pl?action=status_trn&email=mb654@abv.bg&password=53903d217504eb37f3fdb0ce77610558&mb_trn_id=104627261)

Taking subsequent 1-Tap Payments is a two-step process:

1. Send a first request with action set to prepare to receive a session ID for step 2
2. Send a second request with action set to request using the session ID from step 1 to execute the payment.

These steps are described in more detail below.

Executing a Subsequent 1-Tap Payment Preparation Request

This action prepares the transaction that will be executed later using the request action. The following parameters are required:

Field name	Description	Required	Example value
action	The required action	Yes	prepare
email	The email address linked to your Skrill account	Yes	info@example.com
password	The lowercase hex MD5 of your API/MQI password	Yes	9f535b6ae672f627e4e5f79f2b7c63fe
amount	The amount of the request for a debit transaction	Yes	10.50
currency	3-letter code of the currency you wish to debit according to ISO 4217	Yes	EUR
ondemand_note	Text shown to the customer in the payment confirmation email as the reason for the Skrill 1-Tap payment	No	Credit topped up
frn_trn_id	Your transaction ID, used for the payment. This is your own unique reference for this transaction	Yes	A205220
rec_payment_id	Recurring payment ID (rec_payment_id value) sent to your status_url page when you created the Skrill 1-Tap payment	Yes	200005
merchant_fields	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)	No	Field1, Field2
Field1	An additional field you can include, containing your own unique parameters.	No	Value1
Field2	An additional field you can include, containing your own unique parameters.	No	Value2

note

• 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.

Response: Skrill returns an XML response to your prepare request which contains a 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.
• <error> element- included if an error occurs. It includes an tag, which contains the error message description.

Example 1: Successful preparation request

Below is an example of a successful prepare request.

Request:

curl -X POST https://www.skrill.com/app/ondemand_request.pl \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "email=sample.merchant%40sunfish.com" \
  -d "password=fb0dc09bd0989fe975afd3e4ddabb926" \
  -d "action=prepare" \
  -d "amount=1.23" \
  -d "currency=EUR" \
  -d "ondemand_note=ondemand note" \
  -d "frn_trn_id=12341990" \
  -d "rec_payment_id=1668618647"

Response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <sid>4414c2a969c744c27bd674a0b0a5ba8a</sid>
</response>

Example 2: Failed prepare request

This example shows a request that failed, due to an invalid merchant email.

Request:

curl -X POST https://www.skrill.com/app/ondemand_request.pl \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "email=" \
  -d "password=fb0dc09bd0989fe975afd3e4ddabb926" \
  -d "action=prepare" \
  -d "amount=1.23" \
  -d "currency=EUR" \
  -d "ondemand_note=ondemand note" \
  -d "frn_trn_id=12341990" \
  -d "rec_payment_id=1668618647"

Response:

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

General errors:

Error	Description
SESSION_EXPIRED	The session has expired. Session IDs are only valid for 15 minutes.

Errors when making Skrill 1‐Tap payment requests:

Error	Description
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 insufficient
CARD_FAILED	The customer's credit or debit card failed
REQUEST_FAILED	A generic response for the 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
MAX_AMOUNT_REACHED	The payment amount is greater than the maximum amount configured when 1-Tap payments were set up for this user.

Errors when validating parameters:

Error	Description
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

Executing a Subsequent 1-Tap Payment Request

Now that you have received a session ID you can execute the actual payment transaction using the request action. The URL is the same as before. The following parameters are required:

Field name	Description	Required	Example value
action	The required action (i.e., prepare).	Yes	request
sid	Session identifier returned in response to the prepare request.	Yes	7783bfa23641a627e4a5f79f2b7c6

Upon success, Skrill 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 currency code of the amount, according to ISO 4217	EUR
id	Transaction ID	500123
status	Skrill 1-Tap payment status: 2 – processed, -2 – failed	2
status_msg	Text description of the status	processed

note

• If a request fails, you are not allowed to make more than two requests for a debit of a customer's 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.

Example 1: Successful request

Below is an example of a successful request.

Request:

curl -X POST https://www.skrill.com/app/ondemand_request.pl \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "sid=84034fe3e5c9f6ef54e51efbbe9f2767" \
  -d "action=request"

Response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <transaction>
    <amount>10.34</amount>
    <currency>EUR</currency>
    <id>1668624876</id>
    <status>2</status>
    <status_msg>processed</status_msg>
  </transaction>
</response>

Example 2: Failed request

This example shows a request that failed, due to an expired session ID.

Request:

curl -X POST https://www.skrill.com/app/ondemand_request.pl \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "sid=123" \
  -d "action=request"

Response:

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

Checking or cancelling 1‐Tap payments

You can use the MerchantQuery Interface (MQI) to review the status of a 1-Tap payment or to cancel it so that no more 1-Tap payments can be taken.

You can access the MQI by posting an HTTPS GET/POST query to: https://www.skrill.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 the Additional Parameters table for each action below)

Field name	Description	Required	Example value
action	The required action (i.e., prepare).	Yes	request
email	The email address linked to your Skrill account	Yes	info@example.com
password	The lowercase hex MD5 of your API/MQI password	Yes	9f535b6ae672f627e4e5f79f2b7c63fe
amount	The amount of the request for a debit transaction	Yes	10.50

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

Request:

curl -X POST https://www.skrill.com/app/query.pl \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "action=cancel_od" \
  -d "email=info@example.com" \
  -d "password=9f535b6ae672f627e4a5f79f2b7c63fe" \
  -d "trn_id=500123"

Response:

200 OK

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 1: Check status of a cancelled 1‐Tap payment

Request:

curl -X POST https://www.skrill.com/app/query.pl \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "action=status_od" \
  -d "email=info@example.com" \
  -d "password=9f535b6ae672f627e4a5f79f2b7c63fe" \
  -d "trn_id=500123"

Response:

200 OK

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

Example 2: Check status of an active 1‐Tap payment with invalid transaction

Request:

curl -X POST https://www.skrill.com/app/query.pl \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "action=status_od" \
  -d "email=info@example.com" \
  -d "password=9f535b6ae672f627e4a5f79f2b7c63fe" \
  -d "trn_id=500123"

Response:

403 Transaction not found: 123

MQI Error Messages

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

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.