--- updatedAt: 2025-08-20T00:46:10.000Z agentTools: projectIndex: https://developer.authvia.com/llms.txt --- # Get Action > 🔑 [scope](intro/authentication#scopes) `business_processes:read` Retrieves detailed information on specific [Business Process](create-business-process) action associated with a particular [Business Process](create-business-process) and [Customer](customers) reference within the [Account's](account) (Merchant's) [Account](account). Use this API to track, verify, and analyze individual [Business Process](create-business-process) actions effectively. > 🎯 Explore Action types > For detailed information about available action types, please refer to the [Action Catalog](acknowledgement-action) section. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "version": "3.3", "title": "Customers", "description": "Authvia's API empowers developers to create best in class [Customer](customers) facing solutions for their accounts. The rich catalog of [Providers](provider-product-catalog) and [Actions](acknowledgement-action) allow easy access to a rich set of features, and extensions of abilities to other systems. Using [Business Process](create-business-process) you can group various operations into a single workflow, such as document signatures, form capturing, attachments, and payments, among others. The flexibility of the API allows for an infinite combination of behaviors to streamline and enhance business operations across different channels (web/messaging) platforms.", "contact": { "name": "Support", "url": "https://support.authvia.com", "email": "support@authvia.com" } }, "servers": [ { "url": "https://api.authvia.com/v3" } ], "components": { "securitySchemes": { "bearerToken": { "type": "apiKey", "in": "header", "name": "Authorization", "x-bearer-format": "bearer", "x-default": "", "x-scopes": { "accounts:read": "Can read an [Account](get-account), the profile, contacts or the products within it.", "accounts:update": "Can read and update an [Account](get-account), the profile, contacts or the products within it." } } } }, "tags": [ { "name": "Business Processes", "description": "Bundles up a series of 'actions' for a [Customer](customers) to interact with." }, { "name": "Webhook Types Customer", "description": "Webhook events that are sent in the context of the [Customer](customers)." } ], "x-tagGroups": [ { "name": "Customers", "tags": [ "Customers" ] }, { "name": "Addresses", "tags": [ "Addresses" ] }, { "name": "Payment Methods", "tags": [ "Payment Methods" ] }, { "name": "Transactions", "tags": [ "Transactions" ] }, { "name": "Business Processes", "tags": [ "Business Processes" ] }, { "name": "Webhook Types Customer", "tags": [ "Webhook Types Customer" ] } ], "paths": { "/accounts/{account-id}/customers/{ref}/business-processes/{business-process-id}/actions/{action-id}": { "get": { "tags": [ "Business Processes" ], "summary": "Get Action", "operationId": "get-business-process-action", "description": "> 🔑 [scope](intro/authentication#scopes) `business_processes:read`\n\nRetrieves detailed information on specific [Business Process](create-business-process) action associated with a particular [Business Process](create-business-process) and [Customer](customers) reference within the [Account's](account) (Merchant's) [Account](account). Use this API to track, verify, and analyze individual [Business Process](create-business-process) actions effectively.\n\n> 🎯 Explore Action types\n> For detailed information about available action types, please refer to the [Action Catalog](acknowledgement-action) section.\n", "security": [ { "bearerToken": [ "business_processes:read" ] } ], "parameters": [ { "name": "account-id", "in": "path", "description": "The unique identifier (AVID) of the [Account](account).", "schema": { "type": "string" }, "required": true }, { "name": "ref", "in": "path", "description": "The [Account's](account) (Merchant's) unique reference for the [Customer](customers).", "schema": { "type": "string" }, "required": true }, { "name": "business-process-id", "in": "path", "description": "The unique identifier of the [Business Process](create-business-process).", "schema": { "type": "string" }, "required": true }, { "name": "action-id", "in": "path", "description": "The unique identifier of the [Business Process](create-business-process) action to retrieve details.", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Successfully retrieved business process action. Returns the complete action details including context, features, and state.", "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://authvia.com/action", "$comment": "Last updated 2024-08-08T17:57:46.877Z", "description": "Schema for representing an action.", "type": "object", "properties": { "id": { "$id": "#/properties/id", "type": "string", "description": "The unique identifier of the action.", "examples": [ "00000000-0000-0000-0000-000000000000" ] }, "partner": { "$id": "#/properties/partner", "type": "string", "description": "The unique identifier of the partner account.", "examples": [ "PARTNER_REFERENCE" ] }, "merchant": { "$id": "#/properties/merchant", "type": "string", "description": "The unique identifier (AVID) of the merchant's account associated with the action.", "examples": [ "AVID0000-0000-0000-0000-000000000000" ] }, "customer": { "$id": "#/properties/customer", "type": "string", "description": "The unique identifier of the customer within the [account](account)(merchant).", "examples": [ "CUSTOMER_REFERENCE" ] }, "businessProcess": { "$id": "#/properties/businessProcess", "type": "string", "description": "The unique identifier of the business process associated with the action.", "examples": [ "00000000-0000-0000-0000-000000000000" ] }, "type": { "type": "string", "enum": [ "acknowledgement", "approval", "authentic-id", "choice", "convenience-fee", "customer-update", "instructions", "payment", "payment-method", "payment-amount-selection", "service-fee", "signature", "surcharge", "payout", "simple-value", "value-verification", "markdown", "metadata", "reminder", "tip", "line-items", "line-item-customization", "request-attachment", "upload-attachment", "threat-matrix" ], "examples": [ "payout" ], "description": "Specifies the type of business process action to be performed. Each action type represents a distinct step or operation within the business process, such as a payment or capture payment-method step." }, "status": { "$id": "#/properties/status", "type": "string", "enum": [ "in-progress", "failed", "resolved" ], "description": "The current status of the action.", "examples": [ "in-progress" ] }, "blueprint": { "$id": "#/properties/blueprint", "type": "string", "description": "The unique identifier of the blueprint used to create the business process associated with this action. This field is present only if the business process associated with this action was created using a [blueprint](create-blueprint).", "examples": [ "00000000-0000-0000-0000-000000000000" ] }, "updatedOn": { "$id": "#/properties/updatedOn", "type": "string", "description": "The date of the latest update to the action, in ISO date-time format.", "examples": [ "1970-01-01T00:00:00Z" ] }, "completedOn": { "$id": "#/properties/completedOn", "type": "string", "description": "The completion date of the action, in ISO date-time format.", "examples": [ "1970-01-01T00:00:00Z" ] }, "order": { "$id": "#/properties/order", "type": "number", "description": "The order of the action within the business process, showing its sequence in the list of actions.", "examples": [ 0 ] }, "union": { "$id": "#/properties/union", "type": "number", "description": "Defines the relationship of this action with another action in terms of [union](business-processes-union). This field is used to link related actions within the business process.", "examples": [ 0 ] }, "context": { "$id": "#/properties/context", "type": "object", "description": "Provides additional contextual information relevant to the action. This can include any data or parameters that are necessary for executing the action within the given context. for more details on specific action context, refer to context section in action catalog, ex. [approval-action](approval-action#context).", "examples": [ { "key": "value" } ] }, "features": { "$id": "#/properties/features", "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": [ "string", "number", "boolean" ] } }, { "type": "object" } ] }, "examples": [ { "type": "payment", "union": 0, "group": 0 } ], "description": "Specifies additional features or attributes of the action. This field may include both required and optional settings or configurations that further detail how the action should be executed. for more details on specific action features, refer to features section in action catalog, ex. [acknowledgement-action](acknowledgement-action#features-required)." }, "state": { "$id": "#/properties/state", "type": "object", "description": "The state of the action, holding data that varies based on the action's status. Actions in-progress, resolved or failed actions may contain different information in their state. This property may not be fully populated and its data can change until the action is resolved or failed. for more details on specific action state, refer to state section in action catalog, ex. [acknowledgement-action](acknowledgement-action#state).", "examples": [ { "key": "value" } ] } }, "required": [ "id", "businessProcess", "customer", "merchant", "partner", "type", "status", "context", "features", "state", "order" ] }, "examples": { "successfulResponse": { "value": { "id": "00000000-0000-0000-0000-000000000000", "order": 1, "partner": "PARTNER_REFERENCE", "merchant": "AVID0000-0000-0000-0000-000000000000", "customer": "CUSTOMER_REFERENCE", "businessProcess": "00000000-0000-0000-0000-000000000000", "status": "in-progress", "type": "payment", "updatedOn": "1970-01-01T00:00:00Z", "context": { "amount": 0, "expirationMode": "none", "resolutionMode": "amount-due", "metadata": { "foo": "bar" } }, "features": { "reference": "zoom", "description": "Rocket Powered Roller Skates" }, "state": {} } } } } } }, "400": { "description": "Bad Request - The request cannot be processed due to a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).", "content": { "application/json": { "examples": { "badRequestExample": { "summary": "Bad Request example", "value": { "path": "/v3/merchants/a530d3e3-151a-47d6-ad60-f9009bb686b9/customers/Customer_5079772987930815", "action": "PATCH", "errors": [ { "attribute": "email", "message": "Invalid email format", "data": { "value": [ { "type": "string", "value": "test@test" } ], "type": "object" } } ] } } }, "schema": { "title": "400 Bad Request Response", "type": "object", "required": [ "path", "action", "errors" ], "properties": { "path": { "type": "string", "description": "The API path where the bad request occurred.", "example": "/v3/merchants/a530d3e3-151a-47d6-ad60-f9009bb686b9/customers/Customer_5079772987930815" }, "action": { "type": "string", "description": "The HTTP method (e.g., GET, POST, PATCH) associated with the bad request.", "example": "PATCH" }, "errors": { "type": "array", "description": "A list of error details indicating why the request was considered a bad request.", "items": { "type": "object", "required": [ "attribute", "message", "data" ], "properties": { "attribute": { "type": "string", "description": "The JSON pointer to the field in the request that caused the bad request.", "example": "addresses.0/value" }, "message": { "type": "string", "description": "A human-readable message explaining why the request was bad.", "example": "Invalid email" }, "data": { "type": "object", "required": [ "value", "type" ], "properties": { "value": { "type": "array", "items": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "description": "The expected data type of the field that was violated.", "example": "email" }, "value": { "type": "string", "description": "The invalid value that was provided in the request.", "example": "test@test.com" } } } }, "type": { "type": "string", "description": "The data structure type that contains the validation error.", "example": "object" } } } } } } } } } } }, "401": { "description": "The request is valid, but server authentication failed to verify the identity. The user's access token has either expired or is not valid. Creating a new token might resolve the issue.", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"message\": \"Unauthorized\"\n}" } }, "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Unauthorized" } } } } } }, "403": { "description": "The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort. This status is similar to 401, but in this case, re-authenticating will make no difference. The access is permanently forbidden and tied to the application logic, such as insufficient rights to a resource.", "content": { "application/json": { "examples": { "UnauthorizedAccess": { "summary": "Unauthorized Access Example", "value": { "message": "User is not authorized to access this resource" } } }, "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "User is not authorized to access this resource" } } } } } }, "404": { "description": "The requested resource was not found. This response indicates that the server can't find the requested resource. In the context of an API, this can mean that the endpoint is valid but the resource itself does not exist. For developers, this typically means that the URL or its content (such as specific ID) does not exist. Check the URL and the resource identifier.", "content": { "application/json": { "examples": { "EmptyResponse": { "summary": "Empty or Undefined Response", "value": {} } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false } } }, "webhooks": { "transactions.create": { "post": { "tags": [ "Webhook Types Customer" ], "summary": "Transaction Created", "operationId": "transaction-created-webhook", "description": "> 📬 Your system will receive this payload when you create a [Subscription](webhook-subscriptions) with type `transactions.create`\n\nReceive real-time notifications when new [Transactions](transactions) are created in your [Account](account). This webhook enables you to synchronize your systems with transaction creation events.\n\n> 📘 Info\n> \n> The webhook payload contains the transaction ID and basic details. Use the [Get Transaction](get-transaction) endpoint to retrieve complete transaction information.\n\n> ⚠️ Warning\n> \n> Your webhook endpoint must return a 2xx status code within 30 seconds to confirm receipt. Failed deliveries will be retried according to the [redrive policy](subscriptions-redrive).\n\nCommon use cases include updating your accounting system, triggering notifications, or logging transaction events in your analytics platform.", "security": [ { "bearerToken": [ "transactions:read", "subscriptions:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://authvia.com/webhook/transaction", "$comment": "Last updated 2024-03-22T17:57:46.877Z", "description": "Schema for representing transaction details.", "type": "object", "properties": { "id": { "$id": "#/properties/id", "type": "string", "description": "The unique identifier for the transaction." }, "conversationId": { "$id": "#/properties/conversationId", "type": "string", "description": "The unique identifier of the conversation associated with the transaction." }, "description": { "$id": "#/properties/description", "type": "string", "description": "A description of the transaction." }, "action": { "$id": "#/properties/action", "type": "string", "enum": [ "CHARGE", "REVERSAL", "PAYOUT", "AUTHORIZE", "CAPTURE", "VOID", "REFUND" ], "description": "The type of action associated with the transaction.", "examples": [ "CHARGE" ] }, "merchantId": { "$id": "#/properties/merchantId", "type": "string", "description": "The unique identifier of the merchant associated with the transaction." }, "partnerId": { "$id": "#/properties/partnerId", "type": "string", "description": "The unique identifier of the partner associated with the transaction." }, "amount": { "$id": "#/properties/amount", "type": "number", "description": "The amount of the transaction in cents.", "examples": [ 100.5 ] }, "paymentMethod": { "$id": "#/definitions/PaymentMethod", "type": "object", "properties": { "id": { "$id": "#/definitions/paymentMethod/properties/id", "type": "string", "description": "The unique identifier of the payment method associated with the transaction." }, "type": { "$id": "#/definitions/paymentMethod/properties/type", "type": "string", "enum": [ "ach", "creditCard", "token" ], "description": "The type of payment method associated with the transaction.", "examples": [ "creditCard" ] }, "identifier": { "$id": "#/definitions/paymentMethod/properties/identifier", "type": "string", "description": "The identifier of the payment method associated with the transaction." } } }, "status": { "$id": "#/properties/status", "type": "string", "enum": [ "AUTHORIZED", "DECLINED", "ERROR", "FAILED", "NOT AUTHORIZED", "PAYMENT-IN-PROGRESS", "PROCESSING" ], "description": "The status of the transaction.", "examples": [ "AUTHORIZED" ] }, "onStatus": { "$id": "#/properties/onStatus", "type": "object", "description": "Details about the transaction status." }, "references": { "$id": "#/properties/references", "type": "object", "properties": { "customer": { "$id": "#/properties/references/properties/customer", "type": "string", "description": "Reference to the customer associated with the transaction." }, "external": { "$id": "#/properties/references/properties/external", "type": "string", "description": "External reference associated with the transaction." }, "gateway": { "$id": "#/properties/references/properties/gateway", "type": "string", "description": "Gateway reference associated with the transaction." }, "authorization": { "$id": "#/properties/references/properties/authorization", "type": "string", "description": "Authorization reference associated with the transaction." }, "authorization_id": { "$id": "#/properties/references/properties/authorization_id", "type": "string", "description": "Authorization identifier associated with the transaction." }, "parent_authorization_id": { "$id": "#/properties/references/properties/parent_authorization_id", "type": "string", "description": "Parent authorization identifier associated with the transaction." }, "parent_gateway": { "$id": "#/properties/references/properties/parent_gateway", "type": "string", "description": "Parent gateway associated with the transaction." }, "parent_capture_id": { "$id": "#/properties/references/properties/parent_capture_id", "type": "string", "description": "Parent capture identifier associated with the transaction." }, "parent_transaction": { "$id": "#/properties/references/properties/parent_transaction", "type": "object", "properties": { "id": { "$id": "#/properties/references/properties/parent_transaction/properties/id", "type": "string", "description": "Parent transaction identifier associated with the transaction." } } } } }, "adjustments": { "$id": "#/properties/adjustments", "type": "array", "items": { "$id": "#/properties/adjustments/items", "type": "object", "properties": { "type": { "$id": "#/properties/adjustments/items/properties/type", "enum": [ "service", "convenience", "surcharge", "tip" ], "description": "Type of adjustment applied to the transaction.", "examples": [ "service" ] }, "amount": { "$id": "#/properties/adjustments/items/properties/amount", "type": [ "number", "string" ], "description": "Amount of adjustment applied to the transaction.", "examples": [ 10.5 ] } }, "required": [ "type", "amount" ] } }, "error": { "$id": "#/properties/error", "description": "Details about any error occurred during the transaction." }, "metadata": { "$id": "#/properties/metadata", "type": "object", "description": "Additional metadata associated with the transaction." }, "product": { "$id": "#/properties/product", "type": "string", "description": "The product associated with the transaction." } }, "required": [ "id", "action", "merchantId", "partnerId", "amount", "paymentMethod", "status", "steps", "references", "adjustments" ], "definitions": { "PaymentMethod": { "$id": "#/definitions/PaymentMethod", "type": "object", "properties": { "id": { "$id": "#/definitions/paymentMethod/properties/id", "type": "string", "description": "The unique identifier of the payment method associated with the transaction." }, "type": { "$id": "#/definitions/paymentMethod/properties/type", "type": "string", "enum": [ "ach", "creditCard", "token" ], "description": "The type of payment method associated with the transaction.", "examples": [ "creditCard" ] }, "identifier": { "$id": "#/definitions/paymentMethod/properties/identifier", "type": "string", "description": "The identifier of the payment method associated with the transaction." } } } } }, "examples": { "TransactionCreated": { "summary": "Transaction Created", "value": { "id": "00000000-0000-0000-0000-000000000000", "merchantId": "AVID0000-0000-0000-0000-000000000000", "partnerId": "PARTNER0000-0000-0000-0000-000000000000", "references": { "customer": "CUSTOMER_REFERENCE", "external": "ext_ref_123" }, "action": "CHARGE", "amount": 10000, "currency": "USD", "status": "PROCESSING", "createdOn": "2024-01-01T00:00:00Z", "steps": [], "adjustments": [], "paymentMethod": { "id": "00000000-0000-0000-0000-000000000000" } } } } } } }, "responses": { "200": { "description": "> Your system should return a 2xx status to indicate that the data was published successfully. Other statuses will be considered a failure and we will retry later. See the [redrive](subscriptions-redrive) page for more details." } } } }, "transactions.update": { "post": { "tags": [ "Webhook Types Customer" ], "summary": "Transaction Updated", "operationId": "transactions-updated-webhook", "description": "> 📬 Your system will receive this payload when you create a [Subscription](webhook-subscriptions) with type `transactions.update`\n\nReceive real-time notifications when [Transactions](transactions) are updated in your [Account](account). This webhook enables you to synchronize your systems with transaction status changes.\n\n> 📘 Info\n> \n> The webhook payload contains the transaction ID and updated details. Use the [Get Transaction](transactions) endpoint to retrieve complete transaction information.\n\n> ⚠️ Warning\n> \n> Your webhook endpoint must return a 2xx status code within 30 seconds to confirm receipt. Failed deliveries will be retried according to the [redrive policy](subscriptions-redrive).\n\nCommon use cases include updating your accounting system, triggering notifications, or logging transaction status changes in your analytics platform.", "security": [ { "bearerToken": [ "transactions:read", "subscriptions:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://authvia.com/webhook/transaction", "$comment": "Last updated 2024-03-22T17:57:46.877Z", "description": "Schema for representing transaction details.", "type": "object", "properties": { "id": { "$id": "#/properties/id", "type": "string", "description": "The unique identifier for the transaction." }, "conversationId": { "$id": "#/properties/conversationId", "type": "string", "description": "The unique identifier of the conversation associated with the transaction." }, "description": { "$id": "#/properties/description", "type": "string", "description": "A description of the transaction." }, "action": { "$id": "#/properties/action", "type": "string", "enum": [ "CHARGE", "REVERSAL", "PAYOUT", "AUTHORIZE", "CAPTURE", "VOID", "REFUND" ], "description": "The type of action associated with the transaction.", "examples": [ "CHARGE" ] }, "merchantId": { "$id": "#/properties/merchantId", "type": "string", "description": "The unique identifier of the merchant associated with the transaction." }, "partnerId": { "$id": "#/properties/partnerId", "type": "string", "description": "The unique identifier of the partner associated with the transaction." }, "amount": { "$id": "#/properties/amount", "type": "number", "description": "The amount of the transaction in cents.", "examples": [ 100.5 ] }, "paymentMethod": { "$id": "#/definitions/PaymentMethod", "type": "object", "properties": { "id": { "$id": "#/definitions/paymentMethod/properties/id", "type": "string", "description": "The unique identifier of the payment method associated with the transaction." }, "type": { "$id": "#/definitions/paymentMethod/properties/type", "type": "string", "enum": [ "ach", "creditCard", "token" ], "description": "The type of payment method associated with the transaction.", "examples": [ "creditCard" ] }, "identifier": { "$id": "#/definitions/paymentMethod/properties/identifier", "type": "string", "description": "The identifier of the payment method associated with the transaction." } } }, "status": { "$id": "#/properties/status", "type": "string", "enum": [ "AUTHORIZED", "DECLINED", "ERROR", "FAILED", "NOT AUTHORIZED", "PAYMENT-IN-PROGRESS", "PROCESSING" ], "description": "The status of the transaction.", "examples": [ "AUTHORIZED" ] }, "onStatus": { "$id": "#/properties/onStatus", "type": "object", "description": "Details about the transaction status." }, "references": { "$id": "#/properties/references", "type": "object", "properties": { "customer": { "$id": "#/properties/references/properties/customer", "type": "string", "description": "Reference to the customer associated with the transaction." }, "external": { "$id": "#/properties/references/properties/external", "type": "string", "description": "External reference associated with the transaction." }, "gateway": { "$id": "#/properties/references/properties/gateway", "type": "string", "description": "Gateway reference associated with the transaction." }, "authorization": { "$id": "#/properties/references/properties/authorization", "type": "string", "description": "Authorization reference associated with the transaction." }, "authorization_id": { "$id": "#/properties/references/properties/authorization_id", "type": "string", "description": "Authorization identifier associated with the transaction." }, "parent_authorization_id": { "$id": "#/properties/references/properties/parent_authorization_id", "type": "string", "description": "Parent authorization identifier associated with the transaction." }, "parent_gateway": { "$id": "#/properties/references/properties/parent_gateway", "type": "string", "description": "Parent gateway associated with the transaction." }, "parent_capture_id": { "$id": "#/properties/references/properties/parent_capture_id", "type": "string", "description": "Parent capture identifier associated with the transaction." }, "parent_transaction": { "$id": "#/properties/references/properties/parent_transaction", "type": "object", "properties": { "id": { "$id": "#/properties/references/properties/parent_transaction/properties/id", "type": "string", "description": "Parent transaction identifier associated with the transaction." } } } } }, "adjustments": { "$id": "#/properties/adjustments", "type": "array", "items": { "$id": "#/properties/adjustments/items", "type": "object", "properties": { "type": { "$id": "#/properties/adjustments/items/properties/type", "enum": [ "service", "convenience", "surcharge", "tip" ], "description": "Type of adjustment applied to the transaction.", "examples": [ "service" ] }, "amount": { "$id": "#/properties/adjustments/items/properties/amount", "type": [ "number", "string" ], "description": "Amount of adjustment applied to the transaction.", "examples": [ 10.5 ] } }, "required": [ "type", "amount" ] } }, "error": { "$id": "#/properties/error", "description": "Details about any error occurred during the transaction." }, "metadata": { "$id": "#/properties/metadata", "type": "object", "description": "Additional metadata associated with the transaction." }, "product": { "$id": "#/properties/product", "type": "string", "description": "The product associated with the transaction." } }, "required": [ "id", "action", "merchantId", "partnerId", "amount", "paymentMethod", "status", "steps", "references", "adjustments" ], "definitions": { "PaymentMethod": { "$id": "#/definitions/PaymentMethod", "type": "object", "properties": { "id": { "$id": "#/definitions/paymentMethod/properties/id", "type": "string", "description": "The unique identifier of the payment method associated with the transaction." }, "type": { "$id": "#/definitions/paymentMethod/properties/type", "type": "string", "enum": [ "ach", "creditCard", "token" ], "description": "The type of payment method associated with the transaction.", "examples": [ "creditCard" ] }, "identifier": { "$id": "#/definitions/paymentMethod/properties/identifier", "type": "string", "description": "The identifier of the payment method associated with the transaction." } } } } }, "examples": { "TransactionUpdated": { "summary": "Transaction Updated", "value": { "id": "00000000-0000-0000-0000-000000000000", "merchantId": "AVID0000-0000-0000-0000-000000000000", "references": { "customer": "CUSTOMER_REFERENCE", "external": "ext_ref_123" }, "action": "CHARGE", "amount": 10000, "currency": "USD", "status": "CHARGED", "steps": [], "adjustments": [], "updatedOn": "2024-01-01T00:00:00Z" } } } } } }, "responses": { "200": { "description": "> Your system should return a 2xx status to indicate that the data was published successfully. Other statuses will be considered a failure and we will retry later. See the [redrive](subscriptions-redrive) page for more details." } } } }, "payment_methods.create": { "post": { "tags": [ "Webhook Types Customer" ], "summary": "Payment Method Created", "operationId": "payment-method-create-webhook", "description": "> 📬 Your system will receive this payload when you create a [Subscription](webhook-subscriptions) with type `payment_method.create`\n\nReceive real-time notifications when new [Payment Methods](payment-methods) are created in your [Account](account). This webhook enables you to synchronize your systems with payment method creation events.\n\n> 📘 Info\n> \n> The webhook payload contains the payment method ID and basic details. Use the [Get Payment Method](get-payment-method) endpoint to retrieve complete payment method information.\n\n> ⚠️ Warning\n> \n> Your webhook endpoint must return a 2xx status code within 30 seconds to confirm receipt. Failed deliveries will be retried according to the [redrive policy](subscriptions-redrive).\n\nCommon use cases include updating your payment processing system, triggering notifications, or logging payment method events in your analytics platform.", "security": [ { "bearerToken": [ "payment_methods:read", "subscriptions:create" ] } ], "requestBody": { "content": { "application/json": { "examples": { "PaymentMethodCreated": { "summary": "Payment Method Created", "value": { "id": "00000000-0000-0000-0000-000000000000", "merchantId": "AVID0000-0000-0000-0000-000000000000", "customerRef": "CUSTOMER_REFERENCE", "createdOn": "2024-01-01T00:00:00Z" } } } } } }, "responses": { "200": { "description": "> Your system should return a 2xx status to indicate that the data was published successfully. Other statuses will be considered a failure and we will retry later. See the [redrive](subscriptions-redrive) page for more details." } } } }, "payment_methods.update": { "post": { "tags": [ "Webhook Types Customer" ], "summary": "Payment Method Updated", "operationId": "payment-method-updated-webhook", "description": "> 📬 Your system will receive this payload when you create a [Subscription](webhook-subscriptions) with type `payment_method.updated`\n\nReceive real-time notifications when [Payment Methods](payment-methods) are updated in your [Account](account). This webhook enables you to synchronize your systems with payment method modification events.\n\n> 📘 Info\n> \n> The webhook payload contains the payment method ID and updated details. Use the [Get Payment Method](get-payment-method) endpoint to retrieve complete payment method information.\n\n> ⚠️ Warning\n> \n> Your webhook endpoint must return a 2xx status code within 30 seconds to confirm receipt. Failed deliveries will be retried according to the [redrive policy](subscriptions-redrive).\n\nCommon use cases include updating your payment processing system, triggering notifications, or logging payment method changes in your analytics platform.", "security": [ { "bearerToken": [ "payment_methods:read", "subscriptions:create" ] } ], "requestBody": { "content": { "application/json": { "examples": { "PaymentMethodUpdated": { "summary": "Payment Method Updated", "value": { "id": "00000000-0000-0000-0000-000000000000", "merchantId": "AVID0000-0000-0000-0000-000000000000", "customerRef": "CUSTOMER_REFERENCE", "updatedOn": "2024-01-01T00:00:00Z" } } } } } }, "responses": { "200": { "description": "> Your system should return a 2xx status to indicate that the data was published successfully. Other statuses will be considered a failure and we will retry later. See the [redrive](subscriptions-redrive) page for more details." } } } }, "business_processes.create": { "post": { "tags": [ "Webhook Types Customer" ], "summary": "Business Process Created", "operationId": "business-process-created-webhook", "description": "> 📬 Your system will receive this payload when you create a [Subscription](webhook-subscriptions) with type `business_processes.create`\n\nReceive real-time notifications when new [Business Processes](business-processes) are created in your [Account](account). This webhook enables you to synchronize your systems with business process events, such as when new workflows are initiated.\n\n> 📘 Info\n> \n> The webhook payload contains the business process ID and basic details. Use the [Get Business Process](get-business-process) endpoint to retrieve complete information.\n\n> ⚠️ Warning\n> \n> Your webhook endpoint must return a 2xx status code within 30 seconds to confirm receipt. Failed deliveries will be retried according to the [redrive policy](subscriptions-redrive).\n\nCommon use cases include updating your workflow management system, triggering notifications, or logging business process events in your analytics platform.", "security": [ { "bearerToken": [ "business_processes:read", "subscriptions:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://authvia.com/webhook/business-process", "$comment": "Last updated 2024-07-16T00:00:00Z", "description": "Schema for representing a business process.", "type": "object", "properties": { "id": { "$id": "#/properties/id", "type": "string", "description": "The unique identifier v4 id of the business process.", "examples": [ "00000000-0000-0000-0000-000000000000" ] }, "blueprint": { "$id": "#/properties/blueprint", "type": "string", "description": "The blueprint's slugified unique identifier name within an [account](account) (merchant).", "examples": [ "counter-bills", "valet-parking", "authvia-2026" ] }, "partner": { "$id": "#/properties/partner", "type": "string", "description": "The unique identifier of the partner account.", "examples": [ "PARTNER_REFERENCE" ] }, "merchant": { "$id": "#/properties/merchant", "type": "string", "description": "The unique identifier (AVID) of the merchant's account associated with the business process.", "examples": [ "AVID0000-0000-0000-0000-000000000000" ] }, "customer": { "$id": "#/properties/customer", "type": "string", "description": "The unique identifier of the customer within the [account](account)(merchant).", "examples": [ "CUSTOMER_REFERENCE" ] }, "status": { "$id": "#/properties/status", "type": "string", "enum": [ "in-progress", "resolved", "failed", "scheduled" ], "description": "The current status of the business process.", "examples": [ "in-progress" ] }, "statusReason": { "$id": "#/properties/statusReason", "type": "string", "enum": [ "by-merchant", "by-user", "expired" ], "description": "The reason for the current status of the business process.", "examples": [ "by-merchant" ] }, "expiration": { "$id": "#/properties/expiration", "type": "string", "description": "The expiration date of the business process, in ISO date-time format. When the expiration occurs, the status of the business process is set to `failed` and the statusReason is updated to `expired`.", "examples": [ "1970-01-01T00:00:00Z" ] }, "version": { "$id": "#/properties/version", "type": "number", "description": "The version of the business process.", "examples": [ 0 ] }, "agentOf": { "$id": "#/properties/agentOf", "type": "string", "description": "The agent address associated with the business process.", "examples": [ "+1123456789" ] }, "createdOn": { "$id": "#/properties/createdOn", "type": "string", "description": "The date when the business process was closed.", "examples": [ "1970-01-01T00:00:00.000Z" ] }, "actions": { "$id": "#/properties/actions", "type": "array", "items": { "$id": "#/properties/actions/items", "type": "object", "properties": { "id": { "$id": "#/properties/id", "type": "string", "description": "The unique identifier of the action.", "examples": [ "00000000-0000-0000-0000-000000000000" ] }, "type": { "type": "string", "enum": [ "acknowledgement", "approval", "authentic-id", "choice", "convenience-fee", "customer-update", "instructions", "payment", "payment-method", "payment-amount-selection", "service-fee", "signature", "surcharge", "payout", "simple-value", "value-verification", "markdown", "metadata", "reminder", "tip", "line-items", "line-item-customization", "request-attachment", "upload-attachment", "threat-matrix" ], "examples": [ "payout" ], "description": "Specifies the type of business process action to be performed. Each action type represents a distinct step or operation within the business process, such as a payment or capture payment-method step." } }, "required": [ "id", "type" ] }, "description": "A list of business process actions which represents a distinct steps within the business process. for more details please review [actions](actions) page and [action-catalog][acknowledgement-action] section." }, "addresses": { "$id": "#/properties/addresses", "type": "array", "items": { "$id": "#/properties/addresses/items", "type": "object", "properties": { "value": { "$id": "#/properties/addresses/items/properties/value", "type": "string", "description": "The value of the address.", "examples": [ "+11234567890" ] }, "type": { "$id": "#/properties/addresses/items/properties/type", "type": "string", "description": "The type of the address.", "examples": [ "phone" ] }, "subType": { "$id": "#/properties/addresses/items/properties/subType", "type": "string", "description": "The sub-type of the address.", "examples": [ "mobile" ] } }, "required": [ "value", "type", "subType" ] }, "description": "Represents a collection of contact addresses associated with the customer. Each address object must adhere to specific formats,email or phone number." } }, "required": [ "id", "customer", "merchant", "partner", "actions", "addresses", "status", "expiration" ] }, "examples": { "BusinessProcessCreated": { "summary": "Business Process Created", "value": { "id": "00000000-0000-0000-0000-000000000000", "merchantId": "AVID0000-0000-0000-0000-000000000000", "customerRef": "CUSTOMER_REFERENCE", "status": "in-progress", "createdOn": "2024-01-01T00:00:00Z" } } } } } }, "responses": { "200": { "description": "> Your system should return a 2xx status to indicate that the data was published successfully. Other statuses will be considered a failure and we will retry later. See the [redrive](subscriptions-redrive) page for more details." } } } }, "business_processes.update": { "post": { "tags": [ "Webhook Types Customer" ], "summary": "Business Process Updated", "operationId": "business-process-updated-webhook", "description": "> 📬 Your system will receive this payload when you create a [Subscription](webhook-subscriptions) with type `business_processes.update`\n\nReceive real-time notifications when [Business Processes](business-processes) are updated in your [Account](account). This webhook enables you to synchronize your systems with business process status changes, such as when workflows complete or fail.\n\n> 📘 Info\n> \n> The webhook payload contains the business process ID and updated details. Use the [Get Business Process](get-business-process) endpoint to retrieve complete information.\n\n> ⚠️ Warning\n> \n> Your webhook endpoint must return a 2xx status code within 30 seconds to confirm receipt. Failed deliveries will be retried according to the [redrive policy](subscriptions-redrive).\n\nCommon use cases include updating your workflow management system, triggering notifications, or logging business process status changes in your analytics platform.", "security": [ { "bearerToken": [ "business_processes:read", "subscriptions:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://authvia.com/webhook/business-process", "$comment": "Last updated 2024-07-16T00:00:00Z", "description": "Schema for representing a business process.", "type": "object", "properties": { "id": { "$id": "#/properties/id", "type": "string", "description": "The unique identifier v4 id of the business process.", "examples": [ "00000000-0000-0000-0000-000000000000" ] }, "blueprint": { "$id": "#/properties/blueprint", "type": "string", "description": "The blueprint's slugified unique identifier name within an [account](account) (merchant).", "examples": [ "counter-bills", "valet-parking", "authvia-2026" ] }, "partner": { "$id": "#/properties/partner", "type": "string", "description": "The unique identifier of the partner account.", "examples": [ "PARTNER_REFERENCE" ] }, "merchant": { "$id": "#/properties/merchant", "type": "string", "description": "The unique identifier (AVID) of the merchant's account associated with the business process.", "examples": [ "AVID0000-0000-0000-0000-000000000000" ] }, "customer": { "$id": "#/properties/customer", "type": "string", "description": "The unique identifier of the customer within the [account](account)(merchant).", "examples": [ "CUSTOMER_REFERENCE" ] }, "status": { "$id": "#/properties/status", "type": "string", "enum": [ "in-progress", "resolved", "failed", "scheduled" ], "description": "The current status of the business process.", "examples": [ "in-progress" ] }, "statusReason": { "$id": "#/properties/statusReason", "type": "string", "enum": [ "by-merchant", "by-user", "expired" ], "description": "The reason for the current status of the business process.", "examples": [ "by-merchant" ] }, "expiration": { "$id": "#/properties/expiration", "type": "string", "description": "The expiration date of the business process, in ISO date-time format. When the expiration occurs, the status of the business process is set to `failed` and the statusReason is updated to `expired`.", "examples": [ "1970-01-01T00:00:00Z" ] }, "version": { "$id": "#/properties/version", "type": "number", "description": "The version of the business process.", "examples": [ 0 ] }, "agentOf": { "$id": "#/properties/agentOf", "type": "string", "description": "The agent address associated with the business process.", "examples": [ "+1123456789" ] }, "createdOn": { "$id": "#/properties/createdOn", "type": "string", "description": "The date when the business process was closed.", "examples": [ "1970-01-01T00:00:00.000Z" ] }, "actions": { "$id": "#/properties/actions", "type": "array", "items": { "$id": "#/properties/actions/items", "type": "object", "properties": { "id": { "$id": "#/properties/id", "type": "string", "description": "The unique identifier of the action.", "examples": [ "00000000-0000-0000-0000-000000000000" ] }, "type": { "type": "string", "enum": [ "acknowledgement", "approval", "authentic-id", "choice", "convenience-fee", "customer-update", "instructions", "payment", "payment-method", "payment-amount-selection", "service-fee", "signature", "surcharge", "payout", "simple-value", "value-verification", "markdown", "metadata", "reminder", "tip", "line-items", "line-item-customization", "request-attachment", "upload-attachment", "threat-matrix" ], "examples": [ "payout" ], "description": "Specifies the type of business process action to be performed. Each action type represents a distinct step or operation within the business process, such as a payment or capture payment-method step." } }, "required": [ "id", "type" ] }, "description": "A list of business process actions which represents a distinct steps within the business process. for more details please review [actions](actions) page and [action-catalog][acknowledgement-action] section." }, "addresses": { "$id": "#/properties/addresses", "type": "array", "items": { "$id": "#/properties/addresses/items", "type": "object", "properties": { "value": { "$id": "#/properties/addresses/items/properties/value", "type": "string", "description": "The value of the address.", "examples": [ "+11234567890" ] }, "type": { "$id": "#/properties/addresses/items/properties/type", "type": "string", "description": "The type of the address.", "examples": [ "phone" ] }, "subType": { "$id": "#/properties/addresses/items/properties/subType", "type": "string", "description": "The sub-type of the address.", "examples": [ "mobile" ] } }, "required": [ "value", "type", "subType" ] }, "description": "Represents a collection of contact addresses associated with the customer. Each address object must adhere to specific formats,email or phone number." } }, "required": [ "id", "customer", "merchant", "partner", "actions", "addresses", "status", "expiration" ] }, "examples": { "BusinessProcessUpdated": { "summary": "Business Process Updated", "value": { "id": "00000000-0000-0000-0000-000000000000", "merchantId": "AVID0000-0000-0000-0000-000000000000", "customerRef": "CUSTOMER_REFERENCE", "status": "completed", "updatedOn": "2024-01-01T00:00:00Z" } } } } } }, "responses": { "200": { "description": "> Your system should return a 2xx status to indicate that the data was published successfully. Other statuses will be considered a failure and we will retry later. See the [redrive](subscriptions-redrive) page for more details." } } } }, "business_processes.actions.create": { "post": { "tags": [ "Webhook Types Customer" ], "summary": "Business Process Action Created", "operationId": "business-process-action-created-webhook", "description": "> 📬 Your system will receive this payload when you create a [Subscription](webhook-subscriptions) with type `business_processes_actions.create`\n\nReceive real-time notifications when new [Business Process Actions](business-process-actions) are created in your [Account](account). This webhook enables you to synchronize your systems with action events, such as when new steps are initiated in a workflow.\n\n> 📘 Info\n> \n> The webhook payload contains the action ID and basic details. Use the [Get Business Process Action](get-business-process-action) endpoint to retrieve complete information.\n\n> ⚠️ Warning\n> \n> Your webhook endpoint must return a 2xx status code within 30 seconds to confirm receipt. Failed deliveries will be retried according to the [redrive policy](subscriptions-redrive).\n\nCommon use cases include updating your workflow management system, triggering notifications, or logging action events in your analytics platform.", "security": [ { "bearerToken": [ "business_processes:read", "subscriptions:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://authvia.com/webhook/business-process-action", "$comment": "Last updated 2024-07-16T00:00:00Z", "description": "Schema for representing an item.", "type": "object", "properties": { "id": { "$id": "#/properties/id", "type": "string", "description": "The unique identifier of the action.", "examples": [ "00000000-0000-0000-0000-000000000000" ] }, "partner": { "$id": "#/properties/partner", "type": "string", "description": "The unique identifier of the partner account.", "examples": [ "PARTNER_REFERENCE" ] }, "merchant": { "$id": "#/properties/merchant", "type": "string", "description": "The unique identifier (AVID) of the merchant's account associated with the action.", "examples": [ "AVID0000-0000-0000-0000-000000000000" ] }, "businessProcess": { "$id": "#/properties/businessProcess", "type": "string", "description": "The unique identifier of the business process associated with the action.", "examples": [ "00000000-0000-0000-0000-000000000000" ] }, "customer": { "$id": "#/properties/customer", "type": "string", "description": "The unique identifier of the customer within the [account](account)(merchant).", "examples": [ "CUSTOMER_REFERENCE" ] }, "type": { "type": "string", "enum": [ "acknowledgement", "approval", "authentic-id", "choice", "convenience-fee", "customer-update", "instructions", "payment", "payment-method", "payment-amount-selection", "service-fee", "signature", "surcharge", "payout", "simple-value", "value-verification", "markdown", "metadata", "reminder", "tip", "line-items", "line-item-customization", "request-attachment", "upload-attachment", "threat-matrix" ], "examples": [ "payout" ], "description": "Specifies the type of business process action to be performed. Each action type represents a distinct step or operation within the business process, such as a payment or capture payment-method step." }, "status": { "$id": "#/properties/status", "type": "string", "enum": [ "in-progress", "failed", "resolved" ], "description": "The current status of the action.", "examples": [ "in-progress" ] }, "context": { "$id": "#/properties/context", "type": "object", "description": "Provides additional contextual information relevant to the action. This can include any data or parameters that are necessary for executing the action within the given context. for more details on specific action context, refer to context section in action catalog, ex. [approval-action](approval-action#context).", "examples": [ { "key": "value" } ] }, "features": { "$id": "#/properties/features", "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": [ "string", "number", "boolean" ] } }, { "type": "object" } ] }, "examples": [ { "type": "payment", "union": 0, "group": 0 } ], "description": "Specifies additional features or attributes of the action. This field may include both required and optional settings or configurations that further detail how the action should be executed. for more details on specific action features, refer to features section in action catalog, ex. [acknowledgement-action](acknowledgement-action#features-required)." }, "state": { "$id": "#/properties/state", "type": "object", "description": "The state of the action, holding data that varies based on the action's status. Actions in-progress, resolved or failed actions may contain different information in their state. This property may not be fully populated and its data can change until the action is resolved or failed. for more details on specific action state, refer to state section in action catalog, ex. [acknowledgement-action](acknowledgement-action#state).", "examples": [ { "key": "value" } ] } }, "required": [ "id", "businessProcess", "customer", "status", "merchant", "partner", "type", "context", "features", "state" ] }, "examples": { "BusinessProcessActionCreated": { "summary": "Business Process Action Created", "value": { "id": "00000000-0000-0000-0000-000000000000", "businessProcessId": "00000000-0000-0000-0000-000000000001", "type": "payment", "status": "pending", "createdOn": "2024-01-01T00:00:00Z" } } } } } }, "responses": { "200": { "description": "> Your system should return a 2xx status to indicate that the data was published successfully. Other statuses will be considered a failure and we will retry later. See the [redrive](subscriptions-redrive) page for more details." } } } }, "business_processes.actions.update": { "post": { "tags": [ "Webhook Types Customer" ], "summary": "Business Process Action Updated", "operationId": "business-process-action-updated-webhook", "description": "> 📬 Your system will receive this payload when you create a [Subscription](webhook-subscriptions) with type `business_processes_actions.update`\n\nReceive real-time notifications when [Business Process Actions](business-process-actions) are updated in your [Account](account). This webhook enables you to synchronize your systems with action status changes, such as when steps complete or fail.\n\n> 📘 Info\n> \n> The webhook payload contains the action ID and updated details. Use the [Get Business Process Action](get-business-process-action) endpoint to retrieve complete information.\n\n> ⚠️ Warning\n> \n> Your webhook endpoint must return a 2xx status code within 30 seconds to confirm receipt. Failed deliveries will be retried according to the [redrive policy](subscriptions-redrive).\n\nCommon use cases include updating your workflow management system, triggering notifications, or logging action status changes in your analytics platform.", "security": [ { "bearerToken": [ "business_processes:read", "subscriptions:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://authvia.com/webhook/business-process-action", "$comment": "Last updated 2024-07-16T00:00:00Z", "description": "Schema for representing an item.", "type": "object", "properties": { "id": { "$id": "#/properties/id", "type": "string", "description": "The unique identifier of the action.", "examples": [ "00000000-0000-0000-0000-000000000000" ] }, "partner": { "$id": "#/properties/partner", "type": "string", "description": "The unique identifier of the partner account.", "examples": [ "PARTNER_REFERENCE" ] }, "merchant": { "$id": "#/properties/merchant", "type": "string", "description": "The unique identifier (AVID) of the merchant's account associated with the action.", "examples": [ "AVID0000-0000-0000-0000-000000000000" ] }, "businessProcess": { "$id": "#/properties/businessProcess", "type": "string", "description": "The unique identifier of the business process associated with the action.", "examples": [ "00000000-0000-0000-0000-000000000000" ] }, "customer": { "$id": "#/properties/customer", "type": "string", "description": "The unique identifier of the customer within the [account](account)(merchant).", "examples": [ "CUSTOMER_REFERENCE" ] }, "type": { "type": "string", "enum": [ "acknowledgement", "approval", "authentic-id", "choice", "convenience-fee", "customer-update", "instructions", "payment", "payment-method", "payment-amount-selection", "service-fee", "signature", "surcharge", "payout", "simple-value", "value-verification", "markdown", "metadata", "reminder", "tip", "line-items", "line-item-customization", "request-attachment", "upload-attachment", "threat-matrix" ], "examples": [ "payout" ], "description": "Specifies the type of business process action to be performed. Each action type represents a distinct step or operation within the business process, such as a payment or capture payment-method step." }, "status": { "$id": "#/properties/status", "type": "string", "enum": [ "in-progress", "failed", "resolved" ], "description": "The current status of the action.", "examples": [ "in-progress" ] }, "context": { "$id": "#/properties/context", "type": "object", "description": "Provides additional contextual information relevant to the action. This can include any data or parameters that are necessary for executing the action within the given context. for more details on specific action context, refer to context section in action catalog, ex. [approval-action](approval-action#context).", "examples": [ { "key": "value" } ] }, "features": { "$id": "#/properties/features", "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": [ "string", "number", "boolean" ] } }, { "type": "object" } ] }, "examples": [ { "type": "payment", "union": 0, "group": 0 } ], "description": "Specifies additional features or attributes of the action. This field may include both required and optional settings or configurations that further detail how the action should be executed. for more details on specific action features, refer to features section in action catalog, ex. [acknowledgement-action](acknowledgement-action#features-required)." }, "state": { "$id": "#/properties/state", "type": "object", "description": "The state of the action, holding data that varies based on the action's status. Actions in-progress, resolved or failed actions may contain different information in their state. This property may not be fully populated and its data can change until the action is resolved or failed. for more details on specific action state, refer to state section in action catalog, ex. [acknowledgement-action](acknowledgement-action#state).", "examples": [ { "key": "value" } ] } }, "required": [ "id", "businessProcess", "customer", "status", "merchant", "partner", "type", "context", "features", "state" ] }, "examples": { "BusinessProcessActionUpdated": { "summary": "Business Process Action Updated", "value": { "id": "00000000-0000-0000-0000-000000000000", "businessProcessId": "00000000-0000-0000-0000-000000000001", "type": "payment", "status": "completed", "updatedOn": "2024-01-01T00:00:00Z" } } } } } }, "responses": { "200": { "description": "> Your system should return a 2xx status to indicate that the data was published successfully. Other statuses will be considered a failure and we will retry later. See the [redrive](subscriptions-redrive) page for more details." } } } }, "customers.create": { "post": { "tags": [ "Webhook Types Customer" ], "summary": "Customer Created", "operationId": "customers-create-webhook", "description": "> 📬 Your system will receive this payload when you create a [Subscription](webhook-subscriptions) with type `customers.create`\n\nReceive real-time notifications when new [Customers](customers) are created in your [Account](account). This webhook enables you to synchronize your systems with customer events, such as when customers sign up or are added through your application.\n\n> 📘 Info\n> \n> The webhook payload contains the customer reference and basic details. Use the [Get Customer](get-customer) endpoint to retrieve complete customer information.\n\n> ⚠️ Warning\n> \n> Your webhook endpoint must return a 2xx status code within 30 seconds to confirm receipt. Failed deliveries will be retried according to the [redrive policy](subscriptions-redrive).\n\nCommon use cases include updating your CRM system, triggering welcome emails, or logging customer events in your analytics platform.", "security": [ { "bearerToken": [ "customers:read", "subscriptions:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://authvia.com/webhook/customer-details", "$comment": "Last updated 2024-03-22T17:57:46.877Z", "description": "Schema for representing customer details.", "type": "object", "properties": { "ref": { "$id": "#/properties/ref", "type": "string", "description": "Ref serves as a unique identifier for customer within the (account)[account] (merchant).", "examples": [ "CUSTOMER_REFERENCE" ] }, "merchantId": { "$id": "#/properties/merchantId", "type": "string", "description": "The unique identifier (AVID) of the merchant's account.", "examples": [ "AVID0000-0000-0000-0000-000000000000" ] }, "metadata": { "$id": "#/properties/metadata", "type": "object", "description": "Add additional information associated with the customer like name, location etc. A special mention to the [customers/crm/authvia](customers-crm-authvia) product which can enable a signup form for customers to self sign up and/or add validation checking for each customer created.", "examples": [ { "name": "John Doe" } ] }, "appdata": { "$id": "#/properties/appdata", "type": "object", "description": "A merchant can add extra details for a customer, such as notes, references, secret etc, which are not visible to the customer. This attribute is only deliviered on webhook payloads and returned for API calls to load a customer record.", "examples": [ { "key1": "value1", "key2": "value2" } ] } } }, "examples": { "CustomerCreated": { "summary": "Customer Created", "value": { "ref": "CUSTOMER_REFERENCE", "merchantId": "AVID0000-0000-0000-0000-000000000000", "metadata": { "name": "John Doe" }, "appdata": {} } } } } } }, "responses": { "200": { "description": "> Your system should return a 2xx status to indicate that the data was published successfully. Other statuses will be considered a failure and we will retry later See the [redrive](subscriptions-redrive) page for more details." } } } }, "customers.update": { "post": { "tags": [ "Webhook Types Customer" ], "summary": "Customer Updated", "operationId": "customer-updated-webhook", "description": "> 📬 Your system will receive this payload when you create a [Subscription](webhook-subscriptions) with type `customers.update`\n\nReceive real-time notifications when [Customers](customers) are updated in your [Account](account). This webhook enables you to synchronize your systems with customer changes, such as when customer information is modified.\n\n> 📘 Info\n> \n> The webhook payload contains the customer reference and updated details. Use the [Get Customer](get-customer) endpoint to retrieve complete customer information.\n\n> ⚠️ Warning\n> \n> Your webhook endpoint must return a 2xx status code within 30 seconds to confirm receipt. Failed deliveries will be retried according to the [redrive policy](subscriptions-redrive).\n\nCommon use cases include updating your CRM system, triggering notifications, or logging customer changes in your analytics platform.", "security": [ { "bearerToken": [ "customers:read", "subscriptions:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://authvia.com/webhook/customer-details", "$comment": "Last updated 2024-03-22T17:57:46.877Z", "description": "Schema for representing customer details.", "type": "object", "properties": { "ref": { "$id": "#/properties/ref", "type": "string", "description": "Ref serves as a unique identifier for customer within the (account)[account] (merchant).", "examples": [ "CUSTOMER_REFERENCE" ] }, "merchantId": { "$id": "#/properties/merchantId", "type": "string", "description": "The unique identifier (AVID) of the merchant's account.", "examples": [ "AVID0000-0000-0000-0000-000000000000" ] }, "metadata": { "$id": "#/properties/metadata", "type": "object", "description": "Add additional information associated with the customer like name, location etc. A special mention to the [customers/crm/authvia](customers-crm-authvia) product which can enable a signup form for customers to self sign up and/or add validation checking for each customer created.", "examples": [ { "name": "John Doe" } ] }, "appdata": { "$id": "#/properties/appdata", "type": "object", "description": "A merchant can add extra details for a customer, such as notes, references, secret etc, which are not visible to the customer. This attribute is only deliviered on webhook payloads and returned for API calls to load a customer record.", "examples": [ { "key1": "value1", "key2": "value2" } ] } } }, "examples": { "CustomerUpdated": { "summary": "Customer Updated", "value": { "ref": "CUSTOMER_REFERENCE", "merchantId": "AVID0000-0000-0000-0000-000000000000", "metadata": { "name": "John Doe", "email": "john.doe@example.com" }, "appdata": {} } } } } } }, "responses": { "200": { "description": "> Your system should return a 2xx status to indicate that the data was published successfully. Other statuses will be considered a failure and we will retry later. See the [redrive](subscriptions-redrive) page for more details." } } } }, "customers.delete": { "post": { "tags": [ "Webhook Types Customer" ], "summary": "Customer Deleted", "operationId": "customer-deleted-webhook", "description": "> 📬 Your system will receive this payload when you create a [Subscription](webhook-subscriptions) with type `customers.delete`\n\nReceive real-time notifications when [Customers](customers) are deleted from your [Account](account). This webhook enables you to synchronize your systems with customer removal events.\n\n> 📘 Info\n> \n> The webhook payload contains the customer reference and deletion details. Note that the customer data may no longer be accessible through the API.\n\n> ⚠️ Warning\n> \n> Your webhook endpoint must return a 2xx status code within 30 seconds to confirm receipt. Failed deliveries will be retried according to the [redrive policy](subscriptions-redrive).\n\nCommon use cases include updating your CRM system, triggering cleanup processes, or logging customer deletion events in your analytics platform.", "security": [ { "bearerToken": [ "customers:read", "subscriptions:create" ] } ], "requestBody": { "content": { "application/json": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://authvia.com/webhook/customer-details", "$comment": "Last updated 2024-03-22T17:57:46.877Z", "description": "Schema for representing customer details.", "type": "object", "properties": { "ref": { "$id": "#/properties/ref", "type": "string", "description": "Ref serves as a unique identifier for customer within the (account)[account] (merchant).", "examples": [ "CUSTOMER_REFERENCE" ] }, "merchantId": { "$id": "#/properties/merchantId", "type": "string", "description": "The unique identifier (AVID) of the merchant's account.", "examples": [ "AVID0000-0000-0000-0000-000000000000" ] }, "metadata": { "$id": "#/properties/metadata", "type": "object", "description": "Add additional information associated with the customer like name, location etc. A special mention to the [customers/crm/authvia](customers-crm-authvia) product which can enable a signup form for customers to self sign up and/or add validation checking for each customer created.", "examples": [ { "name": "John Doe" } ] }, "appdata": { "$id": "#/properties/appdata", "type": "object", "description": "A merchant can add extra details for a customer, such as notes, references, secret etc, which are not visible to the customer. This attribute is only deliviered on webhook payloads and returned for API calls to load a customer record.", "examples": [ { "key1": "value1", "key2": "value2" } ] } } }, "examples": { "CustomerDeleted": { "summary": "Customer Deleted", "value": { "ref": "CUSTOMER_REFERENCE", "merchantId": "AVID0000-0000-0000-0000-000000000000", "deletedOn": "2024-01-01T00:00:00Z" } } } } } }, "responses": { "200": { "description": "> Your system should return a 2xx status to indicate that the data was published successfully. Other statuses will be considered a failure and we will retry later. See the [redrive](subscriptions-redrive) page for more details." } } } } }, "x-readme": { "headers": [ { "key": "Content-Type", "value": "application/json" } ], "explorer-enabled": true, "proxy-enabled": true, "samples-enabled": true }, "x-readme-fauxas": true } ```