Process flow
PayPal process flow
Configuration for PayPal
PayPal Sandbox test account
If you prefer to test the integration before going Live, and you do not have PayPal Sandbox test account, you should create PayPal Sandbox test account as first step.
1. Login to https://developer.paypal.com/ and go to "Testing Tools" => "Sandbox Accounts"
2. Click "Create account" and choose "Business (Merchant Account)" & Germany as "Country / Region".
3. Choose "View/Edit account"
4. Take "Email ID" and "System Generated Password" and use them as Login/Pass for Sandbox on the next step.
Grant permissions to for transaction processing
In order to allow processing transactions on your behalf, corresponding permissions should be granted to .
Permissions can be granted to under your PayPal account. Please use the following links to login into your PayPal account and follow the steps.
Send PayerID to Merchant Services
To complete merchant setup on side, you should send PayerID to Merchant Services.
PayPal Sandbox
1. Login to https://developer.paypal.com/dashboard and go to "Testing tools" --> "Sandbox Accounts".
2. Select the appropriate Sandbox merchant account and notify Merchant Services about "Account ID".
PayPal Production
PayerID can be found under your PayPal account by https://paypal.com/myaccount/settings/ , as follows. PayerID uniquely identifies merchant in PayPal.
PayPal Smart Button
There are two ways for integration of PayPal V2 via . First one is by using JavaScript module. Another one is setting up PayPal button by copy-paste of JavaScript code, which is prepared below.
JavaScript module
The PayPal JavaScript module provides client-side technology to complement with the integration of PayPal V2 via .
- The module provides quick installation, using one command
- Configuration is done in one place
- Suitable for all platforms which support JS
For the module and the installation instruction please refer to Readme.
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/reference/#link-buttons.
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://paymentpage.axepta.bnpparibas/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://epayment.axepta.bnpparibas/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>
offers 3 possible options for a payment.
- SALE (capture=Auto) (when automatically sends Capture for a payment; this is the default scenario matching most merchant's needs)
- AUTHORIZE (capture=Manual + txtype=Auth) (when Capture should be sent later by the merchant as a separate API call)
- ORDER (capture=Manual + txtype=Order) (when Authorize and Capture should be sent later by the merchant as 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.
Banner
It is possible to show a banner with additional details about usage of "Pay Later" option just under "Pay Later" button.
For this, the following code should be added to the body of product page, and parameter "data-pp-amount" should be updated by actual amount value.
<div data-pp-message data-pp-style-layout="text" data-pp-style-logo-type="inline" data-pp-style-text-color="black" data-pp-style-text-size="12" data-pp-amount=<amount-value> data-pp-placement="product" </div>
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/
interface
Calling the interface
Use the following URL and parameters to initiate a PayPal payment in the form:
ExternalServices/paypalorders.aspx |
With this URL 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.
also supports the separation of authorisation and capture for PayPal Express Checkout. You can set parameters via the 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 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. therefore supports several alternatives for the processing of PayPal payments: we shall be happy to advise you about the implementation of PayPal.
Parameters for PayPal payments
Return parameters for URLSuccess, URLFailure and URLNotify with PayPal
Notice: The address parameters are always transmitted to the shop but are empty if no address data has been exchanged.
PayPal Vault feature
PayPal Vault feature has two use cases.
Use case 1: Showing stored payment methods in PayPal mini-browser
In case PayPal Vault is activated on merchant level on side and parameter CustomerID is provided in request, PayPal mini-browser will show already stored payment options like follows.
How it works:
- Merchant is configured for PayPal Vault on side.
- In this case, by calling paypalorders.aspx sends to PayPal a flag to offer the customer the option "store payment method for further usage" in PayPal mini-browser.
- If the customer agrees with the option, the merchant will receive in response parameters CustomerID and VaultID.
- Next time, if the merchant sends CustomerID in paypayorders.aspx request, the customer will see previously stored payment methods (as on the picture above).
Use case 2: Reference transactions (or billing agreement)
How it works:
- Merchant is configured for PayPal Vault on side.
- In this case, by calling paypalorders.aspx sends to PayPal a flag that this is a first payment in a set of payments and PayPal asks the customer to confirm the set of transacitons in PayPal mini-browser.
- If the customer agrees with this, the merchant will receive in response parameters CustomerID and VaultID.
- To initiate next payment (from set of confirmed payments), merchant calls paypalvault.aspx and sends VaultID in parameter BillingAgreementID.
Important note
For both use cases, two notifications will be sent to URLNotify for request paypalorders.aspx. This is because PayPal processes the request in two steps in case of PayPal Vault. During first step, a Vault is created on PayPal side. On this stage parameters CustomerID and VaultID could not be returned. During second step, the Vault is approved on PayPal side. On this step parameters CustomerID and VaultID are created and returned.
So, it is possible that there are no parameters CustomerID and VaultID in first notification. In this case, please wait for second notification (in most of the cases it comes in 5-10 seconds).
Calling the interface for method "shortcut"
The PayPal "shortcut" method enables a changed transaction procedure which takes the customer back to the shop for payment confirmation. To complete this PayPal payment in the next step, use the following URL and parameters:
paypalComplete.aspx |
Please note the following process description which is triggered by sending "PayPalMethod=shortcut".
By sending "PayPalMethod=shortcut" the end customer will be redirected to PayPal, there he will execute a pre-confirmation (this is not yet the final payment confirmation) and the customer will be redirected back to the store.
The redirect / return is executed here on the URLFailure with the following response parameters. Please note that there is a change here to the older PayPal Classic API. For these the redirect / return is processed on the URLSuccess and via response the open status is reported as follows "Status=AUTHORIZE_REQUEST&Code=00000000&Description=REQUEST".
Please contact the if if you as a retailer would like to process the redirect to URLSuccess and the code and description should be "Status=AUTHORIZE_REQUEST&Code=00000000&Description=REQUEST".
PayPal V2 Response Parameter - open status:
- Status=AUTHORIZE_REQUEST
- Code=21500985
- Description=PENDING
Furthermore it should be noted that the merchant can change the amount for the paypalComplete request after the customer has returned to the open status. However, PayPal has its own restrictions so that the amount cannot be changed upwards arbitrarily. For more details on this topic, please contact your PayPal account manager.
Parameters for PayPal payments with method "shortcut"
Response parameters for PayPal with method "shortcut"
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:
Authorize.aspx |
Parameters for PayPal authorization
Response parameters for PayPal authorization
Capture
To carry out a capture for PayPal via a Server-to-Server connection, please use the following URL:
capture.aspx |
Parameters for PayPal captures
Result parameters for PayPal captures
Credit with reference
To carry out a credit with a reference transaction for PayPal, please use the following URL:
credit.aspx |
Parameters for PayPal credits with reference transaction
Response parameters for PayPal credits with reference transaction
Reversal
In order to cancel a transaction with PayPal, please use the following URL:
reverse.aspx |
Parameters for PayPal reversals
Result parameters for PayPal reversals
Reference Transactions
Prerequisites
- Option "Reference Transactions“ has to be activated in your PayPal account. Please request the activation at PayPal directly.
Process
The process contains two steps.
Billing Agreement Creation (initial Billing Agreement transaction)
- Call PayPalOrders.aspx with TxType=BAID (refer to ). In response returns URL. All parameters except the following are optional in case of TxType=BAID.
- By the URL customer logs in to PayPal account and approves the Billing Agreement.
- Once the Billing Agreement is approved by the customer, Billing Agreement ID will be send using URLNotify.
Billing Agreement Usage
- Call PayPalRefTrans.aspx (described below, as server-to-server request) with BillingAgreementID="Billing Agreement ID" created on previous step. Customer does not need to login to PayPal account for transaction approval anymore.
Revoking of Billing Agreement
- A customer can revoke Billing Agreement ID in own PayPal account.
- If a customer revokes Billing Agreement ID no further subsequent reference transactions (using this Billing Agreement ID) are possible. It is also not possible to reactivate this Billing Agreement ID.
Request
In order to initiate a PayPal subscription payment, please use the following URL:
paypalreftrans.aspx |
Parameters for PayPal Reference Transactions
Response
Result parameters for PayPal Reference Transactions
Vault
Prerequisites
- Option "Vault“ has to be activated in your PayPal account. Please request the activation at PayPal directly.
Process
The process contains two steps.
Vault creation (initial Vault transaction)
- Call PayPalOrders.aspx with TxType=BAID (refer to ). In response returns URL. All parameters except the following are optional in case of TxType=BAID.
- By the URL customer logs in to PayPal account and approves the Vault.
- Once the Vault is approved by the customer, VaultID will be send using URLNotify.
Vault usage
- Call PayPalRefTrans.aspx (described below, as server-to-server request) with VaultID="VaultID" created on previous step. Customer does not need to login to PayPal account for transaction approval anymore.
Revoking of Vault
- A customer can revoke VaultID in own PayPal account.
- If a customer revokes VaultID no further subsequent reference transactions (using this VaultID) are possible. It is also not possible to reactivate this VaultID.
Request
In order to initiate a PayPal subscription payment, please use the following URL:
paypalvault.aspx |
Parameters for PayPal Vault transactions
Response
Result parameters for PayPal Vault transactions
Package tracking
Using Package Tracking feature, it is possible to assign parcel tracking numbers to PayPal orders after a shipping label is created. Providing the shipping details helps to identify items in transit, and improve the in-app payer experience. Also, the shipping information is used by PayPal in dispute resolution process.
To add or remove shipping details via a Server-to-Server connection, please use the following URL:
trackdelivery.aspx |
Parameters for PayPal Package Tracking
Response parameters for PayPal Package Tracking
Batch processing via the interface
MultiExcerpt named Batch_Intro was not found -- Please check the page name and MultiExcerpt name used in the MultiExcerpt-Include macro
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:
Description of the possible batch versions
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>) PAYPAL,REFTRANS,<Amount>,<Currency>,<TransID>,(<RefNr>),(<OrderDesc>),(<Capture>),(<TxType>),<BillingAgreementId> 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>)
MultiExcerpt named Batch_Request_Intro was not found -- Please check the page name and MultiExcerpt name used in the MultiExcerpt-Include macro
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>,(<TID>,)<Status>,<Code>,<CodeExt> PAYPAL,REFTRANS,<Amount>,<Currency>,<TransID>,(<RefNr>),(<OrderDesc>),(<Capture>),(<TxType>),<BillingAgreementId>,<PayID>,<Status>,<Code>,<CodeExt> FOOT,<CountRecords>,<SumAmount>
MultiExcerpt named Batch_Response_Intro was not found -- Please check the page name and MultiExcerpt name used in the MultiExcerpt-Include macro
Description of result parameters within the record for Batch files













