Welcome to Zuora Product Documentation

Explore our rich library of product information

BACS payment processing with Worldline Connect

Zuora determines whether a BACS (DirectDebitUK) payment is a first payment or a recurring payment when processing through the Worldline Connect gateway.

When you process UK Direct Debit (BACS) payments through the Worldline Connect (Ingenico) gateway, Zuora automatically sets the correct payment sequence for each transaction. First payments and recurring payments follow different processing paths that Worldline requires for BACS mandates. Zuora also includes the account holder name on token creation and payment requests, as Worldline requires a valid name to authorize BACS transactions.

Payment sequence logic

Zuora determines the payment sequence based on the number of processed payments associated with the payment method:

  • If the payment method has no processed payments, Zuora treats the payment as a first payment.
  • If the payment method has one or more processed payments, Zuora treats the payment as an nth payment.

This logic applies to payments initiated through payment runs, the Payment API, and the UI. Migrated payment methods follow the same logic. Zuora does not use the ExistingMandate gateway option to determine the payment sequence.

The sequence decision is recorded in the payment transaction log as bacsDecision. The log shows the sequence indicator, transaction type, approval requirement, and the processed-payment count used to make the decision.

First payment processing

When a BACS payment is determined to be a first payment, Zuora sends the transaction to Worldline with recurringPaymentSequenceIndicator: first, transactionType: first-payment, and requiresApproval: true.

If Worldline returns a PENDING_APPROVAL status, Zuora calls the approve operation to complete the authorization. If the approve call fails, the payment result is Declined. A retry of a declined first payment is still sent as a first payment.

Recurring payment processing

When a BACS payment is determined to be recurring, Zuora sends the transaction with recurringPaymentSequenceIndicator: recurring, transactionType: nth-payment, and requiresApproval: false. No approve call is made for recurring payments.

Customer name on BACS requests

Worldline requires a valid account holder name on BACS transactions. Zuora includes personalInformation.name in both token creation requests and payment requests for BACS payment methods. The following limits apply:

  • First name: maximum 15 characters
  • Surname: maximum 70 characters

Both values are truncated to their respective limits if they exceed the maximum length. The name block is omitted when both the first name and surname are blank.

BACS tokens created before this behavior was introduced do not carry the customer name. To populate the name on an existing token, re-create the payment method.

Migrated BACS payment methods

Migrated BACS payment methods follow the same processed-payment-count logic as other BACS payment methods. Zuora treats a payment as a first payment when the method has no processed payments, and as an nth payment when it has one or more processed payments. No separate ExistingMandate check is performed.

Limitations

  • Editing a BACS payment method in a way that clones the payment method resets its processed-payment count. The cloned payment method is treated as a first payment until it has one or more processed payments.