PayPal - Do Reference - Implementation Guides - Developers Area

PayPal - Do Reference

The PayPal Do Reference allows you to authenticate a PayPal user using Express Checkout. Repeat payments can then be taken from that PayPal account.

This service may also be used in conjunction with the PayPal Auth Capture Service to delay settlement of funds until shipment.

When using this service, there are four stages to the payment cycle:

re-direct customer to PayPal
authorisation of billing agreement
creation of billing agreement (with initial payment, if required)
collection of subsequent payments

The first stage is as outlined in the PayPal Express Checkout Service.

Payer Authorises Billing Agreement

The payer authorises the billing agreement. If you are performing an initial payment, they will also confirm that payment. PayPal will then re-direct the payer back to your website.

Creation of Billing Agreement

Once the payer is re-directed back to your website, your system sends a request to the DPG which returns details about the customer verification. If these details are in order, a further request is sent to the DPG. This results in the billing agreement being created. If you are performing an initial payment, funds for this will also be automatically transferred from the Payer's account into your PayPal merchant account.

Collection of Subsequent Payments

When you wish to take a subsequent payment from the payer, the details of the original transaction are passed to DataCash by your system. The DPG locates the billing agreement details and forwards the transaction to PayPal. PayPal transfer the funds and the result of this transaction is then passed back to your system.

Requirements

Before you can go live with this Service, you will need the following:

A PayPal Merchant account
An account with DataCash configured for PayPal

Transaction Processing Models

There are two payment processing models which can be used to implement the PayPal Do Reference Service. Either model can be used for each transaction. There are no restrictions, extra service charges or additional account configuration.

With Initial Payment. The billing agreement is set up and an initial payment is taken from the payer.

Without Initial Payment. The billing agreement is setup without an initial payment being taken.

In addition there are two Billing Types:

Merchant Initiated Billing. A new billing agreement will be created for all customers.
Merchant Initiated Billing Single Source. A new billing agreement will be created for all new customers. If an existing customer already has an active billing agreement with you, this agreement will be utilised, instead of creating a new one.

The subsequent payments which are taken from the agreement may be instant, or delayed if using the PayPal Auth Capture service.

Once the billing agreement has been setup at PayPal, it can be amended or cancelled if required. Any payments which are taken may also be refunded in exactly the same way as normal PayPal Express Checkout transactions. These features are available to both processing models without additional account configuration.

The default timeline setting for PayPal refunds is up to 60 days. In order to change default settings the merchant is advised to contact their Account Manager.

Create Billing Agreement with Initial Payment

When using this transaction processing model, the creation of the billing agreement and initial payment are triggered in the same transaction.

The transaction types that are used to create a billing agreement with this model are:

Transaction Type	Effect
set_express_checkout	Initiates transaction
get_express_checkout_details	Obtains results of customer verification process
do_express_checkout_payment	Transfers funds for initial payment from PayPal User to PayPal Merchant Account. Also creates billing agreement

Create Billing Agreement without Initial Payment

When using this transaction processing model, the billing agreement is created without performing an initial payment. Situations in which this could be implemented include:

Payment in installments
Charity donations
Utility payments, such as Council Tax, mobile phones or electricity

The transaction types that are used with this model are:

Transaction Type	Effect
set_express_checkout	Initiates transaction
get_express_checkout_details	Obtains results of customer verification process
create_billing_agreement	Creates billing agreement

Take Subsequent Payment

Once the billing agreement has been successfully created, your systems initiate the subsequent payments. The subsequent payments may be instant, or delayed if using the PayPal Auth Capture service.

Transaction Type	Effect
do_reference_transaction	Initiates subsequent payment from billing agreement

Update Billing Agreement

Enables the billing agreement description or custom annotation to be updated. It also enables the billing agreement to be cancelled.

Situations in which this could be implemented include:

billing agreement description is updated to reflect a new item or subscription added onto it
subscription expires
billing agreement description is updated to reflect an item or subscription removed from it
subscription is cancelled by customer

Transaction Type	Effect
update_billing_agreement	Updates information about the billing agreement, or cancels agreement

Performing Transactions

Each transaction type requires specific information to be provided. In addition to those listed, each requires a client and password - these are security details which identify your account.

Set Express Checkout

The information required for the set_express_checkout is nearly the same as for the PayPal Express Checkout Service. There is one additional piece of information which is required which specifies the billing_type. This will be one of:

MerchantInitiatedBilling - creates a new billing agreement
MerchantInitiatedBillingSingleSource - creates a new billing agreement if the payer does not already have another billing agreement with you

If an initial payment is not to be taken, the amount supplied with the transaction must be zero.

In addition to these, there are also various optional fields which can be submitted which relate to the billing agreement.

Get Express Checkout Details

The information required for the get_express_checkout_details is the same as for the PayPal Express Checkout Service.

Do Express Checkout Payment

This transaction type will only be used if a payment is being taken immediately. The information required for the do_express_checkout_payment is the same as for the PayPal Express Checkout Service. If successful, this transaction will create the billing agreement and take the initial payment.

Create Billing Agreement

If an initial payment is not being taken, a create_billing_agreement is required to set up the agreement. To perform this, the following information is required:

unique reference number generated by your system - to allow the transactions to be distinguished from each other
the DataCash reference of the set_express_checkout
the transaction method create_billing_agreement
the PayPal token from the set_express_checkout

Subsequent Payments: Do Reference Transaction

To collect a subsequent payment from the billing agreement, a do_reference_transaction is required with the following information:

unique reference number generated by your system - to allow the transactions to be distinguished from each other
the DataCash reference or billing agreement ID from the do_express_checkout or create_billing_agreement transaction
method must be do_reference
the value to be taken from the Payers account

If you wish to use the Auth Capture service to reserve funds and take payment later, the payment_action must be set to order. In this case, a do_authorization and a docapture will also be required to reserve and settle the funds.

In addition to these, there are also various optional fields which can be submitted. These include item and shipping data.

Update a Billing Agreement

To update a billing agreement, information from the transaction which created the agreement is required, in addition to the transaction type and details to be amended:

a unique reference number generated by your system - to allow the transactions to be distinguished from each other
the DataCash reference of the create_billing_agreement or do_express_checkout_payment
the transaction method update_billing_agreement

One or both of these fields should also be presented:

billing_agreement_description - the new description of goods or services associated with the billing agreement
billing_agreement_custom - the new custom annotation

Cancelling a Billing Agreement

To cancel a billing agreement, information from the transaction which created the agreement is required, in addition to the transaction type:

a unique reference number generated by your system - to allow the transactions to be distinguished from each other
the DataCash reference of the create_billing_agreement or do_express_checkout_payment
the transaction method update_billing_agreement
the billing_agreement_status of cancelled

Once an agreement has been cancelled, no further updates can be made to it.

Response Codes

When using this Service, the basic responses and error codes are the same as for the PayPal Express Checkout Service.

Reporting

Like the Express Checkout Service, transactions are detailed in the PayPal section of the DataCash Reporting system. Agreements are also visible within the PayPal Billing Agreement section of the DataCash Reporting system: