Integrating Recurring Payments

Both Direct Payment and Express Checkout support recurring payments. You can set up a recurring payment to handle a subscription and other payments that occur on a fixed schedule.

How Recurring Payments Work

When you support recurring payments for a buyer, you create a recurring payments profile. The profile contains information about the recurring payments, including details for an optional trial period and a regular payment period. Both periods contain information about the payment frequency and payment amounts, including shipping and tax, if applicable.

After creating a profile, PayPal automatically queues payments based on the billing start date, billing frequency, and billing amount. Payments reoccur until the profile expires, there are too many failed payments to continue, or you cancel the profile.

Note The buyer can also cancel a recurring payments profile. See Payment Advice Codes for more information.

After creating a recurring payments profile, you can view profile details or cancel the profile from your PayPal account. You can also access recurring payments reports from the PayPal Business Overview page.

Also, after creating a recurring payments profile, you can use the Recurring Payments API to do the following:

  • Get information about a recurring payments profile.
  • Change the status of a recurring payments profile.
  • Update the details of the recurring payments profile.
  • Bill the outstanding amount of the recurring payments profile.

Recurring Payments Terms

The following table lists and describes terms that are commonly used in the context of PayPal recurring payments.

Term

Definition

Recurring payments profile Your record of a recurring transaction for a single buyer. The profile includes all information required to automatically bill the buyer a fixed amount of money at a fixed interval.
Billing cycle Make one payment per billing cycle. Each billing cycle has 2 components:
  • The billing period specifies the unit to calculate the billing cycle (such as days or months).
  • The billing frequency specifies the number of billing periods that make up the billing cycle.

For example, if the billing period is Month and the billing frequency is 2, the billing cycle is 2 months. If the billing period is Week and the billing frequency is 6, PayPal schedules the payments every 6 weeks.

Regular payment period The main subscription period for this profile, which defines a payment amount for each billing cycle. The regular payment period begins after the trial period, if you specify a trial period for the profile.
Trial period An optional subscription period before the regular payment period begins. A trial period may not have the same billing cycles and payment amounts as the regular payment period.
Payment amount The amount the buyer pays for each billing cycle.
Outstanding balance If a payment fails for any reason, PayPal adds that amount to the profile's outstanding balance.
Profile ID An alphanumeric string (generated by PayPal) that uniquely identifies a recurring profile. You can specify the Profile ID in the TransactionSearch API operation to obtain all payments associated with the identified profile.

Recurring Payments With Direct Payment

Recurring payments with Direct Payment enables a recurring payment to be associated with a debit or credit card. For these payments, you must collect on your website all necessary information from your buyer, including billing amount and buyer's credit card information.

Merchants who offer free trial periods or plan to bill the first installment of a recurring payment at a later date may find it worthwhile to use the card verification feature. This feature allows merchants to verify the buyer's card, as a potential loss mitigation tool, before saving the card information and creating the buyer's recurring payment profile.

After you have collected the information, call the CreateRecurringPaymentsProfile API operation (NVP, SOAP) for each profile to be created. The CreateRecurringPaymentsProfile request must contain all required credit card information and must not contain a value for the TOKEN field.

The following table lists the fields that are required in the CreateRecurringPaymentsProfile request for recurring payments using direct payments.

NVP

SOAP

CREDITCARDTYPE CreditCardDetails.CreditCardType
ACCT CreditCardDetails.CreditCardNumber
EXPDATE CreditCardDetails.ExpMonth and CreditCardDetails.ExpYear
FIRSTNAME CreditCardDetails.CardOwner.PayerName.FirstName
LASTNAME CreditCardDetails.CardOwner.PayerName.LastName
PROFILESTARTDATE RecurringPaymentProfileDetails.BillingStartDate
BILLINGPERIOD ScheduleDetails.PaymentPeriod.BillingPeriod
BILLINGFREQUENCY ScheduleDetails.PaymentPeriod.BillingFrequency
AMT ScheduleDetails.PaymentsPeriod.Amount

The CreateRecurringPaymentsProfile response contains a Profile ID, which is an encoded string that uniquely identifies the recurring payments profile.

As with all direct payments, PayPal is completely invisible to your buyer before, during, and after the purchase. PayPal does not send an email receipt to the buyer, nor will the buyer's credit card statement indicate that PayPal processed the payment.

For more options when creating a recurring payments profile, see Options for Creating a Recurring Payments Profile in the Express Checkout guide.

Recurring Payments in Express Checkout

See the Recurring Payments section in the Express Checkout integration guide for a complete list of features and integration information.

Declined Payments

When some card issuers decline payment, they transmit within the API output a 1-2 digit payment advice code to the merchant. The format of the API output is PaymentAdviceCode=<Code>, where <Code> is the 1 or 2-digit payment advice code.

Payment Advice Codes

Visa and MasterCard send payment advice codes. It is important that merchants capture these codes and determine if the cardholder would like to cancel the recurring payment transaction.

The code contains additional information about why the payment was declined. For example, the advice code may tell you that the card has been terminated or that the transaction was declined for insufficient funds.

Payment advice codes for Visa and MasterCard include the following card-holder initiated codes:

MasterCard Response Values and Definitions
Response Code Possible reason for decline Suggested Action
01 (New account information). Expired Card Account upgrade, or Portfolio Sale Conversion. Obtain new account information before next billing cycle.
02 (Try again later). Over Credit Limit, or insufficient funds. Retry the transaction 72 hours later.
03 (Do not try again. Obtain another type of payment from customer due to account being closed or fraud). Account Closed Fraudulent. Obtain another type of payment from customer.
21 (Do not try again. Cardholder has canceled recurring charge). Cardholder has been unsuccessful at canceling recurring payment through merchant. Stop recurring payment requests.
Visa Response Values and Definitions
Response Code Possible reason for decline Suggested Action
02 (Stop a specific payment). Cardholder wants to stop only one specific payment in the recurring payment relationship. The merchant must NOT resubmit the same transaction. The merchant can continue the billing process in the subsequent billing period.
03 (Revoke authorization for further payments). Cardholder wants to stop all recurring payment transactions for a specific merchant. Stop recurring payment requests.
21 (Cancel all recurring payments for the card number in the request). All recurring payments have been canceled for the card number requested. Stop recurring payment requests.
Payment Advice Code example

The following is an example of a transaction response containing a payment advice code:

	PAYMENTADVICECODE=3&TIMESTAMP=2011%2d06%2d01T23%3a43%3a25Z&CORRELATIONID=bf130fe2af88b
	&ACK=Failure&VERSION=76%2e0&BUILD=1919055&L_ERRORCODE0=10004&L_SHORTMESSAGE0=Invalid%20Data
	&L_LONGMESSAGE0=This%20transaction%20cannot%20be%20processed%2e&L_SEVERITYCODE0=Error
	&AMT=1%2e00&CURRENCYCODE=USD