About PayPal
| Logo |
|
|---|---|
| Info | VR-Payment processes PayPal payments, which offers you worldwide merchant protection and a potential of 425 million international customers in more than 200 countries. PayPal is one of the most popular online payment methods and it can be used in e- and m-Commerce. |
| Type | Payments by eWallet |
General information about PayPal
PayPal has remained at the forefront of the digital payment revolution for more than 20 years. By leveraging technology to make financial services and commerce more convenient, affordable, and secure, the PayPal platform is empowering more than 425 million costomers and merchants in more than 200 markets to join and thrive in the global economy.
Customers in Germany can pay via direct debit, giropay or credit card (American Express, Diners Club, Discover, MasterCard, Visa). Members log into their PayPal account with their email address and a password during checkout and choose the preferred funding source - direct debit, credit card, PayPal credit (Pay Later) and, if applicable purchase on account or by instalment.
For more details visit https://www.paypal.com/.
PayPal Shortcut (former "Express Checkout Shortcut (ECS)")
VR-ePayment Gateway offers the PayPal Shortcut to shorten the order process: Your customer does not need to enter any address data but rather click on Checkout with PayPal in the shopping cart area, log on and select the invoice- and delivery address retained by PayPal. VR-ePayment Gateway then sends the delivery address as a result parameter back to your shop.
Buyers and vendors are protected
PayPal offers buyers and merchants extensive buyer/vendor protection in case "Pay with PayPal" is used as payment method (this excludes alternative payment methods). Buyers are able to claim money back from PayPal in the event of non-fulfilment of a contract of sale. With address verification and PayPal seller protection PayPal removes the merchant of the risk of payment failures in the case of direct debit payments, German credit card payments and unjustified customer complaints. Vendor protection is always linked to PayPal rules and conditions. PayPal risk management with buyer protection and address verification is provided to you via the VR-ePayment Gateway.
Payment online globally
PayPal is particularly beneficial for overseas customer acquisition. VR-ePayment Gateway supports all currencies and markets offered by PayPal. In many countries PayPal offers customers typical payment methods for their country. Customers abroad can often use typical payment methods such as prepaid cards in Italy or debit cards in the UK. Integrating PayPal into your shop provides the option to present your customers several payment methods at once. Of course you are also free to just present "Pay with PayPal" only.
Advantages of Orders V2 ("PayPal Checkout")
Orders V2 has the following advantages against PayPal NVP and SOAP.
- Orders V2 is the basis for any future development of products and featured by PayPal. PayPal will not develop any new feature/extend existing functionality based on PayPal NVP and SOAP anymore.
- Orders V2 adheres to the latest compliance standards.
- Orders V2 offers smoother checkout process using a lightbox (by using JS SDK, so-called "PayPal Mini Browser"), a window overlay that appears on top of the merchant’s online shop page. This allows the customer to stay on merchant's page and to not lose focus.
Further information can be found on the webpage of PayPal (https://www.paypal.com).
Important information
Please note that, unlike our currency table, the currencies HUF (Hungarian ‒ Forints), JPY (Japanese Yen) and TWD (Republic of China ‒ Taiwan-Dollars) must be given without decimal places.
Example: To transfer 100.00 HUF one enters the amount=100.
This exception applies only for the PayPal payment method. For more details refer to https://developer.paypal.com/reference/currency-codes/.
On this page
Process flow
PayPal process flow
Configuration for PayPal
To process PayPal transactions via the VR-ePayment Gateway as merchant you need to have a PayPal Business account. You also need to grant API permissions to VR-Payment in order to enable usage of PayPal interface via VR-ePayment Gateway.
Create and configure PayPal Business account
1 Go to https://developer.paypal.com and:
- Create new PayPal Business account, or
- Log-in using your existing PayPal account and upgrade it to PayPal Business account, or
- Log-in using your existing PayPal Business account.
Create and configure REST API app, and obtain REST API credentials
1. Go to https://developer.paypal.com/developer/applications
2. Log-in to Dashboard using your PayPal Business account, and go to “My Apps & Credentials”
3. Create REST API app by clicking on “Create App” button.
4. Enter App Name and click “Create App” button.
5. The page shows “Sandbox account”, “Client ID” and “Secret” for this App.
6. Go to “Accounts” under SANDBOX section.
7. Find the sandbox account for newly created App (refer to step 5), then click “…” button and choose “View/edit account”.
8. The page shows “Email ID” and “System Generated Password” which will to be used later for log-in to sandbox.paypal.com.
Grant permissions to VR-ePayment Gateway for transaction processing
In order to allow VR-Payment processing transactions on your behalf, corresponding permissions should be granted to VR-Payment.
Permissions can be granted to VR-Payment under your PayPal account. Please use the following links to login into your PayPal account and follow the steps.
Send PayerID to VR-Payment Merchant Services
To complete merchant setup on VR-Payment side, you should send PayerID to VR-Payment Merchant Services.
PayerID can be found under your PayPal account by https://paypal.com/myaccount/settings/ , as follows. PayerID uniquely identifies merchant in PayPal. The identifier is the same for Sandbox and Production environments.
PayPal Smart Button
Setting up the PayPal Button
The client-side implementation of PayPal is realized using the PayPal JavaScript SDK.
Depending on your setup, you can use the following script or prepare you own, using the official PayPal JavaScript SDK documentation https://developer.paypal.com/sdk/js/.
While you are testing in sandbox, you can use client-id that matches your test app from PayPal web developer portal. When going live, replace this with the live client-id.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
</head>
<body>
<!-- Set up a container element for the button -->
<div id="paypal-button-container"></div>
<!-- Include the PayPal JavaScript SDK -->
<!-- While you are testing in sandbox, you can use client-id that matches your test app from PayPal web developer portal. When going live, replace this with the live client-id provided by Paypal -->
<script type="text/javascript" src="https://www.paypal.com/sdk/js?client-id=myClientID¤cy=EUR&disable-funding=giropay,sofort,sepa,card&intent=capture"></script>
<!-- Initialize and show PayPal button -->
<script type="text/javascript">
let mid = "YOUR MERCHANTID";
let len = "LEN OF UNENCRYPTED BLOWFISH STRING";
let data = "BLOWFISH ENCRYPTED STRING";
let payid;
if (len != '' && data != '') {
// Set the request parameter MerchantID, Len and Data
const params = new URLSearchParams({
MerchantID: mid,
Len: len,
Data: data
});
// Render the PayPal button into #paypal-button-container
paypal.Buttons({
// Call your server to set up the transaction
createOrder: function(data, actions) {
return fetch('https://vr-epayment-gateway.de/ExternalServices/paypalorders.aspx', {
method: 'POST',
body: params
}).then(function (res) {
return res.text();
}).then(function(orderData) {
var json = stringToObj(orderData);
payid = json.PayID;
return json.orderid;
});
},
// Call cbPayPal.aspx for continue sequence
onApprove: function (data, actions) {
var rd = "MerchantId=" + mid + "&PayId=" + payid + "&OrderId=" + data.orderid;
window.location = "https://vr-payments.gateway/cbPayPal.aspx?rd=" + window.btoa(rd);
}
}).render('#paypal-button-container');
}
function stringToObj (string) {
var newobj = {};
string.split('&').forEach(function (value) {
var keypair = value.split('=');
newobj[keypair[0]] = keypair[1];
});
return newobj;
}
</script>
</body>
</html>
Enabling PayPal Pay Later Button
The above piece of code contains the following line. In this line it will be possible to define which funding sources will be allowed in the web shop.
<script type="text/javascript" src="https://www.paypal.com/sdk/js?client-id=sb¤cy=EUR&disable-funding=giropay,sofort,sepa,card&intent=capture"></script>
The line corresponded to the following button. By default (using the above line) only PayPal button will be available.
If it is required to have PayPal Pay Later Button in addition to standard PayPal button, the button can be enabled by using parameter enable-funding like follows.
<script type="text/javascript" src="https://www.paypal.com/sdk/js?client-id=sb¤cy=EUR&disable-funding=giropay,sofort,sepa,card&enable-funding=paylater"></script>
As a result the following two buttons will appear.
Full list of values for disable-funding and enable-funding can be found by the link below.
https://developer.paypal.com/docs/regional/th/checkout/reference/customize-sdk/#components
Parameter intent
The above piece of code contains the following line.
<script type="text/javascript" src="https://www.paypal.com/sdk/js?client-id=sb¤cy=EUR&disable-funding=giropay,sofort,sepa,card&intent=capture"></script>
VR-ePayment Gateway offers 3 possible options for a payment.
- SALE (when VR-ePayment Gateway automatically sends Capture for a payment; this is the default scenario matching most merchant's needs)
- AUTHORIZE (when Capture should be sent later by the merchant as a separate API call)
- ORDER (when Authorize and Capture should be sent later by the merchant as a separate API calls)
Parameter intent in the above line must be in synch with these options.
If SALE option is used, parameters intent must be set to "capture" as below.
<script type="text/javascript" src="https://www.paypal.com/sdk/js?client-id=sb¤cy=EUR&disable-funding=giropay,sofort,sepa,card&intent=capture"></script>
If AUTHORIZE or ORDER option is used, parameters intent must be set to "authorize" as below.
<script type="text/javascript" src="https://www.paypal.com/sdk/js?client-id=sb¤cy=EUR&disable-funding=giropay,sofort,sepa,card&intent=authorize"></script>
It is important to set proper value for parameter intent, otherwise an error appears.
PayPal Button Style
The above piece of code for PayPal Button does not have any style-related parameters. This piece of code assumes default PayPal style for the button as follows.
PayPal allows to define different PayPal Button style by using parameters shape, color, layout and label. Full list of style-related parameters can be find by the following link.
https://developer.paypal.com/docs/checkout/advanced/style-guide/
VR-ePayment Gateway interface
Format Description a alphabetical as alphabetical with special characters n numeric an alphanumeric ans alphanumeric with special characters ns numeric with special characters bool boolean expression (true or false) 3 fixed length with 3 digits/characters ..3 variable length with maximum 3 digits/characters enum enumeration of allowed values dttm ISODateTime (YYYY-MM-DDThh:mm:ss) Abbreviation Description CND condition M mandatory O optional C conditional Notice: Please note that the names of parameters can be returned in upper or lower case.Definitions
Data formats
Abbreviations
Comment If a parameter is mandatory, then it must be present If a parameter is optional, then it can be present, but it is not required If a parameter is conditional, then there is a conditional rule which specifies whether it is mandatory or optional
Calling the interface
Use the following URL and parameters to initiate a PayPal payment in the VR-ePayment Gateway form:
https://vr-epayment-gateway.de/ExternalServices/paypalorders.aspx |
With this URL VR-ePayment Gateway supports two different PayPal methods: One the one hand you can offer PayPal quite normally as an additional payment method for the conclusion of a sale. Otherwise you can use PayPal Express Checkout Shortcut, which connects the customers from the shopping cart directly to PayPal, where they can then select their delivery and invoicing address. The customer saves having to re-enter address details and you, as the merchant, enjoy PayPal vendor protection.
VR-ePayment Gateway also supports the separation of authorisation and capture for PayPal Express Checkout. You can set parameters via the VR-ePayment Gateway to control whether the amount on the customer's PayPal account should be blocked or captured immediately.
Notice: One of the following conditions must be fulfilled to enable you to benefit from PayPal seller protection. Either the customer uses PayPal Express Checkout and selects a delivery address which it has saved previously with PayPal, which VR-ePayment Gateway transmits to your shop. Or your shop transmits the already known delivery address to PayPal. Seller protection applies only if the goods have been supplied to this specified address. There may be no more than 3 days between the authorisation of the amount in the customer's PayPal account and capture if you wish to benefit from seller protection. VR-ePayment Gateway therefore supports several alternatives for the processing of PayPal payments: we shall be happy to advise you about the implementation of PayPal.
Notice: For security reasons, VR-ePayment Gateway rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter. The following table describes the encrypted payment request parameters:
The following table gives the result parameters which VR-ePayment Gateway transmits to URLSuccess or URLFailure and URLNotify. If you have specified the Response=encrypt parameter, the following parameters are sent Blowfish encrypted to your system:
pls. be prepared to receive additional parameters at any time and do not check the order of parameters the key (e.g. MerchantId, RefNr) should not be checked case-sentive
Notice: The address parameters are always transmitted to the shop but are empty if no address data has been exchanged.
Calling the interface for a separate authorization
For a PayPal payment the ORDER can be separated from the subsequent authorization and the following steps. Separate authorization is only possible after the order (TxType=Order) is completed.
For a separate authorization with PayPal, please use the following URL:
https://vr-epayment-gateway.de/Authorize.aspx |
Notice: For security reasons, VR-ePayment Gateway rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter. The following table describes the encrypted payment request parameters:
The following table describes the result parameters with which the VR-ePayment Gateway responds to your system pls. be prepared to receive additional parameters at any time and do not check the order of parameters the key (e.g. MerchantId, RefNr) should not be checked case-sentive
Capture
To carry out a capture for PayPal via a Server-to-Server connection, please use the following URL:
https://vr-epayment-gateway.de/capture.aspx |
Notice: For security reasons, VR-ePayment Gateway rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter. The following table describes the encrypted payment request parameters:
The following table describes the result parameters with which the VR-ePayment Gateway responds to your system pls. be prepared to receive additional parameters at any time and do not check the order of parameters the key (e.g. MerchantId, RefNr) should not be checked case-sentive
Credit with reference
To carry out a credit with a reference transaction for PayPal, please use the following URL:
https://vr-epayment-gateway.de/credit.aspx |
Notice: For security reasons, VR-ePayment Gateway rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter. The following table describes the encrypted payment request parameters:
The following table describes the result parameters with which the VR-ePayment Gateway responds to your system pls. be prepared to receive additional parameters at any time and do not check the order of parameters the key (e.g. MerchantId, RefNr) should not be checked case-sentive
Credit without reference
In order to initiate a credit without reference transaction for PayPal payment, please use the following URL:
https://vr-epayment-gateway.de/paypalcreditEx.aspx |
Notice: For security reasons, VR-ePayment Gateway rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter. The following table describes the encrypted payment request parameters:
Parameters for PayPal credits without reference transaction
The following table describes the result parameters with which the VR-ePayment Gateway responds to your system pls. be prepared to receive additional parameters at any time and do not check the order of parameters the key (e.g. MerchantId, RefNr) should not be checked case-sentive
Reversal
In order to cancel a transaction with PayPal, please use the following URL:
https://vr-epayment-gateway.de/reverse.aspx |
Notice: For security reasons, VR-ePayment Gateway rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter. The following table describes the encrypted payment request parameters:
The following table describes the result parameters with which the VR-ePayment Gateway responds to your system pls. be prepared to receive additional parameters at any time and do not check the order of parameters the key (e.g. MerchantId, RefNr) should not be checked case-sentive
Result parameters for PayPal reversals
Batch processing via the interface
Basic information about using Batch files and about their structure can be found in the Batch Manager manual. Within batch processing not alle functions are available which are usually available for the online interface.
This section describes the parameters which must be transferred within the data set (Record) for executing a PayPal payment and which information can be found within the response file about the payment status.
For Batch calls there must be considered batch versions, from which optional parameters depend. All version designations starting with „2.“ pertain calls for a group of enterprises. That means within a batch file for a particular MerchantID can be transferred transactions for other merchants with a separate Sub-MID.
Following table gives an overview of all batch versions that are possible for a specific action and their specialities:
The structure for a PayPal payment within a Batch file to be submitted is the following:
HEAD,<MerchantID>,<Date>,<Version> PAYPAL,Authorize,<Amount>,<Currency>,<TransID>,<PayID> PAYPAL,Capture,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>(,<TID>) PAYPAL,Credit,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>(,<TID>) PAYPAL,CreditEx,<TransID>,(<RefNr>,)<Amount>,<Currency>,<payer>,<note> PAYPAL,Reverse,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>(,<TID>) FOOT,<CountRecords>,<SumAmount>
Example for Master MID function:
HEAD,[Master]MerchantID,Date,2.x Type,Action,[Slave]MID,Amount,Currency,TransID,Data (depends on Action) FOOT,CountRecords,SumAmount
Notice: In Version 1.4 it is also possible to transfer CompleteType together with a Capture action:
PAYPAL,Capture,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>(,<CompleteType>,<TID>)
The following table describes the individual fields and values used within the data set (record) in the batch file:
Description of fields within the record for Batch files
The record area within the response file for Batch transactions looks as follows:
HEAD,<MerchantID>,<Date>,<Version> PAYPAL,Authorize,<Amount>,<Currency>,<TransID>,<PayID>,<Status>,<Code>,<CodeExt> PAYPAL,Capture,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,(TID,)<Status>,<Code>,<CodeExt> PAYPAL,Credit,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,(TID,)<Status>,<Code>,<CodeExt> PAYPAL,CreditEx,<TransID>,(<RefNr>,)<Amount>,<Currency>,<payer>,<note>,<Status>,<Code>,<CodeExt> PAYPAL,Reverse,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,<Status>,<Code>,<CodeExt> FOOT,<CountRecords>,<SumAmount>
The following table describes the response parameters which the Batch Manager saves in the record area for each transaction (standard parameters not explained here, such as <TransID> or <RefNR> and request parameters are returned unchanged and correspond to the call as specified before):
Description of result parameters within the record for Batch files