Payment Gateway Integration Developer - Document

1. Integration steps

STEP 1

Add the PayCEC button

STEP 2

PayCEC Payment Page

STEP 3

Check 3-D Secure

STEP 4

Confirm Payment

2. Prerequisites

To integrate the Redirect service, you must:

1. Read the Eligibility requirements to determine whether your Checkout integration is a good candidate for the Checkout experience. Your buyers are presented with the Checkout full-page redirect checkout flow.
2. Have a PayCEC merchant account.

3. Initiate a payment

The request-token call initiates the Checkout process and generates a token that tracks the buyer throughout the entire checkout process. In this call you:

1. Pass payment details.
2. Redirect the buyer to PayCEC webscreen.

Request token:

1. Live mode: https://secure.paycec.com/redirect-service/request-token

1. Test mode: https://securetest.paycec.com/redirect-service/request-token

Request fields:

Example request:

curl https://secure.paycec.com/redirect-service/request-token \
   -s \   --insecure \
   -d merchantName=merchant_user_name \
   -d merchantSecretKey=merchant_secret_key \
   -d merchantReferenceCode=Payment#12 \
   -d merchantToken=123456789 \
   -d amount=9.95 \
   -d currencyCode=USD \
   -d returnUrl=https://example.com/return.html \
   -d cancelUrl=https://example.com/cancel.html \
   -d shippingTotal=2.5 \
   -d billing=a:9:{s:10:"first_name";s:7:"Example";s:9:"last_name";s:7:"Example";s:7:"address";s:17:"4321 Fake Address";s:7:"country";s:2:"US";s:4:"city";s:8:"Portland";s:5:"state";s:2:"WA";s:6:"postal";s:5:"97209";s:5:"phone";s:10:"0123456789";s:5:"email";s:21:"[email protected]";}
   -d item_0_amt=2.05 \
   -d item_0_name="Product Item 1" \
   -d item_0_qty=1 \
   -d item_1_amt=3.95 \
   -d item_1_name="Product Item 2" \
   -d item_1_qty=2 \
   -d sig= e382caab9cb29709652759551b043e16a855fe0e13e0cff25fea09ca4959d0f9cb71e6452e59c5ba314c3e8adaf15630fa008dd7c27aaf650458ab9499326d2c 

Generate the signature:

1. Build a String of concatenated key and values of the request fields with the following A-Z order: amount, cancelUrl, currencyCode, item_n_amt, item_n_name, item_n_qty, merchantName, merchantReferenceCode, merchantSecretKey, merchantToken, returnUrl, shippingTotal, billing separated by “&” character. The value of each field needs to be encoded by running URL encoding function.
   Example:
   

   amount=9.95&cancelUrl=https%3A%2F%2Fexample.com%2Fcancel.html¤cyCode=USD&item_0_amt=2.05&item_0_name=Product+Item+1&item_0_qty=1&item_1_amt=3.95&item_1_name=Product+Item+2&item_1_qty=2&merchantName=merchant_user_name&merchantReferenceCode=Payment%2312&merchantSecretKey=merchant_secret_key&merchantToken=123456789&returnUrl=https%3A%2F%2Fexample.com%2Freturn.html&shippingTotal=2.5&billing=a%3A9%3A%7Bs%3A10%3A%22first_name%22%3Bs%3A7%3A%22Example%22%3Bs%3A9%3A%22last_name%22%3Bs%3A7%3A%22Example%22%3Bs%3A7%3A%22address%22%3Bs%3A17%3A%224321+Fake+Address%22%3Bs%3A7%3A%22country%22%3Bs%3A2%3A%22US%22%3Bs%3A4%3A%22city%22%3Bs%3A8%3A%22Portland%22%3Bs%3A5%3A%22state%22%3Bs%3A2%3A%22WA%22%3Bs%3A6%3A%22postal%22%3Bs%3A5%3A%2297209%22%3Bs%3A5%3A%22phone%22%3Bs%3A10%3A%223605978306%22%3Bs%3A5%3A%22email%22%3Bs%3A21%3A%22fakeemail%40example.com%22%3B%7D

2. Concatenate the string at step 1 with the endpoint url and “?”.
   Example:
   

   https://secure.paycec.com/request-token?amount=9.95&cancelUrl=https%3A%2F%2Fexample.com%2Fcancel.html¤cyCode=USD&item_0_amt=2.05&item_0_name=Product+Item+1&item_0_qty=1&item_1_amt=3.95&item_1_name=Product+Item+2&item_1_qty=2&merchantName=merchant_user_name&merchantReferenceCode=Payment%2312&merchantSecretKey=merchant_secret_key&merchantToken=123456789&returnUrl=https%3A%2F%2Fexample.com%2Freturn.html&shippingTotal=2.5&billing=a%3A9%3A%7Bs%3A10%3A%22first_name%22%3Bs%3A7%3A%22Example%22%3Bs%3A9%3A%22last_name%22%3Bs%3A7%3A%22Example%22%3Bs%3A7%3A%22address%22%3Bs%3A17%3A%224321+Fake+Address%22%3Bs%3A7%3A%22country%22%3Bs%3A2%3A%22US%22%3Bs%3A4%3A%22city%22%3Bs%3A8%3A%22Portland%22%3Bs%3A5%3A%22state%22%3Bs%3A2%3A%22WA%22%3Bs%3A6%3A%22postal%22%3Bs%3A5%3A%2297209%22%3Bs%3A5%3A%22phone%22%3Bs%3A10%3A%223605978306%22%3Bs%3A5%3A%22email%22%3Bs%3A21%3A%22fakeemail%40example.com%22%3B%7D

3. Use HMAC SHA-512 (Secure hash algorithm-512) to build the hex string from the value at step 2 with password is the merchantSecretKey.
   Example: Result sig value
   

   e382caab9cb29709652759551b043e16a855fe0e13e0cff25fea09ca4959d0f9cb71e6452e59c5ba314c3e8adaf15630fa008dd7c27aaf650458ab9499326d2c

   PHP example code function to build the checksum signature:

   $endpoint = 'https://secure.paycec.com/request-token';
   $params = array(
     'merchantName' => 'merchant_user_name',
     'merchantSecretKey' => 'merchant_secret_key',
     'merchantReferenceCode' => 'Payment#12',
     'merchantToken' => '1504679352',
     'amount' => 9.95,
     'currencyCode' => 'USD',
     'returnUrl' => 'https://example.com/return.html',
     'cancelUrl' => 'https://example.com/cancel.html',
     'shippingTotal' => '2.5',
     'billing' => serialize(array(
           'first_name'    => 'Example',
           'last_name'     => 'Example',
           'address'       => '4321 Fake Address',
           'country'       => 'US',
           'city'          => 'Portland',
           'state'         => 'WA',
           'postal'        => '97209',
           'phone'         => '0123456789',
           'email'         => '[email protected]',
       )),
     'item_0_amt' => 2.05,
     'item_0_name' => 'Product Item 1',
     'item_0_qty' => 1,
     'item_1_amt' => 3.95,
     'item_1_name' => 'Product Item 2',
     'item_1_qty' => 2,
   );
   ksort($params);
   $sigString = $endpoint.'?'.http_build_query($params);
   $params['sig'] = hash_hmac('sha512', $sigString, 'merchant_secret_key', false);     
           

Response fields:

The response is formatted as a JSON string.

Example JSON string reply:

1. Success response:
   

   {"timestamp":"2017-09-06T07:07:42Z","isSuccessful":"true","requestId":"34","token":"WR-48UftXeWZkEuYJh6f8Gxb0XXAjI8Qw3f"}

2. Failed response:
   

   {"timestamp":"2017-09-06T07:10:18Z","isSuccessful":"false","requestId":"35","errorCode":1011,"message":"Merchant  authentication failed"}

Redirect the buyer to the Secure PayCEC webscreen:

The token returned in the request-token response associates a buyer to a particular Checkout transaction. You use this token in all subsequent calls for this transaction.
Once you receive the request-token response, you redirect the buyer to Secure PayCEC by appending the token to a predetermined URL. The final URL looks like this:

1. Live mode: https://secure.paycec.com/redirect-service/webscreen?token=WR-XXXXXXXXXX
2. Test mode: https://securetest.paycec.com/redirect-service/webscreen?token=WR-XXXXXXXXXX

Once the buyer is on the Secure PayCEC website, they will:

1. Fill the billing information and the credit/debit card information.
2. Click Pay Now to make payment.

To specify the return URL in the Checkout API request, append the token in the query string. The return URL looks like this:
https://example.com/return?token=WR-48UftXeWZkEuYJh6f8Gxb0XXAjI8Qw3f

4. Get payment details

The purchase-details call retrieves the result of the transaction such as transaction ID, timestamp, amount, currency code,...

Endpoints:

1. Live mode: https://secure.paycec.com/redirect-service/purchase-details
2. Test mode: https://securetest.paycec.com/redirect-service/purchase-details

Request fields:

Example request:

  curl  https://secure.paycec.com/redirect-service/purchase-details \
    
 -s \
    
 --insecure \
    
 -d merchantName=merchant_user_name \
    
 -d merchantSecretKey=merchant_secret_key  \
    
 -d token=WR-48UftXeWZkEuYJh6f8Gxb0XXAjI8Qw3f  \
    
 -d sig= aff3e6ccd1d2c71709311427fc9c32c9c72a628995eb7e399e1791fcc8b6ed537b373d236f41c9c695c9d4cb1df0cd7ba4bb74e171dffcf2655eb199d959c02a

Generate the signature:

1. Build a String of concatenated key and values of the request fields with the following A-Z order: merchantName, merchantSecretKey, token separated by “&” character.
   Example:
   

    merchantName=merchant_user_name&merchantSecretKey=merchant_secret_key&token=WR-48UftXeWZkEuYJh6f8Gxb0XXAjI8Qw3f

2. URL encoding the string at step 1 to converts characters into a format that can be transmitted over the Internet.
   Example:
   

   merchantName=merchant_user_name&merchantSecretKey=merchant_secret_key&token=WR-48UftXeWZkEuYJh6f8Gxb0XXAjI8Qw3f     

3. Concatenate the string at step 1 with the endpoint url and “?”.
   Example:
   

    https://secure.paycec.com/purchase-details?merchantName=merchant_user_name&merchantSecretKey=merchant_secret_key&token=WR-48UftXeWZkEuYJh6f8Gxb0XXAjI8Qw3f      

4. Use HMAC SHA-512 (Secure hash algorithm-512) to build the sig string from the value at step 3 with password is your merchantSecretKey.
   Example: Result sig value:
   

     aff3e6ccd1d2c71709311427fc9c32c9c72a628995eb7e399e1791fcc8b6ed537b373d236f41c9c695c9d4cb1df0cd7ba4bb74e171dffcf2655eb199d959c02a     

PHP example code function to build the signature:

$endpoint = 'https://secure.paycec.com/purchase-details';
 $params = array(
 'merchantName' => 'merchant_user_name',
 'merchantSecretKey' => 'merchant_secret_key',
 'token' => 'WR-48UftXeWZkEuYJh6f8Gxb0XXAjI8Qw3f',
 );
 ksort($params);
 $sigString =  $endpoint.'?'.http_build_query($params);
 $params['sig']  = hash_hmac('sha512', $sigString, 'merchant_secret_key', false); 

Response fields:

The response is formatted as a JSON string.

Example JSON string reply:

1. Success response:
   

   {"accountSuffix":"0007","billingAddress":"ABC","billingCity":"ABC","billingCountryCode":"US","billingFirstName":"First","billingLastName":"Last","billingState":"ABC","billingZip":"123456","bincode":"520000","exchangeRates":{"USDUSD":"1"},"isSuccessful":"true","isTheCardEnrolled":"true","isThePasswordAuthenticated":"true","referenceCode":"Payment#1505208753","paymentMethod":"mastercard","requestId":"5","timestamp":"2017-09-12T09:33:29Z","token":"WR-lWCJ7Dji0S7Jma6e1rTwkbyP7mGSKroR","total":{"USD":9.95},"totalPurchases":{"USD":9.95},"transactionId":"8222088078686335703109"} 

2. Failed response:
   

   {"errorCode":"2002","errorMessage":"Encountered  a Payer Authentication problem. Payer could not be  authenticated.","isSuccessful":"false","isTheCardEnrolled":"true","isThePasswordAuthenticated":"false","referenceCode":"Payment#1505202084","requestId":"1002395","timestamp":"2017-09-12T07:42:09Z","token":"WR-H3eEKB9xxYZZi2HCH6Ku036cUcfREo84"}

4. Error codes

The following table describes the reason codes returned by the Simple Order API for customer profiles. For a discussion of replies, decisions, and reason codes, see the information about handling replies in.

5. Test your integration

You can use the Secure Test PayCEC website to test your integration.

• Test mode endpoint: http://securetest.paycec.com/redirect-service/

Please contact the support to retrieve the merchant account for the test mode.

5.1. Test Card Numbers

For test transactions, you can use one of the credit cards listed below. When prompted for an expiration date for the credit card, use any date in the future.

Do not use real credit card numbers.

5.1.1. Common sale tests

5.1.2. 3-D Secure tests

5.2. Test Responses

5.2.1. Test Case 1: Currency decimal places

Not all currencies are supported for all processors.

5.2.2. Test Case 2: Verified by Visa Card Enrolled: Unsuccessful Authentication