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
FieldTypeDescriptionReq
custom_codesstring arrayCard 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_idnumberPismo-issued token ID. You can use this to call the Get token information endpoint.Yes
network_brandstring- vts - Visa
- mdes - Mastercard
Yes
cardobject
idnumberPismo-assigned card IDYes
typeenum stringCard type:

- PLASTIC
- VIRTUAL
- RECURRING
- TEMPORARY
Yes
     program_idnumberProgram IDYes
     binstringBank identification numberYes
statusenum stringCard status:

- created
- normal
- damaged
- warning
- lost
- unknown
No
stageenum stringCard lifecycle status

- unknown
- blocked
- unblocked
No
combo_cardobjectNo
statusenum stringCard status:

- created
- normal
- damaged
- warning
- lost
- unknown
original_network_dataobjectRefer 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 codeDescriptionVTS action codeMDES action code
CCSCard status =CANCELLED4605
CEDInvalid expiration date. Exp date entered does not match Pismo's.5405
CNNCard is not inNORMAL status0505
EXPCRDExpired card0505
FR2Entered CVV2 is invalidN705
FRBCREATED status not allowed0505
HSEHSM failed to validate CVV2.0505
NPLCard not plastic. Issuer can override for virtual card.0505
UBTBlocked card. Legacy0505
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
FieldTypeDescriptionRequired
approvebooleanCard approved flagYes
action_codestringDecision 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_methodsobject arrayNeeds challenge methods. At least one is required if used.Yes if action_code = 85.
methodenum stringOne-time passcode (OTP) challenge method:

- OTPSMS - SMS
- OTPAPP - App
- OTPCALL - Call
valuestringAdditional information for challenge - phone number, app, and so on.
platformenum stringOnly used for Visa and only when the method is OPTAPP:

- IOS
- ANDROID
- WINDOWS
- WEB
sourcestringOnly 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:

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": {}
}