Reference Transaction Without Initial Payment

Reference transaction without initial payment for PayPal enables a merchant to execute recurring payment transactions for a particular customer, based on a Billing Agreement, without immediately charging the customer at the time of checkout.

Prerequisites

To activate PayPal Reference Transaction withоut Initial Payment, follow these steps:

Request activation of the PayPal payment method from the Concardis Payengine support team.
Set the PayPal Integrated Signup (ISU) in the Merchant Center.
Request activation of PayPal Reference Transaction withоut Initial Payment from your PayPal account manager. If no account manager is assigned, contact the PayPal support team.

Workflow

The following describes the workflow for this feature:

The merchant creates a PayPal payment Instrument.
- The merchant creates a payment instrument via API. (Payment Instrument creation via Merchant Center is not possible due to an end user interaction requirement.)
- In the Payment Instrument response, Payengine provides the billing agreement approval URL, to which the customer will be redirected.
- Once the merchant receives an approval for the billing agreement from the customer, the payment instrument becomes recurring is ready for use for debit translactions.

Advantages:

This billing agreement provides PayPal with an authorization to captute future payments.
The buyer does not have to log in to PayPal to authorize future payments.

The merchant can place orders on behalf of the customer, using the existing PayPal payment instrument.

Technical flow

The technical flow of Reference Transaction Without Initial Payment follows the steps below:

Step 1 - Create a PayPal Payment Instrument via API

Creating Payment Instrument for Reference Transaction Without Initial Payment is executed via API.

There is an end-user interaction required.

POST/payment-instruments Specific Request Parameters

The parameters returnUrl, cancelUrl, and notifyUrl from the "returnUrl": "https://example.com/return", "cancelUrl": "https://example.com/cancel", "notifyUrl": "https://example.com/notify" URLs, have the following role:

Prerequisite	Mandatory/Optional (M/O)	Create prerequisite
billingAgreementId	O	-
payment.returnUrl	M	The URL to which to redirect the customer when they have successfully accepted the PayPal billing agreement. Maximum length: 2048.
payment.cancelUrl	M	The URL to which the customer is redirected in cases when the PayPal billing agreement must be cancelled. Maximum length: 2048.
payment.notifyUrl	O	Notification URL provided by the merchant. The URL to which notifications are sent, when the PayPal billing agreement is created or canceled or payments on this billing agreement are processed. Read only. Maximum length: 2048.

Create payment instrument request

{
                      "type": "paypal",
                      "payment": {
                      "billingAgreementId": "38ieuikajekajsa"

Response POST/payment-instruments

In the Payment Instrument response, Payengine provides the billing agreement approval URL.

Create payment instrument response

{
                      "createdAt": 1563782183602,
                      "modifiedAt": 1563782183602,
                      "paymentInstrumentId": "paymentinstrument_rwvobmuagt",

The payment instrument will be ready for use in debit requests once:

The billing agreement payment instrument is successfully created.
The recurring parameter is set to true
The billingAgreementId is set in the PayPal object which belongs to the already created PayPal payment instrument.

Update existing payment instrument

PATCH/payment-instruments/{paymentInstrumentId}

Parameter

Description

PATCH/payment-instruments/{paymentInstrumentId}

Note:

Update the payment instrument - only the notifyUrl parameter could be updated.

Patch Request

{
                        "notifyUrl": "https://example.com/notify2"
                    }

Step 2 - Create a debit transaction: POST/orders/debit

Place an order, using an existing PayPal billing agreement.

Use the created payment instrument with the orderID from CreateOrder; and the billingagreementid from BillingAgreementApprove.

PayPal does not allow partial capture for reference transactions. Hence, the preauth and capture option are not allowed in PayEngine.

Request for PayPal debit with created payment instrument

{
                      "product" : "paypal",
                      "terms": 1468590412476,
                      "privacy": 1468590412476,

Success response of create debit with created payment instrument

{
                      "createdAt": 1563782891358,
                      "modifiedAt": 1563782891398,
                      "merchantId": "Merchant-11111111-1111-1111-1111-111111111111",

Refund Specific Request Parameters

POST {{publicApiUrl}}/{{apiVersion}}/orders/{{orderId}}/transactions/{{transactionId}}/refund

Refund specific request

{
                      "description": "description for transaction.",
                      "initialAmount": 200,
                      "currency": "EUR",

Refund specific response

{
                        "createdAt": 1565253820098,
                        "modifiedAt": 1565253823657,
                        "type": "REFUND",

Billing Agreement Cancellation

When the customer wants to cancel an existing billing agreement, the payment instrument must be deleted.

The merchant requests the cancellation of the billing agreement via the PayEngine.

Billing agreement cancellation

DELETE {{publicApiUrl}}/{{apiVersion}}/payment-instruments/{{paymentInstrumentId}}

Specific Request BIlling Agreement Cancellation Parameters

Parameter	Description
DELETE /payment-instruments/{paymentInstrumentId}	Cancels a billing agreement by ID.