Payrix Hosted eDDR (electronic Direct Debit Request)

eDDR (electronic Direct Debit Request)

The Payrix platform offers the ability to utilise the Payrix Hosted eDDR (electronic Direct Debit Request) page which is implemented via a re-direction to the Payrix Hosted eDDR page. This offering is the simplest way to integrate a payment solution to your software with minimal development work required.

Functionality of an eDDR:

Purpose of eDDR is to collect payment method to submit a following scheduled payment via API to debit the payers account
Has the ability to collect either card or bank account as payment method
Payment is NOT submitted in real-time
Submit schedule via API (date and amount specified in API body request)

The process for using the Payrix eDDR token is simply:

Call the POST Generate eDDR Token to obtain a token and a redirect URL.
Redirect your customer to the URL you received with the token.
After your customer has completed the form we will redirect them back to your website using the returnURL you provided when generating the token.
Call the Token Lookup API endpoint to obtain the result of the token.

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.

The typical API workflow is noted below:

Payrix Hosted eDDR
Schedule single or multiple payments - Implement Scheduling API to debit payer
Determine result of scheduled debit - GET Search for transaction status change
Remove transaction from data set - POST Acknowledge transaction status change

Step 1 - Sample API flow for successful eDDR page completion

API

POST Generate eDDR Token

Minimum eDDR property requirements:
- ‘ReturnUrl’
- ‘Template’
- ‘Payer’
  - Minimum fields in Payer Property:
    - ‘UniqueReference’
    - ‘FamilyorBusinessName’
    - ‘GivenName’
    - ‘Email’

Refer to Token [eDDR] Generate Model and Token [eDDR] Payer Model for more information around the API properties.

Sample

Example Request

JSON

{{url}}/businesses/{{business-id}}/services/tokens/eddr/

JSON

    "ReturnUrl": "https://www.payrix.com.au?ddr=123456789",
    "Template": "Basic-eDDR",
    "Payer": {
      "UniqueReference": "EDDR-TOKEN-PAYER-U-1",
      "GroupReference": "EDDR-TOKEN-PAYER-GRP-1",
      "FamilyOrBusinessName": "Surname",
      "GivenName": "FirstName",
      "Email": "payer.eddr.1@payrix.com.au",
      "Phone": "0733332222",
      "Mobile": "0411228833",
      "Address": {
        "Line1": "1 Test St",
        "Line2": null,
        "Suburb": "Testville",
        "State": "QLD",
        "PostCode": "4001",
        "Country": null
      },
      "OverrideExisting": false
    },
    "Schedule": null,
    "Audit": {
      "Username": "EddrTokenTests",
      "UserIP": "444.888.000"
    }
  }'

Example Response

JSON

{
  "token": "28e24e60-0fb8-44e2-918e-e38e038e52f3",
  "redirectToUrl": "https://sandbox.paymentsapi.io/ui/eddr/api/28e43e60-0fb8-78e2-912e-e38e038e52f3"
}

Next Steps once page is completed and submitted

API

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

Trigger this API call when the paying customer has been re-directed to the returnURL, allowing up to 5 - 10 seconds to retrieve response and update your application with the results.
As this example is part of a successful payment flow, take note of the below:
- Token Status property = ‘PROCESSED_SUCCESSFUL’
- Token Event Status = ‘WAITING’, ‘VALIDATED’, ‘PROCESSED_SUCCESSFUL’

Sample

Example Request

JSON

{{url}}/businesses/{{business-id}}/services/tokens/{{token-guid}}

Example Response

JSON

{
    "token": "3b796adf-a044-473e-b96f-3151eafd863d",
    "type": "EDDR",
    "time": "2024-03-26T03:10:00+00:00",
    "status": "PROCESSED_SUCCESSFUL",
    "statusDescription": "PROCESSED_SUCCESSFUL",
    "returnUrl": "https://www.payrix.com.au?ddr=123456789",
    "redirectToUrl": "https://sandbox.hosted.paymentsapi.io/ui/eddr/api/3b796adf-a044-473e-b96f-3151eafd863d",
    "template": "794c6bc8-e7c7-427c-bab6-a15d053ca532",
    "templateName": "Basic-eDDR",
    "transaction": null,
    "payer": {
        "business": {
            "businessId": "90129",
            "businessName": "Payrix Sandbox"
        },
        "payerId": "528830",
        "status": "ACTIVE",
        "statusCode": "A",
        "statusDescription": "Active",
        "statusChangeDate": null,
        "createdTime": "2024-03-26T03:10:20.203+00:00",
        "schedule": null,
        "uniqueReference": "EDDR-TOKEN-PAYER-U-1",
        "GroupReference": "EDDR-TOKEN-PAYER-GRP-1",
        "FamilyOrBusinessName": "Surname",
        "GivenName": "FirstName",
        "Email": "payer.eddr.1@payrix.com.au",
        "phone": "0733332222",
        "mobile": "0411228833",
        "address": {
            "line1": "1 Test St",
            "line2": "",
            "suburb": "Testville",
            "state": "QLD",
            "postCode": "4001",
            "country": "null"
        },
        "dateOfBirth": null,
        "extraInfo": {
            "xeroAutoDebitEnabled": false
        }
    },
    "schedule": null,
    "requestEddr": {
        "returnUrl": "https://www.payrix.com.au?ddr=123456789",
        "template": "Basic-eDDR",
        "payer": {
            "uniqueReference": "EDDR-TOKEN-PAYER-U-1",
            "familyOrBusinessName": "Surname",
            "overrideExisting": false,
            "retainSchedule": false,
            "GroupReference": "EDDR-TOKEN-PAYER-GRP-1",
            "givenName": "FirstName",
            "email": "payer.eddr.1@payrix.com.au",
            "phone": "0733332222",
            "mobile": "0411228833",
            "address": {
                "line1": "1 Test St",
                "line2": "null",
                "suburb": "Testville",
                "state": "QLD",
                "postCode": "4001",
                "country": null
            },
            "dateOfBirth": null,
            "extraInfo": {
                "xeroAutoDebitEnabled": true
            }
        },
        "schedule": null,
        "audit": {
            "username": "EddrTokenTests",
            "userIP": "444.888.000"
        }
    },
    "events": [
        {
            "event": "WAITING",
            "time": "2024-03-26T03:10:00+00:00",
            "description": null,
            "username": "API:  [EddrTokenTests]",
            "ip": "180.189.153.162 [444.888.000]"
        },
        {
            "event": "VALIDATED",
            "time": "2024-03-26T03:10:00+00:00",
            "description": null,
            "username": null,
            "ip": ""
        },
        {
            "event": "PROCESSED_SUCCESSFUL",
            "time": "2024-03-26T03:10:00+00:00",
            "description": null,
            "username": null,
            "ip": "180.189.153.162"
        }
    ]
}

Step 2 - Initiate a scheduled debit

Refer to Implement Scheduling API to debit payer

This concludes the API workflow of implementing the Payrix eDDR page. Refer to the next steps in implementation or our other methods available for accepting payments.