Billing agreements: taking the first payment immediately

[MikeHopley]

Again, this is for the REST API in general.

When creating a billing agreement, the start_date parameter is required. It is formatted as an ISO8601 timestamp.

Generally when people sign up to a subscription, we want to take the first payment immediately. Indeed, my system listens specifically for payment IPNs rather than "subscription started" IPNs.

So what are we supposed to do here? Do we set the start_date to the exact current time? Do we set it in the past? Do we set it a few minutes in the future, hoping that we can guess how long the user will take to finish the Paypal signup?

If we set it too far in the future (say, an hour), the user must wait a while before getting access to premium content. If we set it too soon (say, a minute), then the user may take too long filling in the form; when they come back to our website, we will attempt to start the billing agreement in the past. That worries me. How will Paypal respond if I ask them to take a payment in the past?

Could this parameter be made optional, so that default behaviour is "pay immediately" and delaying the payment is optional?

[jziaja]

I've forwarded this question to the API team and will let you know as soon as I hear back from them. :)

[MikeHopley]

Thank you! :)

[MikeHopley]

One more thought:

Does it even make sense to define this in the billing agreement? Shouldn't things like start date and trial period be defined in the plan?

Here's how I think of it:

The Plan is a template for creating a subscription. It contains all of the logic about how much to charge, how often, when to start, whether to offer a trial, and so on.

The Agreement is where you ask users for permission to sign them up to a plan. The agreement also contains any user-specific data that Paypal or the merchant requires. For example, you might need to pass a user ID from the merchant's database to Paypal's page, which Paypal would return via IPN; this would be done using the Agreement.

[jziaja]

You're correct to think of it that way - that the plan is a template for creating a subscription agreement. However, the plan is (from the API's perspective) intended to be something that can be setup well in advance of creating an agreement. The agreement start_date reflects when the agreement for the plan should begin.

To your point of an agreement representing asking users for permission to sign up with the plan, the agreement is also the part where your users agree exactly when their plan will begin (and how long their trial period will be and what date, specifically, the trial period will end). Granted, most agreements will likely include a start_date that is immediate, but this could be an open-ended property for services that require more setup ahead of time (e.g. a hosting service that first needs to run maintenance tasks in preparation for setting up a hosting environment for a customer).

[MikeHopley]

Ah yes, you're right of course. It does potentially need the start date to be specified in the agreement.

...assuming that the start date is an actual date, rather than an offset. But even then, it's probably more flexible to put a date in the agreement, rather than an offset in the plan. For example, a company might require more setup time over Christmas when staff are on holiday.

[sjmog]

+1 for this, with the added difficulty that I'd like to initially charge a variable amount (so for instance a user signs up with a 50% off your first month code). Is this a viable way to do it?:

• Set up a plan when the user starts checkout with the first billing amount being their discounted price
• Set up a billing agreement for the user to authorise with a start date in an hour
• Once the first payment is cleared, run a cron job to update the plan amount to the undiscounted rate for next month's billing

Seems unbelievably complicated to me but I can't see any other way to do this without forcing the user to authenticate twice (once to authorise a payment, then once to authorise the billing agreement)

[sjmog]

From what I can see, this could be possible with Future Payments (provided they could be handled on the server-side) but I can only see access to that through the mobile SDK.

[sjmog]

Also, the Ruby API ref docs don't have example calls for dealing with Plans.

[jziaja]

Thanks for sharing your use case, @sjmog - we'll include that scenario in our discussions with the Subscription API team and get back to you when we know the answer. I agree that the whole thing is overly complicated in its current form, and we're looking to see if we can help mitigate that complexity a bit by providing more samples and possibly more helper methods in the SDK.

On that note, the PayPal SDK team is currently compiling a list of use cases to discuss with the Subscription API team so we can update our sample projects with descriptions and code walkthroughs of how to handle various types of plans and agreements. Please continue to share any other use cases you might want or need clarification on so we can provide better samples & guidance. :)

As for the developer docs page on Billing Plans & Agreements, it looks like Ruby isn't alone in lacking examples - every other language is missing them as well (except for the cURL calls). I'll notify the docs team to see if we can begin the process of getting those code samples for each language.

[Olliepop]

+1

[sjmog]

Another question – when setting up a Plan, you have the option to add a setup_fee as part of the merchant_preferences. Is this fee taken immediately at checkout, or bundled with the first automatic payment?

If taken instantly, it could accommodate what I'm trying to do.

[jaypatel512]

@sjmog @MikeHopley Good news !! As per @sjmog suggestion, you could use setup_fee to make the first charge.

This is the response from the internal API Team:

• setup_fee immediately starts processing after billing agreement execution. Till the setup_fee is processed, the status of the billing agreement would be pending. So, once the agreement becomes active, it means, you have processed setup_fee.

Note: The setup_fee will get processed when the agreement is executed (and not created) in paypal as funding source. (Once buyer agrees to agreement in the flow)

Let me know if you have any follow up questions around this.

[sjmog]

OK great, thanks. Would be sensible to be able to change the name of setup_fee so it could be use case-dependent.

[MikeHopley]

This is far from intuitive. The documentation will need to be explicit and show examples, or so many people are going to be confused. I remember Worldpay pulling something like this with free trials, where my customers got charged immediately despite being on a free trial. I was not a happy bunny.

Just to get this clear, could I go through two scenarios? This is what I think will happen; please confirm or correct:

Scenario 1: with setup fee

I create a billing agreement for $5 each month. I set the setup_fee to $5. The customer approves the agreement on Paypal's website and returns to my website, where I execute the agreement.

Outcome: the customer is charged $5 immediately, and then $5 a month later, and so on.

Scenario 2: no setup fee

I create a billing agreement for $5 each month, but I leave setup_fee unset. The customer approves the agreement on Paypal's website and returns to my website, where I execute the agreement.

Outcome: the customer is charged nothing at first, but will be charged $5 a month later, and so on.

[sjmog]

@MikeHopley that's what I understand will happen. You have to set the recurring date for the agreement in the future.

As it stands, the only way PayPal can account for variably-priced initial subscriptions (e.g. checkout codes and so on) is if each new subscription has its own plan. And its own agreement. So users will have two objects, a plan and an agreement – which seems needlessly complex, but it's better than not being able to do variable pricing at all.

[MikeHopley]

Thanks @sjmog !

[jaypatel512]

Btw, if you checkout the api docs for creating an agreement, you will see they have an override_merchant_preferences field, that allows you to override setup_fee, on each agreement, where you could add a variable value based on when they start.

So, generally, what I would suggest is to get the subscription start date as for e.g. 1st of every month, and pro-rate the remaining days (charge them for remaining days from the day they sign up the agreement) as a setup_fee. This way, they get charged 1st of every month, from the next month. And you get the amount for the few days from the signed up date, to 1st of next month.

[sjmog]

@jaypatel512 excellent so long as the user has no checkout code or discount!

[nitrotm]

That logic should work but it seems on the sandbox (developer mode) payments are not processed at all. I have a setup_fee which is pending since beginning of December 2014 and several agreements not generating any transactions despite being active. Basically neither setup_fee or monthly payments transactions get sent from test buyer to test facilitator.

Is there something special about the sandbox which freezes subscriptions? Are they simply not scheduled at all? I could try directly in production to see if it works but I would prefer to validate the whole logic in sandbox first.

[ulkas]

@nitrotm there is a known problem with billing plans and agreement on IPN reporting on sandbox as far as i know.

[nitrotm]

@ulkas thanks for the info. In my case it's not only the IPN notifications which are not working but also the execution of the agreement itself. If I log on paypal sandbox and check my accounts (facilitator and/or buyer) the subscriptions are active but no payment is made at all. Maybe it's related to the IPN in some ways but so far I fail to connect these two issues.

[sjmog]

@ulkas ah, ok! What is the known problem?

[gregwym]

Hi @nitrotm, have you figured out the pending issue? Does this issue exists in the live environment as well?

[nitrotm]

@gregwym After going live, I found the initial payment was not processed reliably in production. So I implemented a server-side check to make sure the agreement is in 'active' state as a confirmation that the subscription is still valid, until I can receive and confirm a transaction. Eventually the initial payment is made, but that could be up to a day later.
For the sandbox, I didn't test again, so I can't tell if it now works there.

[ppmtscory]

Internal tickets for tracking setup_fee returning 0.00 and also delay in the charging of setup_fee are noted in #504. Hence, closing this issue.

[benbaler]

Hi,
I have the same problem that first payment not been paid and I added a setup fee like people suggest here but still users subscribe to my plan and I do not get any payment right away.
Does anyone have news on this issue?

[omarkilani]

@benbaler see #504

[aquarelius-]

Hi @ppmtscory,

Could you please throw some light at why did you close this request?

Reading through this and other related threads, I can see that setup_fee is being discussed as workaround to take first payment immediately.

So, are you guys ever going to introduce whatever permanent solution? As I understand original request implies this.

[braebot]

@aquarelius-, please see #504.

[pranishres]

what happens if the customer has 0 balance in his account. If I charge a setup_fee will the agreement gets created? And what happens to the amount of the setup_fee

[omarkilani]

@viper-pranish that's the entire point of #504 . The fix will (hopefully) be live on August 22nd.

[pranishres]

@omarkilani Paypal rest api asks for start date in ISO8601 and I sent the start_date converting my local time to GMT time zone in yyyy-MM-dd'T'HH:mm:ss'Z' format. Lets say I sent the date as 2016-09-10T01:00:00Z which is in future ofcouse. Then when I check the start_date set in agreement, it becomes 2016-09-10T08:00:00Z i.e +7 hours. And the nextBillingDate is also always set to 2016-09-10T10:00:00Z no matter at which time of the day I create the agreement, the nextBillingDate is always set at 10:00:00 hours.

[omarkilani]

@viper-pranish this is an unfortunate "feature" of the PayPal API. The fact that they return timestamps in PDT instead of UTC like any sane service tells you all you need to know about how much they care about this. :)

I think the real issue here is that all this stuff is built on a legacy core, which probably can never be touched because of how entrenched PayPal is.

[m-aarouf]

@omarkilani are you sure about the time zone returned by PayPal ?
I have noticed that lastPaymentDate is being returned in UTC format. However, I am not sure about the time zone of nextBillingDate since as @viper-pranish mentioned it is always being returned at 10:00:00.

[Kyderman]

I have a large amount of customers not being able to get passed the initial payment (state of "cancelled") is passed back, which is what I want.

Why are so many people not able to make the initial payment?

[par0v0zik]

And what if I have next_billing_date as a past date?
Like its 2016-11-08 now, and the next_billing_date is "2016-11-07T10:00:00Z"

[wasa4587]

+1 same as @viper-pranish,
So it will never be solved?

[andreaperizzato]

I'm experiencing the same issue as @viper-pranish. I tried both live and in sandbox.

Sandbox

• Now: 2016-12-05T15:22:09Z
• Request: start_date: 2016-12-05T15:32:09Z
• Response: start_date: 2016-12-05T08:00:00Z, next_billing_date: 2016-12-05T10:00:00Z

Live

• Now: 2016-12-05T14:49:56Z
• Request: start_date: 2016-12-05T14:59:56Z
• Response: start_date: 2016-12-04T23:00:00Z, next_billing_date: 2016-12-05T10:00:00Z.

What am I supposed to do? I just want to subscription to start as soon as users subscribe, by charging them as soon as possible. Is there a document clarifying these issues?

@viper-pranish reported this issue months ago. Has it been solved? Is there a workaround?

Since it looks like an issue related to time-zones, I live in UK (UTC).
Also, I'm using the Node SDK.

[clarkejm]

I'm using the JS API and it has the same issue.
If I try and create an agreement with a start_date in 30 minutes (calculated by UTC) Paypal ignores this and sets the start_date to the next 08:00 UTC time and the next_billing_date to 10:00 UTC.
Even if I try to patch these, it ignores the update and sticks to these times.

Does Recurring Billing even support different times? Is this an undocumented "feature"

P.S the setup_fee workaround is not acceptable as I need to charge the customers actual setup fees!

[omarkilani]

Yes this is a "feature". It aligns it with midnight in America/Los_Angeles because... I'm sure that's just how it was built 15 years ago or whatever. There is no solution apart from setup fee.

[MikeHopley]

P.S the setup_fee workaround is not acceptable as I need to charge the customers actual setup fees!

Could you add the two charges together (actual setup fee + initial subscription charge), and use this value for the setup_fee?

It's a hack, of course. Welcome to Paypal development. ;)

Alternatively, could you make two Paypal charges in separate API calls? One is the subscription with the initial payment using the setup_fee workaround; the second is a basic one-off payment for your actual setup fee.

[clarkejm]

There are ways to code around the issue but they deliver customer experiences that you have to talk around:

Why am I charged a setup fee when I accept the agreement as well as separately on the invoice?
Why does the site say my setup fee will be X and it is Y?
Why does Paypal say my agreement starts in xday/month/year?
How can I update my subscription between the initial transaction and the date it finally becomes effective?

It's not elegant and as your pricing structure gets more complex you create a bigger your barrier to sales.

[omarkilani]

And that's why we primarily use Stripe, and have PayPal as a backup for those who enjoy painful experiences. :)

[wasa4587]

I want to give some example of how to "fix" this
The way/hack to do it, is create a plan with setup fee, or a trial with a fee

This is a test plan I created

	{
	    "description": "Plan for Professional",
	    "merchant_preferences": {
	        "auto_bill_amount": "yes",
	        "cancel_url": base_path+"admin/plans",
	        "initial_fail_amount_action": "continue",
	        "max_fail_attempts": "1",
	        "return_url": base_path+"admin/payment/success",
					"setup_fee": {
							"value": "200",
							"currency": "USD"
					}
	    },
	    "name": "Professional plan",
	    "payment_definitions": [
	        {
	            "amount": {
	                "currency": "USD",
	                "value": "2"
	            },
	            "cycles": "0",
	            "frequency": "DAY",
	            "frequency_interval": "1",
	            "name": "Standard",
	            "type": "REGULAR"
	        },
					{
				    "name": "Trial Standard",
				    "type": "trial",
				    "frequency": "day",
				    "frequency_interval": "1",
				    "amount": {
					    "value": "2.5",
					    "currency": "USD"
				    },
				    "cycles": "1"
					}
	    ],
	    "type": "INFINITE"
	}

This is the list of events I received

BILLING.SUBSCRIPTION.CREATED
    2017-02-01T19:10:51Z

PAYMENT.SALE.COMPLETED
    2017-02-01T19:11:07Z 200.00 USD
    2017-02-01T19:11:38Z 2.50 USD
    2017-02-02T13:04:09Z 2.00 USD
    2017-02-03T10:17:36Z 2.00 USD
    2017-02-04T12:02:48Z 2.00 USD
    2017-02-05T10:15:38Z 2.00 USD
    2017-02-06T10:11:38Z 2.00 USD
    2017-02-07T11:12:17Z 2.00 USD
    2017-02-08T11:35:10Z 2.00 USD
    2017-02-09T11:50:36Z 2.00 USD
    2017-02-10T12:06:07Z 2.00 USD
    2017-02-11T11:52:37Z 2.00 USD
    2017-02-12T11:51:06Z 2.00  USD
    2017-02-13T11:58:08Z 2.00 USD
    2017-02-14T22:24:12Z 2.00 USD
    2017-02-15T12:15:45Z 2.00 USD
    2017-02-16T12:13:08Z 2.00 USD
    2017-02-17T12:21:35Z 2.00 USD
    2017-02-18T12:01:07Z 2.00 USD
    2017-02-19T10:21:06Z 2.00  USD
    2017-02-20T11:59:05Z 2.00 USD
    2017-02-21T12:13:19Z 2.00 USD
    2017-02-22T12:03:05Z 2.00 USD
    2017-02-23T12:04:37Z 2.00  USD

I hope this help some

[laudukang]

Is next_billing_date still always 10:00:00Z? Why not other time?

[randstraw]

In my understanding it is the date that is the important piece. The REST API implementation is built on the same engine as the Classic API, where time was not provided for this value, only the date.

NEXTBILLINGDATE: The next scheduled billing date, in YYYY-MM-DD format.

More details can be found in this thread #681

[usamamashkoor]

hi can anyone let me know how can i get the transaction fee for the setup fee.

[randstraw]

@usamamashkoor I believe you have an answer in another issue but if that is not the case please create one and we will look further.

[usamamashkoor]

@pp-randy yes thanks randy i have the answer.

[karabitski]

Can somebody please point to the topic how to implement customer subscription solution with variable weekly amount. API fails when you try to update Billing Plan payment definition.

[randstraw]

@karabitski we are tracking the ability here. Depending on the amount you can use the Classic API with the same Billing Agreements https://github.com/paypal/PayPal-REST-API-issues/issues/24

You can use https://developer.paypal.com/docs/classic/api/merchant/UpdateRecurringPaymentsProfile_API_Operation_NVP/ with the Billing Agreement Ids to modify prices, within some limitation though.

[mrafi127]

Why you people dont use

ActivationDetails.InitialAmount

          ScheduleDetailsType scheduleDetails = new ScheduleDetailsType();
           scheduleDetails.Description = description;
           scheduleDetails.PaymentPeriod = paymentPeriod;
           scheduleDetails.ActivationDetails.InitialAmount = paymentAmount;
           createRPProfileRequestDetails.ScheduleDetails = scheduleDetails;

https://www.goldieui.info/code-snippets/express-checkout-recurring-payment-initial-amount/
https://stackoverflow.com/questions/27740232/null-reference-with-recurring-paypal-payment-with-initial-amount