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¤cy=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¤cy=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.
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 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. This depends on the status ID. For example, payment captured or payment rejected. |
fee | String | The fee that you charge 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 pre-populated 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 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-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. |
billing_mobile | Integer | The card holder's mobile number. |
billing_idc | Integer | The card holder's mobile dialing 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: • 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. |
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: • 1= normal payment • 2= split payment |
pos | Integer | Point of sale of transaction. For example, countryid - ISO numeric. |
ip_address | String | The IP address of the transaction initiation. |
Updated 5 months ago