Payment Widget parameters

Last Updated: 31 Oct 2022

Configuration parameters

transactionType String Required

Used to indicate if the transaction is a sale or an authorisation that will be captured later.

Enum: “sale”, “authorize”

language String

Enum: “EN”

showTruevo Boolean

Whether to display the trusted Truevo logo and footer text inside the widget content.

iframeStyles Object

iframe styles


theme String

Enum: “card”, “plain”. The CSS theme for the widget content.

style String

Custom CSS stylesheet to apply to the widget content. Learn more about CSS styling capabilities here.

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 Required

Transaction amount.


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 Required

Amount details.


paymentAmount Number Required

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.

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”

descriptor String

May be used to populate the merchant name descriptor presented in the cardholder’s statement. Contact Truevo for details.

redirectUrl String

The URL a cardholder must be redirected to after completing a 3DS challenge in a browser-based flow.

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.

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-DD

contact String

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.


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.

signature String

The generated digital signature that ensures no tampering has occurred with a request sent to us. Read how to create a digital signature here.