Can I set external payment method in a subscribe() call?

Reply
Highlighted
monique Zuora Staff

Zuora Staff

Zuora Staff
Posts: 254
Registered: ‎01-06-2016
Accepted Solution

Can I set external payment method in a subscribe() call?

Question or Problem Statement:

We need to be able to set Bank Transfer to be the Default Payment Method on a Subscribe() call. However, when I tried to do so, there is no error but the Bank Transfer type isn't set as Default Payment Method from the Web UI.



If you found my answer helpful, please give me a kudo ↑
Help others find answers faster by accepting my post as a solution √

monique Zuora Staff

Zuora Staff

Zuora Staff
Posts: 254
Registered: ‎01-06-2016

Re: Can I set external payment method in a subscribe() call?

Solution:

Currently this is not supported in Subscribe() API call.

The current design is that in a Subscribe() call that would create a new billing account, passing the field "PaymentMethod" within the complex type "SubscribeRequest" will set the Payment Method as the default payment method of the Billing Account. However, this field ONLY supports the following:

1. Creating a NEW electronic payment method during a Subscribe() call
2. Passing the field "ID" of the stand alone electronic payment method created thru the Hosted Pages

If the value of the field "ID" under the "PaymentMethod" object of the "SubscribeRequest" is an ID of the system generated external payment method, it will ignore that field -- thus creating the billing account with a NULL value on the field "Default Payment Method". The billing account will ONLY be created if and only if:

 

1. The AutoPay field is set as "False"
2. The complex type "SubscribeOptions" field "ProcessPayments" is set as "False"

Therefore, passing the ID of the system generated external payment method in the field "DefaultPaymentMethodId" of the Billing Account object is not a supported function of the Subscribe() call. Thus, the Subscribe() call created a billing account with a NULL value on the field "Default Payment Method" since the field was ignored.

 

A workaround is to execute an Update() call to specify the DefaultPaymentMethodId to use a system generated External Payment Method after the Customer Account has been created by a Subscribe() call.



If you found my answer helpful, please give me a kudo ↑
Help others find answers faster by accepting my post as a solution √

Richard Zuora Staff

Zuora Staff

Zuora Staff
Posts: 67
Registered: ‎01-19-2016

Re: Can I set external payment method in a subscribe() call?

[ Edited ]

Good news everyone! You can now set an external payment method and even record an external payment capture in a subscribe or amend call (SOAP or REST). This is useful in situations where a non-Zuora payment collection system is used (but why would you do such a thing when Zuora has Z-Payments!) But even this new featuer still won't let you set the DEFAULT payment method on account creation to be specified, so while you can record a CC reference txn using the call below, you still need to follow up the successful subscribe with an Account update to set the default payment method to be, say, CC reference. If you don't the Default Payment Method will be blank, which may or may not be important depending upon your business.

 

The SubscribeOptions clause now has a new subclause. 'ExternalPaymentOptions' where you can specify the external payment details. An example REST call using Curl from a bash shell script is below:

timestamp=$(date +%s) ; echo $timestamp
curl -X POST -H "apiAccessKeyId: $1" -H "apiSecretAccessKey: $2" -H "Content-Type: application/json" -d '{
    "subscribes": [
        {
            "Account": {
                "AccountNumber": "AN_'$timestamp'", 
                "AutoPay": false, 
                "Batch": "Batch1", 
                "BillCycleDay": 23, 
                "Currency": "USD", 
                "Name": "AC_'$timestamp'", 
                "PaymentTerm": "Due Upon Receipt", 
                "Status": "Draft"
            }, 
            "BillToContact": {
                "Address1": "312 2nd Ave W", 
                "City": "Seattle", 
                "Country": "United States", 
                "FirstName": "FN'$timestamp'", 
                "LastName": "LN'$timestamp'", 
                "PersonalEmail": "'$timestamp'@test.com", 
                "PostalCode": "98119", 
                "State": "Washington", 
                "WorkEmail": "'$timestamp'@test.com"
            }, 
            "PreviewOptions": {
                "EnablePreviewMode": false, 
                "NumberOfPeriods": 3
            }, 
            "SubscribeOptions": {
                "GenerateInvoice": true, 
                "ProcessPayments": true, 
                "ExternalPaymentOptions": {
                	"Amount": 326.40,
                	"EffectiveDate": "2017-02-23",
                	"GatewayOrderId": "GOI_'$timestamp'",
                	"PaymentMethodId": "2c92c0f94820b51601483d4f3ed50a66",
                	"ReferenceId": "GRI_'$timestamp'"
                },
                "SubscribeInvoiceProcessingOptions": {}
            }, 
            "SubscriptionData": {
                "RatePlanData": [
                    {
                        "RatePlan": {
                            "ProductRatePlanId": "2c92c0f94820b51201483ddcd5046f8f"
                        } 
                    }
                ], 
                "Subscription": {
                    "AutoRenew": true, 
                    "ContractAcceptanceDate": "2017-02-23", 
                    "ContractEffectiveDate": "2017-02-23", 
                    "InitialTerm": 12, 
                    "Name": "S_'$timestamp'", 
                    "Notes": "this is notes", 
                    "RenewalTerm": 12, 
                    "ServiceActivationDate": "2017-02-23", 
                    "TermStartDate": "2017-02-23", 
                    "TermType": "TERMED"
                }
            }
        }
    ]
}' "https://rest.apisandbox.zuora.com/v1/action/subscribe"

If you save the above to a file, set the file mode to execute (chmod u+x filename.sh). Now edit the file, you have to put in your own tenant's ProductRatePlanId and PaymentMethodId (the Id that corresponds to Check/Wire Transfer/ or whatever the external payment method you want to use is) - spoiler alert, you MUST change these two values, the values in the file are guaranteed not to work. You also have to specify the correct Amount (first field under 'ExternalPaymentOptions', again this value HAS to match the invoice amount, you can't overpay here like you can in the UI. Now, finally, you can run the file with two parameters, your Zuora sandbox login and password, e.g. './filename.sh z-login z-password'. 

 

The example above could you use a lot more polish, you'll likely want to change the ContractEffectiveDate along with the other trigger dates, the Bill To Contact, and it's hard coded to the sandbox (edit the last line and remove 'apisandbox.' to point at production). The $timestamp bash variable just lets me run the thing over and over again making it unlikely the same Account or Subscription number re-occurs. And everyone looking over your shoulder at your bash terminal session will be able to see your password!

 

To find the external payment method id's valid for your tenant, run something like, "Select Id, Name, Type From PaymentMethod where Name='Check'". 

 

In a real world scenario you should be running subscribe with preview enabled first. This will tell you what the invoice amount should be so you can go collect that and then you also know what value to put in under Amount under ExternalPaymentOptions. You should also put in real Gateway and Reference Ids.