S2S

SALE request POST

Payment Platform supports only Dual Message System (DMS) operation type.

DMS used to hold the funds on card account (for example to check card validity).

This request is sent by POST in the background (e.g. through PHP CURL).

All requests are with Content-Type: multipart/form-data.

Endpoint

POST https://api.switcherepay.com/post

Parameters

Name	Type	Description
action required	string	SALE.
client_key required	UUID	Unique key (client_key).
order_id required	string(255)	Transaction ID in the Merchants system.
order_amount required	float	The amount of the transaction.
order_currency required	currency	Currency.
order_description required	string(1024)	Description of the transaction (product name). More information about this field can be found below.
req_token	Y or N (default N)	Special attribute pointing for further tokenization
card_token	string(64)	Credit card token value.
card_number optional	string	Card number. Fields card_number, card_exp_month, card_exp_year are optional if card_token is specified.
card_exp_month optional	string	Month in the form XX. Fields card_number, card_exp_month, card_exp_year are optional if card_token is specified.
card_exp_year optional	string	Year in the form XXXX. Fields card_number, card_exp_month, card_exp_year are optional if card_token is specified.
card_cvv2 required	CVV/CVC2	CVV/CVC2 credit card verification code.
payer_first_name required	string(32)	Customer's name.
payer_last_name required	string(32)	Customer's surname.
payer_middle_name	string(32)	Customer's middle name.
payer_birth_date required	string	Customer's birthday in format yyyy-MM-dd, e.g. 1970-02-17.
payer_address required	string(255)	Customer's address.
payer_address2	string(255)	The adjoining road or locality (if required) of the сustomer's address.
payer_house_number	string(9)	Customer's house or building number.
payer_country required	country code	Customer's country.
payer_state required	string(32)	Customer's state.
payer_city required	string(40)	Customer's city.
payer_district	string(32)	Customer's district of city.
payer_zip required	string(10)	ZIP-code of the Customer.
payer_email required	string(256)	Customer's email.
payer_phone required	string(32)	Customer's phone.
payer_ip required	IP	IP-address of the Customer. Both versions, IPv4 and IPv6, can be used. If you are sending IPv6, make sure the payment provider that processes the payments supports it.
term_url_3ds required	string(1024)	Order status page https://host/paystatus/client_key/order_id/. Use sandbox.switchere.com host for sandbox and swtchrpay.com host for production.
term_url_target	string(1024)	Name of, or keyword for a browsing context where Customer should be returned according to HTML specification. Possible values: _blank, _self, _parent, _top or custom iframe name (default _top).
hash	string	Special signature to validate your request to Payment Platform. More information about this field can be found below.

Tip: order_description description

The parameter should use this pattern: CID:PARTNER-CLIENT-ID-0001.

• CID - is your external client ID, it is only required if the client's email may be changed in the future.

Tip: Generate hash

if parameter card_number is specified hash is calculated by the formula: md5(strtoupper(strrev(email).PASSWORD.strrev(substr(card_number,0,6).substr(card_number,-4))))

if parameter card_token is specified hash is calculated by the formula: md5(strtoupper(strrev(email).PASSWORD.strrev(card_token)))

Response parameters

You will get JSON encoded string with transaction result. If your account supports 3D-Secure, transaction result will be sent to your Notification URL.

Successful sale response

Name	Type	Description
action	string	SALE.
result	string	SUCCESS.
status	string	PENDING.
order_id	string	Transaction ID in the Merchant's system.
trans_id	string	Transaction ID in the Payment Platform.
trans_date	date	Transaction date in the Payment Platform.
descriptor	string	Descriptor from the bank, the same as cardholder will see in the bank statement.
card_token	string	If the parameter req_token was enabled Payment Platform returns the token value.
amount	float	Order amount.
currency	currency	Currency.

Tip: Field parameters info

• currency

Unsuccessful sale response

Name	Type	Description
action	string	SALE.
result	string	DECLINED.
status	string	DECLINED.
order_id	string	Transaction ID in the Merchant's system.
trans_id	string	Transaction ID in the Payment Platform.
trans_date	date	Transaction date in the Payment Platform.
descriptor	string	Descriptor from the bank, the same as cardholder will see in the bank statement.
amount	float	Order amount.
currency	currency	Currency.
decline_reason	string	The reason why the transaction was declined.

Tip: Field parameters info

• currency

3D-Secure transaction response

Name	Type	Description
action	string	SALE.
result	string	REDIRECT.
status	string	3DS/REDIRECT.
order_id	string	Transaction ID in the Merchant's system.
trans_id	string	Transaction ID in the Payment Platform.
trans_date	date	Transaction date in the Payment Platform.
descriptor	string	Descriptor from the bank, the same as cardholder will see in the bank statement.
amount	float	Order amount.
currency	currency	Currency.
redirect_url	string	URL to which the Merchant should redirect the Customer.
redirect_params	string	Object of specific 3DS parameters. It is array if redirect_params have no data. The availability of the redirect_params depends on the data transmitted by the acquirer. redirect_params may be missing. It usually happens when redirect_method = GET.
redirect_method	string	The method of transferring parameters (POST / GET).

Tip: Field parameters info

• currency

CREDITVOID request POST

CREDITVOID request is used to return funds to the card

Endpoint

POST https://api.switcherepay.com/post

Parameters

Name	Type	Description
action required	string	CREDITVOID.
client_key required	UUID	Unique key (client_key).
trans_id required	UUID	Transaction ID in the Payment Platform.
amount	float	The amount of full or partial refund. If amount is not specified, full refund will be issued. In case of partial refund this parameter is required. Several partial refunds are allowed.
hash required	string	Special signature to validate your request to Payment Platform.

Tip: Generate hash

hash is calculated by the formula:

md5(strtoupper(strrev(email).PASSWORD.trans_id.strrev(substr(card_number,0,6).substr(card_number,-4))))

Response parameters

You will get JSON encoded string with transaction result.

Successful response

Name	Type	Description
action	string	CREDITVOID.
result	string	ACCEPTED.
order_id	string	Transaction ID in the Merchant's system.
trans_id	string	Transaction ID in the Payment Platform.

Tip: Field parameters info

• currency

Testing

Card number	Card expiration date (MM/YYYY)	Testing / Result
4111111111111111	01/2025	This card number and card expiration date must be used for testing successful SALE. Response: {action: SALE, result: SUCCESS, status: PENDING}
4111111111111111	02/2025	This card number and card expiration date must be used for testing unsuccessful SALE. Response: {action: SALE, result: DECLINED, status: DECLINED}
4111111111111111	03/2025	This card number and card expiration date must be used for testing unsuccessful CAPTURE after successful SALE. Response: {action: SALE, result: SUCCESS, status: PENDING}
4111111111111111	05/2025	This card number and card expiration date must be used for testing successful SALE after 3DS verification. Response: {action: SALE, result: REDIRECT, status: 3DS}
4111111111111111	06/2025	This card number and card expiration date must be used for testing unsuccessful SALE after 3DS verification. Response: {action: SALE, result: REDIRECT, status: 3DS}
4111111111111111	12/2025	This card number and card expiration date must be used for testing successful SALE after redirect. Response: {action: SALE, result: REDIRECT, status: REDIRECT}
4111111111111111	12/2026	This card number and card expiration date must be used for testing unsuccessful SALE after redirect. Response: {action: SALE, result: REDIRECT, status: REDIRECT}

Examples

SALE request sample

Sample data of the sale request

Parameter	Valid value
action	SALE
client_key	c2b8fb04-110f-11ea-bcd3-0242c0a85004
order_id	ORDER-12345
order_amount	1.99
order_currency	USD
order_description	Product
card_number	4111111111111111
card_exp_month	01
card_exp_year	2025
card_cvv2	000
payer_first_name	John
payer_last_name	Doe
payer_birth_date	1970-02-17
payer_address	Big street
payer_country	US
payer_state	CA
payer_city	City
payer_zip	123456
payer_email	[email protected]
payer_phone	199999999
payer_ip	123.123.123.123
term_url_3ds	https://swtchrpay.com/paystatus/c2b8fb04-110f-11ea-bcd3-0242c0a85004/ORDER-12345/
hash	2702ae0c4f99506dc29b5615ba9ee3c0

The hash above was calculated for PASSWORD equal to13a4822c5907ed235f3a068c76184fc3.

Sample request

curl -X POST --data 'action=SALE&client_key=c2b8fb04-110f-11ea-bcd3-0242c0a85004&order_id=ORDER-12345&order_amount=1.99&order_currency=USD&order_description=Product&card_number=4111111111111111&card_exp_month=01&card_exp_year=2025&card_cvv2=000&&payer_first_name=John&payer_last_name=Doe&payer_address=Big street&payer_birth_date=1970-02-17&payer_country=US&payer_state=CA&payer_city=City&payer_zip=123456&[email protected]&payer_phone=199999999&payer_ip=123.123.123.123&term_url_3ds=https://swtchrpay.com/paystatus/c2b8fb04-110f-11ea-bcd3-0242c0a85004/ORDER-12345/&hash=2702ae0c4f99506dc29b5615ba9ee3c0' https://api.switcherepay.com/post

Response

Successful response sample

{
  "action":"SALE",
  "result":"SUCCESS",
  "status":"SETTLED",
  "order_id":"ORDER-12345",
  "trans_id":"aaaff66a-904f-11ea-833e-0242ac1f0007",
  "trans_date":"2012-04-03 16:02:01",
  "descriptor":"test",
  "amount":"0.02",
  "currency":"USD"
}

Unsuccessful response sample

{
  "action":"SALE",
  "result":"DECLINED",
  "status":"DECLINED",
  "order_id":"ORDER-12345",
  "trans_id":"aaaff66a-904f-11ea-833e-0242ac1f0007",
  "trans_date":"2012-04-03 16:02:01",
  "decline_reason":"Declined by processing"
}

The response if the transaction supports 3D-Secure

{
  "action":"SALE",
  "result":"REDIRECT",
  "status":"3DS",
  "order_id":"1588856266Intelligent",
  "trans_id":"595ceeea-9062-11ea-aa1b-0242ac1f0007",
  "trans_date":"2012-04-03 16:02:01",
  "descriptor":"Descriptor",
  "amount":"0.02",
  "currency":"USD",
  "redirect_url":"https://some.acs.endpoint.com",
  "redirect_params":
      {
      "PaReq":"M0RTIE1hc3RlciBVU0QgU1VDQ0VTUw==",
      "MD":"595ceeea-9062-11ea-aa1b-0242ac1f0007",
      "TermUrl":"https://192.168.0.1:8101/verify/3ds/595ceeea-9062-11ea-aa1b-0242ac1f0007/7d6b9b240ff2779b7209aef786f808d1"
      },
  "redirect_method":"POST"
}

In case of redirect_params is empty

{
  "action":"SALE",
  "result":"REDIRECT",
  "status":"3DS",
  "order_id":"1588856266Intelligent",
  "trans_id":"595ceeea-9062-11ea-aa1b-0242ac1f0007",
  "trans_date":"2012-04-03 16:02:01",
  "descriptor":"Descriptor",
  "amount":"0.02",
  "currency":"USD",
  "redirect_url":"https://some.acs.endpoint.com",
  "redirect_params":[],
  "redirect_method":"POST"
}

In case of an error

{
  "result":"ERROR",
  "error_message":"Error description"
}

3DS features

If your account supports 3D-Secure and credit card supports 3D-Secure, then Payment Platform will return the link to the 3D-Secure Access Control Server to perform 3D-Secure verification. In this case, you need to redirect the cardholder at this link. If there are also some parameters except the link in the result, you will need to redirect the cardholder at this link together with the parameters using the method of data transmitting indicated in the same result.

In the case of 3D-Secure after verification on the side of the 3D-Secure server, the owner of a credit card will come back to your site using the link you specify in the sale request.

⚠️ NOTE:

As per our API for any 3DS transaction after request, we send to merchant response with:

• redirect_url - URL to which the Merchant should redirect the Customer
• redirect_params - Object of specific 3DS parameters. It is an array if redirect_params have no data. The availability of the redirect_params depends on the data transmitted by the acquirer. Redirect_params may be missing. It usually happens when redirect_method = GET (or others).
• redirect_method - The method of transferring parameters (POST or GET) Redirect_params is a value that depends on any particular acquirer. Possible redirect_params: PaReq, TermUrl, and many other multiple values. Each acquirer can send values in different ways and our interface is unified to be able to process redirects to all versions of 3DS and redirection regardless of the acquirer.

Our API states that the merchant has to take mentioned parameters as is and redirect users with them, no need to parse them, split them, or divide them.

e.g. in this case, you would simply POST that string AS IS to the redirect_url:

Sample response

{
  "action": "SALE",
  "amount": "0.02",
  "currency": "USD",
  "order_id": "1588856266Intelligent",
  "redirect_method": "POST",
  "redirect_params": {
    "body": "NHV2MEdQVGk2TzNNWUU4....................WUJlazNBVW1udFE9PQ=="
  },
  "redirect_url": "https://checkout.switcherepay.com/collector/595ceeea-9062-11ea-aa1b-0242ac1f0007",
  "result": "REDIRECT",
  "status": "REDIRECT",
  "trans_date": "2012-04-03 16:02:01",
  "trans_id": "595ceeea-9062-11ea-aa1b-0242ac1f0007"
}

Sample request

<html>
<form method="POST" action="https://checkout.switcherepay.com/collector/595ceeea-9062-11ea-aa1b-0242ac1f0007">
<input type="hidden" name="body" value="NHV2MEdQVGk2TzNNWUU4....................WUJlazNBVW1udFE9PQ=="/>
<input type="submit"/>
</form>
</html>