Client webhooks
This guide details the webhooks (user-defined HTTP calbacks) that customers can code to interact with the Pismo platform during certain operations. Client webhooks should be registered with Pismo during setup. Talk to your Pismo representative about getting these implemented.
Pismo webhook security
For information on webhook security, refer to Verifying webhook requests
Client anti-fraud webhook for card tokenization
As a card issuer, you can provide your own anti-fraud card verification via a webhook that Pismo calls during the tokenization process. If you don't provide one, Pismo uses a default anti-fraud method. You need to configure this webhook with your Pismo representative.
You can:
- Approve a card
- Not approve a card
- Ask Pismo to prompt the cardholder for further identity and verification in the form of SMS, phone call, or app.
For more information, refer to Card tokenization process and onboarding and Card tokenization flow and events .
Webhook specifications
Request fields
Field | Type | Description | Req |
---|---|---|---|
custom_codes | string array | Card status validation codes indicating Pismo's findings. Issuer can still approve. Note that custom codes are listed elsewhere, but not all apply to this webhook. See Custom codes table below. | No |
token_id | number | Pismo-issued token ID. You can use this to call the Get token information endpoint. | Yes |
network_brand | string | - vts - Visa- mdes - Mastercard | Yes |
card | object | ||
id | number | Pismo-assigned card ID | Yes |
type | enum string | Card type: - PLASTIC - VIRTUAL - RECURRING - TEMPORARY | Yes |
program_id | number | Program ID | Yes |
bin | string | Bank identification number | Yes |
status | enum string | Card status: - created - normal - damaged - warning - lost - unknown | No |
stage | enum string | Card lifecycle status - unknown - blocked - unblocked | No |
combo_card | object | No | |
status | enum string | Card status: - created - normal - damaged - warning - lost - unknown | |
original_network_data | object | Refer to the VISA Token Service (VTS) Issuer API Specifications (JSON) manual or the Mastercard Customer Interface Specification manual for more information on the contents of this field. | No |
Custom codes
VTS = Visa, MDES = Mastercard.
Custom code | Description | VTS action code | MDES action code |
---|---|---|---|
CCS | Card status =CANCELLED | 46 | 05 |
CED | Invalid expiration date. Exp date entered does not match Pismo's. | 54 | 05 |
CNN | Card is not inNORMAL status | 05 | 05 |
EXPCRD | Expired card | 05 | 05 |
FR2 | Entered CVV2 is invalid | N7 | 05 |
FRB | CREATED status not allowed | 05 | 05 |
HSE | HSM failed to validate CVV2. | 05 | 05 |
NPL | Card not plastic. Issuer can override for virtual card. | 05 | 05 |
UBT | Blocked card. Legacy | 05 | 05 |
Sample request
{
"card":{
"id": 134142,
"type": "PLASTIC",
"program_id": 1234,
"bin": "5122"
},
"combo_card": { },
"token_id": 432,
"network_brand": "vts",
"custom_codes": ["FRB"],
"original_network_data": {
}
}
Response fields
Field | Type | Description | Required |
---|---|---|---|
approve | boolean | Card approved flag | Yes |
action_code | string | Decision code: - 00 - Approved- 05 - Not approved- 14 - Invalid PAN- 46 - Closed account- 54 - Invalid expiration date- 57 - Not permitted- 58 - Not allowed on terminal- 85 - Needs challenge- 96 - Issuer internal system error- N7 - Invalid CVV2 | Yes |
step_up_methods | object array | Needs challenge methods. At least one is required if used. | Yes if action_code = 85 . |
method | enum string | One-time passcode (OTP) challenge method: - OTPSMS - SMS- OTPAPP - App- OTPCALL - Call | |
value | string | Additional information for challenge - phone number, app, and so on. | |
platform | enum string | Only used for Visa and only when the method is OPTAPP :- IOS - ANDROID - WINDOWS - WEB | |
source | string | Only used for Visa and under certain conditions. This is the Source Address field as discussed in the VISA VTS manual and you should read that document for more information. |
Sample response
{
"step_up_methods": [
{
"method": "OTPCALL",
"value": "+551130039500"
},
{
"method": "OTPSMS",
"value": "5327"
},
{
"method": "OTPAPP",
"value": "app",
"source": "com.issuer.banking://wallet",
"platform": "ANDROID"
}
],
"approve": true,
"action_code": "85"
}
Anti-fraud code sample (Go)
package main
// Anti-fraud code sample in Go
//curl --location --request POST 'http://antifraudhost' \
//--header 'x-pismo-sign: eyJhbGciOiJSUzI1NiIsImtpZCI6IjEzY2VlZWViMWEwNjU1Nzg4Y2UyMDg0ZmZmY2FkMDJmNTFmYzMxNDAiLCJ0eXAiOiJKV1QifQ.eyJhY2NvdW50LWlkIjo5ODY2NTM4NiwiYm9keS1oYXNoIjoiUm0yNWNpTy9RRjNMdmIwL1JZbmVWMFZRUkMzd3pNbzZjemdlR1NHUE1KWT0iLCJleHAiOjE2NTI1MzY2MzAsImlhdCI6MTY1MTY3MjYzMCwiaXNzIjoiYXBpLnBpc21vLmlvIiwia2lkIjoiMTNjZWVlZWIxYTA2NTU3ODhjZTIwODRmZmZjYWQwMmY1MWZjMzE0MCIsInN1YiI6ImFwaS1jYXJkcy10b2tlbml6YXRpb24ifQ.bE7l7KQHRj_0J7zcXtLXgefQuGVQjdUr2BtetTQzTf25_tbHf6iUXHIsGB8iCVujo2e5aUrglxTQScduo3sUuJgzLNUHEyBOgMUc9b6v9K_-reFLpJa9Co0Ct8PmU_os-AZr6jqrYgzGk343I_FYDDw48BmqSMRgwtaJPzHQesaSdd8pjAw_CdSttobstplJjQiwUetufmSvZkOCQHeU-JHTwgdcTwgmtJwVMnFFERIdWQMzoz1UYtP0oMJivw3Zt-MjutqvodkaymOIx9IjJTywp0Oq61rmPtWlKW0pIsI6HCYDR8pASgantt7sXGpNb8cdynUIyvxlixpy77kdfg' \
//--header 'Content-Type: application/json' \
//--data-raw '{
// "card":{
// "id": 134142,
// "type": "PLASTIC"
// },
// "combo_card": null,
// "token_id": 432,
// "network_brand": "vts",
// "custom_codes": ["FRB", "BNB"],
// "original_network_data": {}
//}'
import (
"context"
"crypto/x509"
"encoding/json"
"encoding/pem"
"fmt"
"github.com/labstack/echo/v4"
"github.com/square/go-jose"
"io/ioutil"
"net/http"
)
type clientTokenDecision struct {
Approve bool `json:"approve"`
ActionCode string `json:"action_code"`
StepUpMethods []clientStepUpMethod `json:"step_up_methods"`
}
type clientStepUpMethod struct {
Method string `json:"method"`
Value string `json:"value,omitempty"`
Source string `json:"source"`
Platform string `json:"platform"`
}
func main() {
getPismoCertificates()
e := echo.New()
e.POST("/", handler)
e.Logger.Fatal(e.Start(":1323"))
}
var mapCertificates map[string]*x509.Certificate
func getPismoCertificates() {
url := "https://sandbox.pismolabs.io/robot/v1/metadata/x509/[email protected]"
httpReq, err := http.NewRequestWithContext(context.Background(), http.MethodGet, url, nil)
if err != nil {
panic(err)
}
client := http.Client{}
httpRes, err := client.Do(httpReq)
if err != nil {
panic(err)
}
if httpRes.StatusCode != http.StatusOK {
panic(err)
}
bRes, err := ioutil.ReadAll(httpRes.Body)
if err != nil {
panic(err)
}
tmpMap := make(map[string]string)
err = json.Unmarshal(bRes, &tmpMap)
if err != nil {
panic(err)
}
mapCertificates = make(map[string]*x509.Certificate)
for key, val := range tmpMap {
block, _ := pem.Decode([]byte(val))
if block == nil {
panic("cannot decode block")
}
cer, err := x509.ParseCertificate(block.Bytes)
if err != nil {
panic(err)
}
mapCertificates[key] = cer
}
}
func handler(c echo.Context) error {
tokenString := c.Request().Header.Get("X-Pismo-Sign")
valid := isTokenValid(tokenString)
if !valid {
return fmt.Errorf("certificate not valid")
}
k := clientTokenDecision{
Approve: true,
ActionCode: "85",
StepUpMethods: []clientStepUpMethod{
{
Method: "OTPAPP",
Value: "app.to.app",
},
{
Method: "OTPSMS",
},
},
}
return c.JSON(http.StatusOK, k)
}
func isTokenValid(tokenString string) bool {
jwsSignature, err := jose.ParseSigned(tokenString)
if err != nil {
return false
}
for _, sign := range jwsSignature.Signatures {
kid := sign.Header.KeyID
cert := mapCertificates[kid]
_, err := jwsSignature.Verify(cert.PublicKey)
if err != nil {
return false
}
break
}
return true
}
Examples of the original_network_data field
The original_network_data
field contains all fields present in the ISO message coming from the network, except the PCI-sensitive information. The content varies according to the request being processed, where some fields may or may not be present. Refer to your card network's specification to find all possible fields.
Mastercard
{
"de2_primary_account_number": "[card-hash]",
"de3_processing_code": {
"sf1_cardholder_transaction_type_code": "00",
"sf2_cardholder_from_account_type_code": "30",
"sf3_cardholder_to_account_type_code": "00"
},
"de4_amount_transaction": "000000001000",
"de5_amount_settlement": "000000000251",
"de6_amount_cardholder_billing": "000000001000",
"de7_tranmission_date_and_time": {
"sf1_date": "1110",
"sf2_time": "175808"
},
"de9_conversion_rate_settlement": {
"sf1_decimal_indicator": "7",
"sf2_conversion_rate": "1859259"
},
"de10_conversion_rate_cardholder_billing": {
"sf1_decimal_indicator": "6",
"sf2_cardholderbilling_conversion_rate": "1000000"
},
"de11_stan": "637470",
"de12_time_local_transaction": "145808",
"de13_date_local_transaction": "0727",
"de14_date_expiration": "2704",
"de15_date_settlement": "0727",
"de16_date_conversion": "0726",
"de18_merchant_type": "7994",
"de22_pos_entry_mode": {
"sf1_pos_terminal_pan_entry_mode": "81",
"sf2_pos_terminal_pin_entry_mode": "0"
},
"de28_amount_transaction_fee": {},
"de29_amount_settlement_fee": {},
"de30_amount_transaction_processing_fee": {},
"de31_amount_settlement_processing_fee": {},
"de32_acquiring_institution_id_code": "016800",
"de33_forwarding_institution_id_code": "016800",
"de37_retrieval_reference_number": {
"sf1_transaction_date_and_initiator_discretionary_data": "0727499",
"sf2_terminal_transaction_number": "51999"
},
"de41_card_acceptor_terminal_id": "WA000001",
"de42_card_acceptor_id_code": "00027427823 ",
"de43_card_acceptor_name_location_for_all_transactions": {
"sf1_card_acceptor_name": "MerchantName ",
"sf3_card_acceptor_city": "SAO PAULO ",
"sf5_card_acceptor_state_or_country_code": "BRA"
},
"de48_additional_data_private_user": {
"de48_tcc": "T",
"de48_start": "224",
"de48_size": "123",
"de48SubElements": [
"37",
"42",
"92",
"56",
"75",
"71"
],
"se11_key_exchange_block_data": {},
"se13_mastercard_hosted_mobile_phone_top_up_request_data": {},
"se15_authorization_system_advice_date_and_time": {},
"se18_service_parameters": {},
"se23_payment_initiation_channel": {},
"se25_mastercard_cash_program_data": {},
"se26_wallet_program_data": {},
"se33_pan_mapping_file_information": {},
"se34_atc_information": {},
"se36_visa_mmv": {},
"se37_additional_merchant_data": {
"sf1_payment_facilitador_id": "00000231811",
"sf3_sub_merchant_id": "00027427823 "
},
"se40_eletronic_commerce_merchant_cardholder_certificate_serial_number": {},
"se41_eletronic_commercer_certificate_qualifying_information": {},
"se42_eletronic_commerce_indicator": {
"sf1_eletronic_commerce_security_level_indicator_ucaf_collection_indicator": "910"
},
"se43_ucaf": {},
"se48_mobile_program_indicator": {},
"se49_time_validation_information": {},
"se51_merchant_on_behalf_services": {},
"se55_merchant_fraud_scoring_data": {},
"se56_security_services_additional_data_for_issuers": [
{
"sf1_security_services_indicator": "AQV",
"sf2_security_services_data": "600"
},
{
"sf1_security_services_indicator": "AQS",
"sf2_security_services_data": "408"
},
{
"sf1_security_services_indicator": "AQF",
"sf2_security_services_data": "500"
}
],
"se57_security_services_additional_data_for_acquirers": {},
"se58_atm_additional_data": {},
"se61_pos_data_extended_condition_codes": {},
"se64_transit_program": {},
"se65_terminal_compliant_indicator": {},
"se66_authentication_data": {},
"se67_money_send_information": {},
"se71_onbehalf_services": [
{
"sf1_ob_service": "18",
"sf2_onbehalf_result1": "C",
"sf3_onbehalf_result2": " "
}
],
"se74_additional_processing_information": {},
"se75_fraud_scoring_data": {
"sf1_fraud_score": "036",
"sf2_score_reason_code": "91",
"sf3_rules_score": "036",
"sf4_rules_reason_code1": "91",
"sf5_rules_reason_code2": "00"
},
"se78_payment_service_indicator": {},
"se79_chip_cvr_or_tvr_bit_error_results": {},
"se87_card_validation_code_result_or_cvv2": "U",
"se93_fleet_card_id_request_data": {}
},
"de49_currency_code_transaction": "986",
"de50_currency_code_settlement": "840",
"de51_currency_code_cardholder_billing": "986",
"de55_integrated_circuit_card": {
"sf2_cryptogram_information_data": "80",
"sf3_issuer_application_data": "0120B04009990000000000000000000000FF",
"sf5_terminal_verification_result": "0000048000",
"sf6_transaction_date": "221205",
"sf7_transaction_type": "00",
"sf8_amount_authorized": "000000009910",
"sf9_transaction_currency_code": "0986",
"sf10_application_interchange_profile": "3900",
"sf11_terminal_country_code": "0076",
"sf12_cardholder_verification_method": "420300",
"sf13_terminal_capabilities": "E0F0C8",
"sf23_application_transaction_counter": "0050"
},
"de60_advice_reason_code": {},
"de61_pos_data": {
"sf1_pos_terminal_attendance": "1",
"sf2_reserved_for_future_use": "0",
"sf3_pos_terminal_location": "2",
"sf4_pos_cardholder_presence": "5",
"sf5_pos_card_presence": "1",
"sf6_pos_card_capture_capabilities": "0",
"sf7_pos_transaction_status": "4",
"sf8_pos_transaction_security": "0",
"sf9_reserved_for_future_use": "0",
"sf10_cardholder_activated_terminal_level": "6",
"sf11_pos_card_data_terminal_input_capability_indicator": "0",
"sf12_pos_authorization_life_cycle": "05",
"sf13_pos_country_code_or_submerchant": "076",
"sf14_postal_code_or_submerchant": "01452002 "
},
"de63_network_data": {
"sf1_financial_network_code": "MPL",
"sf2_banknet_reference_number": "JMPDOT"
},
"de90_original_data_elements": {},
"de94_service_indicator": {},
"de95_replacement_amounts": {},
"de97_amount_net_settlement": {},
"de112_additional_data_national_use": {},
"de120_record_data": {},
"de124_member_defined_data": {},
}
Visa
{
"f2_primary_account_number": "[card-hash]",
"f3_processing_code": "000000",
"f4_amount_transaction": "000000001000",
"f6_amount_cardholder_billing": "000000000793",
"f7_transmission_date_and_time": "0516210120",
"f10_conversion_rate_cardholder_billing": "71982500",
"f11_stan": "009836",
"f12_time_local_transaction": "140120",
"f13_date_local_transaction": "0516",
"f14_date_expiration": "2609",
"f15_date_liquidation": "0517",
"f18_merchant_type": "5999",
"f19_acquiring_institution_country_code": "0076",
"f22_pos_entry_mode": "0100",
"f25_pos_condition_code": "59",
"f32_acquiring_institution_id_code": "476113",
"f34_electronic_ecommerce_data": {
"sf01_authentication_data": {}
},
"f37_retrieval_reference_number": "213621009836",
"f41_card_acceptor_terminal_id": "TERMID01",
"f42_card_acceptor_id_code": "CARD ACCEPTOR ",
"f43_card_acceptor_location": "ACQUIRER NAME CITY NAME BR",
"f48_additional_data_private": {},
"f49_currency_code_transaction": "0986",
"f51_currency_code_cardholder_billing": "0840",
"f55_integrated_circuit_card": {
"sf2_cryptogram_information_data": "80",
"sf3_issuer_application_data": "09010A09B02003",
"sf5_terminal_verification_result": "0080099000",
"sf6_transaction_date": "221205",
"sf7_transaction_type": "00",
"sf8_amount_authorized": "000000099900",
"sf9_transaction_currency_code": "0986",
"sf10_application_interchange_profile": "3B00",
"sf11_terminal_country_code": "0076",
"sf12_cardholder_verification_method": "020300",
"sf13_terminal_capabilities": "E0F0C7",
"sf15_amount_other": "000000000000",
"sf23_application_transaction_counter": "002A"
},
"f56_payment_account_reference_data": {},
"f60_additional_pos_data": "0000000005",
"f62_custom_payment_services": {
"sf2_transaction_identifier": "0302136641547109",
"sf21_online_risk_assessment_risk_score_reason_codes": "095A",
"sf22_online_risk_assessment_condition_codes": "02C200"
},
"f63_private_use": {
"sf1_network_id": "0002"
},
"f104_transaction_description_transaction_specific_data": {
"sf5d_installments_data": {},
"sf69_payment_format": {},
"sf67_national_payment_format": {}
},
"f117_national_use": {
"usage_6_argentina_agro": {}
},
"f123_verification_data": {
"token_data": {},
"address_verification_data": {},
"activation_verification_data": {}
},
"f125_supporting_information_data": {
"token_device": {},
"wallet_provider": {}
},
"f126_visa_private_use_fields": {
"sf20_dsecure_indicator": "1"
}
}
Client anti-fraud webhook for banking transactions
This webhook is called during banking operations such as instant pay transactions. Specifically, it would be called during the processing for the following endpoints:
- Pix-out transfer
- Pix reversal
- Pay bank slip
- Cash-out transfer (integrated payments)
Webhook specifications
Request fields
Field | Type | Description | Req |
---|---|---|---|
decision
|
string | Pismo decision Enum: [ " approve ". "reject " ] |
Y |
id
|
string | Request ID | Y |
datetime
|
string | Call datetime in ISO 8601 format | Y |
account_id
|
string | Pismo account ID | Y |
currency_code
|
string | ISO 4217 currency code. For example: 986=Brazil, 840=US. | Y |
amount
|
number | Transaction amount | Y |
origin
|
string | Transaction origin:
Enum:[ " banking ",
"instant-pay ".
"onus "]
|
Y |
operation_type
|
string | Operation type:
Enum: [ " cashin ",
"cashout " ]
|
Y |
processing_code
|
string | Processing code. For more information see Processing codes and transaction types | Y |
entities
|
object | Details of entities related to the transaction. | N |
account
|
object | Account information. | N |
name
|
string | Customer name | N |
document_number
|
string | Customer government document number. | N |
creation_date
|
string | Creation datetime in ISO 8601 format. | N |
limits
|
object | Limits | N |
total
|
number | Total | N |
address
|
object | Address information. | N |
zipcode
|
string | Postal code | N |
phone
|
object | Phone information. | N |
area
|
string | Area code. | N |
country
|
string | Country code. | N |
number
|
string | Phone number | N |
metadata
|
object | Any JSON name-value pairs | N |
raw
|
object | Platform additional information forwarded to the anti-fraud system, varies according to origin. Sent only in onus transactions. | N |
Sample request
{
"decision": "approve",
"id": "id",
"datetime": "2022-07-28T12:45:12.566Z",
"account_id": 102334690,
"currency_code": "986",
"amount": 20,
"origin": "banking",
"operation_type": "cashin",
"processing_code": "003100",
"entities": {
"account": {
"name": "Anne Arbor",
"document_number": "8675309",
"creation_date": "2023-01-01T05:00:00.000Z",
"limits": {
"total": 1000
},
"address": {
"zipcode": 8675309
},
"phone": {
"area": "415",
"country": "55",
"number": "8675309"
}
}
},
"metadata": {
"a": false,
"b": 1,
"c": "test",
"d": {
"d1": "4683bf0c-20d2-4a7f-8877-5f3e9b46252c",
"d2": false,
"d3": 15
}
}
}
Response fields
Field | Type | Description | Req |
---|---|---|---|
decision
|
string | Client decision
Enum: [ " approve ", "
reject "]
|
Y |
metadata
|
object | Any JSON name-value pairs | N |
Sample response
{
“decision”: “approve”,
“metadata”: {}
}
Client webhooks for card transaction authorization
The following webhooks are called, if clients have registered them with Pismo, during the card transaction authorization process. They allow clients to do their own validation and anti-fraud checks in addition to those that Pismo does.
Different webhooks for Full balance and Zero balance
Please note that the following two webhooks - one for Full balance clients and one for Zero balance clients - are not the same and can not be used interchangeably.
For information about the differences between Full balance and Zero balance implementation, refer to the Card network integration guide.
Zero balance validations webhook
This section details how Zero balance customers should code their validations and anti-fraud webhook for the transaction authorization process. The webhook request to Zero balance clients occurs during step 5 in the Full and Zero balance workflows.
Unlike Full balance issuers, Zero balance issuers need to do their own account and limit checks as well as validations and anti-fraud checks. Pismo performs basic card validations for Zero balance customers and, if any of the validations fail, this webhook is not called. This webhook is optional, but if you want to provide one, you should register it during setup.
Webhook specifications
Request headers
Field | Type | Description | Req |
---|---|---|---|
x-tenant |
string | Organization/tenant ID | N |
x-cid |
string | Authorization correlation ID. The CID is used to link related API requests and events. For example, if a user makes an authorization request with 10 installments, this generates 1 authorization event and 10 transaction events all containing the same correlation ID. The x-cid can help the Pismo engineering team track everything related to a call. If one isn't passed, it is automatically generated. You can find it in a response header. | N |
Authorization |
string | Access token | N |
Content-type |
string | A specification for a structured, used application/json | N |
User-Agent |
string | The user agent responsible for making a given HTTP request. For example, pismo/http-client. | N |
Request fields
Field | Type | Description | Req |
---|---|---|---|
id
|
string | Database transaction ID | Y |
entity
|
string | Entity type enum:
- transaction
|
Y |
fields
|
object | Fields submitted through zero balance anti-fraud ingress requests. Note that each entity type has some exclusive fields (Those fields have an additional note between []). | Y |
mti
|
string | Message type ID. For example:
0100 = auth. request
0110 = auth. response
0120 = auth. advice
For more information, refer to MTI. |
Y |
card_id
|
int | Transaction cardholder card ID | Y |
account_id
|
int | Transaction cardholder account ID | Y |
amount_transaction
|
number | Transaction amount in the cardholder's billing currency | Y |
amount_local
|
number | Transaction amount in the merchant's local currency | Y |
transaction_timestamp
|
string | Transaction date and hour (format:yyyy-MM-dd hh:mm:ss) | Y |
amount_settlement
|
number | Amount in settlement currency defined by the issuer | Y |
processing_code
|
string | Transaction's effect on the customer account and the type of accounts affected.
"00" for purchase
"01" for withdraw
"20" for refund
"28" for payment |
Y |
currency
|
string | Transaction country currency code - ISO 4217. For example,
840 (US)
986 (Brazil)
|
Y |
payment_card_brand
|
string | null | Transaction brand -
Visa or
Mastercard .
|
N |
merchant_id_code
|
string | Merchant code as registered at the payments network database (Visa/Mastercard) | N |
merchant_name
|
string | Merchant name as registered at the payments network database (Visa/Mastercard) | N |
merchant_city
|
string | Merchant city as registered at the payments network database (Visa/Mastercard) | N |
merchant_state_or_country_code
|
string | Merchant country code outside USA (OR) Merchant state code from the USA (OR) Canadian province code from Canada.
NOTE: Canadian merchants can either be represented through the province code or the canadian country code. |
N |
merchant_terminal_id
|
string | Terminal ID at acquirer database | N |
atc_chip
|
string | Application Transaction Counter acquired from ISO8583 formatted payments network message | N |
atc_database
|
array of mumbers | null | Application Transaction Counter acquired from authorization platform database. Comma-separated array of numbers. | N |
cvv_data
|
string | CVV data | N |
entry_mode
|
string | Method used for PAN entry to initiate a transaction and the PIN entry capabilities. This field is required and must have 3 or 4 digits.
For example, try 901 or
9010 for magnetic stripe transaction simulation.
|
N |
mcc
|
string | Merchant category codes payments network. | N |
card_type
|
string | Transaction cardholder card type enum:
PLASTIC
VIRTUAL
TEMPORARY
RECURRING
|
N |
country_code
|
string | Card issuer location's country code - ISO 3166-1 | N |
chip_validation
|
bool | Is chip valid flag | N |
postal_code
|
string | Card issuer location's postal code | N |
chip_cryptogram_information_data
|
string | null | Relevant information data from cardholder chip | N |
chip_transaction_date
|
string | null | Transaction date from cardholder chip. Format: yymmdd. |
N |
chip_transaction_type
|
string | Specific transaction type | N |
chip_amount_authorized
|
string | null | Amount authorized for cardholder. Format: 000000000010) | N |
chip_transaction_currency_code
|
string | null | Specific given currency code | N |
chip_application_interchange_profile
|
string | null | Application interchange profile information | N |
chip_terminal_country_code
|
string | null | Terminal country code from payment network. | N |
chip_cardholder_verification_method
|
string | null | Cardholder authorization verification method | N |
chip_terminal_capabilities
|
string | null | Capability code given by POS. Each code has the list of capabilities classified. | N |
chip_amount_other
|
string | niull | If there is no cash back amount, the value of 9F03 is zero. 9F03 may be absent, or present with a zero value.
If there is a cash back amount, presence is mandatory. |
N |
chip_application_transaction_counter
|
string | null | DE 120 (record data) contains Application Transaction Counter file data when DE 101 (file name) contains MCC109 | N |
cardholder_postal_code
|
string | null | Cardholder postal code | N |
transaction_type
|
string| null | Processing code that describes the transaction type being authorized | N |
nsu
|
string | Authorization Network Settlement Utility (NSU) number which tracks the flow of funds between parties involved in a payment card transaction, including the bank, the merchant, and the card network.
Different payment card networks may have their own NSU systems (e.g., Visa - VisaNet, Mastercard - BankNet) or they may use a third party. |
N |
retrieval_reference_number
|
string | Merchant POS system generated number | N |
authorization_code
|
string | Authorization code | Y |
incoming_authorization_code
|
string | Authorization code from card network | N |
response_code
|
string | Network two digit response code. For example:
00 = approve
51 = insufficient funds
57 = card not active
96 = system failure, etc.
For more information, refer to Validation codes for authorization events. If approve =
false , you can use this value to respond to the network.
|
Y |
terminal_capability
|
string | null | Point-of-sale (POS) entry mode code | N |
tvr
|
string | null | Terminal verification results: serves as notification of bit validation errors detected in the TVR within the issuer application data during M/Chip Cryptogram Validation processing. | N |
cvr
|
string | null | Card verification results: serves as notification of bit validation errors detected in the CVR within the issuer application data during M/Chip Cryptogram Validation processing. | N |
number_of_installments
|
int | Authorization's number of installments | N |
network_score
|
number | Payment network score: empty field when no information is present | N |
pos_postal_code
|
string | Terminal machine authorizer postal code | N |
acquirer_code
|
string | Authorizer acquirer code | N |
denial_code
|
string | Code that identifies reason the transaction was denied | N |
financial_network_code
|
string | Financial code from card network | N |
banknet_reference_number
|
string | Authorization banknet reference number | N |
original_network_data
|
object | Raw ISO-8583 message without sensitive fields. | N |
cvv_presence
|
bool | Is CVV data present flag | N |
password_present
|
bool | Is password used flag | N |
account_type
|
string | Account type:
00 for non specified
10 for savings
20 for checking
30 for credit card
|
N |
validation_results
|
object array | Performed validations list | N |
name
|
string | Validation ID
See Authorization rule list for more information. |
N |
status
|
string | Execution status:
APPROVED
REJECTED
SKIPPED
|
N |
reason
|
string | Reason enum
For more information, refer to the authorization list of rules guide. |
N |
description
|
string | Human-readable result reason | N |
program_id
|
integer | Program ID | N |
token_id
|
integer | Transaction cardholder token ID | N |
wallet_id
|
string | Transaction cardholder wallet ID | N |
account_owner_data
|
object | An array that contains the account owner information (sent by Visa for validation).
This is only required if account_name_request="I". |
|
account_owner_type
|
string | Account owner type can be PRIMARY or SECONDARY . |
N |
acount_owner_name_first
|
string | Primary or secondary account owner's first name | N |
account_owner_name_middle
|
string | Primary or secondary account owner's middle name | N |
account_owner_name_last
|
string | Primary or secondary account owner's last name | N |
account_name_request
|
string | Determines request for account name information. | |
cardholder_postal_code
|
string | Card holder's postal code in support of the Address Verification System (AVS) in Canada and Europe. | Y |
cardholder_street_number
|
string | Card holder's street number in support of the Address Verification System (AVS) in Canada and Europe. | Y |
cardholder_street_address
|
string | Card holder's street address in support of the Address Verification System (AVS) in Canada and Europe. | Y |
Sample request
{
"id": "1111",
"entity": "transaction",
"fields": {
"mti": "0100",
"card_id": 1234,
"account_id": 1234,
"amount_transaction": 10,
"amount_local": 10,
"amount_settlement": 10,
"transaction_timestamp": "2019-05-09 15:52:00",
"processing_code": "00",
"payment_card_brand": "Mastercard",
"currency": "986",
"merchant_id_code": "687555537877464",
"merchant_name": "PISMO",
"merchant_city": "SAO PAULO",
"merchant_state_or_country_code": "BRA",
"merchant_terminal_id": "12300004",
"atc_chip": "43",
"atc_database": [
748,
652,
998
],
"cvv_data": "CVV_PRESENT",
"entry_mode": "string",
"mcc": "string",
"card_type": "PLASTIC",
"country_code": "076",
"chip_validation": true,
"postal_code": "31404",
"chip_cryptogram_information_data": "80",
"chip_transaction_date": "190425",
"chip_transaction_type": "string",
"chip_amount_authorized": "000000000010",
"chip_transaction_currency_code": "0076",
"chip_application_interchange_profile": "0076",
"chip_terminal_country_code": "076",
"chip_cardholder_verification_method": "420300",
"chip_terminal_capabilities": "E0F0C8",
"chip_amount_other": "string",
"chip_application_transaction_counter": "3900",
"cardholder_postal_code": "22222222",
"transaction_type": "00",
"nsu": "15469",
"retrieval_reference_number": "5600001085571",
"authorization_code": "ABCD12",
"incoming_authorization_code": "ABCD12",
"response_code": "00",
"terminal_capability": "string",
"tvr": "0000248000",
"cvr": "0110A040002A00000000000000000000FF",
"number_of_installments": 3,
"network_score": 0,
"pos_postal_code": "22222222",
"acquirer_code": "string",
"denial_code": "CED",
"financial_network_code": "ABC",
"banknet_reference_number": "123456",
"cvv_presence": true,
"password_present": true,
"original_network_data": "...",
"account_type": "30",
"validation_results": [
{
"name": "ARQC",
"status": "APPROVED",
"reason": "NO_CRYPTOGRAM",
"description": "No cryptogram present"
}
],
"program_id": 0,
"token_id": 1234,
"wallet_id": "1234"
"account_owner_data": [
{
"account_owner_type": "PRIMARY_OWNER",
"account_owner_name_first": "FirstName",
"account_owner_name_middle": "MiddleName",
"account_owner_name_last": "LastName",
},
],
"additional_service_request_data": {
"account_name_request": "I"
}
"cardholder_postal_code" : 12345
"cardholder_street_number" : 999
"cardholder_street_address" : Production St.
}
}
Response fields
Field | Type | Description | Req |
---|---|---|---|
is_approved
|
bool | Is transaction approved flag | N |
response_code
|
string | Network two digit response code. For example:
00 = approve
51 = insufficient funds
57 = card not active
96 = system failure, etc. For more information, refer to
Validation codes for authorization events. If approve = false , you can use this value to respond to the network.
|
N |
limit_amount
|
number | Limit available. An ordinary case is balance inquiry. Return null if there is no need to pass it. [entity:"transaction" only] | N |
available_credit_limit
|
object | Balance limit for processing code 30 (balance inquiry) | N |
amount
|
number | Available credit limit amount | N |
currency_code
|
integer | ISO 4217 currency code. For example: 986 = Brazilian real. | N |
account_owner_data
|
object | An array that contains the account owner information (sent by Visa for validation).
This is only required if account_name_request="Y". |
|
account_owner_type
|
string | Account owner type can be PRIMARY or SECONDARY . |
N |
acount_owner_name_first
|
string | Primary or secondary account owner's first name | N |
account_owner_name_middle
|
string | Primary or secondary account owner's middle name | N |
account_owner_name_last
|
string | Primary or secondary account owner's last name | N |
account_name_request_result
|
string | Indicates if a match was performed. This is only required if accountNameRequest="I". Possible values:
NAME_MATCH_PERFORMED
NAME_MATCH_NOT_PERFORMED
NAME_MATCH_NOT_SUPPORTED
|
|
name_account_match_decision
|
string | Match decision value is only required if account_name_request="Y". Possible values:
MATCH
PARTIAL_MATCH
NO_MATCH
UNVERIFIED = when for some reason the validation is not performed.
|
|
match_address
|
string | If cardholder_street_address and cardholder_street_number passed in the request matches the customer's street address, this flag is set to true , otherwise it is set to false .
|
Y |
match_postal_code
|
string | If cardholder_postal_code matches the customer's postal code, this flag is set to true , otherwise it is set to false .
|
Y |
no_address_data
|
string | If the customer's address is not in the system and cannot be verified, this flag is set to true , otherwise it is set to false .
|
Y |
Sample response
{
"is_approved": true,
"response_code": "00",
"limit_amount": 12.34
account_owner_data: [
{
account_owner_type : PRIMARY_OWNER,
account_owner_name_first : "FirstName",
account_owner_name_middle : "MiddleName",
account_owner_name_last : "LastName",
},
{
account_owner_type : SECONDARY_OWNER,
account_owner_name_first : "SFirstName",
account_owner_name_middle : "SMiddleName",
account_owner_name_last : "SLastName",
},
additional_service_result_data : {
account_name_request_result : "NAME_MATCH_PERFORMED",
full_name_account_match_decision : "MATCH",
last_name_account_match_decision : "MATCH",
middle_name_account_match_decision : "NO_MATCH",
first_name_account_match_decision : "PARTIAL_MATCH",
},
],
additional_service_request_data: {
account_name_request : "Y"
}
match_address : true
match_postal_code : true
no_address_data : false
}
Full balance anti-fraud webhook
This section details how Full balance customers should code their anti-fraud webhook for the transaction authorization process. This webhook request to Full balance clients occurs during step 5 in the Full and Zero balance workflows. This webhook is optional, but if you want to provide one, you should register it during setup.
For more information, see the Anti-fraud integration guide article.
Webhook specifications
Request headers
Field | Type | Description | Req |
---|---|---|---|
x-tenant |
string | Organization/tenant ID | N |
x-account-id |
number | Transaction cardholder account ID | N |
Authorization |
string | Access token | N |
x-amount |
number | Transaction amount | N |
Request fields
Field | Type | Description | Req |
---|---|---|---|
id
|
string | Database transaction ID. | Y |
entity
|
string | Entity type enum:
- transaction
|
Y |
fields
|
object | Fields submitted through zero balance anti-fraud ingress requests. Please note that each entity type has some exclusive fields (Those fields have an additional note between []). | Y |
mti
|
string | Message type ID. For example:
0100 = auth. request,
0110 = auth. response,
0120 = auth. advice. For more information, see
MTI.
|
Y |
card_id
|
int | Transaction cardholder card ID | Y |
card_status
|
sring | Transaction cardholder card status:
NORNAL UNBOUND BLOCKED PENDING REISSUED LOST ROBBED EXPIRED DAMAFGED FRAUD WARNING CANCELLED CREATED DELETED BROKEN THEFT
|
Y |
card_expiration_date
|
string | Transaction cardholder card expiration date, format = yyyy-mm-dd | Y |
card_type
|
string | Transaction cardholder card type enum:
PLASTIC
VIRTUAL
TEMPORARY
RECURRIMG
|
N |
token_id
|
int | Transaction cardholder token ID | N |
wallet_id
|
string | Transaction cardholder wallet ID | N |
device_id_wallet
|
string | Transaction cardholder device ID | N |
account_id
|
int | Transaction cardholder account ID | Y |
authorization_code
|
string | Authorization code. | Y |
nsu
|
string | Authorization Network Settlement Utility (NSU) number - tracks the flow of funds between parties involved in a payment card transaction, including the bank, the merchant, and the card network. Different payment card networks may have their own NSU systems, ie, Visa - VisaNet, Mastercard - BankNet, or they may use a third party. | N |
advice_reason_code
|
string | If this is an advice, the reason code. For more information about the Advice reason code (DE 60 subfield 01) and Advice detail code (DE 60 subfield 02) see the network manual, Mastercard for example: Customer Interface Specification (2020-MasterCard-CustomerInterfaceSpecification.pdf). | N |
advice_detail_code
|
string | If this is an advice, the detail code. | Y |
amount_transaction
|
number | Transaction amount converted to the cardholder's billing currency. | Y |
amount_local
|
number | Transaction amount in merchant local currency. | Y |
transaction_timestamp
|
string | Transaction date and hour (format:yyyy-MM-dd hh:mm:ss) | Y |
amount_settlement
|
number | Transaction amount in U.S. dollar. | Y |
payment_card_brand
|
string | null | Transaction brand -
Visa or
Mastercard .
|
N |
currency
|
string | Transaction country currency code - ISO 4217. For example,
840 (US) and
986 (Brazil)
|
Y |
merchant_id_code
|
string | Merchant code as registered at the payments network database (Visa/Mastercard) | N |
merchant_name
|
string | Merchant name as registered at the payments network database (Visa/Mastercard) | N |
merchant_city
|
string | Merchant city as registered at the payments network database (Visa/Mastercard) | N |
merchant_state_or_country_code
|
string | Merchant country code outside USA OR Merchant state code from the USA OR Canadian province code from Canada (NOTE:Canadian merchants can either be represented through the province code or the canadian country code) | N |
merchant_terminal_id
|
string | Terminal ID at acquirer database | N |
security_cnp_transaction
|
string | Electronic commerce security indicator. | N |
atc_chip
|
string | Application Transaction Counter acquired from ISO8583 formatted payments network message | N |
atc_database
|
array of mumbers | null | Application Transaction Counter acquired from authorization platform database. Comma-separated array of numbers. | N |
cvv_data
|
string | CVV data | N |
entry_mode
|
string | Method used for PAN entry to initiate a transaction and the PIN entry capabilities. This field is required and must have 3 or 4 digits. For example, try
901 or
9010 for magnetic stripe transaction simulation.
|
N |
mcc
|
string | Merchant category codes payments network. | N |
country_code
|
string | Card issuer location's country code - ISO 3166-1 | N |
postal_code
|
string | Card issuer location's postal code. | N |
chip_cryptogram_information_data
|
string | null | Relevant information data from cardholder chip | N |
chip_transaction_date
|
string | null | Transaction date from cardholder chip, format = yymmdd. | N |
chip_transaction_type
|
string | Specific transaction type. | N |
chip_amount_authorized
|
string | null | Amount authorized for cardholder (format:000000000010) | N |
chip_transaction_currency_code
|
string | null | Specific given currency code. | N |
chip_application_interchange_profile
|
string | null | Application interchange profile information. | N |
chip_terminal_country_code
|
string | null | Terminal country code from payment network. | N |
chip_cardholder_verification_method
|
string | null | Cardholder authorization verification method. | N |
chip_terminal_capabilities
|
string | null | Capability code given by POS, each code has the list of capabilities classified. | N |
chip_amount_other
|
string | niull | If there is no cash back amount, the value of 9F03 is zero. 9F03 may be absent, or present with a zero value. (If there is a cash back amount, presence is mandatory). | N |
chip_application_transaction_counter
|
string | null | DE 120 (record data) contains Application Transaction Counter file data when DE 101 (file name) contains MCC109 | N |
cardholder_postal_code
|
string | null | Cardholder postal code. | N |
transaction_type
|
string| null | Processing code that describes the transaction type being authorized. | N |
terminal_capability
|
string | null | Point-of-sale (POS) entry mode code | N |
tvr
|
string | null | Terminal verification results - serves as notification of bit validation errors detected in the TVR within the issuer application data during M/Chip Cryptogram Validation processing. | N |
cvr
|
string | null | Card verification results - serves as notification of bit validation errors detected in the CVR within the issuer application data during M/Chip Cryptogram Validation processing. | N |
number_of_installments
|
int | Authorization's number of installments. | N |
available_limit
|
number | Available amount limit for payment mode authorized. | |
network_score
|
number | Payment network score - empty field when no information is present. | N |
pos_postal_code
|
string | Terminal machine authorizer postal code. | N |
acquirer_code
|
string | Authorizer acquirer code. | N |
cpf
|
string | Transaction cardholder document number. | N |
total_limit
|
number | Total amount limit for payment mode authorized. | N |
max_credit_limit
|
number | Maximum credit amount approved for this account. | N |
denial_code
|
string | Code that identifies reason if we deny this transaction. | N |
response_code
|
string | Network two digit response code. For example:
00 = approve,
51 = insufficient funds,
57 = card not active,
96 = system failure, etc. For more information, see
Validation codes for authorization events. If
approve =
false , you can use this value to respond to the network.
|
Y |
last_referral_reason
|
string | null | Anti-fraud system's last referral reason. | N |
id_last_referral_reason
|
string | null | Anti-fraud system's last referral ID reason. | N |
id_last_referral_unlock_date
|
string | null | Anti-fraud system's last referral unlock date, format = yyyy-mm-dd hh:mm:ss. | N |
cvv_data
|
bool | Is CVV data present flag. | N |
cvv_response
|
bool | Does CVV have a valid response flag. | N |
unlock_date
|
bool | Last card history unlock date. | N |
password_present
|
bool | Is password used flag. | N |
original_network_data
|
object | Raw ISO-8583 message without sensitive fields. | N |
last_four_digits
|
string | Card last four PAN digits. | N |
bin
|
string | Card BIN (bank identification number). | N |
program_id
|
integer | Program ID. | N |
pin_validation_offline
|
bool | Is pin validation executed offline flag. | N |
validation_results
|
object array | Performed validations list. | N |
name
|
string | Validation ID. | N |
status
|
string | Execution status -
APPROVED ,
REJECTED , or
SKIPPED .
|
N |
reason
|
string | Reason enum. For more information, see the authorization list of rules guide. | N |
description
|
string | Human-readable result reason. | N |
transaction_mode
|
string | Transaction mode - credit or debit. | N |
three_domain_security
|
object | Three domain security information | N |
service_indicator
|
string | Service indicator ID, corresponding to DE48 SE71 on Mastercard or F126 S20 on Visa. | Y |
electronic_commerce_indicator
|
string | Electronic commerce indicator ID, corresponding to DE48 SE42 on Mastercard or F60 S08 on Visa. | Y |
cardholder_authentication
|
string | Cardholder authentication method, corresponding to DE48 SE43 on Mastercard or F44 S13 on Visa. | Y |
authentication_data
|
string | Cardholder authentication method, corresponding to DE48 SE66 on Mastercard or F126 S09 on Visa. | Y |
Sample request
{
"id": "1111",
"entity": "transaction",
"fields": {
"mti": "0100",
"card_id": 1234,
"card_status": "NORMAL",
"card_expiration_date": "2026-10-15T00:00:00.000Z",
"card_type": "PLASTIC",
"token_id": 1234,
"wallet_id": "1234",
"device_id_wallet":"1234",
"account_id": 1234,
"authorization_code": "ABCD12",
"nsu": "15469",
"advice_reason_code": "string",
"advice_detail_code": "0110",
"amount_transaction": 10,
"amount_local": 10,
"amount_settlement": 10,
"transaction_timestamp": "2019-05-09 15:52:00",
"payment_card_brand": "Mastercard",
"currency": "986",
"merchant_id_code": "687555537877464",
"merchant_name": "PISMO",
"merchant_city": "SAO PAULO",
"merchant_state_or_country_code": "BRA",
"merchant_terminal_id": "12300004",
"security_cnp_transaction": "123",
"atc_chip": "43",
"atc_database": [
748,
652,
998
],
"entry_mode": "string",
"mcc": "string",
"country_code": "076",
"postal_code": "31404",
"chip_cryptogram_information_data": "80",
"chip_transaction_date": "190425",
"chip_transaction_type": "string",
"chip_amount_authorized": "000000000010",
"chip_transaction_currency_code": "0076",
"chip_application_interchange_profile": "0076",
"chip_terminal_country_code": "076",
"chip_cardholder_verification_method": "420300",
"chip_terminal_capabilities": "E0F0C8",
"chip_amount_other": "string",
"chip_application_transaction_counter": "3900",
"cardholder_postal_code": "22222222",
"transaction_type": "00",
"terminal_capability": "string",
"tvr": "0000248000",
"cvr": "0110A040002A00000000000000000000FF",
"number_of_installments": 3,
"available_limit": 200.55,
"network_score": 0,
"pos_postal_code": "22222222",
"acquirer_code": "string",
"cpf": "string",
"total_limit": 5000,
"max_credit_limit": 5000,
"denial_code": "CED",
"response_code": "00",
"last_referral_reason": "",
"id_last_referral_reason": "",
"last_referral_unlock_date": "2019-05-09 15:52:00",
"cvv_data": true,
"cvv_response": true,
"unlock_date": "string",
"password_present": true,
"last_four_digits": "string",
"bin": "string",
"program_id": 0,
"pin_validated_offline": true,
"validation_results": [
{
"name": "ARQC",
"status": "APPROVED",
"reason": "NO_CRYPTOGRAM",
"description": "No cryptogram present"
}
],
"transaction_mode": "CREDIT",
"three_domain_security": {
"service_indicator": "S",
"electronic_commerce_indicator": "05",
"cardholder_authentication": "00",
"authentication_data": "0201020590000000000000000000"
}
}
}
Response fields
Field | Type | Description | Req |
---|---|---|---|
approve
|
bool | Anti-fraud response after check for transaction fraud. | N |
force_approve
|
bool | Force approval flag - enables the client's anti-fraud system to take precedence over the Pismo authorization system decision. If true and the account lacks sufficient funds, authorization is forced and the account will be negative. | N |
referral
|
bool | AIs transaction a referral flag. | N |
response_code
|
string | Network two digit response code. For example:
00 = approve,
51 = insufficient funds,
57 = card not active,
96 = system failure, etc. For more information, see
Validation codes for authorization events. If approve = false , you can use this value to respond to the network.
|
N |
metadata
|
object | Is sent as part of a network authorizations event (metadata field) without filtering. | N |
Sample response
{
"approve": true,
"force_approve": true,
"referral": true,
"response_code": "00",
"metadata": {}
}
Updated 5 days ago