Payment API


Payment Facilitator

Encrypt Data to Protect Against Spoofing


At the end of the SPI's process flow, a cardholder's browser is redirected to the merchant's success page. This redirect will contain the payload used to inform a merchant that payment has (or has not) been successful. Normally, a step like this would be vulnerable to a spoofing attack. Because the payload of the SPI is contained in a URL string, it wouldn't even take a technical mind to make a merchant think he or she has been paid. would be a very real possibility!

The SPI prevents this form of cheating because it requires the merchant to encrypt a portion of the POST sent to ProtectPay®. In turn, the SPI will encrypt the payload contained in the final redirect. The merchant can be certain that the response coming back from ProtectPay® is real and that he or she has actually been paid. It is this encryption that makes a TempToken necessary.

Encrypt Merchant Information and Instructions for the SPI

Not all of the data contained in the POST to the SPI needs to be encrypted. In fact, the information entered into the browser by a cardholder cannot be touched by your systems at all. You should encrypt merchant data such as transaction amount, invoice number, etc. (See full list at the bottom of this page.) You should also encrypt the instructions that you provide to the SPI. By using a combination of values passed in to the fields ProcessMethod, and PaymentMethodStorageOption, you can instruct the SPI to perform a number of different tasks:

  1. Store a card as a ProtectPay® on-file payment method.
  2. Authorize a credit card transaction.
  3. Authorize and capture a credit card transaction. (Sometimes referred to as a sale.)
  4. Process a credit card transaction AND store the card as a payment method.
  5. Process a transaction and store the card as a payment method only if charging it is successful.

Encryption Steps

Create a string with key-value pairs of the data which cannot be altered by the cardholder. (See the table at the bottom of this page.)

Then encrypt the Key-Value Pair using the following method:

  1. UTF-8 encode the TempToken string and generate an MD5 hash of the TempToken.
  2. UTF-8 encode the name value string from step 2 and encrypt using AES-128 encryption using Cipher Block Chaining (CBC) mode.
    1. Set both the key and initialization vector (IV) equal to result from (a).
    2. You may need to pad the name value string to match AES encryption requirements.
  3. 3. Base64 encode the result of (b).

The resulting value is called a SettingsCipher and will be posted to the ProtectPay® SPI, along with the cardholder information, and CredentialId. When the ProtectPay® SPI server receives your request, it uses the CredentialId to decipher your SettingsCipher, and process your request.

Encryption Method
Encryption Method
Encryption Method
Encryption Method Header
Encryption Method
Encryption Method
Encryption Method
Encryption Method
Encryption Method
Parameters that Must be Encrypted
Query String Parameter Required Description
AuthToken Y TempToken returned from Create a TempToken method of the ProtectPay® APIAPI.
PayerId Y Id of the payer that is the owner of the credit card.
PaymentProcessType Y Tells the SPR which mechanism to use for processing a transaction:
ProcessMethod Y Tells the SPR how to process transaction prior to storage.
PaymentMethodStorageOption Y Tells the PMI when to store cardholder data. By using this value in conjunction with ProcessMethod, it is possible to create a system to only store payment methods, to only process a transaction, or to process a transaction then store a payment method only if the processing is successful.
CurrencyCode N ISO standard currency code.
Amount N Transaction amount.
InvoiceNumber N Optional field passed to Gateway.
ReturnURL Y URL where response is sent by the PMI. If you wish to include a query string as your ReturnURL, you MUST use http encoding or your SPR post will not work.
Comment1 N Optional fields passed to Gateway.
Comment2 N Optional fields passed to Gateway.
SettingsCipher Y The SettingsCipher is an encrypted value consisting of those parameters that should not be possible to change by a cardholder.
Data from ProPay, Inc API documentation.

What's Your Next Step?

After you create your SettingsCipher, you will be ready to paint a checkout page for your cardholders to enter their payment information.