# OpenAPI definition ```json { "openapi": "3.0.2", "info": { "title": "Webhooks", "version": "1.3", "description": "Praxis webhook APIs OAS 3.0.2 specification document" }, "servers": [ { "url": "https://{merchant_server}", "description": "Merchant's Server URL", "variables": { "merchant_server": { "default": "api.yourdomain.com", "description": "The base URL where your server receives webhooks" } } } ], "paths": { "/api/sync": { "summary": "This specification provides the details for webhooks - customer sync", "description": "Notification from Praxis where the merchant receives the customer's details from their CRM when an agent attempts to access the Virtual Terminal for a customer from the Backoffice.\r\n\r\nTo enable this retrieval, the CRM must implement an API callback endpoint that will be available to receive the request from Praxis and respond with the appropriate customer information.\r\n\r\nImportant: Ensure that you have provided the callback URL to your technical support representative before attempting to use the Virtual Terminal.
\r\n", "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payload_webhook_customer_sync_requestData" }, "examples": { "customer sync request": { "value": { "application_key": "TEST USD", "merchant_id": "Test-Integration-Merchant", "cid": "123", "order_id": "order_68877", "timestamp": 1561206408, "version": "1.3" } } } } }, "required": true }, "tags": [ "Webhooks" ], "parameters": [ { "name": "gt-authentication", "schema": { "$ref": "#/components/schemas/property_req_header_signature_params_for_webhook_customer_sync" }, "in": "header", "required": true } ], "responses": { "200": { "$ref": "#/components/responses/200-ok-webhook-customer-sync-response-data" } }, "operationId": "customerSync", "summary": "Customer Sync Notification" } } }, "components": { "schemas": { "payload_webhook_customer_sync_requestData": { "type": "object", "allOf": [ { "required": [ "cid" ], "type": "object", "properties": { "cid": { "description": "Unique customer id in your system.\r\n\r\n*__Note:__* *Personally Identifiable Information (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to the API.*", "maxLength": 50, "type": "string", "example": "1020" }, "order_id": { "description": "Transaction or session identifier in your system.", "maxLength": 50, "type": "string" } } }, { "required": [ "merchant_id", "application_key", "version", "timestamp" ], "type": "object", "properties": { "merchant_id": { "description": "Merchant API client account identifier.", "maxLength": 50, "type": "string", "example": "Sandbox-API" }, "application_key": { "description": "Identifier of your application (website).", "maxLength": 32, "type": "string", "example": "Sandbox-Application" }, "version": { "description": "API version.", "maxLength": 3, "type": "string", "example": "1.3" }, "timestamp": { "description": "Request time (unix timestamp, seconds).", "maxLength": 11, "type": "integer", "example": "1755853580" } } } ] }, "property_req_header_signature_params_for_webhook_customer_sync": { "title": "signature", "description": "Authentication HTTP header of an incoming webhook customer sync request from Praxis.\nVerify the signature with the below attributes from the webhook customer sync request.\n- `merchant_id`\n- `application_key` \n- `timestamp`\n- `cid`\n\nThe optional `order_id` request field is not included in the signature for v1.3", "type": "string", "example": "15ca3dadf8e1cb8a64301317f3ce5f8587d1adf37e42ae50702ae35732974193f3f464ddcb019fa0e2f5f3043b1cd23b" } }, "responses": { "409-conflict-webhook-notification-response-data": { "content": { "application/json": { "schema": { "required": [ "status", "description", "version", "timestamp" ], "type": "object", "properties": { "status": { "description": "API communication status - for transaction processing status please refer to `transaction.transaction.status`\r\n- 0 if the request was successful.\r\n- Negative integer if internal server/network error occurs.\r\n- Positive integer if application/logical error occurs. Refer [API Status & Error Codes](https://docs.praxis.tech/docs/api-status-and-error-codes) for more information.", "type": "integer" }, "description": { "description": "Accurate description of the result. Return the actual error for any exception as it helps to diagnose issues in production.\r\n", "type": "string", "maxLength": 256 }, "version": { "$ref": "#/components/schemas/payload_webhook_customer_sync_requestData/allOf/1/properties/version" }, "timestamp": { "$ref": "#/components/schemas/payload_webhook_customer_sync_requestData/allOf/1/properties/timestamp" } } }, "examples": { "notification - duplicate response": { "value": { "status": 1, "description": "Transaction already updated manually at the website to final status", "version": "1.3", "timestamp": 1590611635 } } } } }, "description": "Conflict - Duplicate response" }, "200-ok-webhook-customer-sync-response-data": { "headers": { "external-request-signature": { "schema": { "title": "signature", "description": "Authentication HTTP header of the incoming response from the API.\nBelow response parameters should be used for validating the signature in response header.\n- `status`\n- `timestamp`\n- `manual_validation_url`\n- `manual_notification_url`\n- `balance`", "type": "string", "example": "15ca3dadf8e1cb8a64301317f3ce5f8587d1adf37e42ae50702ae35732974193f3f464ddcb019fa0e2f5f3043b1cd23b" } } }, "content": { "application/json": { "schema": { "description": "200 Successful webhook customer sync response", "type": "object", "allOf": [ { "$ref": "#/components/responses/409-conflict-webhook-notification-response-data/content/application~1json/schema" }, { "required": [ "balance" ], "type": "object", "properties": { "customer_data": { "description": "The customer representation object provided during the response.", "type": "object", "allOf": [ { "type": "object", "properties": { "country": { "$ref": "#/components/responses/200-ok-webhook-customer-sync-response-data/content/application~1json/schema/allOf/1/properties/customer_data/allOf/0/properties/billing_address/properties/country", "description": "ISO 3166-1 alpha-2 country code (US, MT, IT, GB, DE etc.)" }, "first_name": { "description": "Customer's first name.", "maxLength": 25, "type": "string" }, "last_name": { "description": "Customer's last name.", "maxLength": 25, "type": "string" }, "avs_alert": { "description": "Address verification status\r\n- 0 for Address Verification System pass\r\n- 1 for Address Verification System failure (coming soon)", "type": "integer", "enum": [ 0 ] }, "verification_alert": { "description": "Customer verification status (fraud monitor)\r\n- 0 if no alert has been detected for customer\r\n- 1 if fraud alert is detected (coming soon)\r\n- -1 if review by the merchant is required (coming soon)", "type": "integer", "enum": [ 0 ] }, "billing_info_address_edited": { "description": "Setting to display billing address. This parameter including in the request by enabling an additional setting on Atlas BO.", "type": "boolean" }, "billing_address": { "description": "Billing address data object This parameter including in the request by enabling an additional setting on Atlas BO.", "required": [ "address", "city", "state", "zip" ], "type": "object", "properties": { "address": { "description": "Customer's address", "maxLength": 100, "type": "string" }, "city": { "description": "City of the customer", "maxLength": 50, "type": "string" }, "state": { "description": "State/Province where the customer resides. Required for countries: US, CA and AU. 2 or 3 characters ISO format.", "maxLength": 3, "type": "string" }, "zip": { "description": "Postal Code of the customer. Required for US and CA. Can provide values for other countries. Limited to 12 alphanumeric characters only.", "maxLength": 12, "type": "string" }, "country": { "description": "ISO 3166-1 alpha-2 country code (US, MT, IT, GB, DE etc.)", "maxLength": 2, "type": "string" } } } } }, { "title": "and customer token", "required": [ "customer_token" ], "type": "object", "properties": { "customer_token": { "description": "HASH value of customer's identity.\n\n**Note:** Either customer_token or customer_data must be provided. If both are missing, the request will trigger a validation error.", "maxLength": 32, "type": "string" } } } ] }, "manual_validation_url": { "description": "URL to which the manual deposit status notification will be sent. Please refer to Notification for more details.", "maxLength": 256, "type": "string" }, "manual_notification_url": { "description": "URL to which the manual deposit validation request will be sent. Please refer to Validation for more details.", "maxLength": 256, "type": "string" }, "balance": { "description": "Customer's current available balance.", "maximum": 20, "type": "integer" } } } ] }, "examples": { "customer sync - success response": { "value": { "status": 0, "description": "OK", "customer_data": { "country": "GB", "first_name": "John", "last_name": "Johnson", "dob": "12/31/1980", "email": "johnjohnson@example.com", "phone": "44201112222", "zip": "WC2N 5DU", "state": "JS", "city": "London", "address": "Random st., 12/3", "profile": 1 }, "manual_notification_url": "https://api.merchant.com/v1/deposits/fxodWAQVvc9SRxhDaWSJJC21f", "manual_validation_url": "https://api.merchant.com/v1/validate_deposits/fxodWAQVvc9SRxhDaWSJJC21f", "balance": 0, "version": "1.3", "timestamp": 1561279426 } }, "customer sync - failure response": { "value": { "status": 1, "description": "Customer not found", "version": "1.3", "timestamp": 1561207146 } } } } }, "description": "OK - Successful response" } } } } ```\r\n Important: Ensure that you have provided the callback URL to your technical support representative before attempting to use the Virtual Terminal.\r\n
\r\n