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 to verify their identity through SMS, a phone call, or an app.

For more information, refer to Card tokenization process and onboarding and Card tokenization flow and events.

Webhook specifications
Request fields
FieldTypeDescriptionRequired
custom_codesstring 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.

Refer to the Custom codes table.

No
token_idnumberPismo-issued token ID. You can use this to call the Get token information endpoint.Yes
network_brandenum string
  • vts - Visa
  • mdes - Mastercard
Yes
network_call_methodenum string
  • VTS_DEVICE_BINDING
  • TA
  • VTS_APPROVE_PROVSIONING
  • VTS_APPROVE_PROVISIONG_ISO
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. Note: The Mastercard manual requires a Mastercard Connect ID log in for access.
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. outdated0505
ELFR2     CVV2 retry limit exceeded                              05               05
MATPC      Exceeded maximum active tokens per card  05               05
FRE        Cryptogram data validation failed                  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
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: <your_signed_jwt>' \
//--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/v1/certs"
	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
}

Did this page help you?