Search site
Hosted Payment Page
Hosted Payment Page parameters
Request parameters
Header parameters
| Parameter | Required / Optional | Description | Data Type |
|---|---|---|---|
|
Accept |
Required
|
application/json
|
String
|
|
Content-Type |
Required |
application/json;charset=UTF-8 |
String |
|
signature |
Optional |
The generated digital signature that ensures no tampering has occurred with a request sent to us. Read how to create it on the digital signature algorithm page. |
String |
Body parameters
transactionType String Required
Indicates whether the transaction is an authorization or a sale. An authorization places a hold on the cardholders funds and requires a follow-up capture transaction to be performed. The sale transaction performs the authorization and a capture at the same time. Possible Values:
- sale
- authorize
storeName String
The name of your store. This is displayed in the header of the hosted payments form.successUrl String
The URL to which the cardholder is redirected following a successful transaction. This would typically be a webpage hosted by your server.failureUrl String
The URL to which the hosted payment redirects the cardholder following a successful transaction.declinedUrl String
The URL to which the hosted payment page redirects the cardholder following the transaction being declined by Truevo or the Issuer.transactionUniqueIdentifier String
Unique identifier previously generated for a transaction. This is only required if a previous step has been performed, such as preparing a checkout. If this is the initial request made, this field can be ignored.merchantReference String Required
A reference provided by you for the transaction, commonly used for reconciliation. It is recommended that the identifier is unique to the transaction.paymentReference String Required
A reference provided as a description for the transaction.amount Object
totalAmount Number Required
The total amount requested for the transaction. If a breakdown is specified, this would represent the sum of all detailed amounts.currencyAlphaCode String Required
The currency alpha code of the transaction, specified with the three-character ISO 4217 code.details Object
paymentAmount Number
The net transaction amount prior to specifying additional amounts, such as gratuity.gratuityAmount Number
The additional amount the payer has chosen to provide as a tip or gratuity.descriptor String
May be used to populate the merchant name descriptor presented in the cardholder’s statement. Contact Truevo for details.mid String Required
The unique identifier issued to you by Truevo.tid String Required
The identity of the terminal utilised in the transaction. This will also be supplied to you by Truevo.physicalAddress Object
Merchant physical address.street1 String
Line 1 of the street address.street2 String
Line 2 of the street address.city String
The name of the city/town.state String
The name of the state/county.postCodeZip String
The postal/zip code.countryAlphaCode String
The alpha 2 code of the country, relates to country name.subMerchantId String
The unique identifier of the sub-merchant. This field is required for Payment Facilitators.firstName String
The first name of the customer.lastName String
The last/family name of the customer.birthDate String
The date of birth of the customer in this format: YYYY-MM-DDnationality String
The nationality of the customer.contact Object
Customer’s contact details.email String Required (if customer object is specified)
The email address of the customer.mobile String
The mobile number of the customer.phone String
The home phone number of the customer.workPhone String
The work phone number of the customer.url String
The website URL of the customer.ip String
The IP address of the customer.companyName String
The company name of the customer.taxRegistration String
The tax registration number of the customer.physicalAddress Object
street1 String
Line 1 of the street address.street2 String
Line 2 of the street address.city String
The name of the city/town.state String
The name of the state/county.postCodeZip String
The postal/zip code.countryAlphaCode String
The alpha 2 code of the country, relates to country name.billingAddress Object
street1 String
Line 1 of the street address.street2 String
Line 2 of the street address.city String
The name of the city/town.state String
The name of the state/county.postCodeZip String
The postal/zip code.countryAlphaCode String
The alpha 2 code of the country, relates to country name.merchantShopperReference String Required(if tokenization object is specified)
The unique reference assigned to a cardholder in order to group tokenized card details under a customer. Ideally, this should be the cardholder username within a e-commerce system.tokenRegistrationProcess String Required(if tokenization object is specified)
Used to indicate the process to be taken for storing cards. If Optional is used, the storing of card details will be done based on the decision of the cardholder at the time of inputting card details for the transaction.Enum: “Always”, “Optional”, “None”
key String (no whitespace)
value StringResponse parameters
| Parameter | Description | Data Type | |
|---|---|---|---|
|
redirect_url |
If successful. The URL of the hosted payment page that has been created to capture the customer’s card details. |
String
|
|
|
outcome |
|
|
Object |
|
status |
Either “SUCCESS” or “FAILURE” |
String |
|
|
message |
A reason or explanation of why the request failed. |
String |
|
