World Payments Corp Integration

Updated time: Dec 21, 2017 , 12:34 (UTC+08:00)

1. Integration steps

Web Flow - Displays a In-Context Checkout window with the Vendor website in the background

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 WPC vendor 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 WorldPaymentCorp webscreen.

Request token:

  1. Live mode: https://secure.nnber.com/redirect-service/request-token
  1. Test mode: https://securetest.nnber.com/redirect-service/request-token

Request fields:

Field Name Description Required / Optional Type & Length
merchantName The vendor user name (of your vendor account). Required String (64)
merchantSecretKey The vendor secret key (of your vendor account). Required String (no limit)
merchantReferenceCode Your transaction description. Required String (100)
merchantToken A random unique string to prevent re-submit calls. Unix-timestamp 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)
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 need to equals to grand total amount 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.nnber.com/redirect-service/request-token \   -s \   --insecure \   -d merchantName=vendor_user_name \   -d merchantSecretKey=vendor_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 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 seperated by “&” character. Value of each field need to be encoding 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=vendor_user_name&merchantReferenceCode=Payment%2312&merchantSecretKey=vendor_secret_key&merchantToken=123456789&returnUrl=https%3A%2F%2Fexample.com%2Freturn.html
  2. Concat the string at step 1 with the endpoint url and “?”.
    Example:
    https://secure.nnber.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=vendor_user_name&merchantReferenceCode=Payment%2312&merchantSecretKey=vendor_secret_key&merchantToken=123456789&returnUrl=https%3A%2F%2Fexample.com%2Freturn.html
  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.nnber.com/request-token';
    $params = array(
      'merchantName' => 'vendor_user_name',
      'merchantSecretKey' => 'vendor_secret_key',
      'merchantReferenceCode' => 'Payment#12',
      'merchantToken' => '1504679352',
      'amount' => 9.95,
      'currencyCode' => 'USD',
      'returnUrl' => 'https://example.com/return.html',
      'cancelUrl' => 'https://example.com/cancel.html',
      '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 return by WPC 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 contains missing or invalid data, you will retreive 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 WPC 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":"Vendor  authentication failed"}

Redirect the buyer to the Secure World Payments Corp 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 WorldPaymentCorp by appending the token to a predetermined URL. The final URL looks like this:

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

Once the buyer is on the Secure WorldPaymentsCorp 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.nnber.com/redirect-service/purchase-details
  2. Test mode: https://securetest.nnber.com/redirect-service/purchase-details

Request fields:

Field Name Description Required / Optional Type & Length

merchantName

The vendor user name (of your vendor account).

Required

String (64)

merchantSecretKey

The vendor secret key (of your vendor 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.nnber.com/redirect-service/purchase-details \
-s \
--insecure \
-d merchantName=vendor_user_name \
-d merchantSecretKey=vendor_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 seperated by “&” character.
    Example:
     merchantName=vendor_user_name&merchantSecretKey=vendor_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=vendor_user_name&merchantSecretKey=vendor_secret_key&token=WR-48UftXeWZkEuYJh6f8Gxb0XXAjI8Qw3f     
  3. Concat the string at step 1 with the endpoint url and “?”.
    Example:
     https://secure.nnber.com/purchase-details?merchantName=vendor_user_name&merchantSecretKey=vendor_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.nnber.com/purchase-details';
$params = array(
'merchantName' => 'vendor_user_name',
'merchantSecretKey' => 'vendor_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 return by WPC system.

All responses

Integer

token

Identifier for this WPC 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 vendor site request to server. Value is a object of key-value pairs

Only success responses

Object

totalPurchases

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

Only success responses

Object

exchangeRates

List of exchange rates. Value is a 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 vendor 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 contains 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 vendor reference code for this authorization request matches the vendor 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 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
1418 The request was received, but a 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 WorldPaymentsCorp 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 WorldPaymentsCorp vendor configuration
1549 You requested a capture, but there is no corresponding, unused authorization record. 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 WorldPaymentsCorp because it did not pass the card verification number (CVN) check
1696 The authorization request was approved by the issuing bank but declined by WorldPaymentsCorp 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 a Payer Authentication problem. Payer could not be authenticated.

5. Test your integration

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

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

Please contact the support to retrieve the vendor 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 Vendor Notes/purpose
4111111111111111 Visa Sale successful.
5555555555554444 MasterCard Sale successful.
371449111020228 Amex Sale successful.

5.1.2. 3-D Secure tests

Number Vendor 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
Vendor 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.