Login As a Guest And Redirect

Description¶

The loginAsGuestRoleThirdpartyAndRedirect endpoint is used to login as a guest and redirect the user to the make a payment page.

Request¶

Endpoint

/v3/loginAsGuestRoleThirdpartyAndRedirect

Method

GET

Attributes

ELEMENT	DESCRIPTION	FORMAT	FIELD CONSTRAINTS
merchantCode	Required The unique code used for the respective merchant.	e.g., vela-atlanta	The value of merchantCode (e.g., vela-atlanta) must be the same as the value in the Base URL (e.g., https://vela-atlanta-test.payvela.com)
signature	Required The Signature will include the Merchant Code + VELA Secret Key + Current Date (yyyy-MM-dd) in GMT + Invoice Number with a semicolon(;) as a delimiter.	Test Environment: Value of VELA Secret Key is iVGZoMkXRi7tG7JB NOTE: For Merchant or Vendor Specific Secret Key or Custom Secret Key, please contact vela@datumtg.com. Production Environment: To Obtain the Production VELA Secret Key, please contact vela@datumtg.com NOTE: If the Signature fails the user will be redirected to the BASE_URL. e.g., https://whatever.abccompany.com/thirdpartyapp/resources/xyzcomp?status=KO&errorCode=-5&errorMsg=SIGNATURE_INVALID An API signature in this context is a cryptographic hash of the request data, created using a secret key held only by the authorized system. The receiving system uses the corresponding secret key to verify the signature, ensuring Authentication, Integrity, and Non-repudiation.
returnURL	Required The Return URL must be in Base64 Encoded to accommodate '+', '/' and '=' characters into special percent-encoded hexadecimal sequences. Upon successful completion, the user will be redirected to this URL with a payment response. Upon failure of the Signature, the user will be redirected to the Originated page. Upon transaction/payment failure the user will be returned to the redirected page, i.e., the Make A Payment page to completet the payment.	e.g., http://whatever.xyzcompany.com/return?invoiceId=AB-123-X-12345&subscriptionId=1248abc&cardNetworkName&cardExpiry&status=OK&signature=4d30141ab0a7416c308b62d56e52dfeaf25b7 684cedf9e11082ac6bdbf84ee98 The Return Signature will include the Merchant Code + Merchant Secret Key + Current Date in GMT (yyyy-MM-DD) + Invoice Number with a semicolon(;) as a delimiter. The value of status is 'OK' for approved transactions and 'KO' for declined/failed transactions. errorCode: If the status’ is 'KO', include the reason for the failure. e.g., 'E452' Signature = sha-256(Merchant Code + ';' + Merchant's Secret Key + ';' + invoiceNumber).
invoiceNumber	Conditional Invoice number related to the payment. Required if the Invoices Module is enabled or Invoice field is enabled.	e.g., 123456	Invoice Number should be at least m characters long and cannot exceed n characters. Minimum (m) & Maximum (n) length depends upon merchant level configuration. Cannot accept special characters except '-' and '_'
membershipNumber	Conditional membership number related to the payment Required if Loyalty is enabled at the merchant level.	e.g., 123456	Membership Number can only contain digits and should be at least one digit long and cannot exceed 11 digits.
loyaltyTierLevel	Conditional Loyalty Tier level of the user for whom the payment is being initiated. Required if Loyalty is enabled at the merchant level.	e.g., TIER1, TIER2 etc.
• productCode1	Conditional Product code for which the payment is being made. Required when the Product/Services feature is enabled at the merchant level. NOTE: For Merchant specific configurations, please contact vela@datumtg.com.	e.g., ABC001	Product Code must be at least 4 characters long. Product Code cannot exceed 20 characters.
• productQuantity1	Conditional Product Quantity of the Product for which the payment is being made. Required when the Product/Services feature is enabled at the merchant level. NOTE: For Merchant specific configurations, please contact vela@datumtg.com.	e.g., 1
• productCode2 to n	Conditional Product code for which the payment is being made. Required when the Product/Services feature is enabled along with Multi Product/Services feature at the merchant level. Up to five (5) product line items can be passed in the request using numbered parameters, each numbered set represents one product/service item. e.g., productCode2 NOTE: For Merchant specific configurations, please contact vela@datumtg.com.	e.g., ABC002 ABC003	Product Code must be at least 4 characters long. Product Code cannot exceed 20 characters.
• productQuantity2 to n	Conditional Quantity of the Product. Required when the Product/Services feature is enabled along with Multi Quantity feature at the merchant level. Up to five (5) product line items can be passed in the request using numbered parameters, each numbered set represents one product/service item. e.g., productQuantity2 NOTE: For Merchant specific configurations, please contact vela@datumtg.com.	e.g., 2 2
bookingNumber	Conditional Booking or Transaction number related to the payment. Required if the Product Type is LODGING.	e.g., 123456	It should be at least m characters long and cannot exceed n characters. Minimum (m) & Maximum (n) length depends upon merchant level configuration.. Cannot accept special characters.
checkInDate	Conditional Check-in Date for which the payment is being initiated. Required if the Product Type is LODGING. The Date Format depends on the Merchant settings.	e.g., yyyy-MM-dd 2022-05-06	Should be greater than the Current Date and less than Check-out Date.
checkOutDate	Conditional Check-Out Date for which the payment is being initiated. Required if the Product Type is LODGING. The Date Format depends on the Merchant settings.	e.g., yyyy-MM-dd 2022-05-07	Should be greater than Check-in Date.
roomNumber	Conditional Room number associated with the Guest for whom the payment is being initiated.	e.g., 101, 205, 305A etc.	Room Number can be alpha numeric and should be at least one character long and cannot exceed 5 characters.
firstName	Required First Name of the user related to the payment.	e.g., John	Accent Characters are not allowed.
lastName	Required Last Name of the user related to the payment.	e.g., Smith	Accent Characters are not allowed.
nameOnCard	Required Cardholder name related to the payment.	e.g., John Smith	Accent Characters are not allowed.
emailAddress	Conditional Email Address of the cardholder/account holder Required if the feature is required by the Merchant or Acquirer	Ex: user.test@email.com
callingCode	Optional Calling Code of the Country.	e.g., 1 (Calling code of USA)
mobileNumber	Optional Mobile Number to which the payment details have to be sent.	e.g., 6787400263	Mobile # must be at least 9 digits long. No other characters are allowed including spaces and hyphens except digits.
addressLine1	Optional Address that is related to the card used. when the selected country is NOT Brazil	e.g., 1234 ABC Road	Must be at least 5 characters long and cannot exceed 40 characters.
addressLine2	Optional Address that is related to the card used.	e.g., Suite 123	Cannot exceed 40 characters.
addressLine3	Optional Address that is related to the card used.	e.g., Near XXXX	Cannot exceed 40 characters.
streetName	Optional Address that is related to the card used. when the selected country is Brazil	e.g., Rua Augusta	Cannot exceed 40 characters.
streetNumber	Optional Address that is related to the card used. when the selected country is Brazil	e.g., 1234	Cannot exceed 10 characters.
city	Optional City.	e.g., ABC City	Must be at least 2 characters long and cannot exceed 35 characters.
state	Optional State to which the card belongs to.	e.g., GA	Two character Standard ISO State Code
zipCode	Optional Zip or Postal Code.	e.g., 12345	ZIP/Postal Code must be at least 2 characters long and cannot exceed 10 characters.
country	Optional Country.	e.g., USA	Three character Standard ISO Country Code
locale	Optional Language. en_US is the default value.	e.g., en_US Other supported locale's are fr_CA, pt_BR, es_MX, it_IT, and de_DE.
amount	Required Payment Amount	10.00 (For most currencies) or 1000 (currencies with 0 exponent ex: JPY) The maximum Amount limit is 999,999.99	Commas are allowed while entering the value.
currencyCode	Required Currency Code used for the payment	e.g., USD	Three character Standard ISO Currency Code
environment	Required The environment in which the redirection occurs	e.g., TEST, UAT, STAGING, PERF or PROD

Given all the details as above, the request Endpoint would appear as follows:

<BASE_URL>/ui/v3/loginAsGuestRoleThirdpartyAndRedirect?locale=en_US&merchantCode=VELA&environment=TEST&returnURL=http%3A%2F%2Fthirdpartyservices-test.payvela.com%2Fthirdpartyapp%2Fresources%Confirmation
&signature=af22d4138fc94142187f4d7395d9b2f421b4ca24b7d36c081d632c286c6e94ad&bookingNumber=321654987&invoiceNumber=123456789&checkInDate=2025-11-15&checkOutDate=2025-12-06&membershipNumber=33457050
&loyaltyTierLevel=TIER1&productCode1=APP-001&productQuantity1=1&subTotal1=100&specialInstructions1=Include+Feather+%26+Down&productCode2=APP-002&productQuantity2=1&subTotal2=20
&specialInstructions2=Serenity+Escape&productCode3=BEV-002&productQuantity3=1&subTotal3=30&specialInstructions3=Camel+Safari&productCode4=DIN-002&productQuantity4=1&subTotal4=40
&specialInstructions4=Sweet+Rose&productCode5=DES-002&productQuantity5=1&subTotal5=50&specialInstructions5=Elderflower+%26+Lemon&amount=240&currencyCode=DOP&paymentAction=
&firstName=John&lastName=Smith&nameOnCard=John+Smith&emailAddress=john.smith%40xyz.com&callingCode=1&mobileNumber=6780000000
&country=USA&addressLine1=12000+Findley+Rd&addressLine2=Suite+350&addressLine3=VELA+Chamber&city=Johns+Creek&state=GA
&zipCode=30097&originURL=https%3A%2F%2Fthirdpartyservices-test.payvela.com%2Fthirdpartyapp%2Fresources%2Fmemberspaces&redirect=

Response¶

"The User will be redirected to the Make a payment page of the respective merchant."

In some cases if the user is not ACTIVE or if any attribute is Invalid, the API request returns with the following error code(s) and message(s) instead of redirecting the user to the Make A Payment page.

DESCRIPTION	ERROR CODE	ERROR MESSAGE
If the user Status is not ACTIVE	-1	UNAUTHORIZED
If the user is not assoicated with a Channel containing Payment methods	-2	MISCONFIGURATION
If under the user's Billing Information State Code is not valid State Code is not valid ex: GAA instead of GA	-3	INVALID_ISO_STATE_CODE
If under the user's Billing Information Country code is not valid Country Code is not valid ex: USAD instead of USA	-4	INVALID_ISO_COUNTRY_CODE
If the Signature is invalid	-5	SIGNATURE_INVALID
If the Signature is Empty	-6	SIGNATURE_EMPTY
If the Product Code is not valid	-7	INVALID_PRODUCT_CODE
If the Loyalty Tier is invalid	-8	INVALID_LOYALTY_TIER_LEVEL
If one or more Product Codes are invalid	-9	ONE_OR_MORE_PRODUCT_CODES_ARE_INVALID
If the Amount is Empty	-10	AMOUNT_EMPTY
If the Currency Code is invalid	-11	INVALID_ISO_CURRENCY_CODE
If the Currency does not match	-12	CURRENCY_DOES_NOT_MATCH

When one of the errors occur as above, the response would include the error code and error message appended to the original URL as follows:

    For example: <THIRDPARTY_URL>?status=KO&errorCode=-4&errorMsg=INVALID_ISO_COUNTRY_CODE

---

Updated As Of Version 7.2.x