Overview

Payment methods refer to choice of payment options available to customer when placing an order. In most cases payment method relies on a third party system (payment gateway) to complete the financial transaction. Although financial operations are fairly standardised and well understood each payment gateway offers unique API to accomplish this. Therefore payment API in YC is composed of two parts:

  • core payment API, which is fully integrated with YC order life cycle, dealing with standard approaches to transactions
  • payment modules, which are payment gateway specific implementations that drive the standard operations.

YC has a number of payment modules implementation provided out of the box with flexibility to add new implementations with ease.

Once the platform up and running all payment modules are automatically detected and contribute to the payment gateways configuration in YC. Through system payment gateway panel business user can enable and disable payment gateways at the platform level. Shop managers when configuring shop instance can choose from the list of platform enabled payment gateways and configure them with shop specific parameters.

Payment gateway parameters are predefined by the payment module, so all that is necessary to enable payment methods for shop is to setup these values, which usually involves entering merchant keys or IDs.

The following payment gateway modules are supported out of the box (with few featured highlighted):

Module Payment method YC version EoL Online External Callback Per Shipment AUTH CAPTURE AUTH_CAPTURE RETURN 
Core            
 Payment to courier 3.0.0+  offline        
 Pre paid (external payments) 3.0.0+  offline        
 In store 3.0.0+  offline        
 Test (card) 3.0.0+  online mock        
 TestExt (card) 3.0.0+  online mock  base callback filter      
Authorize.net            
 AIM 3.0.0+  online        
 SIM 3.0.0+  online  AuthorizeNetSimPaymentOkPage      
CyberSource            
 CyberSource 3.0.0+  online        
PayPal            
 PayPal Button 3.1.0+  online  base callback filter      
 PayFlow  3.0.0+ 3.0.0 online         
 PayPal Express 3.0.0+  online  PayPay express callback filter       3.1.0+ 
 PayPal NPV  3.0.0+ 3.0.0 online        
 PayPal Pro 3.1.0+  online        
LiqPay            
 LiqPay (full) 3.0.0+  online  base callback filter      
 LiqPay (no refund) 3.0.0+  online  base callback filter      
PostFinance            
 PostFinance 3.1.0+  online  base callback filter      

Payment Gateway Management

Payment gateways list loaded into this panel is composed of automatically resolved payment gateways modules installed on current instance. The installation process is very simple and involves specifying few maven profile parameters during build.

When this list is loaded system administrator can select which modules are enabled or disabled by clicking "on" and "off" buttons. If a payment gateway does not appear in this list then it is highly possible that this module was not added to the build, otherwise all payment gateways will appear in this list loaded from bundled modules. 

Each payment gateway has predefined attributes, which can be viewed by clicking "Attributes" button when payment gateway is selected. Note that these parameters are templates - the actual values are set when configuring payment gateway for shop instance.

There is however an option to add additional attributes to template by clicking "New attribute" button. This allows to add new attributes such as new localisation for HTML form when new language is added.

  After new attribute is added to the system payment templates the shop payment gateway has to be turned "off" and then back "on" for new attribute to appear in shop specific settings.

As of 3.4.0+ this view uses "Secure" feature, which means that by default only non-secure parameters are loaded. If you want to see all parameters you have to click the "lock" button. Then you will see all attributes available for payment gateway in the attribute view.

yc-3.4.0-payment-crud.png

Workshops

Activating payment modules
Enabling payment methods in your shop (basics)

Payment Gateway Specific Configurations

Authorize.net

Enabling Authorize.NET (AIM & SIM)
  Play 7:09

To create test account go to http://developer.authorize.net/hello_world/sandbox/ and fill in the form.

After registration is completed you will be provided with:

  1. API Login ID
  2. Transaction Key
  3. MD5 Hash Key

You can login to your test account from here https://sandbox.authorize.net

Key points about your test account:

  • API Login ID and Transaction Key can be viewed in "Settings > Security Settings > API Login ID and Transaction Key"
  • MD5 Hash Key can be reset in "Settings > Security Settings > MD5 Hash"
  • For SIM Receipt Page and Relay Response URL must be configured in "Settings > Security Settings > Receipt Page" and "Settings > Security Settings > Relay Response" respectively.
  • Relay Response is what is used as transaction callback and its response is rendered as confirmation page back to the customer after clicking "Pay" button.

AIM

Key configurations for AIM

Configuration Mandatory Notes 
Merchant login  API Login ID from your Authorize.NET account 
Transaction key  Transaction Key from your Authorize.NET account 
Environment name  test - "SANDBOX"
production - "PRODUCTION" 

SIM

  SIM account is currency specific, so you will not be able to provide different currency when paying with this method. You can configure the currency in the processor settings section

Key points for SIM

Configuration Mandatory Notes 
Merchant login  API Login ID from your Authorize.NET account 
Transaction key  Transaction Key from your Authorize.NET account 
MD5 Hash Key  MD5 Hash Key from your Authorize.NET account used to verify transaction callback 
URL to post form  test - "https://test.authorize.net/gateway/transact.dll"
production - "https://secure.authorize.net/gateway/transact.dll" 
Relay Response URL  must be set to the "https://www.yourdomain.com/yes-shop/anetsimresult".
Note: that this page must be served via HTTPS and it processes the transaction callback.
Note: "/anetsimresult" is mounted to AuthorizeNetSimPaymentOkPage in "wicket.xml" 
SIM test request flag  test transaction - TRUE
actual transaction - FALSE 
Payment form  There is a number of parameters that SIM supports to modify look and feel of the external payment form.
Recommended "Order cancel URL" is "http://www.yourdomain.com/yes-shop/paymentresult?hint=cancel". 

CyberSource

Enabling CyberSource
  Play 7:23

To create test account go to http://www.cybersource.com/register/ and fill in the form.

After registration is completed you will be provided with:

  1. Organization ID
  2. Link to activate Merchant Admin account   You need this account to generate the p12 key
  3. Link to activate Account Admin account

You can login to your test account from here https://ebctest.cybersource.com

Key points about your test account:

  • If you have capital letters in your Organization ID they will be converted to lower case (be aware of this)
  • Generating p12 certificate is done from Login to Merchant Admin > Account Management > Transaction Security Keys > Security Keys for the Simple Order API
  • You need to allow applet in order to save the certificate. Certificate name will be Organization ID with p12 extension.
  • p12 certificate is 2048-bit, so java SDK security must have "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files" installed.
  • on some JDK8 due to classloader bug you may need to copy bcprov-ext-jdk15on.jar into JAVA_HOME/jre/lib/ext if you get "error constructing MAC: java.security.InvalidAlgorithmParameterException: inappropriate parameter type: javax.crypto.spec.PBEParameterSpec"
  • Cybersource uses AVS, so address must be correct for payments to go through.

Key configurations for AIM

Configuration Mandatory Notes 
Merchant id  Organization ID from your Cybersource Merchant Admin account account.
  Be careful with letter case 
Send to production  false - SANDBOX
true - PRODUCTION 
Abstract path to directory with keys  Directory where p12 file will be placed on the server.
  Do not rename this file as filename is expected to match Organization ID
  Encryption is 2048-bit so ensure that JCE policies are installed in java SDK
  It is recommended to set read only permissions of p12 files 
Enable log  Optional parameter to trace SOAP communication for payment.
  Must be disabled for production 
Absolute path to log directory  Path to log directory, when "Enable log" is set 
Cybersource API version  Verified "1.28" 
Use apache HHTP client for communication  true by default 

PayPal

Enabling PayPal (Button, Express Checkout & Pro)
  Play 11:46

To create test account go to https://developer.paypal.com/ and register. You will need to create a business account and several test customer accounts. Note if you would like to use PayPal Pro you need to upgrade account to pro (Sandbox > Accounts > Select Account > Profile > Account Type > Click Upgrade to Pro)

After creating merchant (business) accounts you will be able to access the following from profile menu:

  1. Email ID used by PayPal Button API
  2. Username
  3. Password
  4. Signature

Key points about your test account:

  • YC uses signature signing. If you want to create certificate signing this is not supported.
  • For PayPal Button you need to use Email ID as the login, for all others (Pro and Express) use Username
  • To use Pro features you need to upgrade merchant account (Profile > Account Type > Click Upgrade to Pro)
  • Pro test payments must be done using test Credit card provided in merchant's account (Profile > Funding Tab > Credit Card, use CCV 123 if it is not shown)

PayPal Button

Simple payment API that allows to capture payments from customer with PayPal accounts.

Key configurations for PayPal Button

Configuration Mandatory Notes 
Api user name  Email ID from your PayPal Merchant (Profile > Profile Tab > Email ID) 
Api user password  Password from your PayPal Merchant (Profile > API Credentials Tab > Password) 
Signature  Signature from your PayPal Merchant (Profile > API Credentials Tab > Signature) 
Paypal URL  live - https://www.paypal.com/cgi-bin/webscr
sandbox - https://www.sandbox.paypal.com/cgi-bin/webscr
Return URL  http://www.yourdomain.com/yes-shop/paymentresult?hint=ok
The URL to which PayPal redirects buyers after confirmed payment
  Must be HTTPS 
Cancel URL  http://www.yourdomain.com/yes-shop/paymentresult?hint=cancel
The URL to which PayPal redirects buyers after cancellation of payment
  Must be HTTPS 
Api callback URL  http://www.yourdomain.com/yes-shop/paymentpaypalbutton
The URL to which PayPal posts information about the payment, in the form of Instant Payment Notification messages
  Must be HTTPS
  Must set UTF-8 encoding in IPN preferences https://www.paypal.com/cgi-bin/customerprofileweb?cmd=_profile-language-encoding (see this stack overflow thread) 
PayPal submit button  Can be used to specify PayPal branded buttons 
Environment mode  Environment mode used by callback verification. Values can be: sandbox or live 

PayPal Express

Advanced payment API that allows to capture payments from customer with PayPal accounts and do refunds.

Key configurations for PayPal Express

Configuration Mandatory Notes 
Api user name  Username from your PayPal Merchant (Profile > API Credentials Tab > Username) 
Api user password  Password from your PayPal Merchant (Profile > API Credentials Tab > Password) 
Signature  Signature from your PayPal Merchant (Profile > API Credentials Tab > Signature) 
Paypal URL  Paypal url to redirect to after success SetExpressCheckout operation
live - https://www.paypal.com/cgi-bin/webscr
sandbox - https://www.sandbox.paypal.com/cgi-bin/webscr
Api call url  Api call url
live - https://api-3t.paypal.com/nvp
sandbox - https://api-3t.sandbox.paypal.com/nvp
Return URL  http://www.yourdomain.com/yes-shop/paymentresult?hint=ok
The URL to which PayPal redirects buyers after confirmed payment
  Must be HTTPS 
Cancel URL  http://www.yourdomain.com/yes-shop/paymentresult?hint=cancel
The URL to which PayPal redirects buyers after cancellation of payment
  Must be HTTPS 
Api callback URL  http://www.yourdomain.com/yes-shop/paymentpaypalexpress
The URL to which PayPal posts information about the payment, in the form of Instant Payment Notification messages, which will trigger DoExpressCheckoutPayment
  Must be HTTPS
  Must set UTF-8 encoding in IPN preferences https://www.paypal.com/cgi-bin/customerprofileweb?cmd=_profile-language-encoding (see this stack overflow thread) 
PayPal submit button  Can be used to specify PayPal branded buttons 

PayPal Pro

Fully featured card payments API.

  To use Pro features you need to upgrade merchant account (Profile > Account Type > Click Upgrade to Pro)
  Pro test payments must be done using test Credit card provided in sandbox's account (Profile > Funding Tab > Credit Card), CCV can be left blank. Ensure that you use the same email address as your sandbox test account and correct billing/shipping addresses.
  Sometimes transactions could be rejected with a 10626 error if the order amount is too high

Key configurations for PayPal Pro

Configuration Mandatory Notes 
Api user name  Username from your PayPal Merchant (Profile > API Credentials Tab > Username) 
Api user password  Password from your PayPal Merchant (Profile > API Credentials Tab > Password) 
Signature  Signature from your PayPal Merchant (Profile > API Credentials Tab > Signature) 
HTML Form with card input fields   
Environment mode  Environment mode used by callback verification. Values can be: sandbox or live 
Api call url  Api call url
live - https://api-3t.paypal.com/nvp
sandbox - https://api-3t.sandbox.paypal.com/nvp

IPN

All PayPal payment methods use IPN (callback) to notify of the transaction outcome. As part of the callback YC performs validation of the request. This is done using PayPal SDK library which essentially performs an http request to PayPal server to verify that this IPN originated from their servers. If this verification request fails the validation mechanism fails and thus the order is not updated.

To fix this issue you need to re-send the IPN message from the PayPal account (see this stack overflow thread), which can be performed from the IPN history section: https://www.paypal.com/?cmd=_display-ipns-history. Simply find the failed IPN and re-send it. This will re-validate the callback and update the order.

On new interface you can find the IPN history section in More > Sitemap > IPN History. Note that you need to login with your test merchant's account to sandbox to access this menu.

LiqPay

To create LiqPay account go to https://www.liqpay.com and register. Note that LiqPay uses SMS messages in order to send pin codes for logging in to your account so you will need a valid mobile phone number.

After registration is completed you will be provided with:

  1. public_key
  2. private_key

LiqPay (no refund)

Key configurations for basic LiqPay (no refund) with manual refunds

Configuration Mandatory Notes 
Merchant ID  
  • public_key* from your LiqPay account
Merchant signature  
  • private_key* from your LiqPay account
Form post URL  https://www.liqpay.com/api/
Payment method  Credit cart payments - card
LiqPay account - liqpay 
Page URL to show payment result  Page where customer is taken after clicking "Return" button on payment page.
Recommended is http://www.yourdomain.com/yes-shop/paymentresult configured in wicket.xml 
Callback URL with payment result  This is server-to-server transaction callback that LiqPay server performs right before the customer sees result on the external form page.
Callback filter is mapped to http://www.yourdomain.com/yes-shop/liqpaycallback

LiqPay

This payment gateway allows to automatically refund money when products are returned.

The configuration is the same as for "LiqPay (no refund)" however you must contact LiqPay and activate refund callbacks for your server IP address.

Key configurations for LiqPay with refunds (all configuration as same as "LiqPay no refund" but with the following differences):

Callback URL with payment result  This is server-to-server transaction callback that LiqPay server performs right before the customer sees result on the external form page.
Callback filter is mapped to http://www.yourdomain.com/yes-shop/liqpaynrcallback (note nr in URL) 

PostFinance

Enabling PostFinance
  Play 6:39

To create a test account you need to contact https://www.postfinance.ch. They will ask to fill out a form with your details.

After registration is completed you will be provided with (via email):

  • PSPID which is affiliation name in PostFinance, also use as login
  • Temporary password to login to your account

To access your account go to https://e-payment.postfinance.ch/. For test environment click "Access to test" link before filling out login form.

PostFinance

Key configurations for basic PostFinance

Configuration Mandatory Notes 
Your affiliation name  PSPID (login) from your PostFinance account 
Form action  test - https://e-payment.postfinance.ch/ncol/test/orderstandard.aspproduction - https://e-payment.postfinance.ch/ncol/prod/orderstandard.asp
SHA-IN signature  Signature for validation post to external form.
SHA-IN must be configured in
"Configuration > Technical Information > Global Security Parameters" with the following:
  • Each parameter followed by the passphrase
  • SHA-1
  • UTF-8
    and "Configuration > Technical Information > Data and Origin Verification" with the following:
  • http://www.yourdomain.com/
  • SHA-IN signature (e.g. MySecretPass123!#)
  Currencies  Enable currencies that you support at "Configuration > Account > Currency" 
  Operation  For this configuration is it preset to SAL, which is AUTH_CAPTURE operation (i.e. funds are captured straight away) 
(Absolute) URL of your home page.  http://www.yourdomain.com/yes-shop/
(Absolute) URL of your catalogue.  http://www.yourdomain.com/yes-shop/
URL for accepted payment  http://www.yourdomain.com/yes-shop/paymentresult?hint=okCan also be configured in "Configuration > Technical Information > Transaction Feedback" 
URL for declined payment  http://www.yourdomain.com/yes-shop/paymentresult?hint=declinedCan also be configured in "Configuration > Technical Information > Transaction Feedback" 
URL for error during payment  http://www.yourdomain.com/yes-shop/paymentresult?hint=exceptionCan also be configured in "Configuration > Technical Information > Transaction Feedback" 
URL for cancelled payment  http://www.yourdomain.com/yes-shop/paymentresult?hint=cancelCan also be configured in "Configuration > Technical Information > Transaction Feedback" 
  Callback URL  Server to server callback configured in PostFinance
"Configuration > Technical Information > Transaction Feedback" with the following:
SHA-OUT signature  Signature for validation of server-to-server transaction callback.
Configured at "Configuration > Technical Information > Transaction Feedback" (e.g. MySecretPass123!#) 
Enable itemised data    Must be false. There is a rounding issue in PostFinance API that they need to fix before this can be enabled 

PostFinance (manual capture)

Manual capture allows merchant to control when the capturing of funds happen.

Key configurations for basic PostFinance (Manual Capture) (all configuration as same as regular PostFinance but with the following differences)

Configuration Mandatory Notes 
  Operation  For this configuration is it preset to RES, which is AUTH operation (i.e. funds are not captured straight away)
How funds are captured exactly is configured in "Configuration > Technical Information > Global Transaction Parameters".
Note: that this means that at shipping phase there will be a manual override in YC to capture funds as there is no callback from PostFinance 
  Callback URL  Server to server callback configured in PostFinance
"Configuration > Technical Information > Transaction Feedback" with the following:

Test cards and addresses

Usually test cards resources are specified in documentation of specific payment providers.

  For PayPal Pro use test cards provided on the "Funds" tab of your test accounts' profile 

Here are some examples of working test cards:

Card Number CVV Expiry 
VISA 4111 1111 1111 1111 123 12/2020 

Some payment providers have AVS (Address Verification System, so the address has to be correct as well)

Street 1 City State Country Post code Phone Notes 
1295 Charleston Road Mountain View CA US 94043 650-965-6000   As this is a US address order currency must be USD 
Tags:
Created by Denis Pavlov on 2018/03/09 21:17
    
YesCart.org © 2009 - 2018
v.1.0.0