Get Payment Request Status
GET /v5/devices/{device_id}/payment-requests/{request_id}
Environment and operation
Use this endpoint contract with the account and environment assigned to your integration. Values in angle brackets are placeholders. This reference does not execute requests. Documented server https://sandbox.nmi.com/api Schema reference: field definitions do not include every behavioral rule. Follow the workflow guidance and account prerequisites for this operation before submitting requests.
Request route
Retrieve the status of an asynchronous payment request initiated on a cloud device. The request_id is obtained from the initial payment request response (e.g., from POST /api/v5/devices/{deviceId}/payment-requests/sale). The device_id must match the device that initiated the payment request. This endpoint uses the same underlying functionality as GET /api/asyncstatus. GET /v5/devices/{device_id}/payment-requests/{request_id} Security scheme Type Credential location Scopes merchantApiKey apiKey header Authorization No scopes declared on this operation
Request language templates
Original transport templates derived from this endpoint’s documented method, server, authentication and media type. Replace path/query/credential placeholders with authorized sandbox values. These examples print the raw status and response; they do not infer business success or retry a request. Node requires a runtime with fetch; PHP requires cURL. Generated source-based examples have not been executed against provider accounts. curl --request GET \ --url 'https://sandbox.nmi.com/api/v5/devices/{device_id}/payment-requests/{request_id}' \ --header 'Authorization: <merchantApiKey>' const response = await fetch("https://sandbox.nmi.com/api/v5/devices/{device_id}/payment-requests/{request_id}", { method: 'GET', headers: { "Authorization": "<merchantApiKey>" } }); console.log(response.status, await response.text()); from urllib.request import Request, urlopen from urllib.error import HTTPError request = Request('https://sandbox.nmi.com/api/v5/devices/{device_id}/payment-requests/{request_id}', method='GET', headers={'Authorization': '<merchantApiKey>'}) try: with urlopen(request, timeout=30) as response: print(response.status, response.read().decode()) except HTTPError as error: print(error.code, error.read().decode()) require 'net/http' require 'uri' uri = URI("https://sandbox.nmi.com/api/v5/devices/{device_id}/payment-requests/{request_id}") request = Net::HTTP::Get.new(uri) request["Authorization"] = "<merchantApiKey>" response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https', read_timeout: 30) { |http| http.request(request) } puts response.code puts response.body <?php $curl = curl_init('https://sandbox.nmi.com/api/v5/devices/{device_id}/payment-requests/{request_id}'); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => ['Authorization: <merchantApiKey>'] ]); $response = curl_exec($curl); if ($response === false) { throw new RuntimeException(curl_error($curl)); } echo curl_getinfo($curl, CURLINFO_HTTP_CODE), PHP_EOL, $response; curl_close($curl);
Path and query parameters
Required flags apply to the parameter itself. Additional limits and enum values appear in the contract below. Parameter Location Required Type Description device_id path true string The unique identifier of the cloud device that initiated the payment request request_id path true string The unique identifier of the payment request, obtained from the initial payment request response [ { "name": "device_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the cloud device that initiated the payment request" }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the payment request, obtained from the initial payment request response" } ] true
Responses
Match the HTTP status to its response schema below. For financial operations, also inspect the payment outcome before updating your order or retrying. HTTP status Media type Meaning 200 application/json Payment request status retrieved successfully 400 application/json Bad Request - The request was malformed or contained invalid parameters 401 application/json Unauthorized - Authentication credentials were missing or invalid 404 application/json Not Found - The requested resource could not be found 500 application/json Internal Server Error - An unexpected error occurred on the server { "200": { "description": "Payment request status retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequestStatusResponse" }, "examples": { "inFlight": { "summary": "Customer is still interacting with the device", "value": { "object": "payment-request", "id": "abc123def456", "status": "inFlight" } }, "interactionCompleteApproved": { "summary": "Device interaction finished with an approved transaction", "value": { "object": "payment-request", "id": "abc123def456", "status": "interactionComplete", "transaction": { "id": 12345, "type": "sale", "success": true, "condition": "pendingsettlement", "approval": "123456", "authorized_amount": "10.00", "auth_code": "AUTH123" } } }, "interactionCompleteDeclined": { "summary": "Device interaction finished with a declined transaction", "value": { "object": "payment-request", "id": "abc123def456", "status": "interactionComplete", "transaction": { "id": 12345, "type": "sale", "success": false, "condition": "failed", "auth_code": "" } } }, "interactionCompleteError": { "summary": "Device interaction finished with an error", "value": { "object": "payment-request", "id": "abc123def456", "status": "interactionComplete", "error": { "code": "300", "ref_id": "58523101", "message": "error message will appear here" } } }, "poiDeviceInUse": { "summary": "Another payment request is already in progress on the device", "value": { "object": "payment-request", "id": "abc123def456", "status": "poiDeviceInUse" } }, "cancelledAtTerminal": { "summary": "Customer cancelled at the device", "value": { "object": "payment-request", "id": "abc123def456", "status": "cancelledAtTerminal" } }, "cancelledByApi": { "summary": "Payment request cancelled via DELETE /api/v5/devices/{device_id}/payment-requests", "value": { "object": "payment-request", "id": "abc123def456", "status": "cancelledByApi" } } } } } }, "400": { "description": "Bad Request - The request was malformed or contained invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing what was wrong with the request" }, "code": { "type": "string", "description": "Error code for programmatic handling" } } }, "example": { "error": "Invalid request parameters", "code": "BAD_REQUEST" } } } }, "401": { "description": "Unauthorized - Authentication credentials were missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing the authentication failure" }, "code": { "type": "string", "description": "Error code for programmatic handling" } } }, "example": { "error": "Invalid or missing API key", "code": "UNAUTHORIZED" } } } }, "404": { "description": "Not Found - The requested resource could not be found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing what resource was not found" }, "code": { "type": "string", "description": "Error code for programmatic handling" } } }, "example": { "error": "Resource not found", "code": "NOT_FOUND" } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing the server error" }, "code": { "type": "string", "description": "Error code for programmatic handling" } } }, "example": { "error": "An unexpected error occurred", "code": "INTERNAL_SERVER_ERROR" } } } } } true
Response fields · 200 · application/json
Field Type Required Description Constraints object string yes Resource type identifier enum: ["payment-request"] id string yes Payment request ID status string yes Status of the payment request. When a payment request is first created, the status is always `pending`. When polling for status, values are more granular to show the progress of the transaction based on the device's status or customer's interaction. enum: ["pending", "inFlight", "interactionComplete", "cancelled", "cancelledAtTerminal", "cancelledByApi", "cancelledByTimeout", "poiDeviceInUse", "poiDeviceDisconnected", "terminatedBadCardRead"] transaction object no Transaction details if the payment request has been processed transaction.id integer no Transaction ID transaction.type string no Transaction type (e.g., 'sale', 'auth', 'credit', 'validate') transaction.success boolean no Whether the transaction was successful transaction.condition string no Transaction condition/status transaction.approval string no Approval code transaction.authorized_amount string no Authorized amount. Format: `x.xx` transaction.auth_code string no Authorization code transaction.customer_vault_id string no Customer vault ID associated with the transaction transaction.emv_metadata object no EMV (chip card) metadata transaction.emv_metadata.customer_verification_method string no Customer verification method used transaction.emv_metadata.application_id string no EMV application ID transaction.emv_metadata.application_label string no EMV application label transaction.emv_metadata.application_preferred_name string no EMV application preferred name transaction.emv_metadata.application_pan_sequence_number string no EMV application PAN sequence number transaction.emv_metadata.transaction_status_information string no EMV transaction status information transaction.emv_metadata.masked_merchant_number string no Masked merchant number transaction.emv_metadata.masked_terminal_number string no Masked terminal number transaction.card_tokens array no Card tokens associated with the transaction transaction.card_tokens[].token string no Card token transaction.card_tokens[].type string no Token type error object no Error information if the payment request failed error.code string no Error code error.ref_id string no Error reference ID error.message string no Error message
Response fields · 400 · application/json
Field Type Required Description Constraints error string no Error message describing what was wrong with the request code string no Error code for programmatic handling
Response fields · 401 · application/json
Field Type Required Description Constraints error string no Error message describing the authentication failure code string no Error code for programmatic handling
Response fields · 404 · application/json
Field Type Required Description Constraints error string no Error message describing what resource was not found code string no Error code for programmatic handling
Response fields · 500 · application/json
Field Type Required Description Constraints error string no Error message describing the server error code string no Error code for programmatic handling
Referenced schema definitions
References beginning with #/components resolve to these definitions. These are field contracts, not example payment values. Use the applicable variant, required fields and constraints. { "securitySchemes": { "merchantApiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Merchant API key for RESTful API authentication. This key is used for merchant-specific API access and can be generated from the merchant portal." } }, "examples": { "auth-success": { "summary": "Successful Authorization", "description": "This transaction was successfully authorized.", "value": { "event_id": "322ac05a-cf6c-4c16-948a-3048d007f742", "event_type": "transaction.auth.success", "event_body": { "merchant": { "id": "944025", "name": "Test merchant account" }, "features": { "is_test_mode": true }, "transaction_id": "8584341675", "transaction_type": "cc", "condition": "pending", "processor_id": "ccprocessora", "ponumber": "", "order_description": "", "order_id": "", "customerid": "", "customertaxid": "", "website": "", "shipping": "", "currency": "USD", "tax": "", "surcharge": "", "convenience_fee": "", "misc_fee": "", "misc_fee_name": "", "cash_discount": "", "tip": "", "requested_amount": "10.00", "shipping_carrier": "", "tracking_number": "", "shipping_date": "", "partial_payment_id": "", "partial_payment_balance": "", "platform_id": "", "authorization_code": "123456", "social_security_number": "", "drivers_license_number": "", "drivers_license_state": "", "drivers_license_dob": "", "duty_amount": "0.00", "discount_amount": "0.00", "national_tax_amount": "0.00", "summary_commodity_code": "", "alternate_tax_amount": "0.00", "vat_tax_amount": "0.00", "vat_tax_rate": "0.00", "billing_address": { "first_name": "", "last_name": "", "address_1": "", "address_2": "", "company": "", "city": "", "state": "", "postal_code": "", "country": "", "email": "", "phone": "", "cell_phone": "", "fax": "" }, "shipping_address": { "first_name": "", "last_name": "", "address_1": "", "address_2": "", "company": "", "city": "", "state": "", "postal_code": "", "country": "", "email": "", "phone": "", "fax": "" }, "card": { "cc_number": "411111******1111", "cc_exp": "1025", "cavv": "", "cavv_result": "", "xid": "", "eci": "", "avs_response": "", "csc_response": "M", "cardholder_auth": "", "cc_start_date": "", "cc_issue_number": "", "card_balance": "", "card_available_balance": "", "entry_mode": "4", "cc_bin": "", "cc_type": "Visa", "feature_token": "" }, "merchant_defined_fields": {}, "action": { "amount": "10.00", "action_type": "auth", "date": "20230801113700", "success": "1", "ip_address": "123.123.123.123", "source": "api", "api_method": "direct_post", "username": "test", "response_text": "SUCCESS", "response_code": "100", "processor_response_text": "", "tap_to_mobile": false, "processor_response_code": "", "device_license_number": "", "device_nickname": "" } } } }, "auth-failed": { "summary": "Failed Authorization", "description": "The authorization request was declined by the processor.", "value": { "event_id": "322ac05a-cf6c-4c16-948a-3048d007f742", "event_type": "transaction.auth.failure", "event_body": { "merchant": { "id": "944025", "name": "Test merchant account" }, "features": { "is_test_mode": true }, "transaction_id": "8597004002", "transaction_type": "cc", "condition": "failed", "processor_id": "ccprocessora", "ponumber": "", "order_description": "", "order_id": "", "customerid": "", "customertaxid": "", "website": "", "shipping": "", "currency": "USD", "tax": "", "surcharge": "", "convenience_fee": "", "misc_fee": "", "misc_fee_name": "", "cash_discount": "", "tip": "", "requested_amount": "0.50", "shipping_carrier": "", "tracking_number": "", "shipping_date": "", "partial_payment_id": "", "partial_payment_balance": "", "platform_id": "", "authorization_code": "123456", "social_security_number": "", "drivers_license_number": "", "drivers_license_state": "", "drivers_license_dob": "", "duty_amount": "0.00", "discount_amount": "0.00", "national_tax_amount": "0.00", "summary_commodity_code": "", "alternate_tax_amount": "0.00", "vat_tax_amount": "0.00", "vat_tax_rate": "0.00", "billing_address": { "first_name": "", "last_name": "", "address_1": "", "address_2": "", "company": "", "city": "", "state": "", "postal_code": "", "country": "", "email": "", "phone": "", "cell_phone": "", "fax": "" }, "shipping_address": { "first_name": "", "last_name": "", "address_1": "", "address_2": "", "company": "", "city": "", "state": "", "postal_code": "", "country": "", "email": "", "phone": "", "fax": "" }, "card": { "cc_number": "411111******1111", "cc_exp": "1025", "cavv": "", "cavv_result": "", "xid": "", "eci": "", "avs_response": "", "csc_response": "M", "cardholder_auth": "", "cc_start_date": "", "cc_issue_number": "", "card_balance": "", "card_available_balance": "", "entry_mode": "4", "cc_bin": "", "cc_type": "Visa", "feature_token": "" }, "merchant_defined_fields": {}, "action": { "amount": "10.00", "action_type": "auth", "date": "20230801113700", "success": "0", "ip_address": "123.123.123.123", "source": "api", "api_method": "direct_post", "username": "test", "response_text": "DECLINE", "response_code": "200", "processor_response_text": "", "tap_to_mobile": false, "processor_response_code": "", "device_license_number": "", "device_nickname": "" } } } }, "capture-success": { "summary": "Transaction captured successfully", "description": "Transaction captured successfully", "value": { "event_id": "e5267749-c235-45c9-b93e-21f4379b94d1", "event_type": "transaction.capture.success", "event_body": { "merchant": { "id": "944025", "name": "Test merchant account" }, "features": { "is_test_mode": true }, "transaction_id": "8584341675", "transaction_type": "cc", "condition": "pendingsettlement", "processor_id": "ccprocessora", "ponumber": "", "order_description": "", "order_id": "", "customerid": "", "customertaxid": "", "website": "", "shipping": "0.00", "currency": "USD", "tax": "0.00", "surcharge": "", "convenience_fee": "", "misc_fee": "", "misc_fee_name": "", "cash_discount": "", "tip": "", "requested_amount": "10.00", "shipping_carrier": "", "tracking_number": "", "shipping_date": "", "partial_payment_id": "", "partial_payment_balance": "", "platform_id": "", "authorization_code": "123456", "social_security_number": "", "drivers_license_number": "", "drivers_license_state": "", "drivers_license_dob": "", "duty_amount": "0.00", "discount_amount": "0.00", "national_tax_amount": "0.00", "summary_commodity_code": "", "alternate_tax_amount": "0.00", "vat_tax_amount": "0.00", "vat_tax_rate": "0.00", "billing_address": { "first_name": "", "last_name": "", "address_1": "", "address_2": "", "company": "", "city": "", "state": "", "postal_code": "", "country": "", "email": "", "phone": "", "cell_phone": "", "fax": "" }, "shipping_address": { "first_name": "", "last_name": "", "address_1": "", "address_2": "", "company": "", "city": "", "state": "", "postal_code": "", "country": "", "email": "", "phone": "", "fax": "" }, "card": { "cc_number": "411111******1111", "cc_exp": "1025", "cavv": "", "cavv_result": "", "xid": "", "eci": "", "avs_response": "", "csc_response": "M", "cardholder_auth": "", "cc_start_date": "", "cc_issue_number": "", "card_balance": "", "card_available_balance": "", "entry_mode": "4", "cc_bin": "", "cc_type": "Visa", "feature_token": "" }, "merchant_defined_fields": {}, "action": { "amount": "10.00", "action_type": "capture", "date": "20230801113955", "success": "1", "ip_address": "123.123.123.123", "source": "api", "api_method": "direct_post", "username": "test", "response_text": "SUCCESS", "response_code": "100", "processor_response_text": "", "tap_to_mobile": false, "processor_response_code": "", "device_license_number": "", "device_nickname": "" } } } }, "sale-success": { "summary": "Sale transaction was successful", "description": "Sale transaction was successful", "value": { "event_id": "2aa1bb86-c790-4231-a46e-7cc544a8dc5c", "event_type": "transaction.sale.success", "event_body": { "merchant": { "id": "944025", "name": "Test merchant account" }, "features": { "is_test_mode": true }, "transaction_id": "8584364761", "transaction_type": "cc", "condition": "pendingsettlement", "processor_id": "ccprocessora", "ponumber": "", "order_description": "", "order_id": "", "customerid": "", "customertaxid": "", "website": "", "shipping": "", "currency": "USD", "tax": "", "surcharge": "", "convenience_fee": "", "misc_fee": "", "misc_fee_name": "", "cash_discount": "", "tip": "", "requested_amount": "10.00", "shipping_carrier": "", "tracking_number": "", "shipping_date": "", "partial_payment_id": "", "partial_payment_balance": "", "platform_id": "", "authorization_code": "123456", "social_security_number": "", "drivers_license_number": "", "drivers_license_state": "", "drivers_license_dob": "", "duty_amount": "0.00", "discount_amount": "0.00", "national_tax_amount": "0.00", "summary_commodity_code": "", "alternate_tax_amount": "0.00", "vat_tax_amount": "0.00", "vat_tax_rate": "0.00", "billing_address": { "first_name": "", "last_name": "", "address_1": "", "address_2": "", "company": "", "city": "", "state": "", "postal_code": "", "country": "", "email": "", "phone": "", "cell_phone": "", "fax": "" }, "shipping_address": { "first_name": "", "last_name": "", "address_1": "", "address_2": "", "company": "", "city": "", "state": "", "postal_code": "", "country": "", "email": "", "phone": "", "fax": "" }, "card": { "cc_number": "411111******1111", "cc_exp": "1025", "cavv": "", "cavv_result": "", "xid": "", "eci": "", "avs_response": "", "csc_response": "M", "cardholder_auth": "", "cc_start_date": "", "cc_issue_number": "", "card_balance": "", "card_available_balance": "", "entry_mode": "4", "cc_bin": "", "cc_type": "Visa", "feature_token": "" }, "merchant_defined_fields": {}, "action": { "amount": "10.00", "action_type": "sale", "date": "20230801114200", "success": "1", "ip_address": "123.123.123.123", "source": "api", "api_method": "direct_post", "username": "test", "response_text": "SUCCESS", "response_code": "100", "processor_response_text": "", "tap_to_mobile": false, "processor_response_code": "", "device_license_number": "", "device_nickname": "" } } } }, "sale-failure": { "summary": "Sale transaction failed", "description": "Sale transaction failed", "value": { "event_id": "a4807d52-4e40-4e93-92e2-b6d2dad3ddd9", "event_type": "transaction.sale.failure", "event_body": { "merchant": { "id": "944025", "name": "Test merchant account" }, "features": { "is_test_mode": true }, "transaction_id": "8584372177", "transaction_type": "cc", "condition": "failed", "processor_id": "ccprocessora", "ponumber": "", "order_description": "", "order_id": "", "customerid": "", "customertaxid": "", "website": "", "shipping": "", "currency": "USD", "tax": "", "surcharge": "", "convenience_fee": "", "misc_fee": "", "misc_fee_name": "", "cash_discount": "", "tip": "", "requested_amount": "0.50", "shipping_carrier": "", "tracking_number": "", "shipping_date": "", "partial_payment_id": "", "partial_payment_balance": "", "platform_id": "", "authorization_code": "", "social_security_number": "", "drivers_license_number": "", "drivers_license_state": "", "drivers_license_dob": "", "duty_amount": "0.00", "discount_amount": "0.00", "national_tax_amount": "0.00", "summary_commodity_code": "", "alternate_tax_amount": "0.00", "vat_tax_amount": "0.00", "vat_tax_rate": "0.00", "billing_address": { "first_name": "", "last_name": "", "address_1": "", "address_2": "", "company": "", "city": "", "state": "", "postal_code": "", "country": "", "email": "", "phone": "", "cell_phone": "", "fax": "" }, "shipping_address": { "first_name": "", "last_name": "", "address_1": "", "address_2": "", "company": "", "city": "", "state": "", "postal_code": "", "country": "", "email": "", "phone": "", "fax": "" }, "card": { "cc_number": "411111******1111", "cc_exp": "1025", "cavv": "", "cavv_result": "", "xid": "", "eci": "", "avs_response": "", "csc_response": "M", "cardholder_auth": "", "cc_start_date": "", "cc_issue_number": "", "card_balance": "", "card_available_balance": "", "entry_mode": "4", "cc_bin": "", "cc_type": "Visa", "feature_token": "" }, "merchant_defined_fields": {}, "action": { "amount": "0.50", "action_type": "sale", "date": "20230801114355", "success": "0", "ip_address": "123.123.123.123", "source": "api", "api_method": "direct_post", "username": "test", "response_text": "DECLINE", "response_code": "200", "processor_response_text": "", "tap_to_mobile": false, "processor_response_code": "", "device_license_number": "", "device_nickname": "" } } } }, "void-success": { "summary": "Void transaction was successful", "description": "Void transaction was successful", "value": { "event_id": "56fce295-ee70-46a1-83c2-1f423c43c34c", "event_type": "transaction.void.success", "event_body": { "merchant": { "id": "944025", "name": "Test merchant account" }, "features": { "is_test_mode": true }, "transaction_id": "8584341675", "transaction_type": "cc", "condition": "canceled", "processor_id": "ccprocessora", "ponumber": "", "order_description": "", "order_id": "", "customerid": "", "customertaxid": "", "website": "", "shipping": "0.00", "currency": "USD", "tax": "0.00", "surcharge": "", "convenience_fee": "", "misc_fee": "", "misc_fee_name": "", "cash_discount": "", "tip": "", "requested_amount": "10.00", "shipping_carrier": "", "tracking_number": "", "shipping_date": "", "partial_payment_id": "", "partial_payment_balance": "", "platform_id": "", "authorization_code": "123456", "social_security_number": "", "drivers_license_number": "", "drivers_license_state": "", "drivers_license_dob": "", "duty_amount": "0.00", "discount_amount": "0.00", "national_tax_amount": "0.00", "summary_commodity_code": "", "alternate_tax_amount": "0.00", "vat_tax_amount": "0.00", "vat_tax_rate": "0.00", "billing_address": { "first_name": "", "last_name": "", "address_1": "", "address_2": "", "company": "", "city": "", "state": "", "postal_code": "", "country": "", "email": "", "phone": "", "cell_phone": "", "fax": "" }, "shipping_address": { "first_name": "", "last_name": "", "address_1": "", "address_2": "", "company": "", "city": "", "state": "", "postal_code": "", "country": "", "email": "", "phone": "", "fax": "" }, "card": { "cc_number": "411111******1111", "cc_exp": "1025", "cavv": "", "cavv_result": "", "xid": "", "eci": "", "avs_response": "", "csc_response": "M", "cardholder_auth": "", "cc_start_date": "", "cc_issue_number": "", "card_balance": "", "card_available_balance": "", "entry_mode": "4", "cc_bin": "", "cc_type": "Visa", "feature_token": "" }, "merchant_defined_fields": {}, "action": { "amount": "10.00", "action_type": "void", "date": "20230801115329", "success": "1", "ip_address": "123.123.123.123", "source": "api", "api_method": "direct_post", "username": "test", "response_text": "SUCCESS", "response_code": "100", "processor_response_text": "", "tap_to_mobile": false, "processor_response_code": "", "device_license_number": "", "device_nickname": "" } } } }, "refund-success": { "summary": "Transaction refunded successfully", "description": "Transaction refunded successfully", "value": { "event_id": "e5267749-c235-45c9-b93e-21f4379b94d1", "event_type": "transaction.refund.success", "event_body": { "merchant": { "id": "944025", "name": "Test merchant account" }, "features": { "is_test_mode": true }, "transaction_id": "8597047042", "transaction_type": "cc", "condition": "pendingsettlement", "processor_id": "ccprocessora", "ponumber": "", "order_description": "", "order_id": "", "customerid": "", "customertaxid": "", "website": "", "shipping": "0.00", "currency": "USD", "tax": "0.00", "surcharge": "", "convenience_fee": "", "misc_fee": "", "misc_fee_name": "", "cash_discount": "", "tip": "", "requested_amount": "-1.50", "shipping_carrier": "", "tracking_number": "", "shipping_date": "", "partial_payment_id": "", "partial_payment_balance": "", "platform_id": "", "authorization_code": "123456", "social_security_number": "", "drivers_license_number": "", "drivers_license_state": "", "drivers_license_dob": "", "duty_amount": "0.00", "discount_amount": "0.00", "national_tax_amount": "0.00", "summary_commodity_code": "", "alternate_tax_amount": "0.00", "vat_tax_amount": "0.00", "vat_tax_rate": "0.00", "billing_address": { "first_name": "", "last_name": "", "address_1": "", "address_2": "", "company": "", "city": "", "state": "", "postal_code": "", "country": "", "email": "", "phone": "", "cell_phone": "", "fax": "" }, "shipping_address": { "first_name": "", "last_name": "", "address_1": "", "address_2": "", "company": "", "city": "", "state": "", "postal_code": "", "country": "", "email": "", "phone": "", "fax": "" }, "card": { "cc_number": "411111******1111", "cc_exp": "1025", "cavv": "", "cavv_result": "", "xid": "", "eci": "", "avs_response": "", "csc_response": "", "cardholder_auth": "", "cc_start_date": "", "cc_issue_number": "", "card_balance": "", "card_available_balance": "", "entry_mode": "4", "cc_bin": "", "cc_type": "Visa", "feature_token": "" }, "merchant_defined_fields": {}, "action": { "amount": "-1.50", "action_type": "refund", "date": "20230804155935", "success": "1", "ip_address": "123.123.123.123", "source": "api", "api_method": "direct_post", "username": "test", "response_text": "SUCCESS", "response_code": "100", "processor_response_text": "", "tap_to_mobile": false, "processor_response_code": "", "device_license_number": "", "device_nickname": "" } } } }, "validate-success": { "summary": "Validate transaction was successful", "description": "Validate transaction was successful", "value": { "event_id": "7c19bb37-8679-4ffb-b431-41ae49d8ff75", "event_type": "transaction.validate.success", "event_body": { "merchant": { "id": "944025", "name": "Test merchant account" }, "features": { "is_test_mode": true }, "transaction_id": "8584364761", "transaction_type": "cc", "condition": "complete", "processor_id": "ccprocessora", "ponumber": "", "order_description": "", "order_id": "", "customerid": "", "customertaxid": "", "website": "", "shipping": "", "currency": "USD", "tax": "", "surcharge": "", "convenience_fee": "", "misc_fee": "", "misc_fee_name": "", "cash_discount": "", "tip": "", "requested_amount": "", "shipping_carrier": "", "tracking_number": "", "shipping_date": "", "partial_payment_id": "", "partial_payment_balance": "", "platform_id": "", "authorization_code": "", "social_security_number": "", "drivers_license_number": "", "drivers_license_state": "", "drivers_license_dob": "", "duty_amount": "0.00", "discount_amount": "0.00", "national_tax_amount": "0.00", "summary_commodity_code": "", "alternate_tax_amount": "0.00", "vat_tax_amount": "0.00", "vat_tax_rate": "0.00", "billing_address": { "first_name": "", "last_name": "", "address_1": "", "address_2": "", "company": "", "city": "", "state": "", "postal_code": "", "country": "", "email": "", "phone": "", "cell_phone": "", "fax": "" }, "shipping_address": { "first_name": "", "last_name": "", "address_1": "", "address_2": "", "company": "", "city": "", "state": "", "postal_code": "", "country": "", "email": "", "phone": "", "fax": "" }, "card": { "cc_number": "411111******1111", "cc_exp": "1025", "cavv": "", "cavv_result": "", "xid": "", "eci": "", "avs_response": "", "csc_response": "M", "cardholder_auth": "", "cc_start_date": "", "cc_issue_number": "", "card_balance": "", "card_available_balance": "", "entry_mode": "4", "cc_bin": "", "cc_type": "Visa", "feature_token": "" }, "merchant_defined_fields": {}, "action": { "amount": "0", "action_type": "validate", "date": "20230804160357", "success": "1", "ip_address": "123.123.123.123", "source": "api", "api_method": "direct_post", "username": "test", "response_text": "SUCCESS", "response_code": "100", "processor_response_text": "", "tap_to_mobile": false, "processor_response_code": "", "device_license_number": "", "device_nickname": "" } } } }, "plan-added": { "summary": "Recurring Plan Added", "description": "Recurring Plan has been added", "value": { "event_id": "35f56738-4755-4cd9-9068-ea9e83d60d2e", "event_type": "recurring.plan.add", "event_body": { "merchant": { "id": "944025", "name": "Test merchant account" }, "features": { "is_test_mode": true }, "plan": { "id": "TestPlanId1", "name": "Test Plan", "amount": "10.00", "day_frequency": "", "payments": "Until canceled", "month_frequency": "1", "day_of_month": "15" } } } }, "plan-updated": { "summary": "Recurring Plan Updated", "description": "Recurring Plan has been updated", "value": { "event_id": "35f56738-4755-4cd9-9068-ea9e83d60d2e", "event_type": "recurring.plan.update", "event_body": { "merchant": { "id": "944025", "name": "Test merchant account" }, "features": { "is_test_mode": true }, "plan": { "id": "", "name": "Test Plan Updated", "amount": "20.00", "day_frequency": "", "payments": "Until canceled", "month_frequency": "", "day_of_month": "" } } } }, "plan-deleted": { "summary": "Recurring Plan Deleted", "description": "Recurring Plan has been deleted", "value": { "event_id": "35f56738-4755-4cd9-9068-ea9e83d60d2e", "event_type": "recurring.plan.delete", "event_body": { "merchant": { "id": "944025", "name": "Test merchant account" }, "features": { "is_test_mode": true }, "plan": { "id": "TestPlanId1", "name": "Test Plan Updated", "amount": "20.00", "day_frequency": "15", "payments": "Until canceled", "month_frequency": "1", "day_of_month": "0" } } } }, "subscription-added": { "summary": "Subscription Added", "description": "A new subscription has been added.", "value": { "event_id": "5f5706a2-aec2-4d69-b699-32e5745cf1fd", "event_type": "recurring.subscription.add", "event_body": { "merchant": { "id": "944025", "name": "Test merchant account" }, "features": { "is_test_mode": true }, "subscription_id": "8608342724", "subscription_type": "cc", "processor_id": "", "next_charge_date": "1970-01-01", "completed_payments": "0", "attempted_payments": "0", "remaining_payments": "Until canceled", "ponumber": "", "order_id": "", "order_description": "", "shipping": "", "tax": "", "website": "", "plan": { "id": "TestPlanId1", "name": "Test Plan", "amount": "10.00", "day_frequency": "", "payments": "Until canceled", "month_frequency": "1", "day_of_month": "15" }, "billing_address": { "first_name": "John", "last_name": "Smith", "address_1": "123 Lovely Lane", "address_2": "", "company": "", "city": "New York City", "state": "NY", "postal_code": "11111", "country": "US", "email": "", "phone": "", "cell_phone": "", "fax": "" }, "card": { "cc_number": "411111******1111", "cc_exp": "1025", "cavv": "", "cavv_result": "", "xid": "", "eci": "", "avs_response": "", "csc_response": "", "cardholder_auth": "", "cc_start_date": "", "cc_issue_number": "", "card_balance": "", "card_available_balance": "", "entry_mode": "", "cc_bin": "", "cc_type": "Visa" } } } }, "subscription-updated": { "summary": "Subscription Updated", "description": "A new subscription has been updated.", "value": { "event_id": "9f4c6478-e875-44d5-a83c-e2afebdaab86", "event_type": "recurring.subscription.update", "event_body": { "merchant": { "id": "944025", "name": "Test merchant account" }, "features": { "is_test_mode": true }, "subscription_id": "8608342724", "subscription_type": "cc", "processor_id": "", "next_charge_date": "2023-09-15", "completed_payments": "0", "attempted_payments": "0", "remaining_payments": "Until canceled", "ponumber": "", "order_id": "", "order_description": "", "shipping": "0.00", "tax": "0.00", "website": "", "plan": { "id": "", "name": "", "amount": "10.00", "day_frequency": "", "payments": "Until canceled", "month_frequency": "1", "day_of_month": "15" }, "billing_address": { "first_name": "John", "last_name": "Smith", "address_1": "123 Lovely Lane", "address_2": "", "company": "", "city": "New York City", "state": "NY", "postal_code": "11111", "country": "US", "email": "", "phone": "", "cell_phone": "", "fax": "" }, "card": { "cc_number": "411111******1111", "cc_exp": "1025", "cavv": "", "cavv_result": "", "xid": "", "eci": "", "avs_response": "", "csc_response": "", "cardholder_auth": "", "cc_start_date": "", "cc_issue_number": "", "card_balance": "", "card_available_balance": "", "entry_mode": "", "cc_bin": "", "cc_type": "Visa" } } } }, "subscription-deleted": { "summary": "Subscription Deleted", "description": "A new subscription has been deleted.", "value": { "event_id": "a1c0839a-4156-4f7c-a875-dc9411e2d3a6", "event_type": "recurring.subscription.delete", "event_body": { "merchant": { "id": "944025", "name": "Test merchant account" }, "features": { "is_test_mode": true }, "subscription_id": "8608342724", "subscription_type": "cc", "processor_id": "", "next_charge_date": "2023-09-15", "completed_payments": "0", "attempted_payments": "0", "remaining_payments": "Until canceled", "ponumber": "", "order_id": "", "order_description": "", "shipping": "0.00", "tax": "0.00", "website": "", "plan": { "id": "", "name": "", "amount": "10.00", "day_frequency": "", "payments": "Until canceled", "month_frequency": "1", "day_of_month": "15" }, "billing_address": { "first_name": "John", "last_name": "Smith", "address_1": "123 Lovely Lane", "address_2": "", "company": "", "city": "New York City", "state": "NY", "postal_code": "11111", "country": "US", "email": "", "phone": "", "cell_phone": "", "fax": "" }, "card": { "cc_number": "411111******1111", "cc_exp": "1025", "cavv": "", "cavv_result": "", "xid": "", "eci": "", "avs_response": "", "csc_response": "", "cardholder_auth": "", "cc_start_date": "", "cc_issue_number": "", "card_balance": "", "card_available_balance": "", "entry_mode": "", "cc_bin": "", "cc_type": "Visa" } } } }, "settlement-completed": { "summary": "Settlement Batch Completed", "description": "Settlement batch completed", "value": { "event_id": "11750910-bd03-4f9a-871a-786203df177f", "event_type": "settlement.batch.complete", "event_body": { "batch_id": "12345678", "count": 4, "amount": "402.81", "merchant": { "id": "123456", "name": "Test Account" }, "processor": { "id": "ccprocessor", "name": "CC Processor", "type": "cc" }, "by_card_type": { "visa": { "count": 4, "amount": "402.81" } }, "transaction_ids": [ "1234000000", "1234000001", "1234000002", "1234000003" ] } } }, "settlement-failed": { "summary": "Settlement Batch Failed", "description": "Settlement batch failed", "value": { "event_id": "dfe8156d-5dd9-43ac-8928-3cf70ef74108", "event_type": "settlement.batch.failure", "event_body": { "batch_id": "123456", "merchant": { "id": "123456", "name": "Test Merchant" }, "processor": { "id": "ccprocessor", "name": "CC Processor", "type": "cc" } } } }, "acu.summary.automaticallyupdated": { "summary": "Automatically Updated", "description": "Automatically updated", "value": { "event_id": "7958c536-88f0-47f4-bb55-54575259a3be", "event_type": "acu.summary.automaticallyupdated", "event_body": { "updated_date": "2022-08-22", "merchant": { "id": 123456, "name": "Test Account" }, "cards_checked": { "customer_vault": { "checked": 376, "updated": 4 }, "subscriptions": { "checked": 434, "updated": 3 } }, "vault_count_updated_cards": 1, "vault_updated_cards": [ { "customer_vault_id": "308229500", "billing_id": "1781228768", "cc_number": "445701******0009", "cc_exp": "01/50", "first_name": "Bob", "last_name": "Smith", "email": "bsmith@example.com", "phone": "+14801112222" } ], "vault_count_updated_expiration_dates": 3, "vault_updated_expiration_dates": [ { "customer_vault_id": "2061222895", "billing_id": "350282046", "cc_number": "400000******0002", "cc_exp": "11/70", "first_name": "Bob", "last_name": "Smith", "email": "bobsmith@company.com", "phone": "4801112222" }, { "customer_vault_id": "1039486483", "billing_id": "1408598861", "cc_number": "400000******0034", "cc_exp": "11/70", "first_name": "Jane", "last_name": "Smith", "email": "jane@organization.org", "phone": "+12125551222" }, { "customer_vault_id": "1033346428", "billing_id": "1460247050", "cc_number": "520000******0007", "cc_exp": "12/33", "first_name": "Steve", "last_name": "Customer", "email": "steve@customer.com", "phone": "+13104053434" } ], "recurring_count_updated_cards": 2, "recurring_updated_cards": [ { "subscription_id": "281474976710720", "cc_number": "445701******0459", "cc_exp": "01/50", "first_name": "", "last_name": "", "email": "", "phone": "" }, { "subscription_id": "281474976710726", "cc_number": "445701******1123", "cc_exp": "01/50", "first_name": "Frank", "last_name": "Jones", "email": "fjones@example.com", "phone": "6021234567" } ], "recurring_count_updated_expiration_dates": 1, "recurring_updated_expiration_dates": [ { "subscription_id": "281474976710725", "cc_number": "400000******3223", "cc_exp": "11/70", "first_name": "Susan", "last_name": "Harris", "email": "harris@company.com", "phone": "3125551212" } ] } } }, "acu.summary.closedaccount": { "summary": "Closed Account", "description": "Closed Account", "value": { "event_id": "7bbd4af6-4075-4902-af56-9fc59ab71362", "event_type": "acu.summary.closedaccount", "event_body": { "updated_date": "2022-08-23", "merchant": { "id": 123456, "name": "Test Account" }, "cards_checked": { "customer_vault": { "checked": 123, "updated": 1 }, "subscriptions": { "checked": 232, "updated": 1 } }, "vault_count_updated_closed_account": 1, "vault_updates": [ { "customer_vault_id": "281474976710722", "billing_id": "230304034", "cc_number": "434343******0123", "cc_exp": "11/25", "first_name": "Longterm", "last_name": "Client", "email": "sample@customer.com", "phone": "6025551213" } ], "recurring_count_updated_closed_account": 1, "recurring_updates": [ { "subscription_id": "281474976710727", "cc_number": "601101******0002", "cc_exp": "11/32", "first_name": "Bob", "last_name": "Smith", "email": "bsmith@example.co.uk", "phone": "+440111122222" } ] } } }, "acu.summary.contactcustomer": { "summary": "Contact Support", "description": "Contact Support", "value": { "event_id": "7bbd4af6-4075-4902-af56-9fc59ab71362", "event_type": "acu.summary.contactcustomer", "event_body": { "updated_date": "2022-08-23", "merchant": { "id": 123456, "name": "Test Account" }, "cards_checked": { "customer_vault": { "checked": 123, "updated": 2 }, "subscriptions": { "checked": 232, "updated": 1 } }, "vault_count_updated_contact_customer": 2, "vault_updates": [ { "customer_vault_id": "40403043545", "billing_id": "34544356", "cc_number": "445343******7432", "cc_exp": "06/29", "first_name": "Happy", "last_name": "Customer", "email": "frequent@shopper.com", "phone": "5555559999" }, { "customer_vault_id": "281474976710722", "billing_id": "230304034", "cc_number": "434343******0123", "cc_exp": "11/25", "first_name": "Bill", "last_name": "Thompson", "email": "bill@anothercustomer.com", "phone": "6025551213" } ], "recurring_count_updated_contact_customer": 1, "recurring_updates": [ { "subscription_id": "323232232445", "cc_number": "465333******4232", "cc_exp": "04/30", "first_name": "Recurring", "last_name": "Customer", "email": "buy@repeatedly.com", "phone": "8185552323" } ] } } }, "chargeback.batch.complete": { "summary": "Chargeback Batch Completed", "description": "Chargeback Batch Completed", "value": { "event_id": "7bbd4af6-4075-4902-af56-9fc59ab71362", "event_type": "chargeback.batch.complete", "event_body": { "merchant": { "id": "123456", "name": "Test Account" }, "processor": { "id": "ccprocessor", "name": "CC Processor", "type": "cc" }, "count": 1, "chargeback_amount": "12.34", "chargebacks": [ { "id": "12345678", "date": "2023-08-11", "customer_name": "John Doe", "cc_number": "411111******1111", "amount": "12.34", "reason": "Cardholder Does Not Recognize" } ] } } } }, "schemas": { "PaymentRequestStatusResponse": { "type": "object", "title": "Payment Request Status Response", "description": "Payment request response. Returned when creating an asynchronous payment request or polling for its status.", "properties": { "object": { "type": "string", "enum": [ "payment-request" ], "description": "Resource type identifier" }, "id": { "type": "string", "description": "Payment request ID" }, "status": { "type": "string", "enum": [ "pending", "inFlight", "interactionComplete", "cancelled", "cancelledAtTerminal", "cancelledByApi", "cancelledByTimeout", "poiDeviceInUse", "poiDeviceDisconnected", "terminatedBadCardRead" ], "description": "Status of the payment request. When a payment request is first created, the status is always `pending`. When polling for status, values are more granular to show the progress of the transaction based on the device's status or customer's interaction." }, "transaction": { "type": "object", "description": "Transaction details if the payment request has been processed", "properties": { "id": { "type": "integer", "nullable": true, "description": "Transaction ID" }, "type": { "type": "string", "description": "Transaction type (e.g., 'sale', 'auth', 'credit', 'validate')" }, "success": { "type": "boolean", "description": "Whether the transaction was successful" }, "condition": { "type": "string", "description": "Transaction condition/status" }, "approval": { "type": "string", "description": "Approval code" }, "authorized_amount": { "type": "string", "description": "Authorized amount. Format: `x.xx`" }, "auth_code": { "type": "string", "description": "Authorization code" }, "customer_vault_id": { "type": "string", "description": "Customer vault ID associated with the transaction" }, "emv_metadata": { "type": "object", "description": "EMV (chip card) metadata", "properties": { "customer_verification_method": { "type": "string", "description": "Customer verification method used" }, "application_id": { "type": "string", "description": "EMV application ID" }, "application_label": { "type": "string", "description": "EMV application label" }, "application_preferred_name": { "type": "string", "description": "EMV application preferred name" }, "application_pan_sequence_number": { "type": "string", "description": "EMV application PAN sequence number" }, "transaction_status_information": { "type": "string", "description": "EMV transaction status information" }, "masked_merchant_number": { "type": "string", "description": "Masked merchant number" }, "masked_terminal_number": { "type": "string", "description": "Masked terminal number" } } }, "card_tokens": { "type": "array", "description": "Card tokens associated with the transaction", "items": { "type": "object", "properties": { "token": { "type": "string", "description": "Card token" }, "type": { "type": "string", "description": "Token type" } } } } } }, "error": { "type": "object", "description": "Error information if the payment request failed", "properties": { "code": { "type": "string", "description": "Error code" }, "ref_id": { "type": "string", "description": "Error reference ID" }, "message": { "type": "string", "description": "Error message" } } } }, "required": [ "object", "id", "status" ] }, "Merchant": { "type": "object", "title": "Merchant", "description": "Merchant Details", "properties": { "id": { "type": "string", "description": "Merchant identifier" }, "name": { "type": "string", "description": "Merchant name" } } }, "Features": { "type": "object", "title": "Features", "description": "Features associated with the transaction", "properties": { "is_test_mode": { "type": "boolean", "description": "Test mode status" } } }, "BillingAddress": { "type": "object", "title": "Billing Address", "description": "Billing Address details", "properties": { "first_name": { "type": "string", "description": "The first name of the person associated with the billing address." }, "last_name": { "type": "string", "description": "The last name of the person associated with the billing address." }, "address_1": { "type": "string", "description": "The first line of the street address." }, "address_2": { "type": "string", "description": "The second line of the street address." }, "company": { "type": "string", "description": "The name of the company associated with the billing address." }, "city": { "type": "string", "description": "The name of the city associated with the billing address." }, "state": { "type": "string", "description": "The name of the state or province associated with the billing address.\n \nFormat: `CC`" }, "postal_code": { "type": "string", "description": "The postal code or zip code associated with the billing address." }, "country": { "type": "string", "description": "The name of the country associated with the billing address. *Country codes are as shown in ISO 3166-1 alpha-2*.\n \nFormat: `CC`" }, "email": { "type": "string", "format": "email", "description": "The email address associated with the billing address." }, "phone": { "type": "string", "format": "phone", "description": "The phone number associated with the billing address." }, "cell_phone": { "type": "string", "format": "phone", "description": "The cell phone number associated with the billing address." }, "fax": { "type": "string", "format": "phone", "description": "The fax number associated with the billing address." } } }, "ShippingAddress": { "type": "object", "title": "Shipping Address", "description": "Shipping Address details.", "properties": { "first_name": { "type": "string", "description": "The first name of the person associated with the shipping address." }, "last_name": { "type": "string", "description": "The last name of the person associated with the shipping address." }, "address_1": { "type": "string", "description": "The first line of the street address." }, "address_2": { "type": "string", "description": "The second line of the street address." }, "company": { "type": "string", "description": "The name of the company associated with the shipping address." }, "city": { "type": "string", "description": "The city of the shipping address." }, "state": { "type": "string", "description": "The state or province of the shipping address.\n \nFormat: `CC`" }, "postal_code": { "type": "string", "description": "The postal or zip code of the shipping address." }, "country": { "type": "string", "description": "The country of the shipping address. *Country codes are as shown in ISO 3166-1 alpha-2*.\n \nFormat: `CC`" }, "email": { "type": "string", "description": "The email address associated with the shipping address." }, "phone": { "type": "string", "description": "The phone number associated with the shipping address." }, "fax": { "type": "string", "description": "The fax number associated with the shipping address." } } }, "CardDetails": { "type": "object", "title": "Card Details", "description": "Details related to the credit card used in the transaction. Available for credit card transactions only.", "properties": { "cc_number": { "type": "string", "description": "Masked credit card number" }, "cc_exp": { "type": "string", "description": "Credit card expiration date" }, "cavv": { "type": "string", "description": "Cardholder Authentication Verification Value" }, "cavv_result": { "type": "string", "description": "Cardholder Authentication Verification Value result" }, "xid": { "type": "string", "description": "Cardholder authentication transaction id" }, "eci": { "type": "string", "enum": [ "01", "02", "05", "06", "07", "08", "09", "" ], "description": "Electronic Commerce Indicator" }, "avs_response": { "type": "string", "description": "Address Verification Service response" }, "csc_response": { "type": "string", "description": "Card Security Code response" }, "cardholder_auth": { "type": "string", "enum": [ "verified", "attempted", "" ], "description": "Cardholder Authentication response" }, "cc_start_date": { "type": "string", "description": "Credit card start date" }, "cc_issue_number": { "type": "string", "description": "Credit card issue number" }, "card_balance": { "type": "string", "description": "Card balance" }, "card_available_balance": { "type": "string", "description": "Card available balance" }, "entry_mode": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "7", "8" ], "description": "The type of transaction data to be processed.\n\n<details>\n<summary>Possible values:</summary>\n\n| Code | Description |\n|:------|:--------------------|\n| 0 | Unknown |\n| 1 | Invalid |\n| 2 | NFC MSD |\n| 3 | Swiped |\n| 4 | Keyed |\n| 5 | EMV ICC |\n| 6 | NFC EMV |\n| 7 | Keyed - Fallback |\n| 8 | Swiped - Fallback |\n</details>" }, "cc_bin": { "type": "string", "description": "Credit card BIN (first 6 digits)" }, "cc_type": { "type": "string", "description": "Credit card type (visa, ..)" }, "feature_token": { "type": "string", "description": "Feature token" } } }, "ACHAccountHolderType": { "type": "string", "enum": [ "business", "personal" ], "description": "The customer's ACH account entity." }, "ACHAccountType": { "type": "string", "enum": [ "checking", "savings" ], "description": "The customer's ACH account type." }, "ACHSecCode": { "type": "string", "enum": [ "PPD", "WEB", "TEL", "CCD" ], "description": "ACH standard entry class codes." }, "CheckDetails": { "type": "object", "title": "Check Details", "description": "Details about a check payment. Available for ACH transactions only.", "properties": { "check_account": { "type": "string", "description": "The customer's bank account number." }, "check_aba": { "type": "string", "description": "The customer's bank routing number." }, "check_name": { "type": "string", "description": "The customer's name." }, "account_holder_type": { "$ref": "#/components/schemas/ACHAccountHolderType" }, "account_type": { "$ref": "#/components/schemas/ACHAccountType" }, "sec_code": { "$ref": "#/components/schemas/ACHSecCode" } } }, "EmvMetaData": { "type": "object", "title": "EMV Meta Data", "description": "Details about the EMV transaction", "properties": { "application_id": { "type": "string", "description": "EMV Application ID" }, "application_label": { "type": "string", "description": "EMV Application Label" }, "application_preferred_name": { "type": "string", "description": "EMV Application Preferred Name" }, "transaction_status_info": { "type": "string", "description": "Transaction Status Information" }, "application_pan_sequence_number": { "type": "string", "description": "EMV Application PAN Sequence Number" }, "customer_verification_method": { "type": "string", "enum": [ "signature", "offline_pin", "online_pin", "none", "offline_pin_signature", "consumer_device", "consumer_device_plus_signature", "" ], "description": "EMV Customer Verification Method" } } }, "TransactionAction": { "type": "object", "title": "Transaction Action", "description": "Transaction Action details", "properties": { "amount": { "type": "string", "description": "Amount of the transaction", "format": "decimal" }, "action_type": { "type": "string", "enum": [ "auth", "capture", "sale", "void", "refund", "credit", "return", "validate" ], "description": "Type of transaction" }, "date": { "type": "string", "format": "date-time", "description": "Date of the transaction" }, "success": { "type": "string", "enum": [ "0", "1" ], "description": "Transaction Success Flag (0 - Failed, 1 - Success)" }, "ip_address": { "type": "string", "description": "IP Address of the transaction", "format": "ipv4" }, "source": { "type": "string", "enum": [ "api", "batch_upload", "mobile", "quickclick", "quickbooks", "recurring", "swipe", "virtual_terminal", "internal" ], "description": "Source of the transaction" }, "api_method": { "type": "string", "description": "API Method used for the transaction (direct_post, ..)" }, "username": { "type": "string", "description": "Username" }, "response_text": { "type": "string", "enum": [ "APPROVED", "SUCCESS", "DECLINE" ], "description": "Transaction Response Text" }, "response_code": { "type": "string", "description": "Response Code (100 - OK, 200 - Declined)" }, "processor_response_text": { "type": "string", "description": "Processor Response Text" }, "processor_response_code": { "type": "string", "description": "Processor Response Code" }, "tap_to_mobile": { "type": "boolean", "description": "Tap to Mobile Flag" }, "device_license_number": { "type": "string", "description": "Mobile Device License Number" }, "device_nickname": { "type": "string", "description": "Mobile Device Nickname" } } }, "RecurringCardDetails": { "type": "object", "title": "Card Details", "description": "Details related to the credit card used in the transaction. Available for credit card transactions only.", "properties": { "cc_number": { "type": "string", "description": "Masked credit card number" }, "cc_exp": { "type": "string", "description": "Credit card expiration date" }, "cavv": { "type": "string", "description": "Cardholder Authentication Verification Value" }, "cavv_result": { "type": "string", "description": "Cardholder Authentication Verification Value result" }, "xid": { "type": "string", "description": "Cardholder authentication transaction id" }, "eci": { "type": "string", "enum": [ "01", "02", "05", "06", "07", "08", "09", "" ], "description": "Electronic Commerce Indicator" }, "avs_response": { "type": "string", "description": "Address Verification Service response" }, "csc_response": { "type": "string", "description": "Card Security Code response" }, "cardholder_auth": { "type": "string", "enum": [ "verified", "attempted", "" ], "description": "Cardholder Authentication response" }, "cc_start_date": { "type": "string", "description": "Credit card start date" }, "cc_issue_number": { "type": "string", "description": "Credit card issue number" }, "card_balance": { "type": "string", "description": "Card balance" }, "card_available_balance": { "type": "string", "description": "Card available balance" }, "entry_mode": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "5", "6", "7", "8", "" ], "description": "The type of transaction data to be processed.\n\n<details>\n<summary>Possible values:</summary>\n\n| Code | Description |\n|:------|:--------------------|\n| 0 | Unknown |\n| 1 | Invalid |\n| 2 | NFC MSD |\n| 3 | Swiped |\n| 4 | Keyed |\n| 5 | EMV ICC |\n| 6 | NFC EMV |\n| 7 | Keyed - Fallback |\n| 8 | Swiped - Fallback |\n</details>" }, "cc_bin": { "type": "string", "description": "Credit card BIN (first 6 digits)" }, "cc_type": { "type": "string", "description": "Credit card type (visa, ..)" } } }, "RecurringEventBody": { "type": "object", "title": "Subscription Event Body", "description": "Details about Subscription.", "required": [ "merchant", "features", "plan" ], "properties": { "merchant": { "$ref": "#/components/schemas/Merchant" }, "features": { "$ref": "#/components/schemas/Features" }, "subscription_id": { "type": "string", "description": "Subscription ID" }, "subscription_type": { "type": "string", "enum": [ "cc", "ck" ], "description": "Subscription Type (cc - Credit Card, ck - Check)" }, "processor_id": { "type": "string", "description": "Processor ID" }, "next_charge_date": { "type": "string", "format": "date", "description": "Next Charge Date" }, "completed_payments": { "type": "string", "format": "number", "description": "Completed Payments" }, "attempted_payments": { "type": "string", "format": "number", "description": "Attempted Payments" }, "remaining_payments": { "type": "string", "description": "Remaining Payments (`Until canceled` or number of remaining payments)" }, "ponumber": { "type": "string", "description": "PO Number" }, "order_id": { "type": "string", "description": "Order ID" }, "order_description": { "type": "string", "description": "Order Description" }, "shipping": { "type": "string", "description": "Shipping Details" }, "tax": { "type": "string", "description": "Tax Details" }, "website": { "type": "string", "description": "Website Details" }, "plan": { "type": "object", "title": "Plan", "description": "Plan Details", "properties": { "id": { "type": "string", "description": "Plan ID" }, "name": { "type": "string", "description": "Plan Name" }, "amount": { "type": "string", "description": "Plan Amount" }, "day_frequency": { "type": "string", "description": "Day Frequency" }, "payments": { "type": "string", "description": "Payments Details" }, "month_frequency": { "type": "string", "format": "number", "description": "Month Frequency" }, "day_of_month": { "type": "string", "format": "number", "description": "Day of Month" } } }, "billing_address": { "$ref": "#/components/schemas/BillingAddress" }, "card": { "$ref": "#/components/schemas/RecurringCardDetails" }, "check": { "$ref": "#/components/schemas/CheckDetails" } } }, "TransactionSummary": { "type": "object", "title": "Transactions summary", "description": "Summary (number of transactions and total amount)", "properties": { "count": { "type": "integer", "format": "int64", "description": "Transactions Count" }, "amount": { "type": "string", "format": "number", "description": "Transactions Amount" } } }, "SettlementEventBody": { "type": "object", "title": "Settlement Event Body", "description": "Details about Settlement.", "required": [ "batch_id", "merchant", "processor" ], "properties": { "batch_id": { "type": "string", "format": "int64", "description": "Batch ID" }, "merchant": { "$ref": "#/components/schemas/Merchant" }, "processor": { "type": "object", "title": "Processor", "description": "Processor Details", "properties": { "id": { "type": "string", "description": "Processor ID" }, "name": { "type": "string", "description": "Processor Name" }, "type": { "type": "string", "enum": [ "cc", "ck" ], "description": "Processor Type (cc - Credit Card, ck - Check)" } } }, "count": { "type": "integer", "format": "int64", "description": "Transactions Count" }, "amount": { "type": "string", "format": "number", "description": "Transactions Amount" }, "transaction_ids": { "type": "array", "description": "Transaction IDs", "items": { "type": "string", "description": "Transaction ID" } }, "by_card_type": { "type": "object", "title": "By Card Type", "description": "Transactions by Card Type", "properties": { "visa": { "$ref": "#/components/schemas/TransactionSummary" }, "mastercard": { "$ref": "#/components/schemas/TransactionSummary" }, "amex": { "$ref": "#/components/schemas/TransactionSummary" }, "discover": { "$ref": "#/components/schemas/TransactionSummary" }, "diners": { "$ref": "#/components/schemas/TransactionSummary" }, "jcb": { "$ref": "#/components/schemas/TransactionSummary" }, "maestro": { "$ref": "#/components/schemas/TransactionSummary" }, "ebt": { "$ref": "#/components/schemas/TransactionSummary" } }, "additionalProperties": { "type": "object", "description": "Other card types" } } } }, "AcuCustomerVaultDetails": { "type": "object", "description": "Details about a customer vault card with updated expiration date.", "properties": { "customer_vault_id": { "type": "string", "description": "The ID of the customer vault." }, "billing_id": { "type": "string", "description": "The billing ID of the customer." }, "cc_number": { "type": "string", "description": "The masked credit card number." }, "cc_exp": { "type": "string", "description": "The updated expiration date of the credit card." }, "first_name": { "type": "string", "description": "The first name of the customer." }, "last_name": { "type": "string", "description": "The last name of the customer." }, "email": { "type": "string", "description": "The email address of the customer." }, "phone": { "type": "string", "description": "The phone number of the customer." } } }, "AcuSubscriptionDetails": { "type": "object", "description": "Details about a recurring card that was updated.", "properties": { "subscription_id": { "type": "string", "description": "The ID of the subscription." }, "cc_number": { "type": "string", "description": "The masked credit card number." }, "cc_exp": { "type": "string", "description": "The expiration date of the credit card." }, "first_name": { "type": "string", "description": "The first name of the customer." }, "last_name": { "type": "string", "description": "The last name of the customer." }, "email": { "type": "string", "description": "The email address of the customer." }, "phone": { "type": "string", "description": "The phone number of the customer." } } }, "AcuAutoUpdatedEventBody": { "type": "object", "title": "ACU Automatically Updated Event Body", "description": "Details about ACU Automatically Updated Event.", "required": [ "updated_date", "merchant", "cards_checked" ], "properties": { "updated_date": { "type": "string", "format": "date", "description": "The update date." }, "merchant": { "type": "object", "title": "Merchant", "description": "Merchant Details", "properties": { "id": { "type": "integer", "description": "Merchant identifier" }, "name": { "type": "string", "description": "Merchant name" } } }, "cards_checked": { "type": "object", "description": "Details about the cards that were checked.", "properties": { "customer_vault": { "type": "object", "description": "Details about the customer vault cards that were checked.", "properties": { "checked": { "type": "integer", "description": "The number of customer vault cards that were checked." }, "updated": { "type": "integer", "description": "The number of customer vault cards that were updated." } } }, "subscriptions": { "type": "object", "description": "Details about the subscription cards that were checked.", "properties": { "checked": { "type": "integer", "description": "The number of subscription cards that were checked." }, "updated": { "type": "integer", "description": "The number of subscription cards that were updated." } } } } }, "vault_count_updated_cards": { "type": "integer", "description": "The number of customer vault cards that were updated." }, "vault_updated_cards": { "type": "array", "description": "Details about the customer vault cards that were updated.", "items": { "$ref": "#/components/schemas/AcuCustomerVaultDetails" } }, "vault_count_updated_expiration_dates": { "type": "integer", "description": "The number of customer vault cards with updated expiration dates." }, "vault_updated_expiration_dates": { "type": "array", "description": "Details about the customer vault cards with updated expiration dates.", "items": { "$ref": "#/components/schemas/AcuCustomerVaultDetails" } }, "recurring_count_updated_cards": { "type": "integer", "description": "The number of recurring cards that were updated." }, "recurring_updated_cards": { "type": "array", "description": "Details about the recurring cards that were updated.", "items": { "$ref": "#/components/schemas/AcuSubscriptionDetails" } }, "recurring_count_updated_expiration_dates": { "type": "integer", "description": "The number of recurring cards with updated expiration dates." }, "recurring_updated_expiration_dates": { "type": "array", "description": "Details about the recurring cards with updated expiration dates.", "items": { "$ref": "#/components/schemas/AcuSubscriptionDetails" } } } }, "AcuClosedAccountEventBody": { "type": "object", "title": "ACU Closed Account Event Body", "description": "Details about ACU Closed Account Event.", "required": [ "updated_date", "merchant", "cards_checked" ], "properties": { "updated_date": { "type": "string", "format": "date", "description": "The update date." }, "merchant": { "type": "object", "description": "Details about the merchant.", "properties": { "id": { "type": "integer", "description": "The ID of the merchant." }, "name": { "type": "string", "description": "The name of the merchant." } } }, "cards_checked": { "type": "object", "description": "Details about the cards checked.", "properties": { "customer_vault": { "type": "object", "description": "Details about the customer vault.", "properties": { "checked": { "type": "integer", "description": "The number of customer vaults checked." }, "updated": { "type": "integer", "description": "The number of customer vaults updated." } } }, "subscriptions": { "type": "object", "description": "Details about the subscriptions.", "properties": { "checked": { "type": "integer", "description": "The number of subscriptions checked." }, "updated": { "type": "integer", "description": "The number of subscriptions updated." } } } } }, "vault_count_updated_closed_account": { "type": "integer", "description": "The number of vaults updated for the closed account." }, "vault_updates": { "type": "array", "description": "Details about the vault updates.", "items": { "$ref": "#/components/schemas/AcuCustomerVaultDetails" } }, "recurring_count_updated_closed_account": { "type": "integer", "description": "The number of recurring payments updated for the closed account." }, "recurring_updates": { "type": "array", "description": "Details about the recurring payment updates.", "items": { "$ref": "#/components/schemas/AcuSubscriptionDetails" } } } }, "AcuContactCustomerEventBody": { "type": "object", "title": "ACU Contact Customer Event Body", "description": "Details about ACU Contact Customer Event.", "required": [ "updated_date", "merchant", "cards_checked" ], "properties": { "updated_date": { "type": "string", "format": "date", "description": "The date when the event was updated." }, "merchant": { "type": "object", "description": "Details about the merchant.", "required": [ "id", "name" ], "properties": { "id": { "type": "integer", "description": "The ID of the merchant." }, "name": { "type": "string", "description": "The name of the merchant." } } }, "cards_checked": { "type": "object", "description": "Details about the cards checked.", "required": [ "customer_vault", "subscriptions" ], "properties": { "customer_vault": { "type": "object", "description": "Details about the customer vault.", "required": [ "checked", "updated" ], "properties": { "checked": { "type": "integer", "description": "The number of customer vaults checked." }, "updated": { "type": "integer", "description": "The number of customer vaults updated." } } }, "subscriptions": { "type": "object", "description": "Details about the subscriptions.", "required": [ "checked", "updated" ], "properties": { "checked": { "type": "integer", "description": "The number of subscriptions checked." }, "updated": { "type": "integer", "description": "The number of subscriptions updated." } } } } }, "vault_count_updated_contact_customer": { "type": "integer", "description": "The number of vaults updated." }, "vault_updates": { "type": "array", "description": "Details about the vault updates.", "items": { "$ref": "#/components/schemas/AcuCustomerVaultDetails" } }, "recurring_count_updated_contact_customer": { "type": "integer", "description": "The number of recurring subscriptions updated." }, "recurring_updates": { "type": "array", "description": "Details about the recurring subscriptions updates.", "items": { "$ref": "#/components/schemas/AcuSubscriptionDetails" } } } } }, "parameters": { "WebhookSignature": { "name": "Webhook-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Signature to validate the webhook event." } }, "responses": { "BadRequest": { "description": "Bad Request - The request was malformed or contained invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing what was wrong with the request" }, "code": { "type": "string", "description": "Error code for programmatic handling" } } }, "example": { "error": "Invalid request parameters", "code": "BAD_REQUEST" } } } }, "Unauthorized": { "description": "Unauthorized - Authentication credentials were missing or invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing the authentication failure" }, "code": { "type": "string", "description": "Error code for programmatic handling" } } }, "example": { "error": "Invalid or missing API key", "code": "UNAUTHORIZED" } } } }, "NotFound": { "description": "Not Found - The requested resource could not be found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing what resource was not found" }, "code": { "type": "string", "description": "Error code for programmatic handling" } } }, "example": { "error": "Resource not found", "code": "NOT_FOUND" } } } }, "InternalServerError": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing the server error" }, "code": { "type": "string", "description": "Error code for programmatic handling" } } }, "example": { "error": "An unexpected error occurred", "code": "INTERNAL_SERVER_ERROR" } } } } } } true
Integration checks
Validate the request against its selected schema before submission. Keep secrets outside browser code. Test permitted and denied account access, validation failures and interrupted responses in the sandbox. Account-management or messaging operations require the corresponding partner access and intended recipient context.