Guides

Response Parameters

API Reference: Pay

Suggest Edits

See the following sections for descriptions of Pay response parameters:

For Pay sample code, see Pay.

psp-info

Parent: root

The psp-info element is required, and it has the following attributes:

ParameterFormatRequirementDescription
idIntegerRequiredInternal ID of the PSP in Velocity.

For Wallet transactions, this describes the wallet ID information.
merchant-accountStringConditional Requirement: Required for Wallet transactions.The merchant ID configured and used for this transaction. This will be needed to pass/configure as the merchant-account value for a third-party Wallet transaction.

Applicable to Wallet transactions.
typeIntegerRequiredThe payment type, for backend use. See Reference for possible values.

url

Parent: root: psp-info

The url element is required for Card, APM, and Installment transactions, and it has the following attributes:

ParameterFormatRequirementDescription
content-typeStringOptionalThe content type used for the request to the PSP.

Applicable to Card, APM, Online Banking, and Installment transactions.
methodIntegerConditional Requirement: Optional for Wallet transactions.The method used for submitting the request. This indicates whether the url value is an overlay or a redirection to a specified URL. Possible values:
  • App - Using for payment with the third-party wallet on the device.
  • GET - Using HTTP GET.
  • POST - Using HTTP POST.
type-idIntegerOptionalThe type of transaction used for making payment.

Applicable to Online Banking transactions.

The url element has the following text content:

ParameterFormatRequirementDescription
URLStringConditional Requirement: Optional for Wallet transactions.The URL of the provider, which can be used for redirection or the overlay.

card-number

Parent: root: psp-info

The card-number element is required for Card and Installment transactions, and it has the following text content:

ParameterFormatRequirementDescription
card numberIntegerConditional Requirement: Required for Card and Installment transactions.The number on the payment card.

Applicable to Card and Installment transactions.

expiry-month

Parent: root: psp-info

The expiry-month element is required for Card and Installment transactions, and it has the following text content:

ParameterFormatRequirementDescription
expiration monthInteger, 2NConditional Requirement: Required for Card and Installment transactions.The month in the payment card's expiration date.

Applicable to Card and Installment transactions.

expiry-year

Parent: root: psp-info

The expiry-year element is required for Card and Installment transactions, and it has the following text content:

ParameterFormatRequirementDescription
expiration yearIntegerConditional Requirement: Required for Card and Installment transactions.The year in the payment card's expiration date.

Applicable to Card and Installment transactions.

cvc

Parent: root: psp-info

The cvc element is required for Card and Installment transactions, and it has the following text content:

ParameterFormatRequirementDescription
CVCIntegerConditional Requirement: Required for Card and Installment transactions.The card's security code.

Applicable to Card and Installment transactions.

head

Parent: root: psp-info

The head element is required for Wallet transactions, and it has the following text content:

ParameterFormatRequirementDescription
headStringConditional Requirement: Required for Wallet transactions.The script received in the head node in the Initialize response, which we need to load on the HTML DOM.

Applicable to Wallet transactions.

body

Parent: root: psp-info

The body element is required for Wallet transactions, and it has the following text content:

ParameterFormatRequirementDescription
bodyStringConditional Requirement: Required for Wallet transactions.The script received in the body node in the Initialize response.

Applicable to Wallet transactions.

session-data

Parent: root: psp-info

The session-data element is required for web-based Apple Pay transactions, and it has the following text content:

ParameterFormatRequirementDescription
session dataStringConditional Requirement: Required for web-based Apple Pay transactions.This data must be passed as-is to Apple Pay. Upon verification of the data, Apple Pay provides access to the wallet.

Applicable to web-based Apple Pay transactions.

auth-token

Parent: root: psp-info

The auth-token element is applicable to Wallet, Online Banking, and Installment transactions, and it has the following text content:

ParameterFormatRequirementDescription
authentication tokenStringConditional Requirement: Required for Online Banking and Installment transactions. Optional for Wallet transactions.The authentication token for this payment.

Applicable to Wallet, Online Banking, and Installment transactions.

name

Parent: root: psp-info

The name element is required for Card, APM, Online Banking, and Installment transactions. It has the following text content:

ParameterFormatRequirementDescription
nameStringConditional Requirement: Required for Card, APM, Online Banking, and Installment transactions. Optional for Wallet transactions.The name associated with the method of payment used in this transaction.

clientinfo

Parent: root: psp-info

The clientinfo element is optional, and it has the following text content:

ParameterFormatRequirementDescription
client informationStringOptionalAdditional information about the client.

Applicable to Card and Installment transactions.

accept-url

Parent: root: psp-info

The accept-url element is optional, and it has the following text content:

ParameterFormatRequirementDescription
accept URLStringOptionalThe URL to which Velocity directs a customer after successfully completing a payment transaction. The URL is used for redirecting to either the HPP or merchant’s page after a payment completion.

Note: If you do not provide this parameter, Velocity uses the default URL.

Applicable to Card, Online Banking, and Installment transactions.

return-url

Parent: root: psp-info

The return-url element is optional, and it has the following text content:

ParameterFormatRequirementDescription
return URLStringOptionalThe absolute URL to the back office of a merchant where Velocity POP sends the payment status.

Note: If you do not provide this parameter, Velocity uses the default URL.

Applicable to Card and Installment transactions.

hidden-fields

The hidden-fields element is applicable to Card, APM, and Online Banking transactions. It can have several children; see their descriptions below.

merchant_account_id

Parent: root: psp-info: hidden-fields

The merchant_account_id element is required for Card and Installment transactions, and it has the following text content:

ParameterFormatRequirementDescription
merchant account IDStringConditional Requirement: Required for Card and Installment transactions.The merchant ID configured and used for this transaction.

Applicable to Card and Installment transactions.

request_id

Parent: root: psp-info: hidden-fields

The request_id element is required for Card transactions, and it has the following text content:

ParameterFormatRequirementDescription
request IDStringConditional Requirement: Required for Card transactions.The request ID.

Applicable to Card transactions.

transaction_type

Parent: root: psp-info: hidden-fields

The transaction_type element is required for Card and Installment transactions, and it has the following text content:

ParameterFormatRequirementDescription
transaction typeIntegerConditional Requirement: Required for Card and Installment transactions.A numerical code for the type of transaction. See Reference for possible values.

Applicable to Card and Installment transactions.

requested_amount

Parent: root: psp-info: hidden-fields

The requested_amount element is required for Card and Installment transactions, and it has the following text content:

ParameterFormatRequirementDescription
requested amountIntegerConditional Requirement: Required for Card and Installment transactions.The amount requested in this transaction.

Applicable to Card and Installment transactions.

requested_amount_currency

Parent: root: psp-info: hidden-fields

The requested_amount_currency element is required for Card and Installment transactions, and it has the following text content:

ParameterFormatRequirementDescription
currencyIntegerConditional Requirement: Required for Card and Installment transactions.The currency of the amount requested in this transaction

Applicable to Card and Installment transactions.

client-id

Parent: root: psp-info: hidden-fields

The client-id element is required for Card and Installment transactions, and it has the following text content:

ParameterFormatRequirementDescription
client IDIntegerConditional Requirement: Required for Card and Installment transactions.A unique ID configured for a merchant on the Velocity POP.

Applicable to Card and Installment transactions.

account-id

Parent: root: psp-info: hidden-fields

The account-id element is optional for Card and Installment transactions, and it has the following text content:

ParameterFormatRequirementDescription
account IDStringOptionalThe identification number of a merchant account.

Applicable to Card and Installment transactions.

requested_amount_country

Parent: root: psp-info: hidden-fields

The requested_amount_country element is required for Card and Installment transactions, and it has the following text content:

ParameterFormatRequirementDescription
country codeIntegerConditional Requirement: Required for Card and Installment transactions.The country code for the amount requested in this transaction. See Reference for possible values.

Applicable to Card and Installment transactions.

store-card

Parent: root: psp-info: hidden-fields

The store-card element is optional for Card, APM, and Installment transactions, and it has the following text content:

ParameterFormatRequirementDescription
store cardBooleanConditional Requirement: Required for Card, APM, and Installment transactions.If set to true, the payment method has been stored to Velocity's vault.

Applicable to Card, APM, and Installment transactions.

requested_currency_id

Parent: root: psp-info: hidden-fields

The requested_currency_id element is optional for Card and APM transactions, and it has the following text content:

ParameterFormatRequirementDescription
requested currency IDIntegerOptionalThe identification number of the currency called during a transaction.

Applicable to Card and APM transactions.

transactionId

Parent: root: psp-info: hidden-fields

The transactionId element is required for Card and Installment transactions, and it has the following text content:

ParameterFormatRequirementDescription
transaction IDIntegerConditional Requirement: Required for Card and Installment transactions.The identification number of a transaction.

Applicable to Card and Installment transactions.

payment_ip_address

Parent: root: psp-info: hidden-fields

The payment_ip_address element is required for Card transactions, and it has the following text content:

ParameterFormatRequirementDescription
payment IP addressStringConditional Requirement: Required for Card transactions.The payment IP address.

Applicable to Card transactions.

email

Parent: root: psp-info: hidden-fields

The email element is required for Card transactions, and it has the following text content:

ParameterFormatRequirementDescription
email addressStringConditional Requirement: Required for Card transactions.The client's email address.

Applicable to Card transactions.

phone

Parent: root: psp-info: hidden-fields

The phone element is required for Card transactions, and it has the following text content:

ParameterFormatRequirementDescription
phone numberIntegerConditional Requirement: Required for Card transactions.The client's phone number.

Applicable to Card transactions.

card-type-id

Parent: root: psp-info: hidden-fields

The card-type-id element is required for Card and Installment transactions, and it has the following text content:

ParameterFormatRequirementDescription
testIntegerConditional Requirement: Required for Card and Installment transactions.The numerical code for the method of payment. See Reference for possible values.

Applicable to Card and Installment transactions.

field_name... and field_value...

Parent: root: psp-info: hidden-fields

Elements describing additional fields can be returned in the hidden-fields object for Card transactions. They will appear as below:

ElementRequirementFormat of text contentDescription of text content
field_name_1OptionalStringThe name of the first field.

Applicable to Card transactions.
field_name_2OptionalStringThe name of the second field.

Applicable to Card transactions.
field_name_3OptionalStringThe name of the third field.

Applicable to Card transactions.
field_value_3OptionalStringThe pre-entered value of the third field.

Applicable to Card transactions.
field_name_4OptionalStringThe name of the fourth field.

Applicable to Card transactions.
field_value_4OptionalStringThe pre-entered value of the fourth field.

Applicable to Card transactions.

card_type

Parent: root: psp-info: hidden-fields

The card_type element is required for Card transactions, and it has the following text content:

ParameterFormatRequirementDescription
card typeStringConditional Requirement: Required for Card transactions.The name of the payment method.

Applicable to Card transactions.

notification_url_1

Parent: root: psp-info: hidden-fields

The notification_url_1 element is optional, and it has the following text content:

ParameterFormatRequirementDescription
notification URLIntegerOptionalThe absolute URL to the back office of a merchant where Velocity POP sends the payment status.

Note: If you do not provide this parameter, Velocity uses the default URL.

Applicable to Card transactions.

merchant

Parent: root: psp-info: hidden-fields

The merchant element is optional for APM transactions, and it has the following text content:

ParameterFormatRequirementDescription
merchant dataStringOptionalAn identifier for the merchant.

Applicable to APM transactions.

order.id

Parent: root: psp-info: hidden-fields

The order.id element is optional for APM transactions, and it has the following text content:

ParameterFormatRequirementDescription
order IDStringOptionalThe order ID that a merchant generates.

Note: Some payment providers have strict guidelines for order-no. The recommended pattern is "[a-zA-Z0-9._-].

Applicable to APM transactions.

order.amount

Parent: root: psp-info: hidden-fields

The order.amount element is required for APM transactions, and it has the following text content:

ParameterFormatRequirementDescription
order amountIntegerConditional Requirement: Required for APM transactions.The total amount that a customer is charged for a payment transaction in a country’s smallest currency. For example, the smallest currency of USD is the penny ($0.01). If the transaction amount is $120.30, then the amount field contains value 12030.

Note: The amount is always a non-decimal value in the request. The object amount contains the country-id and currency-id parameters.

Applicable to APM transactions.

order.currency

Parent: root: psp-info: hidden-fields

The order.currency element is optional for APM transactions, and it has the following text content:

ParameterFormatRequirementDescription
order currencyStringOptionalThe currency of the order amount.

Applicable to APM transactions.

session.id

Parent: root: psp-info: hidden-fields

The session.id element is optional for APM transactions, and it has the following text content:

ParameterFormatRequirementDescription
session IDStringOptionalThe ID of a session used for multiple payment transactions during one payment flow. For example, this is used in a split payment or a retry of a failed payment transaction.

Note: A split abandoned payment occurs when a customer starts a new transaction and abandons a current split payment. In this case, the session.id value is sent back in the Initialize request with the full amount.

Applicable to APM transactions.

transaction.id

Parent: root: psp-info: hidden-fields

The transaction.id element is required for APM transactions, and it has the following text content:

ParameterFormatRequirementDescription
transaction IDIntegerConditional Requirement: Required for APM transactions.A unique transaction identification number of a transaction.

Applicable to APM transactions.

sourceOfFunds.type

Parent: root: psp-info: hidden-fields

The sourceOfFunds.type element is optional for APM transactions, and it has the following text content:

ParameterFormatRequirementDescription
payment method typeStringOptionalThe type of payment method that serves as the source of funds for this transaction.

Applicable to APM transactions.

mpoint-id

Parent: root: psp-info: hidden-fields

The mpoint-id element is optional for APM transactions, and it has the following text content:

ParameterFormatRequirementDescription
mpoint IDIntegerOptionalIn this transaction's Initialize response, this is the value of the transaction element's id attribute.

Applicable to APM transactions.

enc

Parent: root: psp-info: hidden-fields

The enc element is required for Online Banking transactions, and it has the following text content:

ParameterFormatRequirementDescription
encStringConditional Requirement: Required for Online Banking transactions.

Applicable to Online Banking transactions.

isAccountOnFileSelectionShown

Parent: root: psp-info: hidden-fields

The isAccountOnFileSelectionShown element is required for Installment transactions, and it has the following text content:

ParameterFormatRequirementDescription
BooleanBooleanConditional Requirement: Required for Installment transactions.If true, the selected account on file is shown on the payment confirmation page.

Applicable to Installment transactions.

variantCode

Parent: root: psp-info: hidden-fields

The variantCode element is required for Installment transactions, and it has the following text content:

ParameterFormatRequirementDescription
variant codeIntegerConditional Requirement: Required for Installment transactions.The variant code.

Applicable to Installment transactions.

isPaymentProductDetailsShown

Parent: root: psp-info: hidden-fields

The isPaymentProductDetailsShown element is required for Installment transactions, and it has the following text content:

ParameterFormatRequirementDescription
BooleanBooleanConditional Requirement: Required for Installment transactions.If true, details of the payment product are shown on the payment confirmation page.

Applicable to Installment transactions.

thirdPartyData

Parent: root: psp-info: hidden-fields

The thirdPartyData element is required for Installment transactions, and it contains the child installment.

Each installment child element has the following text content:

ParameterFormatRequirementDescription
installment numberIntegerConditional Requirement: Required for Installment transactions.The numerical position of this payment in a series of installment payments. For example, 5 indicates that this is the fifth payment.

Applicable to Installment transactions.

card-brands

Parent: root: psp-info: hidden-fields

The card-brands element is optional for an Apple Pay wallet transaction using a mobile channel, and it has the following text content:

ParameterFormatRequirementDescription
list of cardsString, formatted as a comma-separated listOptionalThis is the list of cards the merchant must send to the Apple Pay wallet. Only these cards will be visible or available to select. For example, 'MASTERCARD', 'VISA', 'DISCOVER', 'AMEX'.

Applicable to Apple Pay wallet transactions using a mobile channel.

message

Parent: root: psp-info

The message element is required, and it has the following attributes:

ParameterFormatRequirementDescription
languageStringRequiredThe language that Velocity uses as default when translating the payment pages.

Note: Velocity language codes are based upon the ISO- 639-1 standard.

Refer to https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for details.

status

Parent: root

The status element is required, and it has the following attributes:

ParameterFormatRequirementDescription
codeIntegerRequiredThe status code of the Pay API call. This depends on the payment provider. It can be 1009, 1041, or an error code.

The status element has the following text content:

ParameterFormatRequirementDescription
code descriptionStringRequiredA description of the status code.

Updated 11 days ago