Get Payment Methods

13. Get Payment Methods

The Get Payment Methods API returns a list of payment methods with which a customer is eligible to pay. Their eligibility is based on the Curated Payment Business Rule that is applicable to the transaction.

Path NamePath Details
End Point[Velocity URL]/crs/routingservice/external/get-payment-methods
Format/Content Typetext/xml
AuthenticationHTTP basic access authentication

13.1 Request

The following is an example of a request for the Get Payment Methods API:

?xml version="1.0" encoding="UTF-8"?>
<payment_method_search_criteria>
	<event_id>5754676</event_id>
	<account_id>101118</account_id>
	<transaction>
		<type_id>1</type_id>
		<order_no>MLW761</order_no>
		<product_type>100</product_type>
		<fees>
			<fee>
				<value>2300</value>
				<type>1</type>
			</fee>
		</fees>
		<amount>
			<value>10000</value>
			<country_id>407</country_id>
			<currency_id>840</currency_id>
			<decimal>2</decimal>
		</amount>
		<orders>
			<line_item>
				<product>
					<name>RETURN</name>
					<sku>3HHQM6</sku>
					<description>return</description>
					<airline_data>
						<flight_details>
							<flight_detail>
								<tag>1</tag>
								<trip_count>1</trip_count>
								<service_level>10</service_level>
								<service_class>E</service_class>
								<departure_date>2022-12-15T05:14:00Z</departure_date>
								<arrival_date>2022-12-15T06:10:00Z</arrival_date>
								<departure_country>405</departure_country>
								<arrival_country>405</arrival_country>
								<departure_airport>
									<iata>MDE</iata>
								</departure_airport>
								<arrival_airport>
									<iata>BOG</iata>
								</arrival_airport>
								<time_zone>-5:00</time_zone>
							</flight_detail>
							<flight_detail>
								<tag>1</tag>
								<trip_count>2</trip_count>
								<service_level>10</service_level>
								<service_class>E</service_class>
								<departure_date>2022-12-15T07:10:00Z</departure_date>
								<arrival_date>2022-12-15T08:15:00Z</arrival_date>
								<departure_country>405</departure_country>
								<arrival_country>405</arrival_country>
								<departure_airport>
									<iata>BOG</iata>
								</departure_airport>
								<arrival_airport>
									<iata>AXM</iata>
								</arrival_airport>
								<time_zone>-5:00</time_zone>
							</flight_detail>
						</flight_details>
						<billing_summary>
							<fare_detail>
								<fare>
									<profile_seq>1</profile_seq>
									<description>Base Fare</description>
									<currency>COP</currency>
									<amount>35710000</amount>
									<product_code>BASE</product_code>
									<product_category>FARE</product_category>
									<product_item>Base Fare</product_item>
								</fare>								
								<fare>
									<profile_seq>1</profile_seq>
									<description>Localization Key - Sales Tax Colombia</description>
									<currency>COP</currency>
									<amount>2226000</amount>
									<product_code>YSTR</product_code>
									<product_category>TAX</product_category>
									<product_item>Sales Tax Colombia</product_item>
								</fare>
							</fare_detail>
							<add_ons>
								<add_on>
									<profile_seq>1</profile_seq>
									<trip_tag>1</trip_tag>
									<trip_seq>1</trip_seq>
									<description>Localization Key - SEAT PRICE</description>
									<currency>COP</currency>
									<amount>2999000</amount>
									<product_code>SEAT</product_code>
									<product_category>SERVICE</product_category>
									<product_item>10E</product_item>
								</add_on>								
								<add_on>
									<profile_seq>2</profile_seq>
									<trip_tag>2</trip_tag>
									<trip_seq>1</trip_seq>
									<description>Localization Key - CBAG</description>
									<currency>COP</currency>
									<amount>18000000</amount>
									<product_code>CBAG</product_code>
									<product_category>Service</product_category>
									<product_item>3RD CHECKED BAG OR MORE 23KG</product_item>
								</add_on>
							</add_ons>
						</billing_summary>
					</airline_data>
				</product>
			</line_item>
			<amount>
				<country_id>407</country_id>
				<value>273891000</value>
			</amount>
		</orders>
	</transaction>
	<client_info>
		<platform>HTML5</platform>
		<language>en</language>
		<version>2.00</version>
		<sdk-version>2.0.0</sdk-version>
		<mobile>
			<mobile>9990521077</mobile>
			<mobile_type>MobileEnriched</mobile_type>
			<country_id>407</country_id>
			<validated>true</validated>
		</mobile>
		<email>
			<email>[email protected]</email>
			<email_type>EmailEnriched</email_type>
			<validated>true</validated>
		</email>
		<device_id>2E8667F78B23402BBFF6176313BD58D314566333</device_id>
		<ip>10.36.1.15</ip>
		<client_id>10101</client_id>
	</client_info>
</payment_method_search_criteria>

13.2 Response

The following is an example of a response for the Get Payment Methods API:

<payment_method_search_response>
    <payment_methods>
        <payment_method>
            <id>8</id>
            <psp_type/>
            <preference>1</preference>
            <state_id>1</state_id>
        </payment_method>
        <payment_method>
            <id>7</id>
            <psp_type/>
            <preference>2</preference>
            <state_id>1</state_id>
        </payment_method>
       
    </payment_methods>
</payment_method_search_response>

The parameters are listed and defined in the table below.

Parameter Type Required Description
event_id Integer Yes A unique reference ID used for audit and tracking purposes.
account_id Integer Yes A storefront ID to identify web/mobile payment.
payment_group_code String No A group code provided by the merchant and used by the customer while making payments.
paymentmethod_id Integer Yes A card ID as per the mPoint system defined ID.
For example, 8 for Visa or 7 for Mastercard.
paymentmethod_id Integer Yes A card ID as per the mPoint system defined ID.
For example, 8 for Visa or 7 for Mastercard.
state_id Integer Yes The state ID indicates whether the payment method is enabled or disabled on the payment page. This is used and interpreted by the front end system.
System defined state ids in mPoint. Default is 1 i.e enabled.

CARD_ENABLED_STATE = 1;

CARD_DISABLED_BY_MERCHANT_STATE = 2;

CARD_DISABLED_BY_PSP_STATE = 3;

CARD_PREREQUISITE_NOT_MET_STATE = 4;

CARD_TEMPORARILY_UNAVAILABLE_STATE = 5;

CARD_DISABLED = 6;
card_schemes Array No This is applicable for wallet payment type only. It contains the list of card schemes allowed inside the Card Wallet, which are displayed for the customer to use for payments.
account Integer No The unique ID associated with a payment transaction. It is optional. If you omit this parameter, the payment transaction is associated with the default sub-account.
client-id Integer Yes The unique ID configured for a merchant on the Velocity POP.
Transaction Parameters
transaction Integer Yes Fee > type-1 is used as the service fee rule condition.
order-no String Yes The order ID that a merchant generates. It is an alphanumeric string.
Note: Some Payment Providers have strict guidelines for the order-no. The recommended pattern is "[a-zA-Z0-9._-].
currency-id Integer No The currency of the transaction amount. This should be the ISO 4217 numeric code.
type-id Integer No The type of transaction used for making payment. Velocity supports the following transaction types:
Value Transaction types Examples
1 Online shopping S&B Purchase
2 Offline shopping S&B Purchase
3 Self Service Online MYB Ancillary Purchase, MYB Change Itinerary Payment, OLCI Ancillary Purchase
4 Self Service Offline MYB Pay Later
5 Self Service Online MYB/Self Service Online with additional rules on FOP-- Managed Booking txn where additional rules on FOP can be configured
6 Self Service Online CPL - Payment Link Transaction. Transaction originated from payment link
session-id Integer No The ID of a session used for multiple payment transactions during one payment flow. For example, split payment or retry of a failed payment transaction.
amount Integer Yes 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 penny. 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.
fees/fee Integer No This the addition fees if applicable for the transaction like for specific scenarios like administrative fee for offline payment or pay later.

For example, the smallest currency of USD is penny. If the transaction amount is $120.30, then the amount field contains value 12030.
Note: The fee is always a non-decimal value in the request. The object amount contains the country-id and currency-id parameters.
country-id Integer Yes The CPD-specific country code, which is available in appendix.
callback-url String No 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 String No The URL where Velocity directs a customer after successfully completing a payment transaction.
Note: If you do not provide this parameter, Velocity uses the default URL. The URL is used for redirecting to either the HPP or merchant’s page after a payment completion.
cancel-url String No 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 to either the HPP or merchant’s page after a payment cancellation.
decline-url String No The absolute URL where Velocity directs customers if the payment transaction fails. The URL is used for redirecting to either the HPP or merchant’s page after a payment failure.
auth-url String No The URL which used for single sign-on authentication if provided by an external system.
service-type-id Integer No A value to indicate the type of exchange services used for a transaction. The ID indicates if the FX services such as DCC, MCP, and PCC are opted. The ID is a two-digit number XY in which:
  • X - Represents the type of FX used in a transaction.
  • Y - Represents the service usedꟷ it can be:
    • Opt-in, which has value as “1”
    • Opt-out, which has value as “2”
The following table shows the possible values of exchange service ID:
ID (XY) Service (X) Opted (Y)
11 DCC Opted
12 DCC Not Opted
21 MCP Opted
22 MCP Not Opted
31 External MCP Opted
32 External MCP Not Opted
41 PCC Opted
42 PCC Not Opted
auth-token String No A unique token sent to the specified auth-url to authenticate customers when they pay with a stored card and use single sign-on.
hmac String Yes The Message Authentication Code. It is calculated by creating a sha-512 hash comprising the following input fields in the listed order:
  • clientid
  • account
  • orderid
  • callback-url
  • amount
  • auth-url
  • customer-ref
  • auth-token
  • email
  • mobile
  • [salt]
Note: CPD provides the salt value to merchants.
MAC calculation secures the information sent by the merchant to Velocity by applying the SHA-512 encryption algorithm on key parts of the information sent to protect against tampering. The “salt” is the merchant's shared secret string used to ensure that MAC is unique.
orders Object No The order details with following details: event, location, date or time, ticket type, cost, booking fee, quantity, and total price.
Note: This parameter is used for airline data only, defined in separate guide for Airline Data.
Merchant information parameters
client-info Object Yes An object of client-info, which contains the following merchant details: language, version, platform, and profile ID.
platform String yes The platform from which the request is sent. For example, web, iOS, Android, B2B, and B2C.
sdk-version Integer yes The version of SDK used to send the request.
Note: Use 2.1.0 SDK version in the request.
version String yes The version of the API or application that send the request.
language String yes 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. Refer http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for details.
mobile Integer No The MSISDN of a customer without International Dialling Code.
Note: A mobile number can be mandatory or optional, based on the requirement of a merchant or a PSP.
country-id Integer No The CPD-specific country code, which is provided on request.
Note: Mandatory only if mobile number is provided.
email String No The email address of a customer. If your customer provides this parameter, the Email input field on the Send E-Mail Receipt page is automatically populated with this value.
Note: Email can be mandatory or optional, based on the requirement of a merchant or a PSP.
device-id String No The device ID of a customer’s device.
Note: device ID is optional for a web channel.