PayPal V2

Logo

Info

Computop Paygate 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

Format

Description

a

alphabetical

as

alphabetical with special characters

n

numeric

an

alphanumeric

ans

alphanumeric with special characters

ns

numeric with special characters

bool

boolean expression (true or false)

3

fixed length with 3 digits/characters

..3

variable length with maximum 3 digits/characters

enum

enumeration of allowed values

dttm

ISODateTime (YYYY-MM-DDThh:mm:ss)

Abbreviation

Description

Comment

CND

condition

M

mandatory

If a parameter is mandatory, then it must be present

O

optional

If a parameter is optional, then it can be present, but it is not required

C

conditional

If a parameter is conditional, then there is a conditional rule which specifies whether it is mandatory or optional

MerchantID

BasicAuth.Username

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

TransID

"transactionId": "..."

ans..64

M

TransactionID provided by you which should be unique for each payment

refnr

"referenceNumber": "..."

ans..30

O

Merchant’s unique reference number

Amount

"amount": { "value": ...}

n..10

M

Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Computop Helpdesk, if you want to capture amounts <100 (smallest currency unit).

If OrderDesc(n) is used, there must be valid: Amount=ItemTotal+TaxTotal+SHAmount.

Currency

"amount": { "currency": "..."}

a3

M

Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table. Please note the global PayPal supported currencies at https://developer.paypal.com/api/rest/reference/currency-codes/.

MAC

–––

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here:

• HMAC Authentication (Request)

• HMAC Authentication (Notify)

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 Computop Helpdesk for Manual, to discuss different possibilities of usage.

Important Note: In case of Multi-Seller Payment (Marketplace functionality) only Auto is possible.

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

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.

RTF

–––

ans1

O

Reserved for future use

OrderDesc

"order": {"description": "..."}

ans..127

M

Description of purchased goods, unit prices etc.

OrderDesc(n)

"order": {"items": "..."}

ans..127

O

Customers shopping basket in the form:

OrderDesc(n)=Name,Amount,Number,Quantity,Description,Tax

OrderDesc2 to max. OrderDesc99 permissible. For more information, please visit PayPal at https://developer.paypal.com/docs/api/orders/v2/#orders_create!ct=application/json&path=purchase_units/items&t=request.

For correct execution of displaying function all OrderDesc(n) Amounts must equal to the Paygate parameter Amount.

Example for transferring all variants:

Amount=1600

OrderDesc2=book,500,1111,1,Article,100&

OrderDesc3=book,600,2222,1,Article,100&

ItemTotal=1100&

TaxTotal=200&

ShAmount=300&

Example including discount:

Amount=400

Orderdesc2=book,500,1234,1,nice book,100&

Orderdesc3=Discount,-200,5678,1,nice book,0&

taxtotal=100&

itemtotal=300&

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)

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)

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.

URLSuccess

"urls": {"success": "..."}

ans..256

M

Complete URL which calls up Paygate if payment has been successful. The URL may be called up only via port 443. This URL may not contain parameters: In order to exchange values between Paygate and shop, please use the parameter UserData.

Common notes:

• We recommend to use parameter "response=encrypt" to get an encrypted response by Paygate

• However, fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess/URLNotify. Therefore ensure to check the "code"-value which indicates success/failure of the action. Only a result of "code=00000000" should be considered successful.

URLFailure

"urls": {"failure": "..."}

ans..256

M

Complete URL which calls up Paygate if payment has been unsuccessful. The URL may be called up only via port 443. This URL may not contain parameters: In order to exchange values between Paygate and shop, please use the parameter UserData.

Common notes:

• We recommend to use parameter "response=encrypt" to get an encrypted response by Paygate

• However, fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess/URLNotify. Therefore ensure to check the "code"-value which indicates success/failure of the action. Only a result of "code=00000000" should be considered successful.

Response

–––

a7

O

Status response sent by Paygate to URLSuccess and URLFailure, should be encrypted. For this purpose, transmit Response=encrypt parameter.

URLNotify

"urls": {"notify": "..."}

ans..256

M

Complete URL which Paygate calls up in order to notify the shop about the payment result. The URL may be called up only via port 443. It may not contain parameters: Use the UserDataparameter instead.

Common notes:

• Before follow-up actions (capture / credit / reversal) are carried out on an existing transaction, the first Notify must have been answered by the shop.

• Fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess/URLNotify. Therefore ensure to check the "code"-value which indicates success/failure of the action. Only a result of "code=00000000" should be considered successful.

UserData

"metadata[userData]": "..."

ans..1024

O

If specified at request, Paygate forwards the parameter with the payment result to the shop.

ReqId

"requestId": "..."

ans..32

O

To avoid double payments or actions (e.g. by ETM), enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction or action is submitted again with the same ReqID, Computop Paygate will not carry out the payment or new action, but will just return the status of the original transaction or action.

Please note that the Computop Paygate must have a finalized transaction status for the first initial action (authentication/authorisation). This does not apply to 3-D Secure authentications that are terminated by a timeout. The 3-D Secure Timeout status does not count as a completed status in which the ReqID functionality on Paygate does not take effect. Submissions with identical ReqID for an open status will be processed regularly.

Notice: Please note that a ReqID is only valid for 12 month, then it gets deleted at the Paygate.

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

Language

"language": "..."

an2

O

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

If you would like to control the language for the customer on the PayPal login page, please note the sequence of checks at PayPal and how to influence the language accordingly.

1. The user cookie is primary with PayPal. If this is set it overwrites everything (if the browser language is German, then this always has priority).

2. The parameter Localcode – parameter Language on Paygate – with a 5 digit ISO code (fr_FR). Please see PayPal documentation: https://developer.paypal.com/reference/locale-codes/.

3. The parameter ShipToCountry from the delivery address (if a delivery address is transferred)

4. The parameter Localcode – parameter Language on Paygate – with a 2 digit ISO code (FR)

5. The country code of the PayPal account. Please note, this takes place when the customer has logged into his PayPal account. At this point, the language can no longer be actively controlled.

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.

LastName

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

ans..50

OC

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

AddrStreet

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

ans..100

OC

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

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

AddrCity

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

ans..40

OC

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

AddrState

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

ans..40

C

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

AddrZip

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

ans..20

OC

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

AddrCountryCode

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

an2

O

Country code of the delivery country

Phone

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

n..20

O

Telephone number

NoShipping

n1

O

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

Computop Paygate 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 Computop Helpdesk for this.

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:

1
{
2
 "additional_data": [
3
    {
4
      "key": "sender_first_name",
5
      "value": "John"
6
    },
7
    {
8
      "key": "sender_last_name",
9
      "value": "Doe"
10
    }
11
]
12
}

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:

1
{
2
        merchantemailaddress: "merchant@example.com",
3
        merchantid: "XVRKM94GQDXB2",
4
        amount: "11000",
5
        itemtotal: "8000",
6
        taxtotal: "2000",
7
        shippingamount: "1000",
8
        invoiceid: "xxxxx",
9
        orderdescription: "yyyyy",
10
        orderitems: [
11
        {
12
            name: "zzzzz",
13
            quantity: "1",
14
            unitamount: "3000",
15
            tax: "1000",
16
            description: "xxxx",
17
            category: "PHYSICAL_GOODS"
18
        },
19
        {
20
            name: "xxxxx",
21
            quantity: "2",
22
            unitamount: "2500",
23
            tax: "500",
24
            description: "yyyyy",
25
            category: "DIGITAL_GOODS"
26
        }
27
    ]
28
}

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

mode

an8

O

If mode="redirect" is sent, it means that the merchant does not use PayPal Smart Button and Paygate 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 Paygate 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

REST

Format

CND

Description

"paymentId": "..."

an32

M

May be "00000000000000000000000000000000" if not yet set by Computop Paygate

"_Links.self.type": "..."

an..20

M

"application/json"

"_Links.redirect.href": "..."

an..1024

M

Merchant needs to redirect consumer to this URL to complete payment

"_Links.redirect.type": "..."

an..20

M

"text/html"

mid

ans..30

M

MerchantID, assigned by Computop

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files as well as for capture or credit request.

XID

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

ans..64

M

TransactionID provided by you which should be unique for each payment

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.

Description

ans..1024

M

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

an8

M

Error code according to Paygate Response Codes (A4 Error codes)

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here:

• HMAC Authentication (Request)

• HMAC Authentication (Notify)

refnr

ans..30

O

Merchant’s unique reference number

UserData

ans..1024

O

If specified at request, Paygate forwards the parameter with the payment result to the shop.

CodeExt

n..10

O

Error code from PayPal if agreed with Computop Helpdesk

Name

ans..50

M

First name and surname joined

FirstName

ans..50

M

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

LastName

ans..50

M

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

E-Mail

ans..100

M

Email address of the purchaser

AddrStreet

ans..100

O

Street in the delivery address

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

AddrCity

ans..40

O

Town/city in the delivery address

AddrState

ans..40

O

Federal State in the delivery address

AddrZip

ans..20

O

Postcode in the delivery address

AddrCountryCode

an2

O

Country code of the delivery country

Phone

n..20

O

Telephone number

BillingAgreementID

ans..19

O

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

BillingName

ans..32

O

First name and surname joined

BillingAddrStreet

ans..100

O

Street name of the invoicing address lodged with PayPal

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

For the return of billing data, please contact your PayPal contact person directly, who must activate the return for both the live and the sandbox account.

BillingAddrCity

ans..40

O

Town/city name of the invoicing address saved with PayPal.

For the return of billing data, please contact your PayPal contact person directly, who must activate the return for both the live and the sandbox account.

BillingAddrState

ans..40

O

Federal state of the invoicing address saved with PayPal.

For the return of billing data, please contact your PayPal contact person directly, who must activate the return for both the live and the sandbox account.

BillingAddrZIP

ans..20

O

Postcode of the invoicing address saved with PayPal.

For the return of billing data, please contact your PayPal contact person directly, who must activate the return for both the live and the sandbox account.

BillingAddrCountryCode

an2

O

Country code of the billing address.

For the return of billing data, please contact your PayPal contact person directly, who must activate the return for both the live and the sandbox account.

payerStatus

an..10

O

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

InfoText

ans..255

M

Message to the merchant

PayerID

ans..13

O

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

GrossAmount

an..9

O

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

FeeAmount

an..9

O

PayPal fee amount charged for the transaction

SettleAmount

an..9

O

Amount deposited in your PayPal account after a currency conversion

TaxAmount

an..9

O

Tax charged on the transaction

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.

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.

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.

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:

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

1
{"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).

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.

TransactionID

ans..17

O

The parameter contains unique PayPal-generated Order ID

MerchantID

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

TransID

ans..64

M

TransactionID provided by you which should be unique for each payment

Amount

n..10

M

Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Computop Helpdesk, if you want to capture amounts <100 (smallest currency unit).

Currency

a3

M

Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table. Please note the global PayPal supported currencies at https://developer.paypal.com/api/rest/reference/currency-codes/.

refnr

ans..30

O

Merchant’s unique reference number

PayID

an32

M

ID assigned by Paygate for the payment.

Enter the PayID from the response from paypal.aspx received in the previous transaction procedure.

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.

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.

LastName

ans..50

C

Obligatory if FirstName is transmitted: Surname or name of the company of the delivery address

AddrStreet

ans..100

C

Obligatory if FirstName is transmitted: Street in the delivery address

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

AddrCity

ans..40

C

Obligatory if FirstName is transmitted: Town/city in the delivery address

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.

AddrZip

ans..20

C

Obligatory if FirstName is transmitted: Postcode in the delivery address

AddrCountryCode

an2

C

Obligatory if FirstName is transmitted: Country code of the delivery country

Phone

n..20

C

Obligatory if FirstName is transmitted: Telephone number

mid

ans..30

M

MerchantID, assigned by Computop

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files as well as for capture or credit request.

XID

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

ans..64

M

TransactionID provided by you which should be unique for each payment

Status

a..50

M

OK (URLSuccess) or FAILED (URLFailure)

Description

ans..1024

M

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

an8

M

Error code according to Paygate Response Codes (A4 Error codes)

refnr

ans..30

O

Merchant’s unique reference number

CodeExt

n..10

O

Error code from external partner. Needs to be agreed with Computop Helpdesk.

MerchantID

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files as well as for capture or credit request.

TransID

ans..64

M

TransactionID provided by you which should be unique for each payment

TxType

ans..5

M

Transaction type Auth

Amount

n..10

M

Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Computop Helpdesk, if you want to capture amounts <100 (smallest currency unit).

Currency

a3

M

Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table. Please note the global PayPal supported currencies at https://developer.paypal.com/api/rest/reference/currency-codes/.

FirstName

ans..50

O

Either the first name only or first and second name if a company name is used as a delivery address

LastName

ans..50

O

Surname or name of the company of the delivery address

AddrStreet

ans..100

O

Street in the delivery address

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

AddrCity

ans..40

O

Town/city in the delivery address

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.

AddrZip

ans..20

O

Postcode in the delivery address

AddrCountryCode

an2

O

Country code of the delivery country

Phone

n..20

O

Telephone number

mid

ans..30

M

MerchantID, assigned by Computop

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files as well as for capture or credit request.

XID

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

ans..64

M

TransactionID provided by you which should be unique for each payment

Status

a..50

M

OK (URLSuccess) or FAILED (URLFailure)

Description

ans..1024

M

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

an8

M

Error code according to Paygate Response Codes (A4 Error codes)

CodeExt

n..10

O

Error code from PayPal if agreed with Computop Helpdesk

MerchantID

BasicAuth.Username

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

PayID

"paymentId": "..."

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files as well as for capture or credit request.

TransID

"transactionId": "..."

ans..64

M

TransactionID provided by you which should be unique for each payment

MAC

–––

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here:

• HMAC Authentication (Request)

• HMAC Authentication (Notify)

Amount

"amount": { "value": ...}

n..10

M

Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Computop Helpdesk, if you want to capture amounts <100 (smallest currency unit).

Currency

"amount": { "currency": "..."}

a3

M

Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table. Please note the global PayPal supported currencies at https://developer.paypal.com/api/rest/reference/currency-codes/.

refnr

"referenceNumber": "..."

ans..30

O

Merchant’s unique reference number

ReqId

"requestId": "..."

ans..32

O

To avoid double payments or actions (e.g. by ETM), enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction or action is submitted again with the same ReqID, Computop Paygate will not carry out the payment or new action, but will just return the status of the original transaction or action.

Please note that the Computop Paygate must have a finalized transaction status for the first initial action (authentication/authorisation). This does not apply to 3-D Secure authentications that are terminated by a timeout. The 3-D Secure Timeout status does not count as a completed status in which the ReqID functionality on Paygate does not take effect. Submissions with identical ReqID for an open status will be processed regularly.

Notice: Please note that a ReqID is only valid for 12 month, then it gets deleted at the Paygate.

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.

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%, Paygate automatically sends a request to close the payment).

mid

"merchantId": "..."

ans..30

M

MerchantID, assigned by Computop

PayID

"paymentId": "..."

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files as well as for capture or credit request.

XID

"xId": "..."

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

"transactionId": "..."

ans..64

M

TransactionID provided by you which should be unique for each payment

Status

"status": "OK"

"status": "FAILED"

a..50

M

OK (URLSuccess) or FAILED (URLFailure)

Description

"description": "..."

ans..1024

M

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

"code": ...

an8

M

Error code according to Paygate Response Codes (A4 Error codes)

CodeExt

"externalErrorCode": ...

n..10

O

Error code from PayPal if agreed with Computop Helpdesk

MerchantID

BasicAuth.Username

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

PayID

"paymentId": "..."

an32

M

ID assigned by Paygate for the payment to be credited

TransID

"transactionId": "..."

ans..64

M

TransactionID provided by you which should be unique for each payment

MAC

–––

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here:

• HMAC Authentication (Request)

• HMAC Authentication (Notify)

Amount

"amount": { "value": ...}

n..10

M

Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Computop Helpdesk, if you want to capture amounts <100 (smallest currency unit).

Currency

"amount": { "currency": "..."}

a3

M

Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table. Please note the global PayPal supported currencies at https://developer.paypal.com/api/rest/reference/currency-codes/.

RefNr

"referenceNumber": "..."

ans..30

O

Merchant reference number: here a separate reference number, e.g. an invoice number, can be transferred

ReqId

"requestId": "..."

ans..32

O

To avoid double payments or actions (e.g. by ETM), enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction or action is submitted again with the same ReqID, Computop Paygate will not carry out the payment or new action, but will just return the status of the original transaction or action.

Please note that the Computop Paygate must have a finalized transaction status for the first initial action (authentication/authorisation). This does not apply to 3-D Secure authentications that are terminated by a timeout. The 3-D Secure Timeout status does not count as a completed status in which the ReqID functionality on Paygate does not take effect. Submissions with identical ReqID for an open status will be processed regularly.

Notice: Please note that a ReqID is only valid for 12 month, then it gets deleted at the Paygate.

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.

Note

"reason": "..."

ans..768

C

Explanatory text for recipient

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 Computop Helpdesk to activate this function for you.

mid

"merchantId": "..."

ans..30

M

MerchantID, assigned by Computop

PayID

"paymentId": "..."

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files as well as for capture or credit request.

XID

"xId": "..."

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

"transactionId": "..."

ans..64

M

TransactionID provided by you which should be unique for each payment

Status

"status": "OK"

"status": "FAILED"

a..50

M

OK (URLSuccess) or FAILED (URLFailure)

Description

"description": "..."

ans..1024

M

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

"code": ...

an8

M

Error code according to Paygate Response Codes (A4 Error codes)

CodeExt

"externalErrorCode": ...

n..10

O

Error code from PayPal if agreed with Computop Helpdesk

FeeRefundAmount

"payment": {"feeAmount": ...}

n..10

O

The refunded amount of the PayPal transaction fees. Required for part credit notes to prior partial captures.

GrossRefundAmount

"payment": {"grossAmount": ...}

n..10

O

Amount refunded to the buyer in this refund transaction. Required for part credit notes to prior partial captures.

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.

MerchantID

BasicAuth.Username

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

TransID

"transactionId": "..."

ans..64

M

TransactionID provided by you which should be unique for each payment

refnr

"referenceNumber": "..."

ans..30

O

Merchant’s unique reference number

Amount

"amount": { "value": ...}

n..10

M

Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Computop Helpdesk, if you want to capture amounts <100 (smallest currency unit).

Currency

"amount": { "currency": "..."}

a3

M

Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table. Please note the global PayPal supported currencies at https://developer.paypal.com/api/rest/reference/currency-codes/.

PayerID

ans..13

O

Unique identification number of customer account at PayPal

ReqId

"requestId": "..."

ans..32

O

To avoid double payments or actions (e.g. by ETM), enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction or action is submitted again with the same ReqID, Computop Paygate will not carry out the payment or new action, but will just return the status of the original transaction or action.

Please note that the Computop Paygate must have a finalized transaction status for the first initial action (authentication/authorisation). This does not apply to 3-D Secure authentications that are terminated by a timeout. The 3-D Secure Timeout status does not count as a completed status in which the ReqID functionality on Paygate does not take effect. Submissions with identical ReqID for an open status will be processed regularly.

Notice: Please note that a ReqID is only valid for 12 month, then it gets deleted at the Paygate.

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

Note

"reason": "..."

ans..768

C

MassPay: Explanatory text for recipient

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

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 Computop Helpdesk to activate this function for you.

Payer

ans..100

O

MassPay: Email address of the purchaser

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

mid

"merchantId": "..."

ans..30

M

MerchantID, assigned by Computop

PayID

"paymentId": "..."

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files as well as for capture or credit request.

XID

"xId": "..."

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

"transactionId": "..."

ans..64

M

TransactionID provided by you which should be unique for each payment

Status

"status": "OK"

"status": "FAILED"

a..50

M

OK (URLSuccess) or FAILED (URLFailure)

Description

"description": "..."

ans..1024

M

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

"code": ...

an8

M

Error code according to Paygate Response Codes (A4 Error codes)

CodeExt

"externalErrorCode": ...

n..10

O

Error code from PayPal if agreed with Computop Helpdesk

FeeRefundAmount

"payment": {"feeAmount": ...}

n..10

O

The refunded amount of the PayPal transaction fees. Required for part credit notes to prior partial captures.

GrossRefundAmount

"payment": {"grossAmount": ...}

n..10

O

Amount refunded to the buyer in this refund transaction. Required for part credit notes to prior partial captures.

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.

MerchantID

BasicAuth.Username

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

PayID

"paymentId": "..."

an32

M

ID assigned by Paygate for the payment to be reversed

TransID

"transactionId": "..."

ans..64

M

TransactionID provided by you which should be unique for each payment

MAC

–––

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here:

• HMAC Authentication (Request)

• HMAC Authentication (Notify)

Amount

"amount": { "value": ...}

n..10

M

Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Computop Helpdesk, if you want to capture amounts <100 (smallest currency unit).

Currency

"amount": { "currency": "..."}

a3

M

Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table. Please note the global PayPal supported currencies at https://developer.paypal.com/api/rest/reference/currency-codes/.

ReqId

"requestId": "..."

ans..32

O

To avoid double payments or actions (e.g. by ETM), enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction or action is submitted again with the same ReqID, Computop Paygate will not carry out the payment or new action, but will just return the status of the original transaction or action.

Please note that the Computop Paygate must have a finalized transaction status for the first initial action (authentication/authorisation). This does not apply to 3-D Secure authentications that are terminated by a timeout. The 3-D Secure Timeout status does not count as a completed status in which the ReqID functionality on Paygate does not take effect. Submissions with identical ReqID for an open status will be processed regularly.

Notice: Please note that a ReqID is only valid for 12 month, then it gets deleted at the Paygate.

mid

"merchantId": "..."

ans..30

M

MerchantID, assigned by Computop

PayID

"paymentId": "..."

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files as well as for capture or credit request.

XID

"xId": "..."

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

"transactionId": "..."

ans..64

M

TransactionID provided by you which should be unique for each payment

Status

"status": "OK"

"status": "FAILED"

a..50

M

OK (URLSuccess) or FAILED (URLFailure)

Description

"description": "..."

ans..1024

M

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

"code": ...

an8

M

Error code according to Paygate Response Codes (A4 Error codes)

CodeExt

"externalErrorCode": ...

n..10

O

Error code from PayPal if agreed with Computop Helpdesk

MerchantID

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

TransID

ans..64

M

TransactionID provided by you which should be unique for each payment

Amount

n..10

M

Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Computop Helpdesk, if you want to capture amounts <100 (smallest currency unit).

Currency

a3

M

Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table. Please note the global PayPal supported currencies at https://developer.paypal.com/api/rest/reference/currency-codes/.

refnr

ans..30

O

Merchant’s unique reference number

OrderDesc

ans..30

O

Description of purchased goods, unit prices etc.

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.

mid

ans..30

M

MerchantID, assigned by Computop

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files as well as for capture or credit request.

XID

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

ans..64

M

TransactionID provided by you which should be unique for each payment

Status

a..50

M

OK (URLSuccess) or FAILED (URLFailure)

Description

ans..1024

M

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

an8

M

Error code according to Paygate Response Codes (A4 Error codes)

CodeExt

n..10

O

Error code from PayPal if agreed with Computop Helpdesk

refnr

ans..30

O

Merchant’s unique reference number

OrderID

ans..17

O

Unique PayPal-generated OrderID

TID

ans..17

O

Unique PayPal-generated CaptureID

Name

ans..50

M

First name and surname joined

FirstName

ans..50

M

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

LastName

ans..50

M

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

E-Mail

ans..100

M

Email address of the purchaser

BillingName

ans..32

O

First name and surname joined

BillingAddrCountryCode

an2

O

Country code of the billing address.

For the return of billing data, please contact your PayPal contact person directly, who must activate the return for both the live and the sandbox account.

PayerID

ans..13

O

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

Action

Version

Description

Authorize

1.0 / 2.0

Standard version without return of parameter Code

1.4 / 2.4

with TID

Capture

1.0 / 2.0

Standard version without return of parameter Code

1.x / 2.x

with RefNr (valid for all versions other than 1.0)

1.4 / 2.4

with TID

Credit

1.0 / 2.0

Standard version without return of parameter Code

1.x / 2.x

with RefNr (valid for all versions other than 1.0)

1.4 / 2.4

with TID

CreditEx

1.0 / 2.0

Standard version without return of parameter Code

1.x / 2.x

with RefNr (valid for all versions other than 1.0)

Reverse

1.0 / 2.0

Standard version without return of parameter Code

1.4 / 2.4

with TID

ABO/REFTRANS

1.0 / 2.0

ABO - Classic PayPal API

REFTRANS - Order V2 PayPal API

Standard version without return of parameter Code

1.x / 2.x

with RefNr (valid for all versions other than 1.0)