PayPal integration

logo PayPal

Introduction

This section concerns the payment method PayPal.

It involves redirecting the cardholder to PayPal to finalize its transaction.

info

Upon receipt of EXECCODE = 0002 in the synchronous response, you must redirect the cardholder to the PayPal form by displaying the content of the REDIRECTHTML parameter. (Base64 encoded)

warning

The redirection to PayPal cannot be done inside an iframe.

After validating the payment on PayPal, the cardholder is redirected to the URL specified in the Dalenys Dashboard.

The result of the transaction will also be transmitted by HTTP notification. (See the specifics of the notification)

Compatible operations and options

Authorization specifics

On a PayPal account, the validity period of an authorization to be captured is 3 days.

Server to server integration

In this mode, you have to send a POST request containing your order’s parameters over HTTPS to the Dalenys platform.

Payment / authorization

Example

Here is a server to server request example:

$> curl --request POST --url "https://secure-test.dalenys.com/front/service/rest/process" \
--data "method=payment" \
--data "params[IDENTIFIER]=Demo Shop" \
--data "params[OPERATIONTYPE]=payment" \
--data "params[ORDERID]=1234" \
--data "params[AMOUNT]=1000" \
--data "params[CLIENTIDENT]=john.snow" \
--data "params[CLIENTEMAIL]=john.snow@example.com" \
--data "params[CLIENTUSERAGENT]=Mozilla/5.0 (Windows NT 6.1; WOW64; rv:47.0) Gecko/20100101 Firefox/47.0" \
--data "params[CLIENTIP]=10.1.1.1" \
--data "params[DESCRIPTION]=Knows nothing" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \
--data "params[VERSION]=3.0" \

Parameters

  • AMOUNT integer

    The transaction amount in the smallest money decimal (e.g. cents for euro).

    Example: 1000

  • APIKEYID string (36)

    ID used to authenticate a transaction using APIKEY.

    Example: a688b3a1-d227-4cdd-9454-5d7cfcc74ef9

  • BILLINGADDRESS string(1-50)

    The billing address. Be careful not to integrate any line breaks.

    Example: 285 Fulton Street

  • BILLINGCITY string(1-255)

    The billing city.

    Example: New York

  • BILLINGCOUNTRY string(2)

    The country code (ISO_3166-1_alpha-2).

    Example: US

  • BILLINGFIRSTNAME string(1-15)

    The first name part of the billing address.

    Example: John

  • BILLINGLASTNAME string(1-15)

    The last name part of the billing address.

    Example: Doe

  • BILLINGPHONE string(1-32)

    Billing phone number in international (E.164) format.

    Example: +33111111111

  • BILLINGPOSTALCODE string(1-9)

    The billing postal code.

    Example: 10007

  • CARDFULLNAME string(1-255)

    The holder’s full name (as described on the payment method). For 3-D Secure operations, the field CARDFULLNAME can only contain the following characters : [a-zA-Z1-9 -]

    Example: JOHN SNOW

  • CART[X][BRAND] string(1-100)

    Article brand.

    Example: Micropple

  • CART[X][CATEGORY] computersandsoftware, electronics, appliances, homeandgarden, fashion, healthandbeauty, jewellery, sport, leisureandhobbies, carsandmotorbikes, furniture, kidsandbaby, videogamesandconsoles, toysandgames, pets, foodanddrink, giftandflowers, entertainment, travel, auctionsandgroupbuying, servicesforindividuals, servicesforprofessionals

    Article category.

    Example: electronics

  • CART[X][DELIVERYEXPECTEDDATE] date(YYYY-MM-DD)

    Delivery Date.

    Example: 2017-06-20

  • CART[X][DELIVERYEXPECTEDDELAY] int (1-3)

    Number of days for delivery; must be greater than 0.

    Example: 2

  • CART[X][DELIVERYLABEL] string(1-100)

    Delivery method name or description.

    Example: Micropple store

  • CART[X][DELIVERYSPEED] standard,express

    Speed of the delivery method. (Specify EXPRESS if under 48h).

    Example: express

  • CART[X][DELIVERYTYPE] storepickup, networkpickup, travelpickup, billingaddress, carrier, edelivery, other

    Delivery method:

    storepickup: collection of the goods in the merchant store
    networkpickup: collection in a third party point (like ups, alveol, etc.)
    travelpickup: collection in an airport, train station or travel agency
    billingaddress: carrier such as La Poste, Colissimo, UPS, DHL…or any private carrier using billing address
    carrier: carrier such as La Poste, Colissimo, UPS, DHL…or any private carrier using shipto address
    edelivery: electronic ticket issuance, download, etc.

    Example: storepickup

  • CART[X][DISCOUNT] float

    Applied discount in percentage. The decimal separator is the dot symbol.

    Example: 10.5

  • CART[X][MERCHANTITEMID] string

    Item ID in the merchant system.

    Example: REF-123456

  • CART[X][NAME] string

    Item name.

    Example: Laser printer

  • CART[X][PRICE] int

    Unit price in cents, including potential taxes and discounts.

    Example: 20000

  • CART[X][QUANTITY] integer

    Quantity of this item.

    Example: 3

  • CART[X][SUBMERCHANTEXTERNALID] string(1-64)

    Submerchant account identifier in the marketplace. This field allow a special value “OPERATOR” when the item is sold by the marketplace itself (and not a sub-merchant).

    Example: shop1.com

  • CART[X][TAX] float

    Applied taxes in percentage. The decimal separator is the dot symbol.

    Example: 19.5

  • CART[X][TOTALAMOUNT] integer

    Total amount based on PRICE, QUANTITY. Also FEES when applied.

    Example: 60000

  • CLIENTADDRESS string(1-510)

    The user’s address.

    Example: 285 Fulton Street.

  • CLIENTDOB date(YYYY-MM-DD)

    The user’s date of birth.

    Example: 1982-06-20

  • CLIENTEMAIL email(5-255)

    The user’s email.

    Example: john.snow@example.com

  • CLIENTIDENT string(1-255)

    Unique identifier of the user in your application (e.g. a login or a primary key).

    Example: john.snow

  • CLIENTIP ipv4

    The user’s public IP address.

    Example: 10.1.1.1

  • CLIENTREFERRER string(1-255)

    The user’s HTTP referrer URL.

    Example: https://your_shop.com/order?id=1234

  • CLIENTUSERAGENT string(1-255)

    The HTTP user agent.

    Example: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:47.0) Gecko/20100101 Firefox/47.0

  • DESCRIPTION string(1-510)

    A short description of the operation, can be used to trigger fraud actions. Don’t hesitate to ask your Payment Manager for some advice on this topic.

    Example: Knows nothing

  • EXTRADATA string(1-255)

    Free field (Dalenys will send you back the content of the EXTRADATA you specified ahead).

    Example: referrer=myshop.com;order=premium

  • HASH string(64)

    The transaction’s hash as described in the dedicated section.

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: Demo Shop

  • METADATA string(1-255)

    Additional transactional data. Contact your account manager for more informations.

    Example: @METADATA-MYWEBSITE

  • OPERATIONTYPE payment, authorization

    The action you want to process.

    Example: payment

  • ORDERID string(1-40)

    Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)

    Example: 1234

  • SHIPTOADDRESS string(1-50)

    The shipping address.

    Example: 55 rue de la liberté

  • SHIPTOCITY string(1-255)

    The shipping city.

    Example: New York

  • SHIPTOCOUNTRY string(2)

    The country code (ISO_3166-1_alpha-2 format)

    Example: US

  • SHIPTOFIRSTNAME string(1-15)

    Holder’s first name in the shipping address.

    Example: John

  • SHIPTOLASTNAME string(1-30)

    Holder’s last name in the shipping address.

    Example: Doe

  • SHIPTOPHONE string(1-32)

    Shipping phone number in international (E.164) format.

    Example: +33111111111

  • SHIPTOPOSTALCODE string(1-9)

    The shipping postal code.

    Example: 10007

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

Request result

Here is the request result from the platform:

  • DESCRIPTOR string

    The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.

    Example: myshop.com

  • EXECCODE string(4)

    The operation result code. (See the complete list of execution code)

    Example: 0000

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

    Example: The transaction has been accepted

  • OPERATIONTYPE payment, authorization

    The action you want to process.

    Example: payment

  • REDIRECTHTML string(no length limit)

    HTML content to display to the user to continue the processing. The string is base64 encoded.

    Example:

  • TRANSACTIONID string(1-32)

    Unique Dalenys transaction ID. Make sure to store this ID in your database.

    Example: A1123456

Notification result parameters

Please see the dedicated section about notification and redirection

Here is the request result from the platform:

  • AMOUNT integer

    The transaction amount in the smallest money decimal (e.g. cents for euro).

    Example: 1000

  • CLIENTEMAIL email(5-255)

    The user’s email.

    Example: john.snow@example.com

  • CLIENTIDENT string(1-255)

    Unique identifier of the user in your application (e.g. a login or a primary key).

    Example: john.snow

  • CURRENCY string(3)

    Currency code (ISO 4217 format).

    Example: EUR

  • DESCRIPTOR string

    The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.

    Example: myshop.com

  • EXECCODE string(4)

    The operation result code. (See the complete list of execution code)

    Example: 0000

  • HASH string(64)

    The transaction’s hash as described in the dedicated section.

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: YOUR_IDENTIFIER

  • LANGUAGE fr, en, de, es, it, nl, zh, ru, pt, sk

    Configure the hosted form display language.

    Example: en

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

    Example: The transaction has been accepted

  • OPERATIONTYPE payment, authorization

    The action you want to process.

    Example: payment

  • ORDERID string(1-40)

    Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)

    Example: 1234

  • PP_ADDRESS_STATUS none, confirmed, unconfirmed

    Status of street address on file with PayPal.

    Example: `confirmed`

  • PP_PAYER_ID string(13)

    ID of Paypal payer’s account

    Example: A12345BCD6789

  • PP_PAYER_STATUS none, canceled-reversal, completed, denied, expired, failed, in-progress, partially-refunded, pending, refunded, reversed, processed, voided, completed-funds-held

    The status of the payment.

    Example: completed

  • PP_PROTECTION_ELIGIBILITY eligible, partiallyeligible, ineligible

    The kind of seller protection in force for the transaction.

    Example: eligible

  • PP_PROTECTION_ELIGIBILITY_TYPE itemnotreceivedeligible, unauthorizedpaymenteligible, ineligible

    The kind of seller protection in force for the transaction.

    Example: itemnotreceivedeligible

  • PP_SHIP_TO_CITY string(40 Bytes)

    Shipping city.

    Example: New York City

  • PP_SHIP_TO_COUNTRYCODE string(2)

    Country code.

    Example: NY

  • PP_SHIP_TO_NAME string(1-32)

    Holder’s shipping last name.

    Example: John Doe

  • PP_SHIP_TO_STREET string(1-100)

    Shipping street address.

    Example: Fulton St

  • PP_SHIP_TO_ZIP string(1-20)

    U.S. ZIP code or other country-specific postal code.

    Example: 10007

  • PP_TRANSACTION_ID string(20 max)

    Unique transaction ID of the payment.

    Example: a1B2c3D4e5F6g7H8

  • TRANSACTIONID string(1-32)

    Unique Dalenys transaction ID. Make sure to store this ID in your database.

    Example: A1123456

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

Capture

Authorizations have to be captured by a server to server request.

info

You can only capture a succeeded authorization transaction and an authorization can only be captured once.

warning

A capture must be triggered within 7 days of an authorization, otherwise capture success is no longer guaranteed.

tips

The capture AMOUNT may be lower but cannot exceed the initial authorization’s AMOUNT.

Example

Here is a server to server request example:

$> curl --request POST --url "https://secure-test.dalenys.com/front/service/rest/process" \
--data "method=capture" \
--data "params[IDENTIFIER]=Demo Shop" \
--data "params[OPERATIONTYPE]=capture" \
--data "params[TRANSACTIONID]=A1123456" \
--data "params[ORDERID]=1234" \
--data "params[DESCRIPTION]=Knows nothing" \
--data "params[VERSION]=3.0" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \

Parameters

  • AMOUNT integer

    When not specified, 100% of the authorization amount is captured. Could not be higher than the authorization amount.

    Example: 1000

  • DESCRIPTION string(1-510)

    A short description of the operation, can be used to trigger fraud actions. Don’t hesitate to ask your Payment Manager for some advice on this topic.

    Example: Knows nothing

  • EXTRADATA string(1-255)

    Free field (Dalenys will send you back the content of the EXTRADATA you specified ahead).

    Example: referrer=myshop.com;order=premium

  • HASH string(64)

    The transaction’s hash as described in the dedicated section.

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: Demo Shop

  • OPERATIONTYPE capture

    The action you want to process.

    Example: payment

  • ORDERID string(1-40)

    Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)

    Example: 1234

  • TRANSACTIONID string(1-32)

    The authorization’s TRANSACTIONID you want to capture.

    Example: A1123456

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

Request result

Here is the request result from the platform:

  • DESCRIPTOR string

    The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.

    Example: myshop.com

  • EXECCODE string(4)

    The operation result code. (See the complete list of execution code)

    Example: 0000

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

    Example: The transaction has been accepted

  • OPERATIONTYPE capture

    The action you want to process.

    Example: payment

  • TRANSACTIONID string(1-32)

    Unique Dalenys transaction ID. Make sure to store this ID in your database.

    Example: A1123456

Notification result parameters

Exactly the same result parameters than with hosted form integration.

Refund

Refunds can either be processed through server-to-server request or Dalenys Dashboard.

warning

The default refund period is 180 days from the transaction date.

Example

Here is a server to server request example:

$> curl --request POST --url "https://secure-test.dalenys.com/front/service/rest/process" \
--data "method=refund" \
--data "params[IDENTIFIER]=Demo Shop" \
--data "params[OPERATIONTYPE]=refund" \
--data "params[TRANSACTIONID]=A1123456" \
--data "params[ORDERID]=1234" \
--data "params[DESCRIPTION]=Knows nothing" \
--data "params[VERSION]=3.0" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \

Parameters

  • AMOUNT integer

    The amount to refund. When not specified, refund 100% of the initial transaction resting amount. Could not be higher than the resting amount.

    Example: 1000

  • DESCRIPTION string(1-510)

    A short description of the operation, can be used to trigger fraud actions. Don’t hesitate to ask your Payment Manager for some advice on this topic.

    Example: Knows nothing

  • EXTRADATA string(1-255)

    Free field (Dalenys will send you back the content of the EXTRADATA you specified ahead).

    Example: referrer=myshop.com;order=premium

  • HASH string(64)

    The transaction’s hash as described in the dedicated section.

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: Demo Shop

  • OPERATIONTYPE refund

    The action you want to process.

    Example: payment

  • ORDERID string(1-40)

    Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)

    Example: 1234

  • TRANSACTIONID string(1-32)

    The payment or capture’s TRANSACTIONID you want to refund.

    Example: A1123456

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

Request result

Here is the request result from the platform:

  • DESCRIPTOR string

    The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.

    Example: myshop.com

  • EXECCODE string(4)

    The operation result code. (See the complete list of execution code)

    Example: 0000

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

    Example: The transaction has been accepted

  • OPERATIONTYPE refund

    The action you want to process.

    Example: payment

  • TRANSACTIONID string(1-32)

    Unique Dalenys transaction ID. Make sure to store this ID in your database.

    Example: A1123456

Notification result parameters

Here is the request result from the platform:

  • AMOUNT integer

    The transaction amount in the smallest money decimal (e.g. cents for euro).

    Example: 1000

  • CLIENTEMAIL email(5-255)

    The user’s email.

    Example: john.snow@example.com

  • CLIENTIDENT string(1-255)

    Unique identifier of the user in your application (e.g. a login or a primary key).

    Example: john.snow

  • CURRENCY string(3)

    Currency code (ISO 4217 format).

    Example: EUR

  • DESCRIPTOR string

    The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.

    Example: myshop.com

  • EXECCODE string(4)

    The operation result code. (See the complete list of execution code)

    Example: 0000

  • HASH string(64)

    The transaction’s hash as described in the dedicated section.

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: YOUR_IDENTIFIER

  • LANGUAGE fr, en, de, es, it, nl, zh, ru, pt, sk

    Configure the hosted form display language.

    Example: en

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

    Example: The transaction has been accepted

  • OPERATIONTYPE refund

    The action you want to process.

    Example: payment

  • ORDERID string(1-40)

    Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)

    Example: 1234

  • TRANSACTIONID string(1-32)

    Unique Dalenys transaction ID. Make sure to store this ID in your database.

    Example: A1123456

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

Specific details

PayPal Seller Protection

In order to protect you against fraud attemps, it is possible to benefit the PayPal Seller Protection by sending additional parameters :

  • SHIPTOADDRESS string(1-50)

    The shipping address.

    Example: 55 rue de la liberté

  • SHIPTOCOUNTRY string(2)

    The country code (ISO_3166-1_alpha-2 format)

    Example: US

  • SHIPTOFIRSTNAME string(1-15)

    Holder’s first name in the shipping address.

    Example: John

  • SHIPTOLASTNAME string(1-30)

    Holder’s last name in the shipping address.

    Example: Doe

  • SHIPTOPHONE string(1-32)

    Shipping phone number in international (E.164) format.

    Example: +33111111111

  • SHIPTOPOSTALCODE string(1-9)

    The shipping postal code.

    Example: 10007

Request result

Results of those features will be given in the following notification result parameters:

Request result

  • PP_ADDRESS_STATUS none, confirmed, unconfirmed

    Status of street address on file with PayPal.

    Example: `confirmed`

  • PP_PAYER_ID string(13)

    ID of Paypal payer’s account

    Example: A12345BCD6789

  • PP_PAYER_STATUS none, canceled-reversal, completed, denied, expired, failed, in-progress, partially-refunded, pending, refunded, reversed, processed, voided, completed-funds-held

    The status of the payment.

    Example: completed

  • PP_PROTECTION_ELIGIBILITY eligible, partiallyeligible, ineligible

    The kind of seller protection in force for the transaction.

    Example: eligible

  • PP_PROTECTION_ELIGIBILITY_TYPE itemnotreceivedeligible, unauthorizedpaymenteligible, ineligible

    The kind of seller protection in force for the transaction.

    Example: itemnotreceivedeligible

  • PP_SHIP_TO_CITY string(40 Bytes)

    Shipping city.

    Example: New York City

  • PP_SHIP_TO_COUNTRYCODE string(2)

    Country code.

    Example: NY

  • PP_SHIP_TO_NAME string(1-32)

    Holder’s shipping last name.

    Example: John Doe

  • PP_SHIP_TO_STREET string(1-100)

    Shipping street address.

    Example: Fulton St

  • PP_SHIP_TO_ZIP string(1-20)

    U.S. ZIP code or other country-specific postal code.

    Example: 10007

  • PP_TRANSACTION_ID string(20 max)

    Unique transaction ID of the payment.

    Example: a1B2c3D4e5F6g7H8