Refunds
You can use the Automated Payments Interface to make automated partial or full refunds to customers, up to the amount of the original payment.
You must send your HTTPS refund request to the following URL:
https://www.skrill.com/app/refund.pl
The refund is made in two steps:
- Preparation of the refund
- Execution of the refund
Executing a Refund Preparation request
The following parameters must be included in the refund prepare request:
| Field | Description | Required | Example |
|---|---|---|---|
action | Defines the prepare step of the refund request. | Yes | action=prepare |
email | Your email address. | Yes | info@merchant.com |
password | The MD5 of your API/MQI password. Note: only the lower-case of the MD5 value is accepted. | Yes | 9f535b6ae672f627e4a5f79f2b7c63fe |
transaction_id | Your transaction ID to be refunded. | Yes/No * | 500123 |
mb_transaction_id | The Skrill transaction ID to be refunded. | Yes/No * | 4585262 |
amount | Amount to refund in the currency used by the merchant account. This field is only used for partial refunds. | No | 9.99 |
refund_note | Refund note sent to the customer. This note forms part of the email sent to the customer to inform them that they have received a 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). | 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 |
refund_status_url | URL or email address to which status updates should be sent. The following ports can be used for this URL: 80, 81, 82, 83, 88, 90, 178, 419, 433, 443, 444, 448, 451, 666, 800, 888, 1025, 1430, 1680, 1888, 1916, 1985, 2006, 2221, 3000, 4111, 4121, 4423, 4440, 4441, 4442, 4443, 4450, 4451, 4455, 4567, 5443, 5507, 5653, 5654, 5656, 5678, 6500, 7000, 7001, 7022, 7102, 7777, 7878, 8000, 8001, 8002, 8011, 8014, 8015, 8016, 8027, 8070, 8080, 8081, 8082, 8085, 8086, 8088, 8090, 8097, 8180, 8181, 8443, 8449, 8680, 8843, 8888, 8989, 9006, 9088, 9443, 9797, 10088, 10443, 12312, 18049, 18079, 18080, 18090, 18443, 20202, 20600, 20601, 20603, 20607, 20611, 21301, 22240, 26004, 27040, 28080, 30080, 37208, 37906, 40002, 40005, 40080, 50001, 60080, 60443 | No | https://www.merchant.com/refund_update.cqi |
* 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.
Response
The resulting XML contains a <response> element with one of the following elements, depending on the success of the operation:
<sid>- Session ID element – returned if the prepare request is successful. It must be submitted with the refund action in the next step<error>element – returned if an error occurs. Contains an<error_msg>element containing the error message
Example 1: Successful Refund Preparation
Request:
curl --location 'https://www.skrill.com/app/refund.pl' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'action=prepare' \
--data-urlencode 'email=info@merchant.com' \
--data-urlencode 'password=9f535b6ae672f627e4a5f79f2b7c63fe' \
--data-urlencode 'transaction_id=500123' \
--data-urlencode 'amount=9.99' \
--data-urlencode 'refund_note=example_note' \
--data-urlencode 'refund_status_url=https://www.merchant.com/refund_update.cqi' \
--data-urlencode 'merchant_fields=Field1,Field2' \
--data-urlencode 'Field1=Value1' \
--data-urlencode 'Field2=Value2'
Response:
<response>
<sid>d831e9072e8b89c57a3654ddf5fcb907</sid>
</response>
Example 2: Failed Refund Preparation
Request:
curl --location 'https://www.skrill.com/app/refund.pl' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'action=prepare' \
--data-urlencode 'email=info@merchant.com' \
--data-urlencode 'password=9f535b6ae672f627e4a5f79f2b7c64fe' \
--data-urlencode 'transaction_id=500123' \
--data-urlencode 'amount=9.99' \
--data-urlencode 'refund_note=example_note' \
--data-urlencode 'refund_status_url=https://www.merchant.com/refund_update.cqi' \
--data-urlencode 'merchant_fields=Field1,Field2' \
--data-urlencode 'Field1=Value1' \
--data-urlencode 'Field2=Value2'
Response:
<response>
<error>
<error_msg>CANNOT_LOGIN</error_msg>
</error>
</response>
Error Messages
See the table below for details of error messages.
| Error message | Description |
|---|---|
CANNOT_LOGIN | Invalid combination of email and password is supplied. |
INVALID_EMAIL | An Invalid email parameter is supplied. |
INVALID_OR_MISSING_ACTION | The action parameter is not supplied in the query. |
LOGIN_INVALID | Missing email or password parameters. |
NO_LOGIN_EXPLANATION | Merchant using non-existent email address. |
REFUND_DENIED | Refund feature is not activated. |
Executing a Refund Request
The following parameters must be included in the refund execution request:
| Field | Description | Required | Example |
|---|---|---|---|
action | Defines the execution step of the refund request. | Yes | refund |
sid | Session identifier returned in response to the prepare request. | Yes | d831e9072e8b89c57a3654ddf5fcb907 |
Response
The server returns XML containing a <response> element, which includes some of the following elements, depending on the success of the operation:
| Element | Description | Example |
|---|---|---|
mb_amount | Amount refunded in the currency of your Skrill account. | 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_fields parameter | Value1 |
Field2 | The second additional field pre-defined in merchant_fields parameter | Value2 |
status | 2 = processed, 0 = pending, -2 = failed. | 2 |
error | Error codes and their meanings: BALANCE_NOT_ENOUGH (exceeds balance), CC_REFUND_FAILED (card fail), RESERVE_EXCEEDED (blocked by reserve), GENERIC_ERROR (other errors or already refunded). | CC_REFUND_ FAILED |
Example: Successful Refund
Request:
curl --location 'https://www.skrill.com/app/refund.pl' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'action=refund' \
--data-urlencode '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>
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:
| Field | Description | Required | Example |
|---|---|---|---|
transaction_id | Your transaction ID for the refund as submitted in the request. | Yes/No | 500123 |
mb_transaction_id | The Skrill transaction ID for the refund. | Yes | 5585262 |
status | 2 = processed, -2 = failed. | Yes | 2 |
mb_amount | Amount refunded in the currency of your Skrill account. | Yes | 9.99 |
mb_currency | Currency of your Skrill account. | Yes | EUR |
md5sig | Upper-case MD5 signature. See MD5 signature below. | Yes | 9F535B6AE672F627E4A5F79F2B7C63FE |
sha2sig | Upper-case SHA2 signature. This is constructed in the same way as the MD5 signature, but with a different hashing algorithm. This parameter is not available by default. To enable this option, send a request to merchantservices@skrill.com | No | DBB7101322257A311F08D1C527053058FC7E464E30BCFB4613F09053C22DD1F8 |
MD5 Signature
The md5sig parameter consists of an MD5 sum on a string built by concatenating the following parameters and converting the result to upper-case.
| Field | Description | Example |
|---|---|---|
merchant_id | Your Skrill account user ID. | 4637827 |
mb_transaction_id | The new Skrill transaction ID for refund. | 5585262 |
MD5 of secret word | The upper-case MD5 value of the secret word submitted in the Settings > Developer Settings section of your Skrill account. | 327638C253A4637199CEBA6642371F20 |
mb_amount | Amount refunded in the currency of your account. | 9.99 |
mb_currency | Currency of your account. | EUR |
status | The status of the refund transaction. | 2 |
Example
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 the table above, the following MD5 code is returned: CF9DCA614656D19772ECAB978A56866D.