Callback Request to Merchant Server from Velocity

15.Callback Request to Merchant Server from Velocity

After Velocity completes processing a transaction, the customers know if their payment was processed. The callback request informs you about the payment status as an HTTP POST. This is an asynchronous message in a separate HTTP transaction initiated from Velocity. It is in addition to the original synchronous response to the payment request and the user redirect to confirmation page.

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+Review&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_decimals=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&

The following is a refund callback sample:

mpoint-id=1234556&orderid=TESTID&status=2003&desc=Payment+Refunded&exchange_rate=1&amount=12345&currency=PHP&decimals=2&sale_amount=12345&sale_currency=PHP&sale_decimals=2&fee=0&mobile=987654321&operator=64000&language=en&card-id=8&card-number=444444%2A%2A%2A%2A%2A%2A4444&pspid=4321&psp-name=FIRST+DATA&hmac=23a91b25d76903b4228631854db66af3c773413834e27943646551260acd21929& 22:00:00&first_departure_time_zone=+08:00&pos=640&ip_address=,2021-11-19 00:03:14.567,2021-11-19 00:03:14.345

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

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 the 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 and it depends on the status ID. For example, payment captured or payment rejected.
feeStringThe fee that you charge from 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 prepopulated with this value.
card-idStringThe card ID to identify the card type. For example, Mastercard or Visa.



The Message Authentication Code is calculated by creating a SHA512 hash comprising the following input fields in the listed order:


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 tifica 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.
integerIntegerThe card holder's mobile number.
billing_idcIntegerThe card holder's mobile dialling 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 following table shows the possible values of exchange service ID:

ID (XY)Service (X)Opted
11 DCCOpted
12 DCCNot opted
21 MCPOpted
22 MCPNot opted
31 External MCPOpted
32 External MCPNot opted
41 PCCOpted
42 PCCNot opted

<additional data>
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.