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

NameTypeDescription
action requiredstringSALE.
client_key requiredUUIDUnique key (client_key).
order_id requiredstring(255)Transaction ID in the Merchants system.
order_amount requiredfloatThe amount of the transaction.
order_currency requiredcurrencyCurrency.
order_description requiredstring(1024)Description of the transaction (product name). More information about this field can be found below.
req_tokenY or N (default N)Special attribute pointing for further tokenization
card_tokenstring(64)Credit card token value.
card_number optionalstringCard number. Fields card_number, card_exp_month, card_exp_year are optional if card_token is specified.
card_exp_month optionalstringMonth in the form XX. Fields card_number, card_exp_month, card_exp_year are optional if card_token is specified.
card_exp_year optionalstringYear in the form XXXX. Fields card_number, card_exp_month, card_exp_year are optional if card_token is specified.
card_cvv2 requiredCVV/CVC2CVV/CVC2 credit card verification code.
payer_first_name requiredstring(32)Customer's name.
payer_last_name requiredstring(32)Customer's surname.
payer_middle_namestring(32)Customer's middle name.
payer_birth_date requiredstringCustomer's birthday in format yyyy-MM-dd, e.g. 1970-02-17.
payer_address requiredstring(255)Customer's address.
payer_address2string(255)The adjoining road or locality (if required) of the сustomer's address.
payer_house_numberstring(9)Customer's house or building number.
payer_country requiredcountry codeCustomer's country.
payer_state requiredstring(32)Customer's state.
payer_city requiredstring(40)Customer's city.
payer_districtstring(32)Customer's district of city.
payer_zip requiredstring(10)ZIP-code of the Customer.
payer_email requiredstring(256)Customer's email.
payer_phone requiredstring(32)Customer's phone.
payer_ip requiredIPIP-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 requiredstring(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_targetstring(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).
hashstringSpecial 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
NameTypeDescription
actionstringSALE.
resultstringSUCCESS.
statusstringPENDING.
order_idstringTransaction ID in the Merchant's system.
trans_idstringTransaction ID in the Payment Platform.
trans_datedateTransaction date in the Payment Platform.
descriptorstringDescriptor from the bank, the same as cardholder will see in the bank statement.
card_tokenstringIf the parameter req_token was enabled Payment Platform returns the token value.
amountfloatOrder amount.
currencycurrencyCurrency.

Tip: Field parameters info

Unsuccessful sale response
NameTypeDescription
actionstringSALE.
resultstringDECLINED.
statusstringDECLINED.
order_idstringTransaction ID in the Merchant's system.
trans_idstringTransaction ID in the Payment Platform.
trans_datedateTransaction date in the Payment Platform.
descriptorstringDescriptor from the bank, the same as cardholder will see in the bank statement.
amountfloatOrder amount.
currencycurrencyCurrency.
decline_reasonstringThe reason why the transaction was declined.

Tip: Field parameters info

3D-Secure transaction response
NameTypeDescription
actionstringSALE.
resultstringREDIRECT.
statusstring3DS/REDIRECT.
order_idstringTransaction ID in the Merchant's system.
trans_idstringTransaction ID in the Payment Platform.
trans_datedateTransaction date in the Payment Platform.
descriptorstringDescriptor from the bank, the same as cardholder will see in the bank statement.
amountfloatOrder amount.
currencycurrencyCurrency.
redirect_urlstringURL to which the Merchant should redirect the Customer.
redirect_paramsstringObject 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_methodstringThe method of transferring parameters (POST / GET).

Tip: Field parameters info

CREDITVOID request POST

CREDITVOID request is used to return funds to the card

Endpoint

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

Parameters

NameTypeDescription
action requiredstringCREDITVOID.
client_key requiredUUIDUnique key (client_key).
trans_id requiredUUIDTransaction ID in the Payment Platform.
amountfloatThe 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 requiredstringSpecial 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
NameTypeDescription
actionstringCREDITVOID.
resultstringACCEPTED.
order_idstringTransaction ID in the Merchant's system.
trans_idstringTransaction ID in the Payment Platform.

Tip: Field parameters info

Testing

Card numberCard expiration date (MM/YYYY)Testing / Result
411111111111111101/2025This card number and card expiration date must be used for testing successful SALE.
Response:

{action: SALE, result: SUCCESS, status: PENDING}
411111111111111102/2025This card number and card expiration date must be used for testing unsuccessful SALE.
Response:

{action: SALE, result: DECLINED, status: DECLINED}
411111111111111103/2025This card number and card expiration date must be used for testing unsuccessful CAPTURE after successful SALE.
Response:

{action: SALE, result: SUCCESS, status: PENDING}
411111111111111105/2025This card number and card expiration date must be used for testing successful SALE after 3DS verification.
Response:

{action: SALE, result: REDIRECT, status: 3DS}
411111111111111106/2025This card number and card expiration date must be used for testing unsuccessful SALE after 3DS verification.
Response:

{action: SALE, result: REDIRECT, status: 3DS}
411111111111111112/2025This card number and card expiration date must be used for testing successful SALE after redirect.
Response:

{action: SALE, result: REDIRECT, status: REDIRECT}
411111111111111112/2026This 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

ParameterValid value
actionSALE
client_keyc2b8fb04-110f-11ea-bcd3-0242c0a85004
order_idORDER-12345
order_amount1.99
order_currencyUSD
order_descriptionProduct
card_number4111111111111111
card_exp_month01
card_exp_year2025
card_cvv2000
payer_first_nameJohn
payer_last_nameDoe
payer_birth_date1970-02-17
payer_addressBig street
payer_countryUS
payer_stateCA
payer_cityCity
payer_zip123456
payer_email[email protected]
payer_phone199999999
payer_ip123.123.123.123
term_url_3dshttps://swtchrpay.com/paystatus/c2b8fb04-110f-11ea-bcd3-0242c0a85004/ORDER-12345/
hash2702ae0c4f99506dc29b5615ba9ee3c0

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>
Last Updated: