Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 13 Next »

Usage


Retrieves a token and a URL that allows you to redirect the customer to a form to either capture new payment details (bank account or credit card) or process a real-time payment. At the end of the operation, the user will be redirected to the call back URL provided in the request message and the status of the operation will be returned as a URL parameter. 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.

Note

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

Parameters

Name

Data Type


Description

User




  • Username

String

Required

Provided by Debitsuccess

  • Password

String

Required

Provided by Debitsuccess

RequestInitiator

String

Optional

Optional – allows requesting user to be logged

AccountReferenceNo

String

Optional*

Debitsuccess Reference number

ExternalAccountReferenceNo

String 

Optional*

Your account identifier

​PayMethodType

​Enum

Required

​CreditCard - allows user to save CC details

BankAccount - allows user to save bank account details

Both - Allows the user to save either bank account or CC details

​Amount

Decimal(10,2)

​Optional**

​Amount to pay

Current validation restricts this to $2000 per transaction and only placing the account up to $500 in credit.

​RequestType

​Enum

​Required

​RealTimePayment - Allows token to be used for making a real-time payment using CC and/or save payment details

UpdatePaymentDetail - Allows token to be used for adding payment details

​CreateOneOffCharge

Boolean

​Required

​true – If a payment is successful, a one-off schedule will be created for the Amount

false – If the payment is successful, the Amount will be allocated to the account balance.

When using this call for the Gateway model real-time payments, the CreateOneOffCharge must be set to true.

​PaymentNote

​String

Optional​***

​Any notes to be recorded against the payment. Limited to 30 characters.

​CallbackURL

​String

​Required

​The URL the customer needs to be redirected to after the operation

* At least one of the following parameters must be supplied: AccountReferenceNo, ExternalAccountReferenceNo

** Required if the request type is a real-time payment

*** Required if CreateOneOffCharge is set to true

Response 

Name

Data Type

Description

Maximum Length

DateCreated

DateTime

Date/time message was processed

​

Id

String

Unique ID for the message

​

ResponseNotes ()


Collection of validation messages

​

  • Code

String


​

  • Note

String


​

  • NoteType

Enum

Error, Warning, Info

​

Status

Enum

Failed, Succeed, Unknown

​

GetPaymentToken()



​

Token

String

Auto-generated token

​8 characters

WebhookToken

String

Auto-generated webhook token

8 characters

ValidTo

Datetime

 The expiry date of the token

​

PaymentFormURL

String

URL where customer can make a payment or update payment details. It will have the token appended


Webhook URL

For each facility, you can provide a Webhook URL which, after approval, we will store in our database. 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 WebhookToken, AccountReferenceNo, ExternalAccountReferenceNo, Status and Message. 

Note

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

When a customer is redirected to the call back URL, the following response fields will be appended in the URL.

Scenario

Response Fields

​Status Description

Example

Payment declined

Token,

AccountReferenceNo,

ExternalAccountReferenceNo,

Status,

Message

​Declined

http://www.debitsuccess.com/?Status=Declined&Token=QyqqjL0G&AccountReferenceNo=TST4887235&ExternalAccountReferenceNo=BMWHSHS888300&Message= DO%20NOT%20HONOUR

Payment successful

Token,

AccountReferenceNo, ExternalAccountReferenceNo,

Status,

Message (blank)

​Success

http://www.debitsuccess.com/?Status=Success&Token=TGhZfWjb&AccountReferenceNo=TST4888608&ExternalAccountReferenceNo=BMWHSHS888300&Message=

Payment failed

Token,

AccountReferenceNo, ExternalAccountReferenceNo,

Status,

Message (blank)

​Error

http://www.debitsuccess.com/?Status=Error&Token=56vNqgkE&AccountReferenceNo=TST4888608&ExternalAccountReferenceNo=BMWHSHS888300&Message=

Account validation failed

Token,

AccountReferenceNo, ExternalAccountReferenceNo,

Status,

Message (blank)

AccountIsNotValid

http://www.debitsuccess.com/?Status=AccountIsNotValid&Token=YxLJ87En&AccountReferenceNo=TST4888608&ExternalAccountReferenceNo=BMWHSHS888300&Message=

Load of payment details successful

Token,

AccountReferenceNo, ExternalAccountReferenceNo,

Status,

Message (blank)

​Success

http://www.debitsuccess.com/?Status=Success&Token=4x2Mz9bG&AccountReferenceNo=TST4888608&ExternalAccountReferenceNo=BMWHSHS888300&Message=

Load of payment details failed

Token,

AccountReferenceNo, ExternalAccountReferenceNo,

Status,

Message (blank)

​Failure

http://www.debitsuccess.com/?Status=Failure&Token=3yFZiMrJ&AccountReferenceNo=TST4888608&ExternalAccountReferenceNo=BMWHSHS888300&Message=

Token expired

Token,

AccountReferenceNo (blank), ExternalAccountReferenceNo (blank),

Status,

Message (blank)

​TokenExpired

http://www.debitsuccess.com/?Status=TokenExired&Token=AsYMNsTf&AccountReferenceNo=&ExternalAccountReferenceNo=&Message=

Error Messages


TypeError CodeError Message
Error02Invalid user credentials
Error14034RequestType is required
Error14035PayMethodType is required
Error14036Amount is required when RequestType is RealTimePayment.
Error14038Real time payments can only be processed for Credit Cards. Please ensure PayMethodType is CreditCard when RequestType is RealTimePayment.
Error14039Missing required CallBackUrl.
Error14040CallBackUrl cannot exceed 256 characters
Error14041PaymentNote is required if CreateOneOffCharge is true.
Error14042PaymentNote cannot exceed 30 characters.
Error14043Invalid CallBackUrl - Ensure URL is correctly formatted. Example: https://www.debitsuccess.com
Error12016Missing required reference number. Must provide either ExternalAccountReferenceNo or AccountReferenceNo or both.
Error07Multiple accounts found with this criteria
Error08There is no record found with this criteria
Error10Account is not active
Error14107Cannot update the payment method as this account is an Add on Product. Please update the main account for this customer.
Error14044The Amount provided is more than the maximum amount allowed to pay for this account. Please ensure amount is between {0} and {1}
Error14045Amount cannot be more than the outstanding balance when account is set to fixed term.

Related Pages

On this page:

REST API

POST Generate PaymentToken for Account Payment




  • No labels

© 2021 Debitsuccess. All rights reserved