Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
Usage
| Excerpt |
|---|
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.
| Info |
|---|
NoteWe recommend that this message should be used in conjunction with the message GetCardPaymentStatusForCustomerAccount for confirmation of payment. |
Parameters
Name | Data Type | Description | |||
|---|---|---|---|---|---|
User | |||||
| String | Required | Provided by Debitsuccess | ||
| 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.
| ||
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 | ||
AllowSavePayMethod | Boolean | Optional | A flag that determines whether saving the payment method is allowed. Use this property in conjunction with dbo.Facility.AllowSaveCreditCardDetails to determine whether to display the "Use this card as your preferred payment method for future payments" checkbox. The new property overrides AllowSaveCreditCardDetails if set. | ||
HideBranding | Boolean | Optional | A flag to control the visibility of DS branding. If HideBranding is TRUE (NULL is treated as FALSE), remove branding elements (header, footer, and contact centre phone numbers) across all PayNow pages in the session. |
* 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 | | |
| String | | |
| String | | |
| 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.
| Info |
|---|
NoteWe 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
Please refer to the following links for the Realtime Account Payment transaction Webhooks:
Payment successful: Realtime.Account.Payment.Authorized - Debitsuccess Developer Documentation - Confluence (atlassian.net)
Payment declined: Realtime.Account.Payment.Declined - Debitsuccess Developer Documentation - Confluence (atlassian.net)
Error Messages
Type | Error Code | Error Message |
|---|---|---|
Error | 02 | Invalid user credentials |
Error | 14034 | RequestType is required |
Error | 14035 | PayMethodType is required |
Error | 14036 | Amount is required when RequestType is RealTimePayment. |
Error | 14038 | Real time payments can only be processed for Credit Cards. Please ensure PayMethodType is CreditCard when RequestType is RealTimePayment. |
Error | 14039 | Missing required CallBackUrl. |
Error | 14040 | CallBackUrl cannot exceed 256 characters |
Error | 14041 | PaymentNote is required if CreateOneOffCharge is true. |
Error | 14042 | PaymentNote cannot exceed 30 characters. |
Error | 14043 | Invalid CallBackUrl - Ensure URL is correctly formatted. Example: https://www.debitsuccess.com |
Error | 12016 | Missing required reference number. Must provide either ExternalAccountReferenceNo or AccountReferenceNo or both. |
Error | 07 | Multiple accounts found with this criteria |
Error | 08 | There is no record found with this criteria |
Error | 10 | Account is not active |
Error | 14107 | Cannot update the payment method as this account is an Add on Product. Please update the main account for this customer. |
Error | 14044 | The Amount provided is more than the maximum amount allowed to pay for this account. Please ensure amount is between {0} and {1} |
Error | 14045 | Amount cannot be more than the outstanding balance when account is set to fixed term. |
Related Pages
| Filter by label (Content by label) | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
| Panel | |
|---|---|
On this page:
|
| Panel | ||
|---|---|---|
| ||