Worldpay for Platforms eDDR (electronic Direct Debit Request)

Introduction

This developer guide for implementing the Worldpay for Platforms eDDR (electronic Direct Debit Request) will allow you to integrate our payments platform to start accepting Bank Account and Card direct debit payments processed through the banking system, such as BECS/ACH.

Worldpay for platforms eDDR flowchart

The flowcharts below demonstrates the typical API flow of 2 possible integrated flows separated via their distinct flow, 3D-Secure or no 3D-Secure.

• Worldpay for Platforms eDDR (3DS not applicable).pdf

• Worldpay for Platforms HPP (3DS applicable).pdf

3D-Secure will require a few extra fields within the API body as noted in the flowchart

API steps for eDDR

The process for using the eDDR token is simply:

1. Call the POST Generate eDDR Token to obtain a token and a redirect URL.

   1. Specify CardAuthorizationType:

      1. RECURRING

      2. INSTALMENT

      3. UNSCHEDULED

   2. Minimum payer details:

      1. First name

      2. Last name

      3. Email address

2. Redirect your customer to the URL you received with the token.

3. After the end user has completed the form we will redirect them back to your website using the returnURL you provided when generating the token.

   1. If 3ds is applicable:

      1. If the end user enters card details as the desired payment method, this will trigger the mandatory 3DS validation and the end user will be redirected to complete the 3DS challenge. Once the 3DS challenge is complete, the end user will be redirected back to the returnURL you specified in the original request.

      2. The redirection back to the returnURL is the notification trigger for your software to identify that the eDDR page has been completed.

4. Call the Token Lookup API endpoint to obtain the result of the token.

5. Schedule single or multiple payments:

   1. POST Schedule a single payment

   2. POST Schedule multiple future payments

6. Determine result of scheduled debit - GET Search for transaction status change

7. Remove transaction from data set - POST Acknowledge transaction status change

Please note the token is valid for 20 minutes. You may wish to use a landing page to trigger this if the page will not be completed as part of the flow.

Most software services already contain the information regarding the Payer and when they are to be debited. In this case, it is much simpler for the software to manage the schedule and send a request on the morning they are due to be debited via the POST Schedule a single payment.

Processing times and best approach to Poll transaction results

The table below consists of the the processing cut off times. We recommend all direct debits are requested 30 minutes before the cut off to make sure they get collected in the processing run. Any scheduled debits that miss the processing cut off will be collected in the next run, even if that means it is the next business day

Business days can be considered Weekdays of Monday, Tuesday, Wednesday, Thursday, Friday, however if it is a public holiday, the processing of the direct debit will be the next business day.

In order to poll the result of a direct debit that has been processed, the approach to take is below:

1. Call our GET Search for transaction status changes from 10AM (GMT+10) as a general timeframe daily which will pull a set of all transactions for your business that have had a change of transaction status.

   1. This endpoint is rate limited to once per hour, however when you acknowledge the transactions returned in the data set, the rate limit resets.

2. Following the above API, use our POST Acknowledge transaction status change to acknowledge the transactions and remove them from the data set when you next call the Get New Status Search above.

3. If the transaction status changes again after you have removed it from the data set, it will be returned in the GET Search for transaction status changes to notify you of the change in status.

Transaction status flow for direct debits:

1. Once a direct debit has been processed, the status will sit at P (Pending) or C (Cleared)

   1. This indicates the direct debit has been processed and awaiting bank processing which is a 2 business day timeframe

2. The final result will typically be either S (Settled) successful or R (Rejected) unsuccessful

Bank Account details for testing

Test Bank Account Details

Test Bank Account Details - NZ specific

Test Card details

Within the Sandbox environment, you can test card transactions using the card examples below:

• CVC = Any 3 digit number

• Expiry Date = Any future date

What to do if a scheduled debit has failed?

If the result of the transaction has returned and been identified as failed / rejected, pending on your application’s workflow, you can simply schedule another debit to capture payment and then identify the result of the following debit in the same flow, GET Search for transaction status then POST Acknowledge transaction status change.

Alternatively, you can utilise one of our features to manage collection on failed payments. Refer to our guide here and reach out to your Partner / Account manager to discuss.

How to cancel a scheduled debit from processing?

In order to cancel a scheduled debit from processing, it must be cancelled before our platform has picked it up for processing. If the scheduled debit has already been processed, you can no longer cancel or stop the debit from processing. Utilise any of the 'Find Schedule Details ' API in conjunction with the DELETE Delete Single Payment to confirm the scheduled debit was cancelled successfully.

Example

1. Call GET Look up a scheduled payment or GET Find a Payers scheduled payments or GET Search all scheduled payments to identify the 'scheduledpaymentid'.

   • If the 'scheduledpaymentid' that you are planning to cancel is returned in this API call, the debit has not yet been picked up for processing and you are still able to cancel the scheduled debit.

   • If the 'scheduledpaymentid' is not returned, the debit has been processed and can no longer be cancelled.

2. Cancel the scheduled debit by calling Delete Single Payment

   • This will return a 200 response

3. Confirm the cancellation by calling either of the 3 GET API calls.

   • If the 'scheduledpaymentid' is not returned, the scheduled debit has been deleted.

Self-service function to manually instantly trigger debit or settlement process

Refer to our self-service function here to instantly trigger the debit or settlement process. This will allow you to test the processes without waiting for the automated process in the sandbox environment.