Preparation Request

The preparation request or session initiation call is used to validate several aspects of the payment before making the actual payment. Key validations are authorization and authentication from the merchant initiating the payment. Another key validation is the correctness of the passed payment parameters. Do note that different countries or regions support or require different sets of parameters to be provided. The preparation call validates those criteria.

See Preparation Response for response parameters and error messages.

note

Set your response timeout to 30 seconds for the Preparation Request.

URL: POST https://pay.skrill.com/json Content-Type: application/json

Preparation request parameters

Name	Required	Format	Description
action	Yes	enumerated value [PAYOUT]	The action of the request. Currently, only PAYOUT is supported.
instrument_type	Yes	enumerated value [BANK]	Type of payout payment. Currently, only BANK is supported.
prepare_only	Yes	number, enumerated value [0, 1]	Currently, the only supported value is 1. 0 is reserved for future use.
amount	Yes	floating point numeric	Requested amount to be transferred (e.g. 20 / 20.50). Take in mind the Payout Limits.
currency	Yes	3-letter currency code	3-letter code of the currency of the amount according to ISO 4217.
transaction_id	Yes	string (max length 100)	Unique reference or identification number for the payout in your (the merchant) system. Must be unique for each payment.
payment_description	Yes	string (max length 200)	Purpose of the payout.
pay_from_email	Yes	email	The processing email of your Skrill merchant wallet.
merchant_id	No	numeric	Unique ID of your Skrill wallet.
merchant_client_id	Yes	string (max length 512)	Unique ID that you (the merchant) use to identify the individual or business in your system (i.e. customer ID). If you are sending to a payee who has no account with you, input 000000000.
merchant_client_registration_date	No	string (ISO 8601 Date format)	The date that this consumer registered their account, or started their relationship with, this merchant. ISO 8601 (with time zone). Examples: YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss.sss
merchant_client_kyc_level	No	number, enumerated value [0, 1]	Indicate whether you (the merchant) have done KYC or KYB using legal documents (e.g. passport, driving license). 0 – not verified; 1 – verified with documents
merchant_client_registration_country	No	string (3-letter ISO-3166 code)	The country where you registered the payee.
firstname	Yes	string (max length 50)	For payouts to Individuals: Payee's first name. For payouts to corporates: Company Name
lastname	Yes	string (max length 50)	For payouts to Individuals: Payee's last name. For payouts to corporates: The rest of the company name includes the entity legal form code e.g. Ltd.
date_of_birth	No/Yes ****	string (ddMMyyyy format)	Example: 25011999 (Day-Month-Year with no separators). Not relevant when sending to a corporate account.
phone_number	No	string (only numeric characters, max length 50)	Payee's phone number
country	Yes	string (3-letter ISO-3166 code)	Payee's country 3-letter ISO-3166 code (e.g. GBR)
state	No	string (max length 50)	Payee's country state for countries that have states or regions (e.g. Central London)
city	No/Yes ***	string (max length 40)	Payee's city (e.g. Paris)
address	Yes	string (max length 800)	Payee's address
postal_code	No/Yes ***	string (max length 10)	Payee's postal (zip) code
recipient_type	Yes	enumerated value [INDIVIDUAL, CORPORATE]	Parameter denoting whether the payment recipient is an INDIVIDUAL or CORPORATE.
sign	Yes	string	Security checksum ensuring that the sender of the request is you (the merchant). See SIGN parameter calculation.
pay_to_email	Yes	email (max length 100)	Payee's email address
account_num	No/Yes *	string (max length 50)	Payee's bank account number (reserved field for Non-IBAN countries)
bank_code	No/Yes *	string (max length depends on country)	Payee's bank code required for some countries. UK – the sort code of the recipient bank.
iban	No/Yes *	string (max length 34)	Payee's IBAN
swift	No/Yes *	string (max length 11)	Payee's bank SWIFT code
instrument_token	No/Yes **	UUID string (exactly 36)	A UUID representing the payout instrument token id for subsequent payouts without payment instrument, payee or merchant client fields. Can be used only when the initial payout was processed and settled.
instrument_country	Yes	string (3-letter ISO-3166 code)	3-letter ISO-3166 code of the country in which the bank account of the payee is located (e.g. GBR)
status_url	No	string (max length 400)	URL to which the transaction details are posted after the payout status update. Alternatively, payout status can be acquired by a separate call to the Skrill Merchant Query Interface
status_url2	No	string (max length 400)	Secondary URL to which the transaction details are posted after the payout status update.
merchant_fields	No	string (max length 240)	A comma-separated list of field names passed back to your status URL when status notification is sent.

info

* Mandatory bank fields depending on the bank instrument country. See Mandatory Bank Fields Per Country.

** Required when using a payment instrument token to make a subsequent payout with fewer fields.

*** Mandatory for EU countries and UK (city, postal_code).

**** Mandatory for EU countries (date_of_birth).

Example preparation request

POST https://pay.skrill.com/json
Content-Type: application/json

{
  "action": "payout",
  "instrument_type": "BANK",
  "prepare_only": 1,
  "amount": "20.45",
  "currency": "GBP",
  "pay_from_email": "merchant_email@mail.com",
  "pay_to_email": "payee1@mail.com",
  "merchant_id": "1234567890",
  "transaction_id": "merchant_ref_id",
  "payment_description": "merchant payment description",
  "account_num": "9876543",
  "bank_code": "200052",
  "instrument_country": "GBR",
  "firstname": "fname",
  "lastname": "lname",
  "date_of_birth": "25101999",
  "address": "address",
  "city": "London",
  "postal_code": "E18RU",
  "country": "GBR",
  "recipient_type": "INDIVIDUAL",
  "merchant_client_id": "1241",
  "merchant_client_kyc_level": "1",
  "merchant_client_registration_country": "GBR",
  "merchant_client_registration_date": "2016-08-22T14:30+02:00",
  "status_url": "https://your.webhook.site",
  "sign": "ad34df771d38ba82c4f271115675a6c1ffa5642527a50045b8614f57e186f813"
}

Example preparation request with instrument token

POST https://pay.skrill.com/json
Content-Type: application/json

{
  "action": "payout",
  "instrument_type": "BANK",
  "prepare_only": 1,
  "amount": "20.45",
  "currency": "GBP",
  "pay_from_email": "merchant_email@mail.com",
  "pay_to_email": "payee1@mail.com",
  "merchant_id": "1234567890",
  "transaction_id": "merchant_ref_id",
  "payment_description": "merchant payment description",
  "status_url": "https://your.webhook.site",
  "instrument_token": "fc71683d-efa6-4ffc-a81d-2b7eaee38f75",
  "sign": "ad34df771d38ba82c4f271115675a6c1ffa5642527a50045b8614f57e186f813"
}