PayPal - Do Reference

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 MasterCard Payment Gateway Services 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 MasterCard Payment Gateway Services 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 MasterCard Payment Gateway Services 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 MasterCard Payment Gateway Services 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 MasterCard Payment Gateway Services 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 MasterCard Payment Gateway Services 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 MasterCard Payment Gateway Services Reporting system. Agreements are also visible within the PayPal Billing Agreement section of the MasterCard Payment Gateway Services Reporting system: