Paypal

Paypal is an online financial service that allows paying for items using a secure internet account.

Store the PayPal TRANSACTIONID of the payment as returned by the parameter gatewayReferenceNumber within the data regarding the corresponding session and order for documentation purposes.

To enable the integration of PayPal into the online shop in our QENTA Checkout solutions some third-party permissions have to be added to the PayPal Business Account for accessing PayPal-related payment information. Follow the required setup steps described in 3rd party permissions.

Commands

Pre Transaction Commands

The first step is to generate a unique order number with the command CREATEORDER.

Transaction Commands

INITIATEPAYMENT

Request Parameters
Table 1. Request Parameters
Required Parameters Optional Parameters

MERCHANTKEY

LOGPATH

COMMAND

LANGUAGE

INITTYPE

DEPOSITAMOUNT

PAYMENTTYPE

ORDERREFERENCE

AMOUNT

CUSTOMERSTATEMENT

CURRENCY

TRANSACTION_IDENTIFIER

ORDERNUMBER

CONFIRMURL

ORDERDESCRIPTION

APPLICATIONTYPE

SUCCESSURL

ORIGINATOR

CANCELURL
Parameters of consumer billing data and basket data are required for PayPal Seller Protection.
Table 2. Length Restrictions for Some Basket Data
Parameter Data type Description

BASKET_ITEM_<m>_ARTICLE_NUMBER

Alphanumeric with special characters, up to 128 characters.

Unique ID of article n in the shopping basket.

BASKET_ITEM_<m>_DESCRIPTION

Alphanumeric with special characters, up to 128 characters.

Product description of article n in the shopping basket.
Table 3. Length Restrictions for Some Basket Data
BASKET_ITEM_<m>_ARTICLE_NUMBER

Data

Value

Data type

Alphanumeric with special characters, up to 128 characters.

Description

Unique ID of article n in the shopping basket.

BASKET_ITEM_<m>_DESCRIPTION

Data

Value

Data type

Alphanumeric with special characters, up to 128 characters.

Description

Product description of article n in the shopping basket.

Optional request parameters CUSTOMERSTATEMENT and ORDERREFERENCE, are more restricted about their length and allowed characters than usual.

Parameter basketItem to Redeem Vouchers

If the consumer in the online shop redeems a voucher or coupon during the payment process, the optional request parameter BASKET_ITEMS must be used. This parameter must contain the negative amount corresponding to the voucher or coupon value. For vouchers with a percentage discount, the percentage to be deducted must first be converted into an absolute value. The total basket amount displayed to the consumer in the online shop will then show both the voucher amount and the total basket amount reduced by the voucher amount.

If the consumer in the online shop redeems a voucher or coupon during the payment process, the optional request parameter BASKET_ITEMS must be used. This parameter must contain the negative amount corresponding to the voucher or coupon value. For vouchers with a percentage discount, the percentage to be deducted must first be converted into an absolute value. The total basket amount displayed to the consumer in the online shop will then show both the voucher amount and the total basket amount reduced by the voucher amount.

Response Parameters
Table 4. Response Parameters
Required Parameters Optional Parameters

status

header

version

body

errorCode

message

paySysMessage

originator
Initialization example
PayPal payment method can be initialized if the merchant sends PAYPAL for parameter INITTYPE and PAYPAL for the parameter PAYMENTTYPE.

  1. Send a request.

    Example of Request for Initiation
    COMMAND=INITIATEPAYMENT&
MERCHANTKEY=43gADp5.UOZxPTet6O8o8K6o-7RefQB3BO21OMu4chB65LJUI_&
INITTYPE=PAYPAL&
PAYMENTTYPE=PAYPAL&
ORDERNUMBER=65061&
LANGUAGE=en&
AMOUNT=1&
CURRENCY=EUR&
APPLICATIONTYPE=S&
SERVICEURL=http://yourimprint.com/&
CUSTOMERSTATEMENT=eh3462t3hg346&
SUCCESSURL=https://yoursuccessurl.com&
ORDERDESCRIPTION=Test&
CANCELURL=https://yourfailureurl.com&
TRANSACTION_IDENTIFIER=INITIAL

  2. The response looks like this:

    Example of Response for Initiation
    header=Content-Type%3A+text%2Fhtml%0D%0A&
body=%3Chtml%3E%3Chead%3E%0D%0A%3Cmeta+http-equiv%3D%22refresh%22+content%3D%220%3BURL%3Dhttps%3A%2F%2Fwww.computop-paygate.com%2Fpaypal.aspx%3FMerchantID%3DQenta_Test1%26Len%3D367%26Data%3DE88E6E90321A17CF310FF8F79C02FF346B3256BDB55498C6B466A7607C1D7EA022CF09BCE657275B5E9A10E96DE03C3E4FD1EA73F8C397674F96B7C85EF1725DD52C4CB4A6246FC9782C792CBF35CD5398E8C84AF891B49CAAED9772CF0FF638E6FFE47A2B573F3B4ECC3D53F67AB87CBB08732FCBEFE0AEC998FA1387ED03126D5682A2B4C83647FAA3EBF663D7DA63516FA51F5847FD1965F080670A2998634CC90FB758B990BC40B0CFA09370A7D84423D7E64FB8AB7158C9D2AD08BD0EE5450C991CC680BBED8B28719DCA5A2E614CF8B003D663485E61592A28CC22656E5F10E3A935BB8AF9AF8AC2610BB34D192562AC4AD8D466C549227B367364C40682C873408D90D485B32A84B3C5E525A80EDFF8F9D3D8363A4231E59D0CC74A97A1278699EB6BBFC94EC38C051130BB55A47DFB2DF99CF8ADE0DA128992EAA13F69BFB2E8975DB25D9E8C3395891582BAA2981EDE4C508F77D8338849AED8B4F4B31AC31E7D728BFE6A89C52BFFAD9CC5%22%3E%0D%0A%3C%2Fhead%3E%3C%2Fhtml%3E&
version=qtillserver+3.23.0.47&
status=0

  3. Decode the text with URL Decoder. Use Notepad ++ or some other URL Decoder. After decoding the response should look like this.

    header=Content-Type: text/html
&body=<html><head>
<meta http-equiv="refresh" content="0;URL=https://www.computop-paygate.com/paypal.aspx?MerchantID=Qenta_Test1&Len=367&Data=E88E6E90321A17CF310FF8F79C02FF346B3256BDB55498C6B466A7607C1D7EA022CF09BCE657275B5E9A10E96DE03C3E4FD1EA73F8C397674F96B7C85EF1725DD52C4CB4A6246FC9782C792CBF35CD5398E8C84AF891B49CAAED9772CF0FF638E6FFE47A2B573F3B4ECC3D53F67AB87CBB08732FCBEFE0AEC998FA1387ED03126D5682A2B4C83647FAA3EBF663D7DA63516FA51F5847FD1965F080670A2998634CC90FB758B990BC40B0CFA09370A7D84423D7E64FB8AB7158C9D2AD08BD0EE5450C991CC680BBED8B28719DCA5A2E614CF8B003D663485E61592A28CC22656E5F10E3A935BB8AF9AF8AC2610BB34D192562AC4AD8D466C549227B367364C40682C873408D90D485B32A84B3C5E525A80EDFF8F9D3D8363A4231E59D0CC74A97A1278699EB6BBFC94EC38C051130BB55A47DFB2DF99CF8ADE0DA128992EAA13F69BFB2E8975DB25D9E8C3395891582BAA2981EDE4C508F77D8338849AED8B4F4B31AC31E7D728BFE6A89C52BFFAD9CC5">
</head></html>&version=qtillserver 3.23.0.47&status=0

  4. Beautify code (delete everything above and below html tag, and replace every "+" with empty space).

    <html>
    <head>
        <meta http-equiv="refresh" content="0;URL=https://www.computop-paygate.com/paypal.aspx?MerchantID=Qenta_Test1&Len=367&Data=E88E6E90321A17CF310FF8F79C02FF346B3256BDB55498C6B466A7607C1D7EA022CF09BCE657275B5E9A10E96DE03C3E4FD1EA73F8C397674F96B7C85EF1725DD52C4CB4A6246FC9782C792CBF35CD5398E8C84AF891B49CAAED9772CF0FF638E6FFE47A2B573F3B4ECC3D53F67AB87CBB08732FCBEFE0AEC998FA1387ED03126D5682A2B4C83647FAA3EBF663D7DA63516FA51F5847FD1965F080670A2998634CC90FB758B990BC40B0CFA09370A7D84423D7E64FB8AB7158C9D2AD08BD0EE5450C991CC680BBED8B28719DCA5A2E614CF8B003D663485E61592A28CC22656E5F10E3A935BB8AF9AF8AC2610BB34D192562AC4AD8D466C549227B367364C40682C873408D90D485B32A84B3C5E525A80EDFF8F9D3D8363A4231E59D0CC74A97A1278699EB6BBFC94EC38C051130BB55A47DFB2DF99CF8ADE0DA128992EAA13F69BFB2E8975DB25D9E8C3395891582BAA2981EDE4C508F77D8338849AED8B4F4B31AC31E7D728BFE6A89C52BFFAD9CC5">
    </head>
</html>

  5. Execute the HTML, and the PayPal mask should be seen in a browser. Enter specific test data for PayPal payment method. After that, the merchant will be redirected to the successUrl (which is invalid in this example).

VERIFYPAYMENT

Request Parameters
Table 5. Request Parameters
Required Parameters Optional Parameters

MERCHANTKEY

LOGPATH

COMMAND

LANGUAGE

ORDERNUMBER

APPLICATIONTYPE

PAYMENTNUMBER

QTILL_CLIENT_IP_ADDRESS

ORIGINATOR
Response Parameters
Table 6. Response Parameters
Required Parameters Optional Parameters

status

orders

version

errorCode

message

paySysMessage

originator
Order as a basis type of properties in the response can be returned for this command.
The additional parameters will be returned.
Table 7. Response Parameters
Required Parameters Optional Parameters

status

orders

version

errorCode

message

paySysMessage

originator
Order as a basis type of properties in the response can be returned for this command.
The additional parameters will be returned.
Verifying payment example

  1. Send a request.

    Request Parameters
    MERCHANTKEY=43gADp5.UOZxPTet6O8o8K6o-7RefQB3BO21OMu4chB65LJUI_&
COMMAND=VERIFYPAYMENT&
APPLICATIONTYPE=S&
ORDERNUMBER=65061&
LANGUAGE=en

  2. The response looks like this:

    Response Parameters
    order.1.amount=1.00&
payment.1.1.paymentNumber=65061&
payment.1.1.paypalPayerAddressCity=Graz&
payment.1.1.timeModified=02.11.2022+11%3A56%3A39&
payment.1.1.paymentType=PAYPAL&
order.1.merchantNumber=840&
order.1.depositAmount=1.00&
payment.1.1.paypalPayerAddressCountryCode=AT&
payment.1.1.approvalCode=8AM085001W130254S&
payment.1.1.providerReferenceNumber=8AM085001W130254S&
payment.1.1.paypalPayerAddressName=QentaXYZ1+QCP+Example&payment.1.1.paypalPayerAddressCountry=%D6sterreich&
payment.1.1.orderNumber=65061&
payment.1.1.paypalPayerAddressStreet1=Reininghausstrasse+10&
order.1.approveAmount=0&
order.1.credits=0
&payment.1.1.merchantNumber=840&
order.1.payments=1&
version=qtillserver+3.23.0.48&
order.1.refundAmount=0&
payment.1.1.currency=EUR&
order.1.state=ORDERED&
payment.1.1.paypalPayerAddressZIP=8020&
orders=1&
payment.1.1.batchNumber=300000607&
order.1.acquirer=PayPal&
order.1.brand=PayPal&
payment.1.1.paypalPayerAddressState=Graz&
status=0&
payment.1.1.paypalBillingAgreementID=B-5TT20067KS239603K&
payment.1.1.depositAmount=1.00&
order.1.orderText=Test&
order.1.contractNumber=qenta+test&
payment.1.1.state=payment_deposited&
order.1.customerStatement=eh3462t3hg346&
order.1.providerContractNumber=Qenta_Test1&
payment.1.1.paypalPayerLastName=Spintzyk&
order.1.timeModified=02.11.2022+11%3A56%3A39&
order.1.orderNumber=65061&
payment.1.1.gatewayReferenceNumber=bdd2452a746b48e387012b2b67ae4866& (1)
payment.1.1.paypalPayerFirstName=Wirecardbuyer&
payment.1.1.approveAmount=1.00&
order.1.currency=EUR&
payment.1.1.paypalPayerEmail=paypal.buyer2%40wirecard.com&
order.1.timeCreated=02.11.2022+11%3A55%3A18&
order.1.orderDescription=Test&
payment.1.1.timeCreated=02.11.2022+11%3A56%3A39&
order.1.paymentType=PAYPAL
1 Store the PayPal TRANSACTIONID of the payment as returned by the parameter gatewayReferenceNumber.

Post Transaction Commands

GETORDERDETAILS

Request Parameters
Table 8. Request Parameters
Required Parameters Optional Parameters

MERCHANTKEY

LOGPATH

COMMAND

LANGUAGE

ORDERNUMBER

APPLICATIONTYPE

ADMIN_PASSWORD

ORIGINATOR
Response Parameters
Table 9. Response Parameters
Required Parameters Optional Parameters

status

orders

version

errorCode

message

paySysMessage

originator
Order as a basis type of properties in the response can be returned for this command.
The additional parameters will be returned.
Table 10. Response Parameters
Required Parameters Optional Parameters

status

orders

version

errorCode

message

paySysMessage

originator
Order as a basis type of properties in the response can be returned for this command.
The additional parameters will be returned.
Getting order details example

  1. Send a request.

    Request Parameters
    MERCHANTKEY=43gADp5.UOZxPTet6O8o8K6o-7RefQB3BO21OMu4chB65LJUI_&
COMMAND=GETORDERDETAILS&
ORDERNUMBER=65061&
ADMIN_PASSWORD=9p3a0m5f&
APPLICATIONTYPE=S&

  2. The response looks like this:

    Response Parameters
    order.1.amount=1.00&
payment.1.1.paymentNumber=65061&
payment.1.1.paypalPayerAddressCity=Graz&
payment.1.1.timeModified=02.11.2022+11%3A56%3A39&
payment.1.1.paymentType=PAYPAL&
order.1.merchantNumber=840&
order.1.depositAmount=1.00&
payment.1.1.paypalPayerAddressCountryCode=AT&
payment.1.1.approvalCode=8AM085001W130254S&
payment.1.1.providerReferenceNumber=8AM085001W130254S&
payment.1.1.paypalPayerAddressName=QentaXYZ1+QCP+Example&
payment.1.1.orderNumber=65061&payment.1.1.paypalPayerAddressCountry=%D6sterreich&
payment.1.1.paypalPayerAddressStreet1=Reininghausstrasse+10&
order.1.approveAmount=0&
order.1.credits=0&
payment.1.1.merchantNumber=840&
order.1.payments=1&
version=qtillserver+3.23.0.48&
order.1.state=ORDERED&
payment.1.1.currency=EUR&
order.1.refundAmount=0&
payment.1.1.paypalPayerAddressZIP=8020&
orders=1&
order.1.brand=PayPal&
order.1.acquirer=PayPal&
payment.1.1.batchNumber=300000607&
payment.1.1.paypalPayerAddressState=Graz&status=0&
payment.1.1.paypalBillingAgreementID=B-5TT20067KS239603K&
payment.1.1.depositAmount=1.00&
order.1.orderText=Test&
order.1.contractNumber=qenta+test&
payment.1.1.state=payment_deposited&
order.1.customerStatement=eh3462t3hg346&
order.1.providerContractNumber=Qenta_Test1&
payment.1.1.paypalPayerLastName=Spintzyk&
order.1.orderNumber=65061&
order.1.timeModified=02.11.2022+11%3A56%3A39&
payment.1.1.gatewayReferenceNumber=bdd2452a746b48e387012b2b67ae4866&objectsTotal=1&
payment.1.1.approveAmount=1.00&
payment.1.1.paypalPayerFirstName=Wirecardbuyer&
order.1.currency=EUR&
payment.1.1.paypalPayerEmail=paypal.buyer2%40wirecard.com&
order.1.timeCreated=02.11.2022+11%3A55%3A18&
order.1.orderDescription=Test&
payment.1.1.timeCreated=02.11.2022+11%3A56%3A39&
order.1.paymentType=PAYPAL

DEPOSIT

PayPal transactions are by default set to be approved and deposited in one step, but it can be split it up into a two-step process. That allows distinguishing between approved and deposited payments and performing certain actions for each of them.

To separate the transaction flow into authorization and capture, get in contact with the integration specialists. Look at the order flow diagram of the payment method for closer information.

The transaction is automatically deposited by using the command INITIATEPAYMENT, in this case, the command DEPOSIT isn’t used. Look at the order flow diagram of the payment method for closer information.

APPROVEREVERSAL

For using the command APPROVEREVERSAL, payment needs to be in an approved state. Look at the order flow diagram of the payment method for closer information.
By default, a Paypal payment is automatically captured with the full amount. If want to separate the transaction flow into authorization and capture, get in contact with the integration specialists.

RECURPAYMENT

Request Parameters
The parameter TRANSACTION_IDENTIFIER must be set to INITIAL with the command INITIATEPAYMENT to flag it as a transaction to recur at a later point.

For using the command RECURPAYMENT a request approval is needed, so contact PayPal Customer Support or the PayPal account representative. After receiving approval from PayPal also contact our integration specialists to enable this feature.

If the parameter CONSUMER_SHIPPING_COUNTRY is set, PayPal will display its own pages in the language of that country; otherwise, PayPal will use the language configured within the web browser of the consumer.

If the parameter CONSUMER_SHIPPING_COUNTRY is set, PayPal will display its own pages in the language of that country; otherwise, PayPal will use the language configured within the web browser of the consumer.

If no shipping address is entered e.g. only digital goods are sold and there is no shipping then the respective parameter is NOSHIPPING=1. To prevent the consumer in the online shop from editing the shipping address then the respective parameter is ADDROVERRIDE=1.
The merchant configuration has to be changed by our integration specialists.
Table 11. Request Parameters
Required Parameters Optional Parameters

MERCHANTKEY

LOGPATH

COMMAND

LANGUAGE

ORDERNUMBER

APPLICATIONTYPE

SOURCEORDERNUMBER

DEPOSITAMOUNT

CURRENCY

CUSTOMERSTATEMENT

AMOUNT

ORIGINATOR

ADMIN_PASSWORD

ORDERDESCRIPTION
Response Parameters
Table 12. Response Parameters
Required Parameters Optional Parameters

status

orders

version

errorCode

message

paySysMessage

originator
Recurring payment example

  1. Send a request.

    Request Parameters
    COMMAND=RECURPAYMENT&
MERCHANTKEY=43gADp5.UOZxPTet6O8o8K6o-7RefQB3BO21OMu4chB65LJUI_&
ORDERNUMBER=4196405&
SOURCEORDERNUMBER=65061&
AMOUNT=1&
CURRENCY=EUR&
ORDERDESCRIPTION=Test:0000&
ADMIN_PASSWORD=9p3a0m5f&
APPLICATIONTYPE=S&

  2. The response looks like this:

    Response Parameters
    version=qtillserver+3.23.0.48&
status=0

REFUND

Request Parameters
Table 13. Request Parameters
Required Parameters Optional Parameters

Required Parameters

Optional Parameters

MERCHANTKEY

LOGPATH

COMMAND

LANGUAGE

ORDERNUMBER

APPLICATIONTYPE

AMOUNT

CREDITNUMBER

ADMIN_PASSWORD

CURRENCY

MERCHANTREFERENCE

CUSTOMERSTATEMENT

ISO_TRANSACTION_TYPE

ORIGINATOR
For refunds, basket item data are additional optional parameters.
Response Parameters
Table 14. Response Parameters
Required Parameters Optional Parameters

status

orders

version

errorCode

message

paySysMessage

originator

creditNumber
Refunding example

  1. Send a request.

    Request Parameters
    MERCHANTKEY=43gADp5.UOZxPTet6O8o8K6o-7RefQB3BO21OMu4chB65LJUI_&
COMMAND=REFUND&
ORDERNUMBER=65061&
CURRENCY=EUR&
AMOUNT=1.00&
ADMIN_PASSWORD=9p3a0m5f&
APPLICATIONTYPE=S&
LANGUAGE=en

  2. The response looks like this:

    Response Parameters
    creditNumber=14394755&
version=qtillserver+3.23.0.48&
status=0

Query Commands

For every payment method commands QUERYORDERS, QUERYCREDITS, and QUERYBATCHES are used.

Order Flow Diagram

One Step Transaction (default)

Image

Two Step Transaction

Contact our integration specialists to enable this workflow.
Image

To interpret this diagram, the successful completion of a NEW PAYMENT is assumed. Starting from this command it’s possible to carry out different commands.

All possible commands for specific acquirers are found here.