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
| Field | Type | Description | Required |
|---|---|---|---|
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. Refer to the Custom codes table. | No |
token_id | number | Pismo-issued token ID. You can use this to call the Get token information endpoint. | Yes |
network_brand | enum string |
| Yes |
network_call_method | enum string |
| Yes |
card | object | ||
id | number | Pismo-assigned card ID | Yes |
type | enum string | Card type:
| Yes |
program_id | number | Program ID | Yes |
bin | string | Bank identification number | Yes |
status | enum string | Card status:
| No |
stage | enum string | Card lifecycle status
| No |
combo_card | object | No | |
status | enum string | Card status:
| |
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. Note: The Mastercard manual requires a Mastercard Connect ID log in for access. | 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. outdated | 05 | 05 |
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
| Field | Type | Description | Required |
|---|---|---|---|
approve | boolean | Card approved flag | Yes |
action_code | string | Decision code:
| 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:
| |
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:
| |
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: <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
}Updated about 13 hours ago
Did this page help you?