Response Parameters

API Reference: Initialize

Suggest Edits

See the following sections for descriptions of Initialize response parameters:

For Initialize sample code, see Initialize.

`client-config` object

Parent: root

Below is reference information for the client-config element and its child elements.

`client-config`

Parent: root

The client-config element is required, and it has the following attributes:

Parameter	Format	Requirement	Description
`account`	Integer	Optional	The number for the sub-account with which the payment transaction is associated. The Account ID is an integer greater than 100000 and account number is an integer smaller than 1000. The payment transaction is associated with the default sub-account if you do not provide this parameter. CellPoint Digital recommends you provide this parameter.
`auto-capture`	Boolean	Required	When set to `true`, payment information is captured automatically.
`enable-cvv`	Boolean	Optional	If `true`, you have enabled CVV.
`id`	Integer	Required	The unique ID of a merchant in the Velocity platform.
`max-stored-cards`	Integer	Optional	The maximum allowable number of cards whose payment information a customer may store. `-1` means there is no maximum limit.
`mode`	Integer	Optional	A parameter used in the SDK to switch between production and staging environments.
`store-card`	Integer	Required	This defines the type of configuration merchants have set to store cards. Possible values: `0` - Cards are not stored `1` - INVALID `2` - Stored cards are available for specific accounts only. `3` - Use stored cards only and make them available for specific accounts only. The e-money based prepaid account is unavailable. `4` - Stored cards are available for all accounts. (Note: Velocity must be hosted by a Master Merchant.)

`name`

Parents: root: client-config

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

Parameter	Format	Requirement	Description
name	String	Optional	The name a merchant gives to a card as configured in Velocity.

`callback-url`

Parents: root: client-config

The callback-url element is required, and it has the following text content:

Parameter	Format	Requirement	Description
callback URL	String, in a URL format	Required	The absolute URL to the back office of a merchant where Velocity POP sends the payment status.

`accept-url`

Parents: root: client-config

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

Parameter	Format	Requirement	Description
accept URL	String, in a URL format	Required	The 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.

`cancel-url`

Parents: root: client-config

The cancel-url element be mandatory or optional, based on the integration type, and it has the following text content:

Parameter	Format	Requirement	Description
cancel URL	String, in a URL format	Conditional Requirement: This can be mandatory or optional, based on the integration type.	The absolute URL where Velocity directs customers if they cancel a payment transaction midway. Note: If you do not provide this parameter, Velocity uses the default URL. The URL is used for redirecting back to the HPP or the merchant’s page after a payment cancellation.

`app-url`

Parents: root: client-config

The app-url element can be mandatory or optional, based on the integration type, and it has the following text content:

Parameter	Format	Requirement	Description
app URL	String, in a URL format	Conditional Requirement: This can be mandatory or optional, based on the integration type.	The app URL.

`css-url`

Parents: root: client-config

The css-url element can be mandatory or optional, based on the integration type, and it has the following text content:

Parameter	Format	Requirement	Description
CSS URL	String, in a URL format	Conditional Requirement: This can be mandatory or optional, based on the integration type.	A CSS URL used to include a style sheet file.

`logo-url`

Parents: root: client-config

The logo-url element can be mandatory or optional, based on the integration type, and it has the following text content:

Parameter	Format	Requirement	Description
logo URL	String, in a URL format	Conditional Requirement: This can be mandatory or optional, based on the integration type.	A URL used to include a logo image.

`base-image-url`

Parents: root: client-config

The base-image-url element can be mandatory or optional, based on the integration type, and it has the following text content:

Parameter	Format	Requirement	Description
base image URL	String, in a URL format	Conditional Requirement: This can be mandatory or optional, based on the integration type.	A URL used to include a base image.

`additional-config`

Parents: root: client-config

The additional-config element is optional, and it may have multiple property children.

Each property child element has the following attribute:

Parameter	Format	Requirement	Description
`name`	String	Optional	The name of the configured property.

The property element has the following text content:

Parameter	Format	Requirement	Description
Boolean	Boolean	Conditional Requirement: Required if `name` is present.	Defines the state of the property listed in `name`.

`accounts`

Parents: root: client-config

The accounts element is optional, and it may have multiple account children.

Each account child element has the following attributes:

Parameter	Format	Requirement	Description
`id`	Integer	Optional	The account ID number.
`markup`	String	Optional	The account markup.

`transaction` object

Parent: root

Below is reference information for the transaction element and its child elements.

`transaction`

Parent: root

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

Parameter	Format	Requirement	Description
`auto-capture`	Boolean	Required	When set to `true`, payment information is captured automatically.
`eua-id`	Integer	Optional	This identifies if the API to be called is for a savings account or savings card.
`id`	Integer	Required	The unique ID configured for a merchant on the Velocity Platform.
`language`	String	Required	The language that Velocity uses as default when translating the payment pages. Velocity uses a default language set by a merchant if this parameter is omitted. Note: Velocity language codes are based upon the ISO- 639-1 standard. See http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for details.
`mode`	Integer	Optional	A parameter used in SDK to switch between production and staging environments.
`order-no`	String	Required	The order ID that a merchant generates for a customer. It is an alphanumeric string. Note: Some payment providers have strict guidelines for the order-no. The recommended pattern is `"[a-zA-Z0-9._-]`
`type-id`	Integer	Required	The type of application used for a transaction. For example, `40` indicates a mobile app purchase and `30` indicates a web purchase.

`amount`

Parents: root: transaction

The amount element in transaction is required, and it has the following attributes:

Parameter	Format	Requirement	Description
`alpha2code`	String	Optional	The two-letter country code for the transaction currency.
`alpha3code`	String	Optional	The three-letter currency code for the transaction currency.
`code`	Integer	Optional	The CellPoint Digital-specific currency code for the country whose currency is used in the transaction.
`country-id`	Integer	Optional	The CellPoint Digital-specific country code, which is provided on request.
`currency`	String	Optional	The format of the currency used for the transaction.
`currency-id`	Integer	Optional	The currency code for the transaction currency.
`format`	String	Optional	The format in which the price is presented.
`symbol`	String	Optional	A symbol used to indicate the currency of the transaction.

The amount element has the following text content:

Parameter	Format	Requirement	Description
amount	Integer	Required	The total amount a customer is charged for a payment transaction, expressed in the specified 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 text content of `amount` is `12030`.

`mobile`

Parents: root: transaction

The mobile element can be mandatory or optional, based on the requirement of a merchant or a PSP, and it has the following attributes:

Parameter	Format	Requirement	Description
`country-id`	Integer	Conditional Requirement: Required if mobile number is present.	The CellPoint Digital-specific country code, which is provided on request.
`operator-id`	Integer	Optional	The ID of a customer’s mobile network operator. CellPoint Digital recommends including this parameter in a request to ensure that Velocity interacts with the operator accurately.

The mobile element has the following text content:

Parameter	Format	Requirement	Description
mobile number	Integer	Conditional Requirement: A mobile number can be mandatory or optional, based on the requirement of a merchant or a PSP.	The MSISDN of a customer without International Dialing Code.

`callback-url`

Parents: root: transaction

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

Parameter	Format	Requirement	Description
callback URL	String, in a URL format	Optional	The 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.

`accept-url`

Parents: root: transaction

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

Parameter	Format	Requirement	Description
accept URL	String, in a URL format	Optional	The URL where 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.

`cancel-url`

Parents: root: transaction

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

Parameter	Format	Requirement	Description
cancel URL	String, in a URL format	Optional	The absolute URL where Velocity directs customers if they cancel a payment transaction midway. Note: If you do not provide this parameter, Velocity uses the default URL. The URL is used for redirecting back to the HPP or the merchant’s page after a payment cancellation.

`session` object

Parent: root

Below is reference information for the session element and its child elements.

`session`

Parent: root

The session element is required when processing multiple payment transactions during one payment flow, such as a split payment or a retry of a failed payment transaction. It has the following attributes:

Parameter	Format	Requirement	Description
`id`	Integer	Optional	The internal ID of a session used for multiple payment transactions during one payment flow. For example, a split payment or a retry of a failed payment transaction.
`total-amount`	Integer	Optional	The total amount of the transaction. Applicable to session payments.
`type`	Integer	Optional	The numeric code for the type of payment session. Possible values: • `1` - Full payment session • `2` - Split payment session

`amount`

Parents: root: session

The amount element in session is required when session is present. It describes the amount applied to the current payment session when processing multiple payment transactions during one payment flow, such as a split payment or a retry of a failed payment transaction.

The amount element has the following attributes:

Parameter	Format	Requirement	Description
`alpha2code`	String	Optional	The two-letter country code for the session amount. Applicable to split payments and other payment flows with multiple payment transactions.
`alpha3code`	String	Optional	The three-letter currency code for the session amount. Applicable to split payments and other payment flows with multiple payment transactions.
`code`	Integer	Optional	The CellPoint Digital-specific currency code for the country whose currency is used in the session amount. Applicable to split payments and other payment flows with multiple payment transactions.
`country-id`	Integer	Optional	The CellPoint Digital-specific country code, which is provided on request. Applicable to split payments and other payment flows with multiple payment transactions.
`currency`	String	Optional	The format of currency used for the payment session. Applicable to split payments and other payment flows with multiple payment transactions.
`currency-id`	Integer	Optional	The currency code of the session amount's currency. Applicable to split payments and other payment flows with multiple payment transactions.
`format`	String	Optional	The format in which the price of the session amount is presented. Applicable to split payments and other payment flows with multiple payment transactions.
`symbol`	String	Optional	A symbol indicating the currency used in the session amount. Applicable to split payments and other payment flows with multiple payment transactions.

The amount element has the following text content:

Parameter	Format	Requirement	Description
amount	Integer	Required	The amount paid in the current payment session, expressed in the specified country’s smallest currency. For example, the smallest currency of USD is the penny ($0.01). If the session amount is $120.30, then the text content of `amount` is `12030`. In the case of a split abandoned payment, this value is equal to the value of `total-amount`. A split abandoned payment happens when a customer starts a fresh transaction and leaves a current split payment. Applicable to split payments and other payment flows with multiple payment transactions.

`status`

Parents: root: session

The status element is optional when processing multiple payment transactions during one payment flow, such as a split payment or a retry of a failed payment transaction. It has the following text content:

Parameter	Format	Requirement	Description
status	Integer	Optional	The numeric code for the session's status. Find possible values in Reference. Applicable to split payments and other payment flows with multiple payment transactions.

`split-payment` object

Parent: root

The split-payment element is required for any Initialize response in a split payment flow.

Please note:

First response - In the first Initialize response for a split payment, the split_payment element has one child: configuration.
Subsequent response - In subsequent Initialize responses for a split payment, the split_payment element has two children: active_split and configuration.

See the descriptions of active_split and configuration below.

`active_split`

Parent: root: split-payment

Please note:

The active_split element is required in subsequent Initialize responses for a split payment.
The active_split element gives information on the current payment session in a split payment flow.
The active_split element has two children: current_split_sequence and transactions. See their descriptions below.

`current_split_sequence`

Parent: root: split-payment: active_split

The current_split_sequence element is required in subsequent Initialize responses for a split payment. It has the following text content:

Parameter	Format	Requirement	Description
sequence number	Integer	Conditional Requirement: Required in subsequent Initialize responses for a split payment.	Sequence number of the current session in a split payment flow. For example, if this is the second payment session in the flow, the value of `current_split_sequence` is `2`. Applicable to split payments.

`transactions`

Parent: root: split-payment: active_split

Please note:

The transactions element is required in subsequent Initialize responses for a split payment.
The transactions element shows the transactions that previously succeeded during the split payment flow.
The transactions element may contain multiple transaction children.

Each transaction child element has the following children:

Element	Requirement	Format of text content	Description of text content
`payment_type`	Conditional Requirement: Required in subsequent Initialize responses for a split payment.	Integer	The numeric code for this payment method's type of payment (like card, wallet, or APM). Possible values: `1` - Card `2` - Voucher and Credit `3` - Wallet `4` - APM `5` - Card Token `6` - Virtual `7` - Online Banking `8` - Offline Payment `9` - Mobile Money `10` - Pay Later `11` - Point of Sale `12` - UPI `13` - EMI Applicable to subsequent Initialize responses during split payments.
`id`	Conditional Requirement: Required in subsequent Initialize responses for a split payment.	Integer	The ID number for this transaction. Applicable to subsequent Initialize responses during split payments.
`sequence`	Conditional Requirement: Required in subsequent Initialize responses for a split payment.	Integer	The sequence number of this transaction in the split. For example, if this transaction is the second payment session in the flow, the value of `sequence` is `2`. Applicable to subsequent Initialize responses during split payments.

`configuration`

Parent: root: split-payment

The configuration element is required for all Initialize responses in a split payment flow.

Please note:

The configuration element contains one child: applicable_combinations.
The applicable_combinations element describes one or more possible combinations for making payment; it may contain multiple combination children.
Each combination child element has one or more payment_type children; see the description below.
Each combination child element also has the child is_one_step_authorization; see the description below.

`payment_type`

Parent: root: split-payment: configuration: applicable_combinations: combination

The payment_type object inside combination is required for all Initialize responses in a split payment flow. It describes one payment method in a possible combination for making payment.

Each payment_type object has the following children:

Element	Requirement	Format of text content	Description of text content
`id`	Conditional Requirement: Required in a split payment.	Integer	The numeric code for this payment method's type of payment (like card, wallet, or APM). Possible values: `1` - Card `2` - Voucher and Credit `3` - Wallet `4` - APM `5` - Card Token `6` - Virtual `7` - Online Banking `8` - Offline Payment `9` - Mobile Money `10` - Pay Later `11` - Point of Sale `12` - UPI `13` - EMI Applicable to split payments.
`sequence`	Conditional Requirement: Required in a split payment.	Integer	The sequence number of this payment method, or when it is used in the split payment workflow. For example, `1` indicates it will be used in the first payment session, `2` indicates the second session. Applicable to split payments.

`is_one_step_authorization`

Parent: root: split-payment: configuration: applicable_combinations: combination

The is_one_step_authorization element is required for all Initialize responses in a split payment flow. It has the following text content:

Parameter	Format	Requirement	Description
Boolean	Boolean	Conditional Requirement: Required in a split payment.	If `true`, this combination for making payment uses one-step authorization. Applicable to split payments.

`cards` object

Parent: root

The cards element is required, and it can have multiple card children.

`card`

Parents: root: cards

Each card element has the following attributes:

Parameter	Format	Requirement	Description
`cvc-length`	Integer	Required	The length of the card verification code (CVC) on a card.
`cvcmandatory`	Boolean	Required	If `true`, the CVC is mandatory for the transaction. This is used for a wallet transaction.
`dcc`	Boolean	Required	If `true`, DCC currency conversion is available.
`enabled`	Boolean	Required	If `true`, the card was enabled.
`id`	Integer	Required	The numeric code for the method of payment. Traditionally this only indicated the card type, but we've expanded this field to identify any method of payment. Find possible values in Reference.
`installment`	String	Optional	This is no longer used in a transaction.
`max-length`	Integer	Required	The maximum length of a card number.
`min-length`	Integer	Required	The minimum length of a card number.
`payment-type`	Integer	Required	The numeric code for the type of payment (like card, wallet, or APM). Find possible values in Reference.
`preferred`	Boolean	Required	If `true`, the customer has set the card as a preferred method of payment.
`presentment-currency`	Boolean	Optional	Deprecated
`processor-type`	Integer	Required	The numeric code for the type of processor used to process payment. Find possible values in Reference.
`psp-id`	Integer	Required	The numeric code denoting the PSP used for a card. Find possible values in Reference.
`state-id`	Integer	Required	The numeric code for the state of a card; for example, enabled or disabled by PSP. Find possible values in Reference.
`type-id`	Integer	Required	The numeric code for the type of application used for the transaction. For example: • `40` - mobile app purchase • `30` - web purchase • `41` - Google Pay • `96` - offline transaction

`name`

Parents: root: cards: card

The name element is required, and it has the following text content:

Parameter	Format	Requirement	Description
name	String	Required	The name of the stored card.

`prefixes`

Parents: root: cards: card

Note the following:

The prefixes element is optional, and it can have multiple prefix children.
Each prefix child element has two children: min and max.

The min element has the following text content:

Parameter	Format	Requirement	Description
minimum	Integer	Optional	The minimum prefixed number that a card can have.

The max element has the following text content:

Parameter	Format	Requirement	Description
maximum	Integer	Optional	The maximum prefixed number that a card can have.

`stored-cards` object

Parent: root

The stored-cards element is optional, and it may contain multiple card children.

`card`

Parents: root: stored-cards

Each card element has the following attributes:

Parameter	Format	Requirement	Description
`id`	Integer	Required	The unique ID number for this card in the storage system.
`preferred`	Boolean	Required	If `true`, the customer has set the card as a preferred method of payment.
`psp-id`	Integer	Required	The numeric code denoting the PSP used for a card. Find possible values in Reference.
`type-id`	Integer	Required	The type of application used for a transaction. For example, `40` indicates a mobile app purchase and `30` indicates a web purchase.
`dcc`	Boolean	Required	If `true`, DCC currency conversion is available.

`name`

Parents: root: stored-cards

The name element is required, and it has the following text content:

Parameter	Format	Requirement	Description
name	String	Required	The assigned name for this card in the storage system.

`card-number-mask`

Parents: root: stored-cards

The card-number-mask element is required, and it has the following text content:

Parameter	Format	Requirement	Description
masked number	String	Required	The masked card number.

`expiry`

Parents: root: stored-cards

The expiry element is required, and it has the following text content:

Parameter	Format	Requirement	Description
expiry date	String	Required	The card's expiration date, in `MM/YY` format.

`wallets` object

Parent: root

The wallets element is required for a wallet transaction. It may contain multiple card children.

`card`

Parents: root: wallets

The card element is required for a wallet transaction. See cards object: card for a description of card attribute parameters.

`name`

Parents: root: wallets: card

The name element is required for a wallet transaction. See cards object: name for a description of name.

`prefixes`

Parent: root: wallets: card

The prefixes element is optional, and it can have multiple prefix children. See cards object: prefixes for a description of prefixes.

`url`

Parent: root: wallets: card

The url element is optional, and it has the following attribute:

Parameter	Format	Requirement	Description
`method`	String	Optional	The request method. Applicable to wallet transactions.

The url element has the following text content:

Parameter	Format	Requirement	Description
URL	String	Optional	The URL for the request.

`head`

Parent: root: wallets: card

The head element is required for a wallet transaction, and it has the following text content:

Parameter	Format	Requirement	Description
head script	String	Required	You will use this script in your payment page. See the Google Pay and Apple Pay guides for more information. Applicable to wallet transactions.

`body`

Parent: root: wallets: card

The body element is required for a wallet transaction, and it has the following text content:

Parameter	Format	Requirement	Description
body script	String	Required	You will use this script in your payment page. See the Google Pay and Apple Pay guides for more information. Applicable to wallet transactions.

`auth-token`

Parent: root: wallets: card

The auth-token element is required for a wallet transaction, and it has the following text content:

Parameter	Format	Requirement	Description
auth token	String	Required	A unique token sent to the specified auth-url to authenticate the customer when they pay with a stored card and use single sign-on. Applicable to wallet transactions.

`APMs` object

Parent: root

The apms object may contain multiple card children. Note that the structure and description of each root: apms: card child element is identical to those of the root: cards: card object.

`card`

Parents: root: apms

The card element is required in an apms object. See cards object: card for a description of card attribute parameters.

`name`

Parents: root: apms: card

The name element is required in an apms object. See cards object: name for a description of name.

`prefixes`

Parents: root: apms: card

The prefixes element is optional, and it can have multiple prefix children. See cards object: prefixes for a description of prefixes.

`aggregators` object

Parent: root

The aggregators object can have multiple card children.

`card`

Parents: root: aggregators

The card element is required when the aggregators object is present. See cards object: card for a description of card attribute parameters.

`name`

Parents: root: aggregators: card

The name element is required when the aggregators object is present. See cards object: name for a description of name.

`prefixes`

Parents: root: aggregators: card

The prefixes element is optional, and it can have multiple prefix children.

Each prefix child element can have the following children:

Element	Requirement	Format of text content	Description of text content
`min`	Optional	Integer	The minimum prefixed number that a card can have.
`max`	Optional	Integer	The maximum prefixed number that a card can have.
`id`	Optional	Integer	Applicable to Pix transactions.

`active-payment-methods`

Parents: root: aggregators: card

The active-payment-methods element is required when the aggregators object is present. It may contain multiple payment-method children.

Each payment-method child element contains the children described in the table below:

Element	Requirement	Format of text content	Description of text content
`logoName`	Conditional Requirement: Required when `payment-method` is present.	String	An identifier for the payment method's displayed logo.
`logoURL`	Conditional Requirement: Required when `payment-method` is present.	String	A URL used to include the logo image.
`displayName`	Conditional Requirement: Required when `payment-method` is present.	String	The displayed name of the payment method.
`issuingBank`	Conditional Requirement: Required when `payment-method` is present.	Integer	A unique ID number for the bank associated with the payment method.
`displayOrder`	Conditional Requirement: Required when `payment-method` is present.	Positive Integer	The order in which this payment method should be displayed. The payment method associated with the lowest number (`1`) is displayed first.

`offline` object

Parent: root

The offline object is required when processing an offline payment. It may contain multiple card children. Note that the structure and description of each root: offline: card child element is identical to those of the root: cards: card object.

`card`

Parents: root: offline

The card element is required for an offline transaction. See cards object: card for a description of card attribute parameters.

`name`

Parents: root: offline: card

The name element is required for an offline transaction. See cards object: name for a description of name.

`prefixes`

Parents: root: offline: card

The prefixes element is optional, and it can have multiple prefix children. See cards object: prefixes for a description of prefixes.

`vouchers` object

Parent: root

The vouchers object is applicable to the use of payment vouchers, and it may contain multiple card children. Note that the structure and description of each root: vouchers: card child element is identical to those of the root: cards: card object.

`card`

Parents: root: vouchers

The card element is required in a vouchers object. See cards object: card for a description of card attribute parameters.

`name`

Parents: root: vouchers: card

The name element is required in a vouchers object. See cards object: name for a description of name.

`prefixes`

Parents: root: vouchers: card

The prefixes element is optional, and it can have multiple prefix children. See cards object: prefixes for a description of prefixes.

Updated 3 months ago

client-config object

client-config

name

callback-url

accept-url

cancel-url

app-url

css-url

logo-url

base-image-url

additional-config

accounts

transaction object

transaction

amount

mobile

callback-url

accept-url

cancel-url

session object

session

amount

status

split-payment object

active_split

current_split_sequence

transactions

configuration

payment_type

is_one_step_authorization

cards object

card

name

prefixes

stored-cards object

card

name

card-number-mask

expiry

wallets object

card

name

prefixes

url

head

body

auth-token

APMs object

card

name

prefixes

aggregators object

card

name

prefixes

active-payment-methods

offline object

card

name

prefixes

vouchers object

card

name

prefixes

`client-config` object

`client-config`

`name`

`callback-url`

`accept-url`

`cancel-url`

`app-url`

`css-url`

`logo-url`

`base-image-url`

`additional-config`

`accounts`

`transaction` object

`transaction`

`amount`

`mobile`

`callback-url`

`accept-url`

`cancel-url`

`session` object

`session`

`amount`

`status`

`split-payment` object

`active_split`

`current_split_sequence`

`transactions`

`configuration`

`payment_type`

`is_one_step_authorization`

`cards` object

`card`

`name`

`prefixes`

`stored-cards` object

`card`

`name`

`card-number-mask`

`expiry`

`wallets` object

`card`

`name`

`prefixes`

`url`

`head`

`body`

`auth-token`

`APMs` object

`card`

`name`

`prefixes`

`aggregators` object

`card`

`name`

`prefixes`

`active-payment-methods`

`offline` object

`card`

`name`

`prefixes`

`vouchers` object

`card`

`name`

`prefixes`