Configuration for PayPal

To process PayPal transactions via the as merchant you need to have a PayPal business account . You also need to enable the PayPal interface for use via  and to make the necessary settings for receiving payments.

Create and configure the PayPal business account

1. Please call the PayPal URL of your country, e.g. http://www.paypal.co.uk.
2. Use the Button „Sign Up“ to open a new business account
   
   
3. The following page shows possible account types which can be created.
4. Please choose “Business Account” and press “Continue”.
   
   
5. Now you are forwarded to the page "Create Business Account". Please enter your email address, which will be used for your PayPal Account and press “Continue”.
   
   
6. Please enter here your Business information. Accept the User Agreement and press the button “Agree and Continue”.
   
   
7. Please complete the required information about your company on the next pages.
8. In the next step you will get an email to confirm your email address. Please confirm your email address.
   
   
9. Please add the further required information about your company.
   
   

Setting up the API permission

In order to process PayPal transactions through you will need to setup an API permission Therefore please complete the six steps explained below.

1. Please go to the menu -> Profile -> Profile and Settings
   
   
2. Please go to „Activity“ and then select „API access“
    
    
   
3. Inside the API Access area, please choose “Grant API permission”
    
   
4. Please enter the following API Third Party Username and press the button “Lookup” frank.arnoldt_api1.computop.de
   
5. Please check the following API Access Level boxes, all other boxes remain unchecked. Press “Add” to confirm and finish API permission settings.
   - Use Express Checkout to process payments
   - Issue a refund for a specific transaction
   - Authorise and capture your PayPal transactions
   - Obtain information about a single transaction
   - Search your transactions for items that match specific criteria and display the results
    
   
6. You will get the confirmation, that the third party supplier „frank.arnoldt_api1.computop.de“ was added.
    
   

Setting up PayPal-API permissions for Sandbox

For the PayPal Sandbox you can set up API permissions with the following steps.

1. At https://developer.paypal.com below "Accounts" --> (Accountname) --> "Manage accounts" --> "View/ edit account" you will find the credentials of the respective merchant account.
   
2. With this credentials please login at https://sandbox.paypal.com.
   
   
3. Click on the name on the upper right and go to "Account settings".
   
   
4. Click on "API access" --> "Set up API permission" --> Enter "test_paypal_api_api1.computop.com".
   
   
5. Please check the boxes for following permissions:
   - Use PayPal Express to process payments
   - Issue a refund for a specific transaction
   - Authorise and capture your PayPal transactions
   - Obtain information about a single transaction
   - Search your transactions for items the match specific criteria and display the results

Settings for Payment Receiving Preferences

1. Please go to “Profile” and click on “Profile and Settings”.
   
   
   
2. Below "Payment preferences" please select "Block payments" with the link “Update”.
    
   
3. Please use the following settings.
   - Block payments sent in a currency not provided
   - Block accidental payments with duplicate invoice IDs
   - Set up automatic payments for eBay-refunds.
   - Display “Add Instructions to Seller” text input field
    
   Please confirm your selected options by clicking on the "Save" button.
   

interface

Calling the interface

Use the following URL and parameters to initiate a PayPal payment in the form:

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: Please note that a PayPal connection in the shop via i-Frame is not possible due to PayPal-Regulations. Express Checkout always connects the Customer directly to PayPal.

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.

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:

Key Format CND Description Beschreibung PayID an32 M ID assigned by for the payment. Enter the PayID from the response from paypal.aspx received in the previous transaction procedure. Vom vergebene ID für die Zahlung. Übergeben Sie hier die PayID aus der Antwort von paypal.aspx, die Sie im bisherigen Transaktionsablauf erhalten haben. RefNr ans..30 O Unique reference number eindeutige Referenznummer OrderDesc(n) ans..2048 O Customers shopping basket in the form: OrderDesc(n)=Name,Amount,Number,Quantity,Description,Tax OrderDesc2 to max. OrderDesc99 permissible For correct execution of displaying function all OrderDesc(n) Amounts must equal to the parameter Amount. If OrderDesc(n) is used, there must be valid: Amount=ItemTotal+TaxTotal+SHAmount Notice: If OrderDesc(n) is changed also the Amount has to be modified. Warenkorb des Kunden in der Form: OrderDesc(n)=Name,Amount,Number,Quantity,Description,Tax OrderDesc2 bis max. OrderDesc99 zulässig Zur korrekten Ausführung der Darstellungsfunktion müssen alle OrderDesc(n) Amounts mit dem übergebenen Parameter Amount übereinstimmen. Wenn OrderDesc(n) verwendet wird, muss gelten: Amount=ItemTotal+TaxTotal+ShAmount Hinweis: Bei Änderung von OrderDesc(n) muss auch der Amount angepasst werden. Address information. When you transfer these values you can also change an address. Notice: If transferring FirstName, all other values should also be entered. If not transferring FirstName, other address parameters are not taken into account. Adressinformationen. Durch Übergabe dieser Werte ist auch eine Adress-Änderung möglich. Hinweis: Wenn FirstName übergeben wird, sollten auch alle anderen Werte übergeben werden. Wenn FirstName nicht übergeben wird, werden andere Adressparameter nicht berücksichtigt. FirstName ans..30 C Mandatory in order to transfer address information Either the first name only or first and second name if a company name is used as a delivery address. Pflicht, um Adressangaben zu übermitteln: Entweder nur der Vorname oder Vor- und Nachname, falls ein Firmenname als Lieferadresse genutzt wird. LastName ans..30 C Obligatory if FirstName is transmitted: Surname or name of the company of the delivery address Pflicht, wenn FirstName übergeben wird: Nachname oder Firmenbezeichnung der Lieferadresse AddrStreet ans..100 C Obligatory if FirstName is transmitted: Street in the delivery address Pflicht, wenn FirstName übergeben wird: Straßenname der Lieferadresse AddrStreet2 ans..100 C Obligatory if FirstName is transmitted: Street in the delivery address Pflicht, wenn FirstName übergeben wird: Straßenname der Lieferadresse AddrCity ans..40 C Obligatory if FirstName is transmitted: Town/city in the delivery address Pflicht, wenn FirstName übergeben wird: Ortsname der Lieferadresse AddrState ans..40 C Obligatory if FirstName is transmitted: Federal state of the delivery address. The town submitted in AddrCity must be located in the given federal state, otherwise PayPal refused this payment. For possible values please refer to the PayPal-API-reference documentation. Pflicht, wenn FirstName übergeben wird: Bundesland (Bundesstaat) der Lieferadresse. Die in AddrCity übergebene Stadt muss im angegebenen Bundesstaat liegen, sonst lehnt PayPal die Zahlung ab. Mögliche Werte entnehmen Sie bitte der PayPal-API-Reference Dokumentation. AddrZip ans..20 C Obligatory if FirstName is transmitted: Postcode in the delivery address Pflicht, wenn FirstName übergeben wird: Postleitzahl der Lieferadresse AddrCountryCode an2 C Obligatory if FirstName is transmitted: Country code of the delivery country Pflicht, wenn FirstName übergeben wird: Ländercode des Lieferlandes Phone n..20 C Obligatory if FirstName is transmitted: Telephone number Pflicht, wenn FirstName übergeben wird: Telefonnummer

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, call the following URL:

Parameters for PayPal authorization

Response parameters for PayPal authorization

Calling the interface for a capture

To carry out a Capture for PayPal via a Server-to-Server connection please use the following URL:

Parameters for PayPal captures

Result parameters for PayPal captures

Calling the interface for a credit with reference

To carry out a credit with a reference transaction for PayPal, please use the following URL:

Parameters for PayPal credits with reference transaction

Response parameters for PayPal credits with reference transaction

Calling the interface for credits without reference

Use the following URL and parameters to initiate a credit without reference transaction for PayPal payment in the form:

Parameters for PayPal credits without reference transaction

Response parameters for PayPal credits without reference transaction

Call of interface for reversals

To cancel a transaction with PayPal, please use the following URL:

Parameters for PayPal reversals

Result parameters for PayPal reversals

Call of interface for subscriptions

Requirements

• The option „reference transaction“ has to be activated in your PayPal account. Please request the activation at PayPal directly.
• In addtion, please configure the corresponding permission in your mechant PayPal account
• Charge an existing customer based on a prior transaction
• Obtain authorisation for pre-approved payments and initiate pre-approved transctions
• The option “reference transaction” has to be activated for your MerchantID.

Process

1. In order to process the initial recurring payment use paypal.aspx and add the parameter “RTF=I”. The additional parameter triggers a recurring flag to be recognized by PayPal. If you want to get the „BillingAgreementID“ only with the first request without to show the original amount to the customer, please submit the parameter "txtype=BAID" to . If txtype=BAID is submitted, sets the value automatically to 0,00.
   Please note, that the merchant never may send an amount of 0,00€, because cannot process this.
   That means the merchant has to specify an amount X >0,00 an changes this for PayPal to 0,00.
2. You will receive PayPal`s standard parameters as well as the additional parameter “BillingAgreementID” in  response. Please add and save this parameter in your system.
3. In order to process the second/recurring payment, please use the URL paypalAbo.aspx. In this server-to-server based request, please use the regular parameters as well as the parameter “BillingAgreementID”. The additional parameter triggers the second/recurring payment with reference to the initial recurring payment. This way amount withdrawals are available without the need of a customer login into PayPal.

Notice

• The following addition will be displayed during payment process within the customer`s PayPal account (example):
  "Hereby you authorise –merchant name– for future direct withdrawals from your PayPal account without any action on your part. You can revoke this authorisation at any time within your profile."
• The customer can obtain information about this function within his PayPal account.

Capture on demand (capture=manual + txtype=Order or Auth)

• If you are initiating payments including txtype=Order or Auth returns the "BillingAgreementID" for this action already within the notification. The "BillingAgreementID" is not necessary for the subsequent action capture. Only if a new payment is initiated it is necessary as a referral.

Deleting BillingAgreementID

• The customer can revoke the BillingAgreementID in his PayPal account. The merchant will only be informed about the cancellation if the additional option IPN “instant payment notification” is activated for his account. The activation has to be done by the  as well as PayPal account. Please keep in mind that by activating IPN the merchant receives a notification for each status change of a PayPal payment.
• If a customer revokes the BillingAgreementID no further recurring payments are possible. It is also not possible to reactivate a BillingAgreementID.

Payment processing for subscriptions

The processing of PayPal payments by subscription requires an initial transaction to have been processed via the normal interface. Also the possibility of subscriptions must have been activated previously with both PayPal and . Therefore the option “Reference transaction” muss be arranged with and PayPal. Besides following 3 API Access Level boxes options must be checked in the section “Available permissions” during setup (see section Setting up the API permission above):

- Charge existing accounts based on earlier transactions
- Setup and manage subscription payments
- Request of authorization and initializing PayPal payments via merchant debit

Use the following URL and parameters to initiate a PayPal subscription payment in the form:

Parameters for PayPal subscriptions

Result parameters for PayPal subscriptions

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:

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,ABO,<Amount>,<Currency>,<TransID>,(<RefNr>),(<OrderDesc>),(<Capture>),(<TxType>,)<BillingAgreementId>
FOOT,<CountRecords>,<SumAmount>

Example for Master MID Funktion:

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,<Betrag>,<Währung>,<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>
PAYPAL,ABO,<Amount>,<Currency>,<TransID>,(<RefNr>),(<OrderDesc>),(<Capture>),(<TxType>,)<BillingAgreementId>,<CodeExt>,<PayID>,<Status>,<Code>
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