Gateway Billing
Overview of Gateway Billing Process
The Debitsuccess gateway billing process differs from the full service (recurring) billing process because Debitsuccess does not hold a balance to be collected for a customer account or a schedule for when to collect payments, instead the client CRM system maintains the balance and schedule and submits one-off schedules to Debitsuccess when payment becomes due.
When processing payments Debitsuccess will normally only process a schedule once and will not re-attempt it if it fails. It is possible to enable retries, in which case if a customer is paying using a credit card Debitsuccess will re-attempt a failed payment the next working day.
Gateway Billing Usecases |
|---|
Gateway Billing Standard Payment Flow
Initially, on-board customers using POST Customer, POST Account, and payment method capture widget. Capture returned account reference.
When it is time to bill customers, use POST oneOffSchedules to load payment requests (using previously captured account reference) to the Debitsuccess platform
Handle rejections of any POST oneOffSchedules requests (some could be due to a payment stop on the account because of a previous payment failure for a reason such as Lost/Stolen card, Account Closed etc).
Make regular calls to GET PaymentStatuses specifying an appropriate date range (based on the frequency of polling).
Handle returned payment status changes appropriately, e.g., mark either cleared or settled payments (depending on which status you are using) as complete, mark failed payments. Potentially you could also have payments in an unbillable state (due to, for example, a payment stop being added to the account after the schedule was loaded) or a Retry state if retries are enabled for credit card payments.
Handle any errors, such as a timeout when calling the API.
Web Service Messages
The primary API messages that would be used to manage a gateway customer account (including payments) are:
SOAP API | REST API | Function |
|---|---|---|
| Used to retrieve information about who is paying the establishment fee (customer or business) and how much it is. This may be required if you want to show the customer what they are going to be paying. | |
|
| This will return the commission settings for a facility account and will tell you whether the customer is paying a commission and how much the commission will be. Again this may be required if you want to show the customer what they are going to be paying. |
| POST Account | Create customer account information (customer name, address, email addresses, phone numbers, ExternalAccountReferenceNo. |
Used to capture payment method details after PostCustomerAccount is processed successfully. | ||
POST Schedule (One-off) | Used to load a one-off schedule for a customer account. You can specify a unique identifier for each schedule you load. | |
GET Payment History | Allows you to request all payments in a date range for a specific status (Failed, InRetry, or Settled). | |
GetCustomerPaymentByStatusForDateRange
| GET Payment Status | Similar to GetPaymentHistoryByStatusForDateRange, this message returns a list of payments with state changes within the specified date range. The main differences with this message are that it also returns the Cleared status and you can choose whether or not to filter or a specific status. |
GetCustomerPaymentByStatusForAccountId
| GET Payment Status | Returns the payment status of active one-off schedules belonging to the AccountReferenceNo or ExternalAccountReferenceNo provided in the request. |
On this page
Gateway Only SOAP APIs
The following APIs are meant to be used only for the gateway billing process:
© 2021 Debitsuccess. All rights reserved