Process a real-time payment for an account

Real-time payment services are offered to businesses that would like to allow their customers to make a payment towards their account outside of the normal billing cycles. These payments are The customers can make a real-time payment for different reasons. It could be to clear an arrear in payment or make an advance payment.

Clear an arrear in payment

Using PaymentToken for account payment (REST) or GetPaymentToken (SOAP) call for real-time payments gives you a few options such as:

Receive a link to pass on to the customers to make a payment
A separate one-off charge can be created for this payment if it has been successful
Define the amount that needs to be paid
Provide a URL for the customer to be redirected to after the payment is processed (call back URL)
You can provide a Webhook URL that we will store in our database after approval for each business. We will post the transaction details to this Webhook URL once as a JSON object. The transaction details are the same as what we send back for CallbackURL - the Token, AccountReferenceNo, ExternalAccountReferenceNo, Status and Message.

The CallbackURL should not be used for payment verification as it can be altered by the user. Instead, the webhook URL should be used for payment authentication.

We recommend that you store the WebhookToken we provide in the response securely to authenticate the information received through the WebhookURL is from Debitsuccess.

The token has a lifespan of 10 minutes. This will mean that the customer needs to access the payment form URL within 10 minutes of the token being issued.
The token is for one-time usage. Once the operation has started (link is clicked), it cannot be reused.

REST API

Use the Generate PaymentToken for account payment endpoint of Customer Services API to make a payment to an account using a credit card.

POST https://<ServerURL>/CustomerServices/v1.0/accounts/{accountId}/paymentTokens

Provide the following:

amount Amount to pay.
callbackURL The URL the customer needs to be redirected to after the operation.
createOneOffCharge True – a one-off schedule will be created for the Amount. False – amount will be allocated to account balance.
paymentNote Any notes to be recorded against the payment.

SOAP API

GetPaymentToken

The GetPaymentToken call can mostly be offered to customers who need to make an initial payment towards the account setup with Debitsuccess. It requires the following information:

Account Reference No.
Amount
Call back URL
Create a one-off charge
For the Gateway model, the CreateOneOffCharge parameter has to be set to true.
Payment method type
Payment notes
Request type

We recommend that this message should be used in conjunction with the message GetCardPaymentStatusForCustomerAccount for confirmation of payment.

In the GetPaymentToken process, a PayNow link is generated (the link is in the response field a:PaymentFormURL) and that can be shared with the customer to process a payment. This will ensure that you do not have to handle the credit card information of the customer.

Sample Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:deb="Debitsuccess.WebServices.WCF" xmlns:deb1="http://schemas.datacontract.org/2004/07/Debitsuccess.WebServices.Core" xmlns:deb2="http://schemas.datacontract.org/2004/07/Debitsuccess.WebServices.Core.RequestMessages">
   <soapenv:Header/>
   <soapenv:Body>
      <deb:GetPaymentToken>
            <deb:request>    
            <deb1:User>
               <deb1:Id></deb1:Id>
               <deb1:Password>#QualIT</deb1:Password>
               <deb1:Username>QualIT</deb1:Username>
            </deb1:User>
            <deb1:AccountReferenceNo>DEA2884229</deb1:AccountReferenceNo>
            <deb2:Amount>6</deb2:Amount>
            <deb2:CallBackUrl>http://www.abc.com</deb2:CallBackUrl>
            <deb2:CreateOneOffCharge>false</deb2:CreateOneOffCharge>
            <deb2:PayMethodType>CreditCard</deb2:PayMethodType>
            <deb2:PaymentNote></deb2:PaymentNote>
            <deb2:RequestType>RealTimePayment</deb2:RequestType>
         </deb:request>
      </deb:GetPaymentToken>
   </soapenv:Body>
</soapenv:Envelope>

Sample Response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Header>
      <ActivityId CorrelationId="ebe8875e-91bb-4442-8c87-35cf30062cf7" xmlns="http://schemas.microsoft.com/2004/09/ServiceModel/Diagnostics">00000000-0000-0000-0000-000000000000</ActivityId>
   </s:Header>
   <s:Body>
      <GetPaymentTokenResponse xmlns="Debitsuccess.WebServices.WCF">
         <GetPaymentTokenResult xmlns:a="http://schemas.datacontract.org/2004/07/Debitsuccess.WebServices.Core.ResponseMessages" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <DateCreated xmlns="http://schemas.datacontract.org/2004/07/Debitsuccess.WebServices.Core">2020-09-22T08:35:44.5866836+12:00</DateCreated>
            <Id xmlns="http://schemas.datacontract.org/2004/07/Debitsuccess.WebServices.Core">3472ecbb-5845-4e87-92d8-96675e3167bd</Id>
            <ResponseNotes xmlns="http://schemas.datacontract.org/2004/07/Debitsuccess.WebServices.Core">
               <ResponseMessageNote>
                  <Code>00</Code>
                  <Note>Success</Note>
                  <NoteType>Info</NoteType>
               </ResponseMessageNote>
            </ResponseNotes>
            <Status xmlns="http://schemas.datacontract.org/2004/07/Debitsuccess.WebServices.Core">Succeed</Status>
            <a:AccountId>c48ae86c-5202-4d59-a580-a499ce3a561a</a:AccountId>
            <a:PaymentFormURL>https://OC-QA-ChaosRiders.debitsuccess.com/PayNow/T/fjDd9MhY</a:PaymentFormURL>
            <a:Token>fjDd9MhY</a:Token>
            <a:ValidTo>2020-09-22T08:45:44.977003+12:00</a:ValidTo>
            <a:WebhookToken>Tjn3yXOe</a:WebhookToken>
         </GetPaymentTokenResult>
      </GetPaymentTokenResponse>
   </s:Body>
</s:Envelope>

ProcessRealTimeCardPayment

The ProcessRealTimeCardPayment call can be used to process a real-time card payment on behalf of the customer. However, it is recommended to use GetPaymentToken to adhere to PCI Compliance.

It requires the following information:

Account Reference No.
UseStoredCardDetails
AccountHolder
CVC
CardNumber
CreditCardType
ExpiryDate
Amount
Create one-off charge
Notes

It gives you a few options such as:

Use a card already stored against the customer’s account.
Provide a new credit card number to make a payment
A separate one-off charge can be created for this payment if it has been successful
Define the amount that needs to be paid

We recommend that this message should be used in conjunction with the message GetCardPaymentStatusForCustomerAccount for confirmation of payment.

Sample Request

ExternalTransactionIdentifier should be unique for the business.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:deb="Debitsuccess.WebServices.WCF" xmlns:deb1="http://schemas.datacontract.org/2004/07/Debitsuccess.WebServices.Core">
   <soapenv:Header/>
   <soapenv:Body>
      <deb:ProcessRealTimeCardPayment>
         <deb:request>
            <deb1:User>
               <deb1:Password>#QualIT</deb1:Password>
               <deb1:Username>QualIT</deb1:Username>
            </deb1:User>
            <deb1:AccountReferenceNo>DEA2884229</deb1:AccountReferenceNo>
            <deb1:ExternalTransactionIdentifier>DEMO88888163-1</deb1:ExternalTransactionIdentifier>
            <deb1:AccountHolder>Test</deb1:AccountHolder>
            <deb1:Amount>10</deb1:Amount>
            <deb1:CVC>123</deb1:CVC>
            <deb1:CardNumber>4111111111111111</deb1:CardNumber>
            <deb1:CreateOneOffCharge>false</deb1:CreateOneOffCharge>
            <deb1:CreditCardType>Visa</deb1:CreditCardType>
            <deb1:ExpiryDate>2020-12-01</deb1:ExpiryDate>
            <deb1:Notes>test</deb1:Notes>
            <deb1:UseStoredCreditCard>false</deb1:UseStoredCreditCard>
         </deb:request>
      </deb:ProcessRealTimeCardPayment>
   </soapenv:Body>
</soapenv:Envelope>

Sample Response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Header>
      <ActivityId CorrelationId="bf791ebf-970c-4e15-b17e-82f78dfa5e82" xmlns="http://schemas.microsoft.com/2004/09/ServiceModel/Diagnostics">00000000-0000-0000-0000-000000000000</ActivityId>
   </s:Header>
   <s:Body>
      <ProcessRealTimeCardPaymentResponse xmlns="Debitsuccess.WebServices.WCF">
         <ProcessRealTimeCardPaymentResult xmlns:a="http://schemas.datacontract.org/2004/07/Debitsuccess.WebServices.Core" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <a:DateCreated>2020-09-23T07:16:27.2812805+12:00</a:DateCreated>
            <a:Id>9d399b3a-9398-4161-b273-a5d632ab88c7</a:Id>
            <a:ResponseNotes>
               <a:ResponseMessageNote>
                  <a:Code>00</a:Code>
                  <a:Note>Success</a:Note>
                  <a:NoteType>Info</a:NoteType>
               </a:ResponseMessageNote>
            </a:ResponseNotes>
            <a:Status>Succeed</a:Status>
            <a:PayerAuthenticationRequest i:nil="true"/>
            <a:PayerAuthenticationUrl i:nil="true"/>
            <a:PaymentGatewayResponse i:nil="true"/>
            <a:TransactionStatus>Authorised</a:TransactionStatus>
         </ProcessRealTimeCardPaymentResult>
      </ProcessRealTimeCardPaymentResponse>
   </s:Body>
</s:Envelope>

Make an advance payment

This service needs to be enabled for the business so that their customers can avail the service. There is a maximum limit of $2000 for the advance payment amount.

The customer will NOT be allowed to make a new real-time payment if:

There is a billing due today
The account is closed

The REST and SOAP API calls mentioned in the above sections can be used to make an advance payment.

Process a real-time payment for an account

Clear an arrear in payment

REST API

SOAP API

GetPaymentToken

Sample Request

Sample Response

ProcessRealTimeCardPayment

Sample Request

Sample Response

Make an advance payment

Related Articles