Menu

Payment Gateway Integration Developer - Document

1. Integration steps

Add the PayCEC button

Add the PayCEC button

PayCEC Payment Page

PayCEC Payment Page

Check 3-D Secure

Check 3-D Secure

Confirm Payment

Confirm Payment

1

Required

Learn about the checkout flow.

2

Required

Meet the prerequisites.

3

Required

Place code on your server to initiate a payment.

4

Required

Get payment details.

5

Required

Test your integration.

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:

Field Name Description Required / Optional Type & Length
merchantName

The merchant user name (of your merchant account).

Required String (64)
merchantSecretKey

The merchant secret key (of your merchant account).

Required String (no limit)
merchantReferenceCode

Your transaction description.

Required String (100)
merchantToken

A random unique string to prevent re-submit calls. Unix-timestamp The value is recommenced.

Required String (64)
amount

Grand total for the order. This value cannot be Negative. You can include a decimal point (.), but you cannot include any other special characters.

Required String (15)
currencyCode

Currency used for the order. Use the threecharacter
ISO Standard Currency Codes.

Required String (3)
returnUrl

URL of the final review page on your website where the buyer confirms the order and payment. Please don’t use any get parameters in your return URL.

Required String (255)
cancelUrl

URL of the cancel page on your website. Please don’t use any get parameters in your cancel URL.

Required String (255)
shippingTotal

Total shipping cost for the order. This value cannot be Negative. You can include a decimal point (.), but you cannot include any other special characters.

Optional String (15)
billing

String encoding (serialize) of billing information, including "first_name", "last_name", "address", "country", "city", "state", "postal", "phone", "email". This information can be left blank and defaults to an empty string.

Optional String (no limit)

Fields for cart items You can add up to 10 items to the transaction (0 <= n <= 9). SUM of item_n_amt * item_n_qty have to equals transaction grand total amount.

item_n_amt

The price of the item at index n. When you set the amount for at least 1 item, the item total needs to equals to grand total amount + shippingTotal (optional) of the transaction. Example: item_0_amt = 2.9

Optional String (15)
item_n_name

The name of the item at index n. Default is empty.

Optional String (255)
item_n_qty

The quantity of the item at index n. Quantity value have to between 1 and 65500. Default value is 1.

Optional Integer
sig

Generate a HMAC-SHA512 string of concatenated values of all the request fields except the field “sig”.

Required String (128)

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.

Field Name Description Required / Optional Type & Length
timestamp

Times are expressed in UTC (Coordinated Universal Time), with a special UTC designator ("Z") (UTC+0:00).

All responses String (20)
isSuccessful

Indicates success or failure for the request. Possible values:

  1. true
  2. false
All responses String (5)
requestId

The unique request id is returned by PayCEC system.

All responses Integer
errorCode

The error code. Reference at the Error codes table.

Only failed responses Integer
errorField

If the errorCode is 1011, means one or more fields in the request contain missing or invalid data, you will retrieve the errorField.

Only failed responses with missing/invalid data error code

String (255)
message The error message. Only failed responses String (no limit)
token

Identifier for this PayCEC transaction. You must use this token in subsequent calls for this transaction.

Only success responses String (35)

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:

Field Name Description Required / Optional Type & Length
merchantName

The merchant user name (of your merchant account).

Required String (64)
merchantSecretKey

The merchant secret key (of your merchant account).

Required String (no limit)
token

The token you get in the token parameter of the return url.

Required String (35)
sig

Generate a HMAC-SHA512 string of concatenated values of all the request fields except the field “sig”

Required String (128)

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.

Field Name Description Required / Optional Type & Length
timestamp

Times are expressed in UTC (Coordinated Universal Time), with a special UTC designator ("Z") (UTC+0:00).

All responses String (20)
isSuccessful

Indicates success or failure for the request. Possible values:

  1. true
  2. false
All responses String (5)
isTheCardEnrolled

Indicates card is enrolled or not. Possible values:

  1. true
  2. false
All responses String (5)
isThePasswordAuthenticated

Indicates the password is authenticated. Possible values:

  1. true
  2. false

Only responses have isTheCardEnrolled = true

String (5)
requestId

The unique request id is returned by PayCEC system.

All responses Integer
token

Identifier for this PayCEC transaction.

All responses String (35)
errorCode

The error code. Reference at the Error codes table.

Only failed responses Integer
errorField

If the errorCode is 1011 or 1012, means one or more fields in the request contains missing or invalid data, you will retreive the errorField.

Only failed responses with missing/invalid data error code

String (255)
errorMessage The error message. Only failed responses String (no limit)
transactionId

A unique string transaction ID that is used to identify each transaction.

Only success responses String (64)
paymentMethod

Payment method. Possible values:

  1. visa
  2. mastercard
  3. amex
Only success responses String (10)
total

Total amount and currency code that the merchant site request to server. The value is a object of key-value pairs

Only success responses Object
totalPurchases

Total amount purchases of the currency that the merchant set on PayCEC merchant settings. If the currency code in the request-token call is different from the merchant currency code setting, PayCEC will calculate request currency and merchant currency exchange rate. Value is a object of key-value pairs

Only success responses Object
exchangeRates

List of exchange rates. The value is an object of key-value pairs

Only success responses Object
accountSuffix Account number suffix. Only success responses String (4)
bincode

The bin code of the credit/debit account. Warning: Please use it safely! Please only use this value to check risk, don’t share it with any one or show it on your website.

Only success responses String (6)
billingAddress

The billing street address as it
appears on the credit card issuer’s records.

Only success responses String (255)
billingCity

City of the billing address.

Only success responses String (255)
billingCountryCode

Billing country for the account. Use the two-character country codes.

Only success responses String (255)
billingFirstName

Customer’s first name.The value should be the
same as the value that appears on the card.

Only success responses String (255)
billingLastName Customer’s last name. Only success responses String (255)
billingState

State or province of the customer.

Only success responses String (255)
billingZip

Postal code of the billing address.

Only success responses String (255)

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.

Error Code Description
1001 General system failure
1002 Please use POST request
1003 Token expired
1004 The merchant information is invalid
1005 Cannot init the transaction
1006 Your access domain has been declined
1010 The request is missing one or more required fields
1011 One or more fields in the request contain invalid data
1012 The totals of the cart item amounts do not match order amounts
1032 The card has reached the credit limit
1049 Inactive card or card not authorized for card-not-present transactions
1069 General decline by the processor
1101 Unable to verify or correct address
1106 The requested transaction amount must match the previous transaction amount
1113 The order is marked for review by Decision Manager
1117 The capture or credit is not voidable because the capture or credit information has already been submitted to your processor. Or, you requested a void for a type of transaction that cannot be voided
1121 Insufficient funds in the account
1125 Issuing bank unavailable
1138 The card type sent is invalid or does not correlate with the credit card number
1155 Invalid account number
1162 The order has been rejected by Decision Manager
1178 The card type is not accepted by the payment processor
1192 The transaction has already been settled
1216 Invalid card verification number (CVN)
1222 CVN did not match
1235 The merchant reference code for this authorization request matches the merchant reference code of another authorization request that you sent within the past 15 minutes
1258 Expired card. You might also receive this if the expiration date you provided does not match the date the issuing bank has on file.
1275 Address match not found (no reason given)
1277 Account is prohibited from processing stand-alone refunds
1301 Export email_country match
1353 Customer's account is frozen
1356 The issuing bank has questions about the request. You do not receive an authorization code programmatically, but you might receive one verbally by calling the processor
1362 Fraud score exceeds the threshold
1365 Multiple address matches were found
1370 House/Box number not found on street
1376 Insufficient address information
1388 Street name not found in Postal code
1414 Export hostname_country/ip_country match
1419 The request was received, but service did not finish running in time
1419 The customer matched the Denied Parties List
1433 Generic Decline
1434 The referenced request id is invalid for all follow-on transactions
1436 Postal code not found in database
1438 The customer matched an entry on the processor’s negative file
1449 Processor failure
1452 General decline of the card. No other information provided by the issuing bank
1465 The boleto request was declined by your processor
1469 Route service identifier not found or out of range
1491 Only a partial amount was approved
1496 The authorization request was approved by the issuing bank but declined by PayCEC because it did not pass the Address Verification Service (AVS) check
1518 The Pinless Debit card's use frequency or maximum amount per use has been exceeded
1519 The requested capture amount exceeds the originally authorized amount
1520 The request was received, but there was a timeout at the payment processor
1528 The request was received but there was a server timeout. This error does not include timeouts between the client and the server
1546 There is a problem with your PayCEC merchant configuration
1549 You requested a capture, but there is no corresponding, unused authorization record.This occurs if there was not a previously successful authorization request or if the previously successful authorization has already been used by another capture request.
1607 The transaction has already been settled or reversed.
1630 Export bill_country/ship_country match
1641 You requested a credit for a capture that was previously voided
1662 Unsupported character set
1663 Stolen or lost card
1666 Apartment number missing or not found
1669 Multiple address matches were found (international)
1672 The authorization request was approved by the issuing bank but declined by PayCEC because it did not pass the card verification number (CVN) check
1696 The authorization request was approved by the issuing bank but declined by PayCEC based on your Smart Authorization settings
1707 P.O. Box identifier not found or out of range
1717 The authorization has already been reversed
2001 The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction
2002 Encountered The payer Authentication problem. The payer could not be authenticated.

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

Number Merchant Notes/purpose
4111111111111111 Visa Sale successful.
5555555555554444 MasterCard Sale successful.
371449111020228 Amex Sale successful.

5.1.2. 3-D Secure tests

Number Merchant Notes/purpose
4000000000000002 Visa Sale successful.
4000000000000127
4000000000000028 Visa Card enrolled, verification failed.
4000000000000010
5200000000000007 MasterCard Sale successful.
5200000000000106
5200000000000023 MasterCard Card enrolled, verification failed.
5200000000000015
340000000003961 Amex Sale successful.
344400000000569
340000000006022 Amex Card enrolled, verification failed.

5.2. Test Responses

5.2.1. Test Case 1: Currency decimal places

Not all currencies are supported for all processors.

Amout 9.9999
CurrencyCode USD
Results Failed
Error code          1001
Message One or more fields in the request contains invalid data
Error Field Amount
Reason Most currencies require two decimal places.The decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals.

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

Card Number 4000000000000028
Merchant Visa
Results Failed
Error Code 2002
Error Message Encountered a Payer Authentication problem. Payer could not be authenticated.
Reason Card enrolled, verification failed.
User failed authentication.
Payer cannot be authenticated.