GetPaymentToken

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

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

Page:

Capture Payment Method Details
Page:

Create a customer account for an ongoing gym membership
Page:

Process a real-time payment for an account
Page:

Update customer's payment method
Page:

Using our hosted payments form (PayNow)

On this page:

REST API

POST Generate PaymentToken for Account Payment