--- updatedAt: 2026-07-06T22:14:49.000Z agentTools: siteIndex: https://developers.pismo.io/llms.txt projectIndex: https://developers.pismo.io/pismo-docs/llms.txt --- # 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.1.1", "info": { "title": "Card issuing - 3DS authentication", "description": "3DS API endpoint documentation", "contact": { "name": "API Support", "url": "https://developers.pismo.io/support/" }, "license": { "name": "Copyright Pismo" }, "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": { "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\n\n**Note**: This field must not be used to send Personally Identifiable Information (PII), Payment Card Industry (PCI) data, or any sensitive/regulated information. Metadata fields are intended for operational, non-sensitive data only. For sensitive data, use the specific parameters designed for that purpose. For more information, refer to [Get started with Pismo APIs](https://developers.pismo.io/pismo-docs/reference/get-started-with-pismo-apis#metadata).\n", "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": [], "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" } } } } } } ```