About PayPal

Logo

Info

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)")

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

Payment online globally

PayPal is particularly beneficial for overseas customer acquisition. 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/.

If you want to use the MassPay functionality, please contact the

to activate this function for you.

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"

Documentation > PayPal V2 > image2023-4-3_16-34-32.png

2. Click "Create account" and choose "Business (Merchant Account)" & Germany as "Country / Region".

Documentation > PayPal V2 > image2023-4-3_16-35-46.png

Documentation > PayPal V2 > image2023-4-3_16-37-16.png

3. Choose "View/Edit account"

Documentation > PayPal V2 > image2023-4-3_16-38-29.png

4. Take "Email ID" and "System Generated Password" and use them as Login/Pass for Sandbox on the next step.

Documentation > PayPal V2 > image2023-4-3_16-41-38.png

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.

<br/>
<script type="text/javascript">
    function sh() {
        alert('Failed to acquire paypal registration link, please contact customer support or try again later.')
    }
  
    function getPPRegUrl(merchId,dataKey,dataLen) {
        const request = new XMLHttpRequest();
        request.open('GET', 'https://www.computop-paygate.com/ExternalServices/paypalorders.aspx?MerchantID='+merchId+'&Len='+dataLen+'&Data='+dataKey, false);
        request.send(null);
        if (request.status === 200) {
            console.log(request.responseText);
            try {
                return request.responseText.split('&').filter(p=>p.startsWith('paypalurl')).map(pv=>pv.substring(pv.indexOf('=')+1))[0]
            } catch (ex) {
                console.log("Unable to extract PP Url");
                sh()
            }
        } else {
            sh()
        }
        return ""
    }

     (function(d, s, id) {
      var js, ref = d.getElementsByTagName(s)[0];
      if (!d.getElementById(id)) {
        js = d.createElement(s);
        js.id = id;
        js.async = true;
        js.src = "https://www.paypal.com/webapps/merchantboarding/js/lib/lightbox/partner.js";
        ref.parentNode.insertBefore(js, ref);
      }

    }(document, "script", "paypal-js"));

</script> 
 <div dir="ltr" style="text-align: center;" trbidi="on">
  <a id="paypal-reg-button-sb" data-paypal-button="true" href="<Action-URL>&displayMode=minibrowser" target="PPFrame"><h3>Sign up for PayPal Sandbox</h3></a>
  <script type="text/javascript">
    
    function setUrlSB(e) {
        const newUrl = getPPRegUrl('VR_PayPal_Onboarding_Sandbox','B2A9541947EDE49D6816CC2B6F9D9416C4C0BFA90369E078093B42632311A37A453224B2ADA9EB418186376231F4FA825E4CC01B883F608F5FFD31A187806B1FC5DC4D6515C03081CC1B02A62DB70E089C0E9B705438183B2F9531A3196A1610BB2F135863D5B344628C1C744460F1E1','105')
        if (newUrl) {
            const elm = e.currentTarget
            if (elm) {
                elm.setAttribute("href", "<Action-URL>&displayMode=minibrowser".replace("<Action-URL>", newUrl))
                return true
            }
        }
        if (!e) e = window.event;
        e.cancelBubble = true;
        if (e.stopPropagation) e.stopPropagation();
        return false
    }

    const ppLinkSB = document.getElementById("paypal-reg-button-sb")
    if (typeof window.addEventListener != "undefined") {
        ppLinkSB.addEventListener("click",setUrlSB);
    } else {
        ppLinkSB.attachEvent("onclick",setUrlSB);
    }

  </script>
</div> <br/>
<div dir="ltr" style="text-align: center;" trbidi="on">
  <a id="paypal-reg-button-prod" data-paypal-button="true" href="<Action-URL>&displayMode=minibrowser" target="PPFrame"><h3>Sign up for PayPal Production</h3></a>
  <script type="text/javascript">
    
    function setUrlProd(e) {
        const newUrl = getPPRegUrl('VR_PayPal_Onboarding_Prod','D26BF9A4F0528FA3BC4F1F1364CB2FD9A4CC34DC1813ED4E3D21F31360A3E130601DEFF6B3C8D7382349E7E993D9A114E41619E79707ABE474612FE349F3113CECA4890982584B0D1F7750FE6CD0E425A28F868E6C05CC1AF83D586A115C17F33902A092B5AE283F','102')
        if (newUrl) {
            const elm = e.currentTarget
            if (elm) {
                elm.setAttribute("href", "<Action-URL>&displayMode=minibrowser".replace("<Action-URL>", newUrl))
                return true
            }
        }
        if (!e) e = window.event;
        e.cancelBubble = true;
        if (e.stopPropagation) e.stopPropagation();
        return false
    }

    const ppLinkProd = document.getElementById("paypal-reg-button-prod")
    if (typeof window.addEventListener != "undefined") {
        ppLinkProd.addEventListener("click",setUrlProd);
    } else {
        ppLinkProd.attachEvent("onclick",setUrlProd);
    }

  </script>
</div>

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".

Documentation > PayPal V2 > image-2023-7-24_18-46-17.png

2. Select the appropriate Sandbox merchant account and notify Merchant Services about "Account ID".

Documentation > PayPal V2 > image-2023-7-24_18-49-15.png

PayPal Production

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.

Documentation > PayPal V2 > image2023-3-29_21-32-47.png

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/.

Documentation > PayPal V2 > PayPal_button.jpg

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 -->
    <!-- Replace <PayerID> with your value, available under your PayPal account --> 
    <!-- Replace <Currency> with the currency which should be used, e.g., EUR -->
    <!-- When going live, replace client-id with the live client-id provided by Computop -->
    <!-- When going live, replace data-partner-attribution-id with the live data-partner-attribution-id provided by Computop --> 
    <script type="text/javascript" src="https://www.paypal.com/sdk/js?client-id=Aavp9mlxVFQydGXJHBVZ0LEL1c1VtBcaPahoHzwu2VienquZGZjDzCXOKH_jDGlzkieWazhrixEEcd4X&merchant-id=<PayerID>&currency=<Currency>&disable-funding=giropay,sofort,sepa,card&intent=capture" data-partner-attribution-id="VRPayment_PSP_Computop_Test"></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.

The line corresponded to the following button. By default (using the above line) only PayPal button will be available.

Documentation > PayPal V2 > image2022-2-16_11-23-36.png

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.

As a result the following two buttons will appear.

Documentation > PayPal V2 > image2022-2-16_11-30-38.png

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.

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.

If AUTHORIZE or ORDER option is used, parameters intent must be set to "authorize" as below.

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.

Documentation > PayPal V2 > image2022-2-16_11-45-12.png

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.

Key	REST	Format	CND	Description	Beschreibung
Amount	"amount": { "value": ...}	n..10	M	Amount in the smallest currency unit (e.g. EUR Cent). Please contact the , if you want to capture amounts <100 (smallest currency unit). If OrderDesc(n) is used, there must be valid: Amount=ItemTotal+TaxTotal+SHAmount.	Betrag in der kleinsten Währungseinheit (z.B. EUR Cent). Bitte wenden Sie sich an den , wenn Sie Beträge < 100 (kleinste Währungseinheit) buchen möchten. Falls OrderDesc(n) verwendet wird, muss gelten: Amount=ItemTotal+TaxTotal+SHAmount

Key	REST	Format	CND	Description	Beschreibung
Capture	"capture": {"auto": "Yes"} "capture": {"manual": "Yes"}	a..6	O	Auto or Manual: determines whether the requested amount is settled immediately or at a later stage. Important Note: Please contact for Manual, to discuss different possibilities of usage.	Auto oder Manual: bestimmt, ob der angeforderte Betrag sofort oder später abgerechnet wird. Wichtiger Hinweis: Bitte wenden Sie sich an den für Manual, um verschiedene Möglichkeiten der Nutzung zu besprechen.
TxType	"payment": {"card": { "transactionType": "Order" }} "payment": {"card": { "transactionType": "Auth" }} "payment": {"card": { "transactionType": "BAID" }}	ans..5	C	Obligatory for Capture=Manual: Transaction type with possible values Order or Auth. For initial Billing Agreement transaction (Billing Agreement creation) TxType=BAID. In case TxType=BAID, all parameters except the following are optional. RefNr MUST be unique for each Billing Agreement creation transaction. MerchantID TransID RefNr Amount Currency OrderDesc TxType URLSuccess URLFailure URLNotify MAC	Pflicht bei Capture=Manual: Transaktionstyp mit den möglichen Werten Order oder Auth. Für die erste Billing Agreement transaction TxType=BAID. Im Fall TxType=BAID sind alle Parameter außer den folgenden optional. RefNr MUSS für jede Transaktion zur Erstellung einer Billing Agreement eindeutig sein. MerchantID TransID RefNr Amount Currency OrderDesc TxType URLSuccess URLFailure URLNotify MAC
PayPalMethod	"payment": {"payPal": { "method": "..." }}	enum	O	The "shortcut" value selects the changed transaction procedure which takes the customer back to the shop for payment confirmation. You then need to call up the interface paypalcomplete.aspx to complete the sale.	Wert "shortcut" wählt den geänderten Transaktionsablauf, bei dem der Kunde für die Zahlungsbestätigung in den Shop zurückgeleitet wird. Zum Abschließen der Bestellung muss anschließend die Schnittstelle paypalcomplete.aspx aufgerufen werden.
RTF	---	ans1	O	Reserved for future use	Für zukünftige Verwendung reserviert
OrderDesc	"order": {"description": "..."}	ans..127	M	Description of purchased goods, unit prices etc.	Beschreibung der gekauften Waren, Einzelpreise usw.
OrderDesc(n)	"order": {"items": "..."}	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.	Warenkorb des Kunden im Format: OrderDesc(n)=Name,Amount,Number,Quantity,Description,Tax OrderDesc2 bis max. OrderDesc99 zulässig Zur korrekten Ausführung der Anzeigefunktion müssen alle OrderDesc(n) Amounts gleich dem -Parameter Amount sein.
TaxTotal	"amount": {"taxTotal": ...}	n..10	C	Mandatory, if +Tax is given in description of OrderDesc(n): Total amount of taxes of all single articles in the smallest currency unit (e.g. EUR Cent) = Sum(Tax*Number)	Pflicht, wenn +Tax in der Beschreibung von OrderDesc(n) angegeben ist: Gesamtbetrag der Steuern aller Einzelartikel in der kleinsten Währungseinheit (z.B. EUR Cent) = Sum(Tax*Number)
ItemTotal	"amount": {"itemTotal": ...}	n..10	C	Mandatory, if +tax is given in description of OrderDesc(n): Gross amount of all single articles in the smallest currency unit (e.g. EUR Cent) = Sum(Amount*Number)	Pflicht, wenn +Tax in der Beschreibung von OrderDesc(n) angegeben ist: Bruttobetrag aller Einzelartikel in der kleinsten Währungseinheit (z.B. EUR Cent) = Sum(Amount*Number)
ShAmount	"amount": {"shippingTotal": ...}	n..10	C	Shipping costs in the smallest currency unit (e.g. EUR Cent). Can be used only in case ShAmount <> 0 and connection with parameters ItemTotal and TaxTotal.	Lieferkosten in der kleinsten Währungseinheit (z.B. EUR Cent). Kann nur verwendet werden, wenn ShAmount <> 0 und in Verbindung mit den Parametern ItemTotal und TaxTotal.

Key

REST

Format

CND

Description

Beschreibung

Account

"payment": {"payPal": { "accountId": "..." }}

ans..128

O

For managing multiple PayPal accounts, Merchant account: ID or e-Mail address for which the request should be submitted to PayPal

Für die Verwaltung mehrerer PayPal-Konten, Händlerkonto: ID oder E-Mail-Adresse, für die die Anfrage an PayPal gesendet werden soll

Language

"language": "..."

an2

O

Language: AU, DE, FR, IT, GB, ES, US; default DE

Sprache: AU, DE, FR, IT, GB, ES, US; Standardwert DE

FirstName

"billing": {"consumer": { "firstName": "..." }}

ans..50

OC

(obligatory for USA and Canada): Either the first name only or first and second name if a company name is used as a delivery address.

(Pflicht für USA und Kanada): Entweder nur der Vorname oder Vor- und Nachname, wenn ein Firmenname als Lieferadresse verwendet wird.

LastName

"billing": {"consumer": { "lastName": "..." }}

ans..50

OC

(obligatory for USA and Canada): Surname or name of the company of the delivery address

(Pflicht für USA und Kanada): Nachname oder Firmenname der Lieferadresse

AddrStreet

"billing": {"addressInfo": { "addressLine1": { "street": "..." }}}

ans..100

OC

(obligatory for USA and Canada): Street in the delivery address

(Pflicht für USA und Kanada): Straßenname in der Lieferadresse

AddrStreet2

"billing": {"addressInfo": { "addressLine2": "..." }}

ans..100

O

2. Street name in the delivery address that contains additional information e.g. packing station or similar. In order to receive this as a response parameter, it needs to be activated separately by the .

2. Straßenname in der Lieferadresse, der weitere Informationen zu Packstation o.ä. enthält. Damit dieser Parameter in der Antwort zurückgeliefert werden kann, muss dieser separat vom aktiviert werden.

AddrCity

"billing": {"addressInfo": { "city": "..." }}

ans..40

OC

(obligatory for USA and Canada): Town/city in the delivery address

(Pflicht für USA und Kanada): Ort in der Lieferadresse

AddrState

"billing": {"addressInfo": { "state": "..." }}

ans..40

OC

(obligatory for USA and Canada): 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 für USA und Kanada): Bundesstaat der Lieferadresse. Der in AddrCity hinterlegte Ort muss im angegebenen Bundesland liegen, ansonsten lehnt PayPal diese Zahlung ab. Mögliche Werte entnehmen Sie bitte der PayPal-API-Referenzdokumentation.

AddrZip

"billing": {"addressInfo": { "postalCode": "..." }}

ans..20

OC

(obligatory for USA and Canada): Postcode in the delivery address

(Pflicht für USA und Kanada): Postleitzahl in der Lieferadresse

AddrCountryCode

"billing": {"addressInfo": { "country": { "A2": "..." }}}

an2

O

Country code of the delivery country

Ländercode in der Lieferadresse

Phone

"billing": {"contactInfo": { "phone": "..." }}

n..20

O

Telephone number

Telefonnummer

NoShipping

n1

O

Handover NoShipping=1 prevents the delivery address registered with Paypal from being displayed.

also offers the option to permanently suppress the delivery address for you on your MID. Please note that the delivery address should only be suppressed in the case of digital goods, as the seller protection is also linked to this. Please contact the for this.

Die Übergabe von NoShipping=1 verhindert, dass die bei Paypal hinterlegte Lieferadresse angezeigt wird.

Zusätzlich bietet das die Variante an, dass wir an Ihrer MID die Unterdrückung der Adresse fest für Sie hinterlegen. Bitte beachten Sie, dass die Lieferadresse nur im Fall digitaler Güter unterdrückt werden sollte, da daran auch der Verkäuferschutz geknüpft ist. Bitte wenden Sie sich dafür an den .

RiskEvaluation

ans..2048

O

Array of key-value pair (base64-encoded). List of keys has to be agreed with PayPal (can be different for different merchants) before usage of parameter RiskEvaluation.

Example:

{
 "additional_data": [
    {
      "key": "sender_first_name",
      "value": "John"
    },
    {
      "key": "sender_last_name",
      "value": "Doe"
    }
]
}

Array von Key-Value-Paaren (Base64-codiert). Die Liste der Schlüssel muss vor der Verwendung des Parameters RiskEvaluation mit PayPal vereinbart werden (kann bei verschiedenen Händlern unterschiedlich sein).

Beispiel:

{
 "additional_data": [
    {
      "key": "sender_first_name",
      "value": "John"
    },
    {
      "key": "sender_last_name",
      "value": "Doe"
    }
]
}

PaymentUnit(n)

ans..2048

O

In case of Multi-Seller Payment (Marketplace functionality) each PaymentUnit(n) is related to a separate Seller (merchant within the Marketplace) and contains JSON object (base64-encoded) with the following format.

Example:

{
        merchantemailaddress: "merchant@example.com",
        merchantid: "XVRKM94GQDXB2",
        amount: "11000",
        itemtotal: "8000",
        taxtotal: "2000",
        shippingamount: "1000",
        invoiceid: "xxxxx",
        orderdescription: "yyyyy",
        orderitems: [
        {
            name: "zzzzz",
            quantity: "1",
            unitamount: "3000",
            tax: "1000",
            description: "xxxx",
            category: "PHYSICAL_GOODS"
        },
        {
            name: "xxxxx",
            quantity: "2",
            unitamount: "2500",
            tax: "500",
            description: "yyyyy",
            category: "DIGITAL_GOODS"
        }
    ]
}

Where MerchantID is PayPal PayerID of the merchant.
InvoiceID must be unique per MerchantID. Merchant cannot use the same InvoiceID twice.
Valid values for Category are DIGITAL_GOODS, PHYSICAL_GOODS and DONATION. In scope of one PayPal transaction it is allowed to use 1) DIGITAL_GOODS and/or PHYSICAL_GOODS; 2) DONATION. DONATION cannot be combined with DIGITAL_GOODS or PHYSICAL_GOODS.
ItemTotal is the summary of UnitAmount * Quantity of all Order Items related to this merchant.
TaxTotal is the summary of Tax of all Order Items related to this merchant.
Amount is the summary of ItemTotal, TaxTotal and ShippingAmount of this merchant.

Bei einer Multi-Seller-Zahlung (Marktplatzfunktionalität) bezieht sich jede PaymentUnit(n) auf einen separaten Verkäufer (Händler innerhalb des Marktplatzes) und enthält ein JSON-Objekt (Base64-codiert) mit dem folgenden Format.

Beispiel:

{
        merchantemailaddress: "merchant@example.com",
        merchantid: "XVRKM94GQDXB2",
        amount: "11000",
        itemtotal: "8000",
        taxtotal: "2000",
        shippingamount: "1000",
        invoiceid: "xxxxx",
        orderdescription: "yyyyy",
        orderitems: [
        {
            name: "zzzzz",
            quantity: "1",
            unitamount: "3000",
            tax: "1000",
            description: "xxxx",
            category: "PHYSICAL_GOODS"
        },
        {
            name: "xxxxx",
            quantity: "2",
            unitamount: "2500",
            tax: "500",
            description: "yyyyy",
            category: "DIGITAL_GOODS"
        }
    ]
}

Dabei ist MerchantID die PayPal PayerID des Händlers.
InvoiceID muss pro MerchantID eindeutig sein. Der Händler darf dieselbe InvoiceID nicht zweimal verwenden.
Gültige Werte für die Category sind DIGITAL_GOODS, PHYSICAL_GOODS und DONATION. Für eine PayPal-Transaktion ist die Verwendung von 1) DIGITAL_GOODS und/oder PHYSICAL_GOODS; 2) DONATION. DONATION kann nicht mit DIGITAL_GOODS oder PHYSICAL_GOODS kombiniert werden.
ItemTotal ist die Zusammenfassung von UnitAmount * Quantity aller Bestellartikel, die sich auf diesen Händler beziehen.
TaxTotal ist die Zusammenfassung von Tax aller Bestellartikel dieses Händlers.
Amount ist die Zusammenfassung von ItemTotal, TaxTotal und ShippingAmount dieses Händlers.

mode

an8

O

If mode="redirect" is sent, it means that the merchant does not use PayPal Smart Button and should redirect the customer to PayPal.

if mode is not sent (or sent with any other value except "redirect"), it means that the merchant uses PayPal Smart Button and will not redirect the customer to PayPal (redirection will be handled by PayPal Smart Button).

Common notes:

We recommend to use the PayPal Smart Button for additional fraud protection and improved user experience

Wenn mode="redirect" gesendet wird, bedeutet dies, dass der Händler den PayPal Smart Button nicht verwendet und den Kunden zu PayPal weiterleiten sollte.

Wenn mode nicht gesendet wird (oder mit einem anderen Wert außer „redirect“ gesendet wird), bedeutet dies, dass der Händler den PayPal Smart Button verwendet und den Kunden nicht zu PayPal weiterleitet (die Umleitung wird über den PayPal Smart Button abgewickelt).

Allgemeine Hinweise:

Wir empfehlen, die Verwendung des PayPal Smart Button für zusätzlichen Betrugsschutz und ein verbessertes Benutzererlebnis

Parameters for PayPal payments

Key	Format	CND	Description	Beschreibung
Status	a..50	M	OK, AUTHORIZE_REQUEST or Timeout (only if Capture=Manual) on the URLSuccess page or FAILED on the URLFailure page. AUTHORIZE_REQUEST – is returned actively only for request parameter "TxType=auth" or "PayPalMethod=shortcut". When using TxType=auth or without TxType the final status is returned directly. Timeout – all open payments with status AUTHORIZE_REQUEST will be closed ~ 3hours later automatically and are reported as Timeout.	OK, AUTHORIZE_REQUEST oder Timeout (nur bei Capture=Manual) auf der URLSuccess-Seite oder FAILED auf der URLFailure-Seite. AUTHORIZE_REQUEST – wird nur bei Anfrageparameter „TxType=auth“ oder „PayPalMethod=shortcut“ aktiv zurückgegeben. Bei Verwendung von TxType=auth oder ohne TxType wird direkt der finale Status zurückgegeben. Timeout – alle offenen Zahlungen mit Status AUTHORIZE_REQUEST werden etwa 3 Stunden später automatisch geschlossen und als Timeout gemeldet

Key

Format

CND

Description

Beschreibung

CodeExt

n..10

O

Error code from PayPal if agreed with

Fehlercode von PayPal, wenn mit abgesprochen

Name

ans..50

M

First name and surname joined

Vorname und Nachname zusammen

FirstName

ans..50

M

First name of payer (PayerInfo, may differ from the account name)

Vorname des Zahlers (PayerInfo, kann vom Kontonamen abweichen)

LastName

ans..50

M

Last name of payer (PayerInfo, may differ from the account name)

Nachname des Zahlers (PayerInfo, kann vom Kontonamen abweichen)

E-Mail

ans..100

M

Email address of the purchaser

E-Mail-Adresse des Käufers

AddrStreet

ans..100

O

Street in the delivery address

Straßenname in der Lieferadresse

AddrStreet2

ans..100

O

2. Street name in the delivery address that contains additional information e.g. packing station or similar. In order to receive this as a response parameter, it needs to be activated separately by the .

2. Straßenname in der Lieferadresse, der weitere Informationen zu Packstation o.ä. enthält. Damit dieser Parameter in der Antwort zurückgeliefert werden kann, muss dieser separat vom aktiviert werden.

AddrCity

ans..40

O

Town/city in the delivery address

Ort in der Lieferadresse

AddrState

ans..40

O

Federal State in the delivery address

Bundesstaat in der Lieferadresse

AddrZip

ans..20

O

Postcode in the delivery address

Postleitzahl in der Lieferadresse

AddrCountryCode

an2

O

Country code of the delivery country

Ländercode in der Lieferadresse

Phone

n..20

O

Telephone number

Telefonnummer

BillingAgreementID

ans..19

O

Billing Agreement ID which can be used for subsequent transactions, based on this Billing Agreement.

Billing Agreement, die für nachfolgende Transaktionen basierend auf dieser Billing Agreement verwendet werden kann.

BillingName

ans..32

O

First name and surname joined

Vorname und Nachname zusammen

BillingAddrStreet

ans..100

O

Street name of the invoicing address lodged with PayPal

Straßenname der bei PayPal hinterlegten Rechnungsadresse

BillingAddrStreet2

ans..100

O

2. Street name of the invoicing address lodged with PayPal that contains additional information e.g. packing station or similar. In order to receive this as a response parameter, it needs to be activated separately by the .

2. Straßenname der bei PayPal hinterlegten Rechnungsadresse, der weitere Informationen zu Packstation o.ä. enthält. Damit dieser Parameter in der Antwort zurückgeliefert werden kann, muss dieser separat vom aktiviert werden.

BillingAddrCity

ans..40

O

Town/city name of the invoicing address saved with PayPal

Ortsname der bei PayPal hinterlegten Rechnungsadresse

BillingAddrState

ans..40

O

Federal state of the invoicing address saved with PayPal

Bundesstaat der bei PayPal hinterlegten Rechnungsadresse

BillingAddrZIP

ans..20

O

Postcode of the invoicing address saved with PayPal

Postleitzahl der bei PayPal hinterlegten Rechnungsadresse

BillingAddrCountryCode

an2

O

Country code of the billing address

Ländercode in der Rechnungsadresse

payerStatus

an..10

O

Status of buyer with possible values "verified" or "unverified"

Status des Käufers mit den möglichen Werten "verified" oder "unverified"

InfoText

ans..255

M

Message to the merchant

Nachricht an den Händler

PayerID

ans..13

O

(if response is activated): Unique identification number of customer account at PayPal

(falls Antwort aktiviert ist): Eindeutige Identifikationsnummer des Kundenkontos bei PayPal

GrossAmount

an..9

O

Final amount charged, including any shipping and taxes from your Merchant profile

Abgerechneter Endbetrag, einschließlich Versandkosten und Steuern aus Ihrem Händlerprofil

FeeAmount

an..9

O

PayPal fee amount charged for the transaction

Für die Transaktion berechneter Betrag der PayPal-Gebühr

SettleAmount

an..9

O

Amount deposited in your PayPal account after a currency conversion

Auf Ihrem PayPal-Konto nach einer Währungsumrechnung eingezahlter Betrag

TaxAmount

an..9

O

Tax charged on the transaction

Auf die Transaktion erhobene Steuer

ExchangeRate

an..17

O

Exchange rate if a currency conversion occurred. Relevant only if you are billing in their non-primary currency. If the buyer chooses to pay with a currency other than the non-primary currency, the conversion occurs in the buyer's account.

Wechselkurs, falls eine Währungsumrechnung stattgefunden hat. Nur relevant, wenn Sie in ihrer Nicht-Hauptwährung abrechnen. Wenn der Käufer mit einer anderen Währung als der Nicht-Primärwährung bezahlt, erfolgt die Umrechnung im Konto des Käufers.

mc_fee

an..9

C

Only in case of separate Notify from PayPal: Transaction fee associated with the payment. mc_gross minus mc_fee equals the amount deposited into the receiver_email account. Equivalent to payment_fee for USD payments. If this amount is negative, it signifies a refund or reversal, and either of those payment statuses can be for the full or partial amount of the original transaction fee.

Nur bei einem separaten Notify von PayPal: Transaktionsgebühr im Zusammenhang mit der Zahlung. mc_gross minus mc_fee entspricht dem Betrag, der auf das Konto receiver_email eingezahlt wurde. Entspricht Payment_fee für USD-Zahlungen. Wenn dieser Betrag negativ ist, bedeutet dies eine Rückerstattung oder Stornierung, und jeder dieser Zahlungsstatus kann für den vollen oder einen Teilbetrag der ursprünglichen Transaktionsgebühr gelten.

mc_gross

an..9

C

Only in case of separate Notify from PayPal: Full amount of the customer's payment before transaction fee is subtracted. Equivalent to payment_gross for USD payments. If this amount is negative, it signifies a refund or reversal, and either of those payment statuses can be for the full or partial amount of the original transaction.

Nur bei einem separaten Notify von PayPal: Gesamtbetrag der Zahlung des Kunden vor Abzug der Transaktionsgebühr. Äquivalent zu payment_gross für USD-Zahlungen. Wenn dieser Betrag negativ ist, bedeutet dies eine Rückerstattung oder Stornierung, und jeder dieser Zahlungsstatus kann für den gesamten oder einen Teilbetrag der ursprünglichen Transaktion gelten.

OrderStatus(n)

ans..255

O

In case of Multi-Seller Payment (Marketplace functionality), each OrderStatus(n) contains Status and Capture ID (to be used in case of Credit) for corresponding OrderDesc(n) sent in request. JSON object (base64-encoded) with the following format.

Examples:

{"status":"COMPLETED", "id":"3C679366HH908993F1", "invoiceid":"PU1_20230812"}

{"status":"FAILED", "id":"na", "invoiceid":""}

Status has been analysed, because a customer could not have enough money for all merchants. In this case PayPal will approve only some of OrderDesc(n) (only for some merchants).

Bei einer Multi-Seller-Zahlung (Funktionalität Marketplace) enthält jeder OrderStatus(n) den Status und die Capture-ID (bei einer Gutschrift zu verwenden) für die entsprechenden in der Anfrage gesendeten OrderDesc(n). JSON-Objekt (Base64-codiert) mit dem folgenden Format.

Beispiele:

{"status":"COMPLETED", "id":"3C679366HH908993F1", "invoiceid":"PU1_20230812"}

{"status":"FAILED", "id":"na", "invoiceid":""}

Der Status wurde analysiert, da ein Kunde nicht genug Geld für alle Händler haben könnte. In diesem Fall genehmigt PayPal nur einige OrderDesc(n) (nur für einige Händler).

TID

ans..17

O

In case of SALE, the parameter contains unique PayPal-generated Capture ID.

In case of AUTH, the parameter contains unique PayPal-generated Authorization ID.

Bei SALE enthält der Parameter eine eindeutige, von PayPal generierte Capture-ID.

Bei AUTH enthält der Parameter eine eindeutige, von PayPal generierte Autorisierungs-ID.

TransactionID

ans..17

O

The parameter contains unique PayPal-generated Order ID

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:

paypalComplete.aspx

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.
			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..50	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..50	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: 2. Street name in the delivery address that contains additional information e.g. packing station or similar. In order to receive this as a response parameter, it needs to be activated separately by the .	Pflicht, wenn FirstName übergeben wird: 2. Straßenname in der Lieferadresse, der weitere Informationen zu Packstation o.ä. enthält. Damit dieser Parameter in der Antwort zurückgeliefert werden kann, muss dieser separat vom aktiviert werden.
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, please use the following URL:

Authorize.aspx

Key	Format	CND	Description	Beschreibung
TxType	ans..5	M	Transaction type Auth	Transaktionstyp Auth

Key	Format	CND	Description	Beschreibung
FirstName	ans..50	O	Either the first name only or first and second name if a company name is used as a delivery address	Entweder nur der Vorname oder Vor- und Nachname, wenn ein Firmenname als Lieferadresse verwendet wird
LastName	ans..50	O	Surname or name of the company of the delivery address	Nachname oder Firmenname der Lieferadresse
AddrStreet	ans..100	O	Street in the delivery address	Straßenname in der Lieferadresse
AddrStreet2	ans..100	O	2. Street name in the delivery address that contains additional information e.g. packing station or similar. In order to receive this as a response parameter, it needs to be activated separately by the .	2. Straßenname in der Lieferadresse, der weitere Informationen zu Packstation o.ä. enthält. Damit dieser Parameter in der Antwort zurückgeliefert werden kann, muss dieser separat vom aktiviert werden.
AddrCity	ans..40	O	Town/city in the delivery address	Ort in der Lieferadresse
AddrState	ans..40	O	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.	Bundesstaat der Lieferadresse. Der in AddrCity hinterlegte Ort muss im angegebenen Bundesland liegen, ansonsten lehnt PayPal diese Zahlung ab. Mögliche Werte entnehmen Sie bitte der PayPal-API-Referenzdokumentation.
AddrZip	ans..20	O	Postcode in the delivery address	Postleitzahl in der Lieferadresse
AddrCountryCode	an2	O	Country code of the delivery country	Ländercode in der Lieferadresse
Phone	n..20	O	Telephone number	Telefonnummer

Parameters for PayPal authorization

Key	Format	CND	Description	Beschreibung
CodeExt	n..10	O	Error code from PayPal if agreed with	Fehlercode von PayPal, wenn mit abgesprochen

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

Key	REST	Format	CND	Description	Beschreibung
RefNr	"referenceNumber": "..."	ans..30	O	Merchant reference number: here a separate reference number, e.g. an invoice number, can be transferred	Referenznummer des Händlers: hier kann eine separate Referenznummer übertragen werden, z.B. eine Rechnungsnummer

Key

REST

Format

CND

Description

Beschreibung

TID

"payment": {"payPal": { "generatedCaptureId": "..." }}

ans..17

O

Unique PayPal-generated Capture ID. The value is required for a refund after several partial captures.

Example: A merchant did 3 partial captures for an authorization. For each capture unique PayPal-generated Capture ID is returned in TID (e.g., TID=111, TID=222, TID=333). Then, a refund for second capture should be done. In this case the merchant needs to send TID=222 in refund request.

Eindeutige, von PayPal generierte Capture-ID. Der Wert wird für eine Rückerstattung nach mehreren Teilbuchungen benötigt.

Beispiel: Ein Händler hat 3 Teilbuchungen für eine Autorisierung durchgeführt. Für jede Buchung wird eine eindeutige, von PayPal generierte Capture-ID in der TID zurückgegeben (z. B. TID=111, TID=222, TID=333). Dann sollte eine Rückerstattung für die zweite Buchung erfolgen. In diesem Fall muss der Händler TID=222 in der Anfrage der Rückerstattung senden.

CompleteType

"payment": {"payPal": { "completeType": "..." }}

ans..3

O

If <YES> is transferred, the possible open order of PayPal is closed on capture. (Reason: a 115% capture is permissible on the part of PayPal. If a capture reached 100%, automatically sends a request to close the payment).

Wenn <YES> übergeben wird, wird die eventuell offene Bestellung von PayPal bei der Buchung geschlossen. (Grund: Seitens PayPal ist eine 115%ige Buchung zulässig. Wenn eine Buchung 100% erreicht, sendet das automatisch eine Anfrage zum Schließen der Zahlung).

Parameters for PayPal captures

Key	REST	Format	CND	Description	Beschreibung
CodeExt	"externalErrorCode": ...	n..10	O	Error code from PayPal if agreed with	Fehlercode von PayPal, wenn mit abgesprochen

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

Key	REST	Format	CND	Description	Beschreibung
RefNr	"referenceNumber": "..."	ans..30	O	Merchant reference number: here a separate reference number, e.g. an invoice number, can be transferred	Referenznummer des Händlers: hier kann eine separate Referenznummer übertragen werden, z.B. eine Rechnungsnummer

Key

REST

Format

CND

Description

Beschreibung

TID

"payment": {"payPal": { "generatedCaptureId": "..." }}

ans..17

O

Unique PayPal-generated Capture ID. The value is required for a refund after several partial captures.

Example: A merchant did 3 partial captures for an authorization. For each capture unique PayPal-generated Capture ID is returned in TID in capture response (e.g., TID=111, TID=222, TID=333). Then, a refund for second capture should be done. In this case the merchant needs to send TID=222 in refund request.

Eindeutige, von PayPal generierte Capture-ID. Der Wert wird für eine Rückerstattung nach mehreren Teilbuchungen benötigt.

Beispiel: Ein Händler hat 3 Teilbuchungen für eine Autorisierung durchgeführt. Für jede Buchung wird eine eindeutige, von PayPal generierte Capture-ID in der TID zurückgegeben (z. B. TID=111, TID=222, TID=333). Dann sollte eine Rückerstattung für die zweite Buchung erfolgen. In diesem Fall muss der Händler TID=222 in der Anfrage der Rückerstattung senden.

Note

"reason": "..."

ans..768

C

Explanatory text for recipient

Erläuterungstext für den Empfänger

Subject

"payment": {"payPal": { "massPayEmailSubject": "..." }}

ans..255

C

MassPay: E-Mail subject to recipient

Notice: If you want to use the MassPay functionality, please contact the to activate this function for you.

MassPay: E-Mail-Betreff an den Empfänger

Wenn Sie die MassPay-Funktionalität nutzen möchten, wenden Sie sich bitte an den , um diese Funktion für Sie zu aktivieren.

Parameters for PayPal credits with reference transaction

Key	REST	Format	CND	Description	Beschreibung
CodeExt	"externalErrorCode": ...	n..10	O	Error code from PayPal if agreed with	Fehlercode von PayPal, wenn mit abgesprochen
FeeRefundAmount	"payment": {"feeAmount": ...}	n..10	O	The refunded amount of the PayPal transaction fees. Required for part credit notes to prior partial captures.	Der erstattete Betrag der PayPal-Transaktionsgebühren. Erforderlich für Teilgutschriften zu früheren Teilbuchungen.
GrossRefundAmount	"payment": {"grossAmount": ...}	n..10	O	Amount refunded to the buyer in this refund transaction. Required for part credit notes to prior partial captures.	Betrag, der dem Käufer bei dieser Gutschrift erstattet wird. Erforderlich für Teilgutschriften zu früheren Teilbuchungen.
NetRefundAmount	"payment": {"netAmount": ...}	n..10	O	Amount deducted from your PayPal account to make this refund. Required for part credit notes to prior partial captures.	Betrag, der von Ihrem PayPal-Konto abgezogen wird, um diese Gutschrift vorzunehmen. Erforderlich für Teilgutschriften zu früheren Teilbuchungen.

Response parameters for PayPal credits with reference transaction

Credit without reference

In order to initiate a credit without reference transaction for PayPal payment, please use the following URL:

paypalcreditEx.aspx

Key	REST	Format	CND	Description	Beschreibung
PayerID		ans..13	O	Unique identification number of customer account at PayPal	Eindeutige Identifikationsnummer des Kundenkontos bei PayPal

Key	REST	Format	CND	Description	Beschreibung
Account	"payment": {"payPal": { "accountId": "..." }}	ans..128	O	For managing multiple PayPal accounts, Merchant account: ID or e-Mail address for which the request should be submitted to PayPal	Für die Verwaltung mehrerer PayPal-Konten, Händlerkonto: ID oder E-Mail-Adresse, für die die Anfrage an PayPal gesendet werden soll
Note	"reason": "..."	ans..768	C	MassPay: Explanatory text for recipient If you want to use the MassPay functionality, please contact the to activate this function for you.	MassPay: Erläuterungstext für den Empfänger Wenn Sie die MassPay-Funktionalität nutzen möchten, wenden Sie sich bitte an den , um diese Funktion für Sie zu aktivieren.
Subject	"payment": {"payPal": { "massPayEmailSubject": "..." }}	ans..255	C	MassPay: E-Mail subject to recipient If you want to use the MassPay functionality, please contact the to activate this function for you.	MassPay: E-Mail-Betreff an den Empfänger Wenn Sie die MassPay-Funktionalität nutzen möchten, wenden Sie sich bitte an den , um diese Funktion für Sie zu aktivieren.
Payer		ans..100	O	MassPay: Email address of the purchaser If you want to use the MassPay functionality, please contact the to activate this function for you.	MassPay: E-Mail-Adresse des Käufers Wenn Sie die MassPay-Funktionalität nutzen möchten, wenden Sie sich bitte an den , um diese Funktion für Sie zu aktivieren.

Parameters for PayPal credits without reference transaction

Key	REST	Format	CND	Description	Beschreibung
CodeExt	"externalErrorCode": ...	n..10	O	Error code from PayPal if agreed with	Fehlercode von PayPal, wenn mit abgesprochen
FeeRefundAmount	"payment": {"feeAmount": ...}	n..10	O	The refunded amount of the PayPal transaction fees. Required for part credit notes to prior partial captures.	Der erstattete Betrag der PayPal-Transaktionsgebühren. Erforderlich für Teilgutschriften zu früheren Teilbuchungen.
GrossRefundAmount	"payment": {"grossAmount": ...}	n..10	O	Amount refunded to the buyer in this refund transaction. Required for part credit notes to prior partial captures.	Betrag, der dem Käufer bei dieser Gutschrift erstattet wird. Erforderlich für Teilgutschriften zu früheren Teilbuchungen.
NetRefundAmount	"payment": {"netAmount": ...}	n..10	O	Amount deducted from your PayPal account to make this refund. Required for part credit notes to prior partial captures.	Betrag, der von Ihrem PayPal-Konto abgezogen wird, um diese Gutschrift vorzunehmen. Erforderlich für Teilgutschriften zu früheren Teilbuchungen.

Response parameters for PayPal credits without reference transaction

Reversal

In order to cancel a transaction with PayPal, please use the following URL:

reverse.aspx

Parameters for PayPal reversals

Key	REST	Format	CND	Description	Beschreibung
CodeExt	"externalErrorCode": ...	n..10	O	Error code from PayPal if agreed with	Fehlercode von PayPal, wenn mit abgesprochen

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. The merchant can only be informed about the cancellation if additional option IPN “instant payment notification” is activated for merchant account. The activation has to be done by the . Please keep in mind that after IPN activation the merchant will receive notifications for each status change of a PayPal payment.
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

Key	Format	CND	Description	Beschreibung
OrderDesc	ans..30	O	Description of purchased goods, unit prices etc.	Beschreibung der gekauften Waren, Einzelpreise usw.
BillingAgreementID	an19	M	Identification number of the invoice agreement. When the buyer confirms the invoice agreement it is validated and remains valid until revoked by the buyer.	Identifikationsnummer der Rechnungsvereinbarung. Wenn der Käufer die Rechnungsvereinbarung bestätigt, wird diese validiert und bleibt gültig, bis sie vom Käufer widerrufen wird.

Parameters for PayPal Reference Transactions

Response

Key	Format	CND	Description	Beschreibung
CodeExt	n..10	O	Error code from PayPal if agreed with	Fehlercode von PayPal, wenn mit abgesprochen

Key	Format	CND	Description	Beschreibung
OrderID	ans..17	O	Unique PayPal-generated OrderID	Eindeutige, von PayPal generierte OrderID
TID	ans..17	O	Unique PayPal-generated CaptureID	Eindeutige, von PayPal generierte CaptureID
Name	ans..32	O	First name and surname joined	Vor- und Nachname zusammengefügt
FirstName	ans..50	O	First name of payer (PayerInfo, may differ from the account name)	Vorname des Zahlers (PayerInfo, kann vom Kontonamen abweichen)
LastName	ans..50	O	Last name of payer (PayerInfo, may differ from the account name)	Nachname des Zahlers (PayerInfo, kann vom Kontonamen abweichen)
E-Mail	ans..100	O	Email address of the purchaser	E-Mail-Adresse des Käufers
BillingName	ans..32	O	First name and surname joined	Vor- und Nachname zusammengefügt
BillingAddrCountryCode	an2	O	Country code of the billing address	Ländercode der Rechnungsadresse
PayerID	ans..13	O	(if response is activated): Unique ID of customer account at PayPal	(bei aktivierter Antwort): Eindeutige ID des Kundenkontos bei PayPal

Result parameters for PayPal Reference Transactions

Batch processing via the 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:

Action	Version	Description	Beschreibung
Authorize	1.0 / 2.0	Standard version without return of parameter Code	Standardversion ohne Rückgabe von Parameter Code
	1.4 / 2.4	with TID	mit TID
Capture	1.0 / 2.0	Standard version without return of parameter Code	Standardversion ohne Rückgabe von Parameter Code
	1.x / 2.x	with RefNr (valid for all versions other than 1.0)	mit RefNr (gilt für alle Versionen außer 1.0)
	1.4 / 2.4	with TID	mit TID
Credit	1.0 / 2.0	Standard version without return of parameter Code	Standardversion ohne Rückgabe von Parameter Code
	1.x / 2.x	with RefNr (valid for all versions other than 1.0)	mit RefNr (gilt für alle Versionen außer 1.0)
	1.4 / 2.4	with TID	mit TID
CreditEx	1.0 / 2.0	Standard version without return of parameter Code	Standardversion ohne Rückgabe von Parameter Code
	1.x / 2.x	with RefNr (valid for all versions other than 1.0)	mit RefNr (gilt für alle Versionen außer 1.0)
Reverse	1.0 / 2.0	Standard version without return of parameter Code	Standardversion ohne Rückgabe von Parameter Code
	1.4 / 2.4	with TID	mit TID
ABO/REFTRANS	1.0 / 2.0	ABO - Classic PayPal API REFTRANS - Order V2 PayPal API Standard version without return of parameter Code	ABO - Classic PayPal API REFTRANS - Order V2 PayPal API Standardversion ohne Rückgabe von Parameter Code
	1.x / 2.x	with RefNr (valid for all versions other than 1.0)	mit RefNr (gilt für alle Versionen außer 1.0)

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>,<CodeExt>,<PayID>,<Status>,<Code>
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>)

Key	Format	CND	Description	Beschreibung
Type	a..11	M	HEAD for Header, FOOT for Footer, PAYPAL for PayPal	HEAD für Header, FOOT für Footer, PAYPAL für PayPal
Action	a..20	M	The parameter Action defines the type of transaction: Authorize Capture Credit CreditEx (credit note without previous capture; please agree this with beforehand) Reverse (cancellation) ABO (subscription, Classic API) REFTRANS (subscription, Order V2 API)	Der Action-Parameter definiert die Art der Transaktion: Authorize (Autorisierung) Capture (Buchung) Credit (Gutschrift) CreditEx (Gutschrift ohne vorherige Buchung; bitte vereinbaren Sie das vorher mit dem ) Reverse (Storno) ABO (Abonnement, Classic API) REFTRANS (Abonnement, Order V2 API)

Key	Format	CND	Description	Beschreibung
payer	ans..100	O	MassPay: Email address of the purchaser: In this case you transfer the received email parameter from the Response If you want to use the MassPay functionality, please contact the to activate this function for you.	MassPay: E-Mail-Adresse des Käufers: In diesem Fall übergeben Sie den empfangenen E-Mail-Parameter aus der Antwort Wenn Sie die MassPay-Funktionalität nutzen möchten, wenden Sie sich bitte an den , um diese Funktion für Sie zu aktivieren.
note	ans..758	O	Explanatory text for recipient	Erläuterungstext für den Empfänger

Key	Format	CND	Description	Beschreibung
TID	ans..17	O	PayPal unique transaction number. Required for a number of authorisations or part captures, part credit notes or part cancellations.	Eindeutige PayPal-Transaktionsnummer. Erforderlich für eine Reihe von Autorisierungen oder Teilbuchungen, Teilgutschriften oder Teilstornierungen.
OrderDesc	ans..127	O	Description of purchased goods, unit prices etc.	Beschreibung der gekauften Waren, Einzelpreise usw.
Capture	a..6	O	Auto or Manual: determines whether the requested amount is settled immediately or at a later stage. For REFTRANS only Auto is possible.	Auto oder Manual: legt fest, ob der angeforderte Betrag sofort oder zu einem späteren Zeitpunkt abgerechnet wird. Für REFTRANS ist nur Auto möglich.
TxType	ans..5	OC	Obligatory for Capture=Manual: Transaction type with possible values Order and Auth	Pflicht bei Capture=Manual: Transaktionstyp mit den möglichen Werte Order und Auth
BillingAgreementID	an19	OC	Identification number of the invoice agreement. When the buyer confirms the invoice agreement it is validated and remains valid until revoked by the buyer. Mandatory in case of ABO and REFTRANS.	Identifikationsnummer der Rechnungsvereinbarung. Wenn der Käufer die Rechnungsvereinbarung bestätigt, wird sie gültig und bleibt gültig, bis sie vom Käufer widerrufen wird. Pflicht bei X und Y.

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>
PAYPAL,REFTRANS,<Amount>,<Currency>,<TransID>,(<RefNr>),(<OrderDesc>),(<Capture>),(<TxType>),<BillingAgreementId>,<CodeExt>,<PayID>,<Status>,<Code>
FOOT,<CountRecords>,<SumAmount>

Key	Format	CND	Description	Beschreibung
Action	a..20	M	The parameter Action defines the type of transaction like capture or credit.	Der Action-Parameter definiert die Art der Transaktion wie Buchung oder Gutschrift.

Key	Format	CND	Description	Beschreibung
CodeExt	n..10	O	Error code from PayPal if agreed with	Fehlercode von PayPal, wenn mit abgesprochen

Description of result parameters within the record for Batch files

About PayPal

General information about PayPal

PayPal Shortcut (former "Express Checkout Shortcut (ECS)")

Buyers and vendors are protected

Payment online globally

Advantages of Orders V2 ("PayPal Checkout")

Important information

On this page

Process flow

Configuration for PayPal

PayPal Sandbox test account

Grant permissions to for transaction processing

Send PayerID to Merchant Services

PayPal Sandbox

PayPal Production

PayPal Smart Button

Setting up the PayPal Button

Enabling PayPal Pay Later Button

Parameter intent

PayPal Button Style

interface

Calling the interface

Calling the interface for method "shortcut"

Calling the interface for a separate authorization

Capture

Credit with reference

Credit without reference

Reversal

Reference Transactions

Prerequisites

Process

Revoking of Billing Agreement

Request

Response

Batch processing via the interface