Callback Request to Merchant Server from Velocity
17. 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¤cy=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&email=email%40example.name&expiry=2023-01&session-id=106800&customer-country-id=200&approval-code=360020&payment-method=CD&payment-type=1&invoice-no=2CQQJKMT050320180&date-time=2020-04-06T08:33:28+00:00&local-date-time=2020-04-06T16:33:28+08:00&issuing-bank=sbi&billing_first_name=Abc&billing_last_name=xyz&billing_street_address=Barshinger+Avenue&billing_city=New+York&billing_country=640&billing_state=Agusan+del+Norte&billing_postal_code=212435&billing_email=data%40test.com&billing_mobile=2147483647&billing_idc=200&service_type_id=11&session-type-id=1
The following is a refund callback sample:
mpoint-id=1234556&orderid=TESTID&status=2003&desc=Payment+Refunded&exchange_rate=1&amount=12345¤cy=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&email=test%40test.com&expiry=2022-05&session-id=5432&session-type-id=1&approval-code=1234&payment-method=CD&payment-type=1&payment-provider-id=62&cfx_status_code=115&pre_auth_ext_status_code=105&merchant=6160800539&issuer-approval-code=1234&session_token=testToken&hold_fee_amount=333&hold_fee_currency_code=608&hold_period=480&fraud_status_code=3117&fraud_status_desc=Post+Auth+Screen+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&billing_street_address=TEST+ADDRESS&billing_city=TEST&billing_country=640&billing_state=Metro+Manila&billing_postal_code=1421&billing_email=TEST%40TEST.com&billing_mobile=987654321&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
The callback response parameters are listed and defined in the table below.
| Parameter | Type | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| mpoint-id | Integer | Velocity’s unique ID for the payment transaction. | |||||||||||||||||||||||||||
| payment-method | String | The type of method used for payment. For example, card, APM, or wallet. | |||||||||||||||||||||||||||
| payment-type | String | The type of payment. For example, card, APM, or wallet. | |||||||||||||||||||||||||||
| payment-provider-id | integer | A unique identification of the payment provider. | |||||||||||||||||||||||||||
| short-code | integer | An SMS short code if opted for SMS notification. | |||||||||||||||||||||||||||
| orderid | integer | The order ID the merchant provides when a transaction is initiated. | |||||||||||||||||||||||||||
| status | Integer | An integer code indicating the status of the transaction; the values can be either 0 or 1. Refer to the Transaction Status Codes for details. | |||||||||||||||||||||||||||
| amount | Integer | Total 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. | |||||||||||||||||||||||||||
| currency | String | The currency in which the customer was charged. Note: If you are availing FX, this field contains the converted currency. | |||||||||||||||||||||||||||
| mobile | String | MSISDN of the customer without an International Dialling Code. | |||||||||||||||||||||||||||
| operator | integer | The ID of a customer’s Mobile Network Operator. A typical value is “country id” multiplied by 100. | |||||||||||||||||||||||||||
| desc | String | The description of the transaction status and it depends on the status ID. For example, payment captured or payment rejected. | |||||||||||||||||||||||||||
| fee | String | The fee that you charge from a customer. | |||||||||||||||||||||||||||
| String | 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 prepopulated with this value. | ||||||||||||||||||||||||||||
| card-id | String | The card ID to identify the card type. For example, Mastercard or Visa. | |||||||||||||||||||||||||||
HMAC | String | 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 [salt] is the merchant's shared secret used to ensure that the provided MAC is unique. | |||||||||||||||||||||||||||
| date-time | String | The date and time when the transaction takes place | |||||||||||||||||||||||||||
| local-date-time | String | The local time and date when the transaction takes place | |||||||||||||||||||||||||||
| approval-code | String | The unique ID that a PSP provides for a transaction. | |||||||||||||||||||||||||||
| session-id | String | The session ID that Velocity sends as a callback request. | |||||||||||||||||||||||||||
| wallet-id | String | The ID of the wallet used. | |||||||||||||||||||||||||||
| payment-type | String | The type of payment. For example, card, wallet, or APM. | |||||||||||||||||||||||||||
| pspid | String | ID of the transaction at PSP or ACQ. This varies in every transaction. | |||||||||||||||||||||||||||
| psp-name | String | The name of the PSP or ACQ used for completing the transaction. For example, 2C2P, 2C2P-ALC, GlobalPayment, Worldpay, or ChasePayment. | |||||||||||||||||||||||||||
| office-id | integer | The office ID received from approver. | |||||||||||||||||||||||||||
| ep-number | integer | The number received from PSP. | |||||||||||||||||||||||||||
| invoice-no | String | The invoice number of a transaction. | |||||||||||||||||||||||||||
| issuer-approval-code | Alpha numeric string | The code issued by an approver. | |||||||||||||||||||||||||||
| txn-status | Integer | The status of a transaction. | |||||||||||||||||||||||||||
| card-holder-name | String | The name of a card holder. | |||||||||||||||||||||||||||
| orderid | Integer | The order identification number of a transaction. | |||||||||||||||||||||||||||
| errorcode | Integer | An integer code indicating the error status of the transaction. | |||||||||||||||||||||||||||
| customer-country-id | Integer | The country ID of a mobile. | |||||||||||||||||||||||||||
| device-id | String | The device ID of the customer. | |||||||||||||||||||||||||||
| card-number | String | The masked card number if present for a transaction. | |||||||||||||||||||||||||||
| expiry | String | The card expiry date (YYYY-MM) if present for the transaction. | |||||||||||||||||||||||||||
| language | String | Default language encoding set during client onboarding. | |||||||||||||||||||||||||||
| description | String | The transaction description as provided during payment initiation. | |||||||||||||||||||||||||||
| issuing-bank | String | The issuing bank name for payment transactions done through online banking payment option. | |||||||||||||||||||||||||||
| decimals | Integer | The 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_currency | Integer | This 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_amount | Integer | This 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_rate | Integer | The conversion rate given by FX. If you do not subscribe to FX, the value of this field is 1. | |||||||||||||||||||||||||||
| fraud_status_code | Integer | The final fraud status code. For example, 3011 or 3111. | |||||||||||||||||||||||||||
| fraud_status_desc | String | Final fraud status description. For example, Accepted or Review | |||||||||||||||||||||||||||
| pre_auth_ext_status_code | Integer | The pre-auth fraud check system response code. | |||||||||||||||||||||||||||
| pre_auth_ext_id | Integer | The pre-auth fraud check system transaction ID. | |||||||||||||||||||||||||||
| post_auth_ext_id | Integer | Post-auth fraud check system transaction ID. | |||||||||||||||||||||||||||
| post_auth_ext_status_code | String | The post-auth fraud check system response code. | |||||||||||||||||||||||||||
| billing_first_name | String | The cardholder's billing address first name. | |||||||||||||||||||||||||||
| billing_last_name | String | The cardholder's billing address last name. | |||||||||||||||||||||||||||
| billing_street_address | String | The cardholder's billing address street address. | |||||||||||||||||||||||||||
| billing_city | String | The cardholder's billing address city name. | |||||||||||||||||||||||||||
| billing_country | Integer | The cardholder's billing address country ID. | |||||||||||||||||||||||||||
| billing_state | String | The cardholder billing address state/region value. | |||||||||||||||||||||||||||
| billing_postal_code | integer | The cardholder's billing address zip code. | |||||||||||||||||||||||||||
| billing_email | String | The card holder's email address. | |||||||||||||||||||||||||||
| integer | Integer | The card holder's mobile number. | |||||||||||||||||||||||||||
| billing_idc | Integer | The card holder's mobile dialling country code. | |||||||||||||||||||||||||||
| service_type_id | Integer | A 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:
The following table shows the possible values of exchange service ID:
| |||||||||||||||||||||||||||
| <additional data> | String | If 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-id | Integer | The session type ID in which:
| |||||||||||||||||||||||||||
| pos | Integer | Point of sale of transaction. For example, countryid - ISO numeric. | |||||||||||||||||||||||||||
| ip_address | String | The IP address of the transaction initiation. |
Updated 10 months ago