# Send pre-authentication info

Send pre-authentication information to the client's anti-fraud validator to evaluate. Pismo calls the validator's webhook and gets a response before sending a response to the caller.

Pismo provides the encrypt/decrypt keys for the hashed PAN. Talk to your Pismo representative about getting these keys.

For information on PAN encryption, refer to the [PAN encryption for 3DS authentication](doc:pan-encryption-for-3ds-authentication) guide.


# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Card issuing - 3DS authentication",
    "description": "3DS API endpoint documentation.",
    "contact": {
      "name": "API Support",
      "email": "support@pismo.com.br",
      "url": "https://developers.pismo.io/support/"
    },
    "license": {
      "name": "Copyright Pismo",
      "url": "https://developers.pismo.io/licenses/"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api-sandbox.pismolabs.io/3ds-acs",
      "description": "Sandbox API server for testing"
    }
  ],
  "tags": [
    {
      "name": "Pre-authentication",
      "description": "Endpoint to provide pre authentication integration"
    }
  ],
  "components": {
    "parameters": {
      "tenantIDheader": {
        "name": "x-tenant",
        "in": "header",
        "schema": {
          "type": "string"
        },
        "required": true,
        "description": "Tenant/org ID"
      }
    },
    "schemas": {
      "AccountID": {
        "type": "integer",
        "description": "Pismo account ID",
        "example": 10045896
      },
      "AccountStatus": {
        "type": "string",
        "description": "Account status",
        "example": "NORMAL",
        "enum": [
          "NORMAL",
          "BLOCKED",
          "CANCELLED"
        ]
      },
      "BadRequest": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "example": "INVALID-REQUEST-PAYLOAD"
          },
          "message": {
            "type": "string",
            "example": "The request payload is invalid"
          }
        }
      },
      "CardID": {
        "type": "integer",
        "description": "Card ID",
        "example": 869572
      },
      "CardStatus": {
        "type": "string",
        "description": "Card status",
        "enum": [
          "NORMAL",
          "BLOCKED",
          "PENDING",
          "LOST",
          "ROBBED",
          "EXPIRED",
          "DAMAGED",
          "FRAUD",
          "WARNING",
          "CANCELED",
          "CREATED",
          "DELETED"
        ],
        "example": "BLOCKED"
      },
      "CardType": {
        "type": "string",
        "description": "Card type",
        "enum": [
          "PLASTIC",
          "VIRTUAL",
          "RECURRING",
          "TEMPORARY"
        ],
        "example": "PLASTIC"
      },
      "CorrelationID": {
        "type": "string",
        "description": "The Correlation identifier field is used to link related API requests and events. The CID can help the Pismo engineering team track everything related to a call. If not passed, a random one is generated. You can find the CID in the response header.\n",
        "example": "c737895c-8159-4c0c-a92a-a4f8600bff37"
      },
      "CustomerID": {
        "type": "number",
        "description": "Customer ID",
        "example": 867604
      },
      "Decision": {
        "type": "string",
        "example": "approve",
        "description": "Client's anti-fraud decision",
        "enum": [
          "approve",
          "reject"
        ]
      },
      "Email": {
        "type": "string",
        "description": "E-mail",
        "example": "ho_lee_smokes@gmail.com"
      },
      "ExternalID": {
        "type": "string",
        "description": "Provider-generated unique ID for client monitoring and tracking",
        "example": "ABC123456"
      },
      "InternalServerError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "example": "INVALID-STRUCT-SIGNATURE"
          },
          "message": {
            "type": "string",
            "example": "An error occurred while interpreting a structure"
          }
        }
      },
      "Metadata": {
        "type": "object",
        "description": "Metadata returned from client's anti-fraud validator",
        "example": {
          "valueA": "a",
          "valueB": 1,
          "valueC": false,
          "valueD": {
            "valueD1": "x"
          },
          "valueN": "..."
        }
      },
      "Name": {
        "type": "string",
        "example": "Paul Bearer",
        "description": "name"
      },
      "PANhash": {
        "type": "string",
        "description": "Encrypted PAN using 2048 rsa key and base64 encoded.\nPismo provides the encrypt/decrypt keys for this field.\n",
        "example": "WEPvOQuZvjfYEd0iBmr43bhWyOsylIsW95ebYrLD89App2iEq9IizP+8w73pxKQ4mI47EdhzYHF9RfXjrBOyug=="
      },
      "Phone": {
        "type": "string",
        "description": "Phone number",
        "example": "+5531998675309"
      },
      "PreAuthenticationAccount": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/AccountID"
          },
          "status": {
            "$ref": "#/components/schemas/AccountStatus"
          },
          "name": {
            "$ref": "#/components/schemas/Name"
          },
          "phone": {
            "$ref": "#/components/schemas/Phone"
          },
          "email": {
            "$ref": "#/components/schemas/Email"
          }
        }
      },
      "PreAuthenticationCard": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/CardID"
          },
          "status": {
            "$ref": "#/components/schemas/CardStatus"
          },
          "type": {
            "$ref": "#/components/schemas/CardType"
          },
          "hash": {
            "$ref": "#/components/schemas/PANhash"
          },
          "printed_name": {
            "$ref": "#/components/schemas/PrintedName"
          }
        }
      },
      "PreAuthenticationCustomer": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/CustomerID"
          },
          "name": {
            "$ref": "#/components/schemas/Name"
          },
          "phone": {
            "$ref": "#/components/schemas/Phone"
          },
          "email": {
            "$ref": "#/components/schemas/Email"
          }
        }
      },
      "PreAuthenticationResponse": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/CorrelationID"
          },
          "external_id": {
            "$ref": "#/components/schemas/ExternalID"
          },
          "decision": {
            "$ref": "#/components/schemas/Decision"
          },
          "account": {
            "$ref": "#/components/schemas/PreAuthenticationAccount"
          },
          "customer": {
            "$ref": "#/components/schemas/PreAuthenticationCustomer"
          },
          "card": {
            "$ref": "#/components/schemas/PreAuthenticationCard"
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          }
        }
      },
      "PreAuthenticationRequest": {
        "type": "object",
        "required": [
          "id",
          "pan"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/ProviderID"
          },
          "pan": {
            "$ref": "#/components/schemas/PANhash"
          },
          "raw_provider": {
            "$ref": "#/components/schemas/RawProvider"
          }
        }
      },
      "PrintedName": {
        "type": "string",
        "minLength": 2,
        "maxLength": 26,
        "example": "Nan Tucket",
        "description": "Printed card name"
      },
      "ProviderID": {
        "type": "string",
        "description": "Client-generated caller ID.",
        "example": "ff77635e-1cd6-4fda-992d-5ceb71d75644"
      },
      "RawProvider": {
        "type": "object",
        "description": "All non-PCI information received from provider. Check provider documentation for details."
      },
      "UnprocessableEntityError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error code"
          },
          "message": {
            "type": "string",
            "description": "Error message"
          }
        },
        "required": [
          "code",
          "message"
        ]
      }
    },
    "responses": {
      "400BadRequestError": {
        "description": "Bad request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/BadRequest"
            }
          }
        }
      },
      "422UnprocessableEntityError": {
        "description": "Unprocessable entity error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/UnprocessableEntityError"
            },
            "examples": {
              "E3DS-001": {
                "value": {
                  "code": "E3DS-001",
                  "message": "No account were found with the specified parameters"
                }
              },
              "E3DS-002": {
                "value": {
                  "code": "E3DS-002",
                  "message": "No account were found with address"
                }
              },
              "E3DS-003": {
                "value": {
                  "code": "E3DS-003",
                  "message": "No account were found with active phone"
                }
              },
              "E3DS-004": {
                "value": {
                  "code": "E3DS-004",
                  "message": "The account is not in a valid state"
                }
              },
              "E3DS-005": {
                "value": {
                  "code": "E3DS-005",
                  "message": "No card were found with the specified parameters"
                }
              },
              "E3DS-006": {
                "value": {
                  "code": "E3DS-006",
                  "message": "No card were found with this PAN"
                }
              },
              "E3DS-007": {
                "value": {
                  "code": "E3DS-007",
                  "message": "The card is not in a valid state"
                }
              },
              "E3DS-008": {
                "value": {
                  "code": "E3DS-008",
                  "message": "No customer were found with the specified parameters"
                }
              },
              "E3DS-009": {
                "value": {
                  "code": "E3DS-009",
                  "message": "There is no configuration to process this request"
                }
              },
              "E3DS-010": {
                "value": {
                  "code": "E3DS-010",
                  "message": "Entity not found"
                }
              },
              "E3DS-011": {
                "value": {
                  "code": "E3DS-011",
                  "message": "There was a failure communicating with an external service"
                }
              },
              "E3DS-012": {
                "value": {
                  "code": "E3DS-012",
                  "message": "Error while fetching customer phone"
                }
              },
              "E3DS-013": {
                "value": {
                  "code": "E3DS-013",
                  "message": "No active phones found to this customer"
                }
              }
            }
          }
        }
      },
      "500InternalServerError": {
        "description": "Internal server error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/InternalServerError"
            }
          }
        }
      }
    }
  },
  "paths": {
    "/v1/preauthenticate": {
      "post": {
        "summary": "Send pre-authentication info",
        "description": "Send pre-authentication information to the client's anti-fraud validator to evaluate. Pismo calls the validator's webhook and gets a response before sending a response to the caller.\n\nPismo provides the encrypt/decrypt keys for the hashed PAN. Talk to your Pismo representative about getting these keys.\n\nFor information on PAN encryption, refer to the [PAN encryption for 3DS authentication](https://developers.pismo.io/pismo-docs/docs/pan-encryption-for-3ds-authentication) guide.\n",
        "operationId": "postPreAuthenticate",
        "tags": [
          "Pre-authentication"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/tenantIDheader"
          }
        ],
        "requestBody": {
          "description": "Send information to evaluation",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PreAuthenticationRequest"
              },
              "examples": {
                "Basic example": {
                  "value": {
                    "id": "ff77635e-1cd6-4fda-992d-5ceb71d75644",
                    "pan": "SdEwfAxa93DJkuBvsfuRfOuqV+Gl3WJIJg4UkL9uK8/2up5UjxsJGNppELuQaad5xb04BE21uy7V0W9fvvGmQmLEpqomG/3J6ppEE0Ufs/CjV2MUacXYwu/Shvl81PPHdEm5gqoOgF4Pter0VVq8YLOEEgiO89htuzuxq8UdOPpFz48ojVLlWb6RYM8XdqPJ0MK/cmlygvpXiYlz/bmsIpinUztvejimyHIi+4Yw2ZjiuG+4Ie+3nndB17vHgNLCtD5krRukD28Y81QDvIzbWAUnqxzESA9gcVHzoWsRPrPksRUH/uce+25qnXnvNbyW0VsHYN2/vLkMhiGkeYBoCg==",
                    "raw_provider": {
                      "valueA": "a",
                      "valueB": 1,
                      "valueC": false,
                      "valueD": {
                        "valueD1": "x"
                      },
                      "valueN": "..."
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreAuthenticationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400BadRequestError"
          },
          "422": {
            "$ref": "#/components/responses/422UnprocessableEntityError"
          },
          "500": {
            "$ref": "#/components/responses/500InternalServerError"
          }
        }
      }
    }
  }
}
```