Webhook Notifications (async)

The callback request informs the merchant back-end system of the payment transaction status. This is an asynchronous message in a separate HTTP transaction initiated from CellPoint Digital’s (CPD) Payment Orchestration Platform (POP). It is in addition to the synchronous response to the payment request for API as the channel and the user redirects to the confirmation page for the Hosted Payment Page (HPP) as the channel.

The transaction status, along with additional transaction information, is posted to the callback URL configured for the client.

Content-type: application/x-www-form-urlencoded 
HTTP: POST

Callback Request in JSON Format

The JSON Callback Request to the merchant is shown below.

{
	"client_id": 10018, - M
	"account_id": 1100, - M
	"session_id": 1234, - M
	"session_type":1 - O
	"callback_url": "//callback" - O
	"sale_amount": { - M
		"value": 1000, - M
		"currency_id": 840 - M
		"decimals": 2, - O
		"alpha3code": "PHP" - O
		"conversion_rate": 1 - O
	},
	"pending_amount": { - O
		"value": 1000, - M
		"currency_id": 840 - M
		"decimals": 2, - O
		"alpha3code": "PHP" - O
		"conversion_rate": 1 - O
	},
	"status": { - M
		"code": 2XXX or 4XXX, - M
		"sub_code": 20102, - O
		"message": "message" - M
	},
	"additional_data": [ - O
		{
			"name": "name", - M
			"text": "value" - M
		}
	],
	"transactions": [ - M
		{
		"id": 1, - M
		"route_config_id": 12 - M // If legacy routing is configure for Merchant then value will be 0
		"order_id": "order_id", - M
		"description": "description", - O
		"fee": 0, - O
		"hmac": "sdsfsfdsd", - C
		"approval_code": "approval-code", - O
		"wallet_id": "wallet-id", - O
		"txn_type_id": 1, - M
		"payment_method": "payment-method", - M
		"payment_type": "payment-type", - M
		"short_code": "short-code", - C
		"date_time": "date-time", - M
		"local_date_time": "local-date-time", - C
		"issuing_bank": "issuing-bank", - O
		"foreign_exchange_id": 1, - O
		"service_type_id":1, - O
		"pos": 640, - O
		"ip_address": "106.202.163.166", - O
		"installment":0, - O
		"accept_url": "//accept_url" - O
		"cancel_url": "//cancel_url" - O
		"amount": { - M
			"value": 1000, - M
			"currency_id": 840 - M
			"decimals": 2, - O
			"alpha3code": "PHP" - O
			"conversion_rate": 1 - O
			},
		"status": { - M
			"code": 2XXX or 1XXX, - M
			"sub_code": 20102, - O
			"message": "message", - M
			"provider_message" : "provider_message", - O
			"provider_status_code" : "code" - 			O 
			},
		"psp" : {
			"id": 18, - C
			"name": "Wirecard", - C
			"external-id": "external-id" - C
			},
		"card" : {
			"id": 7, - O
			"name":"VISA" - O
			"mask_card_number": "4444********1111", - O
			"expiry": "expiry" - O
			},
		"customer_info" : {
			"email": "email", - O
			"country_id": 123, - O
			"mobile": "9876543210", - O
			"operator": 20000, - O
			"language": "en", - M
			"device_id": "device-id" - O
			},
		"additional_data": [ - O
			{
				"name": "name", - M
				"text": "value" - M
			}
		],
		"client_data": [ - O
			{
				"name": "name", - M
				"text": "value" - M
			}
		],
		"product_info": [ - O
			{
				"name": "name", - M
				"quantity": 1, - M
				"price": 1 - M
			}
		],
		"delivery_info": [ - O
			{
				"name": "name", - M
				"text": "value" - M
			}
		],
		"shipping_info": [ - O
			{
				"name": "name", - M
				"text": "value" - M
			}
		],
		"billing_address": { - O
			"first_name": "deb", - M
			"last_name": "de", - M
			"street": "reotuhesdfdss", - O
			"city": "sdfds", - O
			"state": "Abra", - O
			"country": "Philippines", - O
			"postal_code": "12345", - O
			"alpha2code": "PH" - O
			"mobile": "9999999999" - O
			"email": "[email protected]" - O
			"billing_idc": "1" - O
			},
		"fraud": { - O
			"status_code": "Post Auth Success", - M
			"status_desc": "Post Auth Success", - M
			"post_auth_ext_id": "6255590973676885104011", - O
			"post_auth_ext_status_code": "ACCEPT" - O
			"pre_auth_ext_id":"77777777" - O
			"pre_auth_ext_status_code" : "ACCEPT" - O
			},	 
		},
		"order_data": { - O
			"ticket_no": 12345, - O
			"profiles": [ - O
				{
					"id": 1, - M
					"first_name": 
					"fName", - O
					"last_name": 
					"lName", - O
					"type": 
					"ADT", - O
					"additional_data": [ - O
						{
							"name": "name1",
							"value": "val1"
						},
						{
							"name": "name2",
							"value": "val2"
						}
					],
					"title": "Title1", - O
					"email": "[email protected]", - O
					"mobile": "8989898989", - O
					"country_id": "130", - O
					"amount": "20000", - O
					"seq": "1" - O
				}
			],
			"trips": [
				{
					"id": 1, - O
					"service_class": "G", - O 
					"departure_airport": "DVO", - O
					"arrival_airport": "MNL", - O
					"op_airline_code": "5J", - O
					"mkt_airline_code": "1", - O
					"arrival_date": "2022-05-21 01:20:00", - O
					"departure_date": "2022-05-20 23:20:00", - O 
					"additional_data": [ - O
						{
							"name": "name1",
							"value": "val1"
						},
						{
							"name": "name2",
							"value": "val2"
						}
					],	
					"mkt_flight_number": "962", - O 
					"op_flight_number": "XYZ", - O
					"tag": "1", - O
					"trip_count": "1", - O
					"service_level": "3", - O 
					"departure_country_id": "130", - O
					"arrival_country_id": "150", - O 
					"dept_time_zone": "+08:00", - O
					"arrival_time_zone": "+08:00", - O 
					"arrival_terminal": "testAT1", - O
					"dept_terminal": "testDT1", - O 
					"dept_city": "Francisco Bangoy International Airport", - O
					"arrival_city": "Ninoy Aquino International Airport", - O 
					"aircraft_type": "1" - O
				} 
			],
			"billing_summary": { - O
				"fare_details": [ - O
					{
						"id": 1, - M
						"journey_ref": "", - O
						"bill_type": 
						"Fare", - O
						"description": "Localization Key - SEAT PRICE", - O 
						"amount": "20000", - O
						"currency": "PHP", - O
						"profile_seq": "1", - O
						"trip_tag": "1", - O
						"trip_seq": "1", - O
						"product_code": "YSTR", - O 
						"product_category": "TAX", - O
						"product_item": "Sales Tax Colombia" - O
					}
				],
				"add_on": [ - O
					{ 
						"id": 4, - M
						"journey_ref": "", - O
						"bill_type": "Addon", - O
						"description": "Localization Key - SEAT PRICE", - O 
						"amount": "20000", - O
						"currency": "PHP", - O 
						"profile_seq": "2", - O 
						"trip_tag": "2", - O
						"trip_seq": "2", - O
						"product_code": "YSTR", - O
						"product_category": "TAX", - O
						"product_item": "Sales Tax Colombia" - O 
					} 
				]
			}
		}
	]
}

Examples

The following is an example of a callback request:

mpoint-id=8068110&office-id=PHPNMA&ep-number=PM10004843&invoice-no=2CQQJKMT050320180
&issuer-approval-code=007283&fraud_status_code=3014&fraud_status_desc=Pre+Auth+Revie
w&pre_auth_ext_id=5900006009536418604009&pre_auth_ext_status_code=105&post_auth_ext_
id=6163976912096333904010&post_auth_ext_status_code=ACCEPT&txn-status=A&card-holder-
name=Primary Mastercard
Card&orderid=NL4PJN&status=2001&desc=Payment+captured+by+PSP&exchange_rate=1&amount=
358700&fee=0&currency=CNY&decimals=2&sale_amount=358700&sale_currency=CNY&sale_decim
als=2&mobile=22532290&operator=13600&language=us&card-id=7&card-number=557781%2A%2A%
2A%2A%2A%2A0004&pspid=1951911&device-id=12ABC&psp-name=2c2p-alc&description=Captured
&hmac=bac9357b196c4cf17cede735ba68c75aee98dc17&email=email%40example.name&expiry=202
3-01&session-id=106800&customer-country-id=200&approval-code=360020&payment-method=C
D&payment-type=1&invoice-no=2CQQJKMT050320180&date-time=2020-04-06T08:33:28+00:00&lo
cal-date-time=2020-04-06T16:33:28+08:00&issuing-bank=sbi&billing_first_name=Abc&bill
ing_last_name=xyz&billing_street_address=Barshinger+Avenue&billing_city=New+York&bil
ling_country=640&billing_state=Agusan+del+Norte&billing_postal_code=212435&billing_e
mail=data%40test.com&billing_mobile=2147483647&billing_idc=200&service_type_id=11&se
ssion-type-id=1

The following is a refund callback sample:

mpoint-id=1234556&orderid=TESTID&status=2003&desc=Payment+Refunded&exchange_rate=1&a
mount=12345&currency=PHP&decimals=2&sale_amount=12345&sale_currency=PHP&sale_decimal
s=2&fee=0&mobile=987654321&operator=64000&language=en&card-id=8&card-number=444444%2
A%2A%2A%2A%2A%2A4444&pspid=4321&psp-name=FIRST+DATA&hmac=23a91b25d76903b4228631854db
66af3c773413834e27943646551260acd21929&email=test%40test.com&expiry=2022-05&session-
id=5432&session-type-id=1&approval-code=1234&payment-method=CD&payment-type=1&paymen
t-provider-id=62&cfx_status_code=115&pre_auth_ext_status_code=105&merchant=616080053
9&issuer-approval-code=1234&session_token=testToken&hold_fee_amount=333&hold_fee_cur
rency_code=608&hold_period=480&fraud_status_code=3117&fraud_status_desc=Post+Auth+Sc
reen+Skip+-+Business+Rules&date-time=2021-11-18T23:59:30+00:00&local-date-time=2021-
11-19T07:59:30+08:00&billing_first_name=TEST+USER+NAME&billing_last_name=TEST&billin
g_street_address=TEST+ADDRESS&billing_city=TEST&billing_country=640&billing_state=Me
tro+Manila&billing_postal_code=1421&billing_email=TEST%40TEST.com&billing_mobile=987
654321&billing_idc=63&first_departure_time=2021-11-21
22:00:00&first_departure_time_zone=+08:00&pos=640&ip_address=111.111.111.111,2021-11
-19 00:03:14.567,2021-11-19 00:03:14.345

Parameters

The callback response parameters are listed and defined in the tables below.

ParameterTypeDescription
mpoint-idIntegerVelocity’s unique ID for the payment transaction.
payment-methodStringThe type of method used for payment. For example, card, APM, or wallet.
payment-typeStringThe type of payment. For example, card, APM, or wallet.
payment-provider-idIntegerA unique identification of the payment provider.
short-codeIntegerAn SMS short code if opted for SMS notification.
orderidIntegerThe order ID the merchant provides when a transaction is initiated.
statusIntegerAn integer code indicating the status of the transaction; the values can be either 0 or 1. Refer to Transaction Status Codes for details.
amountIntegerTotal amount that the customer was charged for the payment transaction in a country’s smallest currency.

Note: If you have subscribed to FX, this field contains the converted amount.
currencyStringThe currency in which the customer was charged.

Note: If you are availing FX, this field contains the converted currency.
mobileStringMSISDN of the customer without an International Dialling Code.
operatorIntegerThe ID of a customer’s Mobile Network Operator. A typical value is “country id” multiplied by 100.
descStringThe description of the transaction status. This depends on the status ID. For example, payment captured or payment rejected.
feeStringThe fee that you charge a customer.
emailStringThe email address of a customer. If your customer provides this parameter, the Email input field on the Send E-Mail Receipt page is automatically pre-populated with this value.
card-idStringThe card ID to identify the card type. For example, Mastercard or Visa.
HMACStringThe Message Authentication Code is calculated by creating a SHA512 hash comprising the input fields in the order listed in the Message Authentication Code table.

Using the 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 used to ensure that the provided MAC is unique.
date-timeStringThe date and time when the transaction takes place
local-date-timeStringThe local time and date when the transaction takes place
approval-codeStringThe unique ID that a PSP provides for a transaction.
session-idStringThe session ID that Velocity sends as a callback request.
wallet-idStringThe ID of the wallet used.
payment-typeStringThe type of payment. For example, card, wallet, or APM.
pspidStringID of the transaction at PSP or ACQ. This varies in every transaction.
psp-nameStringThe name of the PSP or ACQ used for completing the transaction. For example, 2C2P, 2C2P-ALC, GlobalPayment, Worldpay, or ChasePayment.
office-idIntegerThe office ID received from approver.
ep-numberIntegerThe number received from PSP.
invoice-noStringThe invoice number of a transaction.
issuer-approval-codeAlpha numeric stringThe code issued by an approver.
txn-statusIntegerThe status of a transaction.
card-holder-nameStringThe name of a card holder.
orderidIntegerThe order identification number of a transaction.
errorcodeIntegerAn integer code indicating the error status of the transaction.
customer-country-idIntegerThe country ID of a mobile.
device-idStringThe device ID of the customer.
card-numberStringThe masked card number if present for a transaction.
expiryStringThe card expiry date (YYYY-MM) if present for the transaction.
languageStringDefault language encoding set during client onboarding.
descriptionStringThe transaction description as provided during payment initiation.
issuing-bankStringThe issuing bank name for payment transactions done through online banking payment option.
decimalsIntegerThe currency precision; for example, 2 for USD for the currency parameter. If you subscribe to FX, this field contains the converted currency in decimals.
sale_currencyIntegerThis is the checkout or sale currency.

If you do not subscribe to FX, the sale currency has the same value as that of the currency parameter.
sale_amountIntegerThis is the checkout or sale amount.

If you do not subscribe to FX services, the same amount will have the same value as that of the amount parameter.
exchange_rateIntegerThe conversion rate given by FX. If you do not subscribe to FX, the value of this field is 1.
fraud_status_codeIntegerThe final fraud status code. For example, 3011 or 3111.
fraud_status_descStringFinal fraud status description. For example, Accepted or Review
pre_auth_ext_status_codeIntegerThe pre-auth fraud check system response code.
pre_auth_ext_idIntegerThe pre-auth fraud check system transaction ID.
post_auth_ext_idIntegerPost-auth fraud check system transaction ID.
post_auth_ext_status_codeStringThe post-auth fraud check system response code.
billing_first_nameStringThe cardholder's billing address first name.
billing_last_nameStringThe cardholder's billing address last name.
billing_street_addressStringThe cardholder's billing address street address.
billing_cityStringThe cardholder's billing address city name.
billing_countryIntegerThe cardholder's billing address country ID.
billing_stateStringThe cardholder billing address state/region value.
billing_postal_codeIntegerThe cardholder's billing address zip code.
billing_emailStringThe card holder's email address.
billing_mobileIntegerThe card holder's mobile number.
billing_idcIntegerThe card holder's mobile dialing country code.
service_type_idIntegerA value to indicate the type of exchange services used for a transaction. The ID indicates if FX such as DCC, MCP, and PCC are opted. The ID is a two-digit number XY in which:

• X - Represents the type of exchange service used in a transaction.
• Y - Represents the exchange used--it can be opt-in or opt-out.

The Exchange Service ID table shows the possible values of exchange service ID.
StringIf the PSP sends additional data related to transaction, mPoint sends it in callback. For example, ep-number and office-id are additional information sent by 2c2p-ALC.
session-type-idIntegerThe session type ID in which:
• 1= normal payment
• 2= split payment
posIntegerPoint of sale of transaction. For example, countryid - ISO numeric.
ip_addressStringThe IP address of the transaction initiation.