Get
GET /v5/payments/{payment_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 details for a specific payment by payment ID. GET /v5/payments/{payment_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/payments/{payment_id}' \ --header 'Authorization: <merchantApiKey>' const response = await fetch("https://sandbox.nmi.com/api/v5/payments/{payment_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/payments/{payment_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/payments/{payment_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/payments/{payment_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 payment_id path true string The payment ID to retrieve [ { "name": "payment_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The payment ID to retrieve" } ] 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 Success 401 No response media type declared Unauthorized 404 application/json Transaction not found { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Transaction not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } true
Response fields · 200 · application/json
Field Type Required Description Constraints object string yes Resource type identifier enum: ["transaction"] id string yes Payment ID type string no Customer's payment type (e.g., 'cc', 'ck', 'cs') amount string no Payment amount. Format: `x.xx` currency string no Payment currency (ISO 4217) auth_code string no Authorization code avs_response string no Address Verification Service response code cvv_response string no Card Verification Value response customer_vault_id string no Customer vault ID associated with the payment status string no Payment status response string no Response code: 1 = approved, 2 = declined, 3 = error enum: ["1", "2", "3"] response_text string no Textual description of the operation's result response_code string no Processor response code processor_id string no Processor ID used for the payment created_date string no Payment creation date in UTC ISO 8601 format format: "date-time" updated_date string no Payment last update date in UTC ISO 8601 format format: "date-time" signature_image string no Base64 encoded cardholder signature image. Omitted when no signature was captured. Returned on get and list when the payment was loaded with signature data. merchant_defined_fields object no Custom fields configured in the merchant control panel under Settings → Merchant Defined Fields (`field_1` through `field_20`). merchant_defined_fields.field_1 string no Merchant defined field 1 maxLength: 255 merchant_defined_fields.field_2 string no Merchant defined field 2 maxLength: 255 merchant_defined_fields.field_3 string no Merchant defined field 3 maxLength: 255 merchant_defined_fields.field_4 string no Merchant defined field 4 maxLength: 255 merchant_defined_fields.field_5 string no Merchant defined field 5 maxLength: 255 merchant_defined_fields.field_6 string no Merchant defined field 6 maxLength: 255 merchant_defined_fields.field_7 string no Merchant defined field 7 maxLength: 255 merchant_defined_fields.field_8 string no Merchant defined field 8 maxLength: 255 merchant_defined_fields.field_9 string no Merchant defined field 9 maxLength: 255 merchant_defined_fields.field_10 string no Merchant defined field 10 maxLength: 255 merchant_defined_fields.field_11 string no Merchant defined field 11 maxLength: 255 merchant_defined_fields.field_12 string no Merchant defined field 12 maxLength: 255 merchant_defined_fields.field_13 string no Merchant defined field 13 maxLength: 255 merchant_defined_fields.field_14 string no Merchant defined field 14 maxLength: 255 merchant_defined_fields.field_15 string no Merchant defined field 15 maxLength: 255 merchant_defined_fields.field_16 string no Merchant defined field 16 maxLength: 255 merchant_defined_fields.field_17 string no Merchant defined field 17 maxLength: 255 merchant_defined_fields.field_18 string no Merchant defined field 18 maxLength: 255 merchant_defined_fields.field_19 string no Merchant defined field 19 maxLength: 255 merchant_defined_fields.field_20 string no Merchant defined field 20 maxLength: 255 payment_details object no Payment method details (card or check) payment_details.card_number string no Masked credit card number payment_details.card_exp string no Credit card expiration date. Format: `MMYY` payment_details.card_hash string no Card hash payment_details.card_type string no Card type (e.g., 'Visa', 'Mastercard') payment_details.card_bin string no Card BIN (Bank Identification Number) payment_details.entry_mode string no Entry mode payment_details.cavv string no Cardholder Authentication Verification Value payment_details.cavv_result string no CAVV result payment_details.xid string no Identifier for 3D Secure payment_details.eci string no Electronic Commerce Indicator payment_details.card_start_date string no Card start date. Format: `MMYY` payment_details.card_issue_number string no Card issue number payment_details.cardholder_auth string no Cardholder authentication payment_details.check_account string no Masked check account number payment_details.check_aba string no Bank routing number payment_details.check_name string no Name on the check payment_details.account_type string no Account type enum: ["checking", "savings"] payment_details.account_holder_type string no Account holder type enum: ["personal", "business"] payment_details.sec_code string no Standard Entry Class code enum: ["PPD", "WEB", "TEL", "CCD", "POP", "RCK"] billing_address object no Billing address information billing_address.first_name string no First name billing_address.last_name string no Last name billing_address.company string no Company name billing_address.address1 string no Address line 1 billing_address.address2 string no Address line 2 billing_address.city string no City billing_address.state string no State or province billing_address.zip string no ZIP or postal code billing_address.country string no Country code (ISO 3166-1 alpha-2) billing_address.phone string no Phone number billing_address.cell_phone string no Cell phone number billing_address.email string no Email address format: "email" billing_address.fax string no Fax number shipping_address object no Shipping address information shipping_address.first_name string no First name shipping_address.last_name string no Last name shipping_address.company string no Company name shipping_address.address1 string no Address line 1 shipping_address.address2 string no Address line 2 shipping_address.city string no City shipping_address.state string no State or province shipping_address.zip string no ZIP or postal code shipping_address.country string no Country code (ISO 3166-1 alpha-2) shipping_address.email string no Email address format: "email" shipping_address.phone string no Phone number shipping_address.fax string no Fax number order_details object no Order details order_details.order_id string no Order ID order_details.ip_address string no IP address of cardholder order_details.order_description string no Order description order_details.customer_id string no Customer ID order_details.customer_tax_id string no Customer tax ID order_details.tax string no Tax amount. Format: `x.xx` order_details.shipping string no Shipping amount. Format: `x.xx` order_details.discount_amount string no Discount amount. Format: `x.xx` order_details.surcharge string no Surcharge amount. Format: `x.xx` order_details.tip string no Tip amount. Format: `x.xx` order_details.po_number string no Purchase order number order_details.shipping_carrier string no Shipping carrier order_details.tracking_number string no Tracking number order_details.shipping_date string no Shipping date in UTC ISO 8601 format format: "date-time" actions array no Array of actions for the payment actions[].id string no Action ID actions[].type string no Action type actions[].amount string no Action amount. Format: `x.xx` actions[].success boolean no Whether the action was successful actions[].response string no Response code: 1 = approved, 2 = declined, 3 = error enum: ["1", "2", "3"] actions[].response_text string no Response text actions[].response_code string no Response code actions[].auth_code string no Authorization code actions[].avs_response string no AVS response actions[].cvv_response string no CVV response actions[].processor_id string no Processor ID actions[].ip_address string no IP address actions[].user_id string no User ID who performed the action actions[].date string no Action date in UTC ISO 8601 format format: "date-time" actions[].source string no Source of the action
Response fields · 404 · application/json
Field Type Required Description Constraints type string yes Error type (e.g., 'validationError', 'internalError', 'authenticationError') error_code string yes Error code (e.g., 'E_INTERNAL', 'E_VALIDATION') message string yes Human-readable error message ref_id string no Reference ID for the error (transaction ID, etc.) details array no Validation error details details[].fieldName string yes Request field path. details[].message string yes Human-readable validation message for the field.
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": { "MerchantDefinedFields": { "type": "object", "title": "Merchant Defined Fields", "description": "Custom fields configured in the merchant control panel under Settings \u2192 Merchant Defined Fields (`field_1` through `field_20`).", "properties": { "field_1": { "type": "string", "maxLength": 255, "description": "Merchant defined field 1" }, "field_2": { "type": "string", "maxLength": 255, "description": "Merchant defined field 2" }, "field_3": { "type": "string", "maxLength": 255, "description": "Merchant defined field 3" }, "field_4": { "type": "string", "maxLength": 255, "description": "Merchant defined field 4" }, "field_5": { "type": "string", "maxLength": 255, "description": "Merchant defined field 5" }, "field_6": { "type": "string", "maxLength": 255, "description": "Merchant defined field 6" }, "field_7": { "type": "string", "maxLength": 255, "description": "Merchant defined field 7" }, "field_8": { "type": "string", "maxLength": 255, "description": "Merchant defined field 8" }, "field_9": { "type": "string", "maxLength": 255, "description": "Merchant defined field 9" }, "field_10": { "type": "string", "maxLength": 255, "description": "Merchant defined field 10" }, "field_11": { "type": "string", "maxLength": 255, "description": "Merchant defined field 11" }, "field_12": { "type": "string", "maxLength": 255, "description": "Merchant defined field 12" }, "field_13": { "type": "string", "maxLength": 255, "description": "Merchant defined field 13" }, "field_14": { "type": "string", "maxLength": 255, "description": "Merchant defined field 14" }, "field_15": { "type": "string", "maxLength": 255, "description": "Merchant defined field 15" }, "field_16": { "type": "string", "maxLength": 255, "description": "Merchant defined field 16" }, "field_17": { "type": "string", "maxLength": 255, "description": "Merchant defined field 17" }, "field_18": { "type": "string", "maxLength": 255, "description": "Merchant defined field 18" }, "field_19": { "type": "string", "maxLength": 255, "description": "Merchant defined field 19" }, "field_20": { "type": "string", "maxLength": 255, "description": "Merchant defined field 20" } } }, "TransactionResponse": { "type": "object", "title": "Payment Response", "description": "Generic payment response", "properties": { "object": { "type": "string", "enum": [ "transaction" ], "description": "Resource type identifier" }, "id": { "type": "string", "description": "Payment ID" }, "type": { "type": "string", "description": "Customer's payment type (e.g., 'cc', 'ck', 'cs')" }, "amount": { "type": "string", "description": "Payment amount. Format: `x.xx`" }, "currency": { "type": "string", "description": "Payment currency (ISO 4217)" }, "auth_code": { "type": "string", "description": "Authorization code" }, "avs_response": { "type": "string", "description": "Address Verification Service response code" }, "cvv_response": { "type": "string", "description": "Card Verification Value response" }, "customer_vault_id": { "type": "string", "description": "Customer vault ID associated with the payment" }, "status": { "type": "string", "description": "Payment status" }, "response": { "type": "string", "enum": [ "1", "2", "3" ], "description": "Response code: 1 = approved, 2 = declined, 3 = error" }, "response_text": { "type": "string", "description": "Textual description of the operation's result" }, "response_code": { "type": "string", "description": "Processor response code" }, "processor_id": { "type": "string", "description": "Processor ID used for the payment" }, "created_date": { "type": "string", "format": "date-time", "description": "Payment creation date in UTC ISO 8601 format" }, "updated_date": { "type": "string", "format": "date-time", "description": "Payment last update date in UTC ISO 8601 format" }, "signature_image": { "type": "string", "description": "Base64 encoded cardholder signature image. Omitted when no signature was captured. Returned on get and list when the payment was loaded with signature data." }, "merchant_defined_fields": { "$ref": "#/components/schemas/MerchantDefinedFields", "description": "Merchant defined fields stored with the payment (`field_1` through `field_20`). Only non-empty values are included; returns an empty object when none are set." }, "payment_details": { "type": "object", "description": "Payment method details (card or check)", "properties": { "card_number": { "type": "string", "description": "Masked credit card number" }, "card_exp": { "type": "string", "description": "Credit card expiration date. Format: `MMYY`" }, "card_hash": { "type": "string", "description": "Card hash" }, "card_type": { "type": "string", "description": "Card type (e.g., 'Visa', 'Mastercard')" }, "card_bin": { "type": "string", "description": "Card BIN (Bank Identification Number)" }, "entry_mode": { "type": "string", "description": "Entry mode" }, "cavv": { "type": "string", "description": "Cardholder Authentication Verification Value" }, "cavv_result": { "type": "string", "description": "CAVV result" }, "xid": { "type": "string", "description": "Identifier for 3D Secure" }, "eci": { "type": "string", "description": "Electronic Commerce Indicator" }, "card_start_date": { "type": "string", "description": "Card start date. Format: `MMYY`" }, "card_issue_number": { "type": "string", "description": "Card issue number" }, "cardholder_auth": { "type": "string", "description": "Cardholder authentication" }, "check_account": { "type": "string", "description": "Masked check account number" }, "check_aba": { "type": "string", "description": "Bank routing number" }, "check_name": { "type": "string", "description": "Name on the check" }, "account_type": { "type": "string", "enum": [ "checking", "savings" ], "description": "Account type" }, "account_holder_type": { "type": "string", "enum": [ "personal", "business" ], "description": "Account holder type" }, "sec_code": { "type": "string", "enum": [ "PPD", "WEB", "TEL", "CCD", "POP", "RCK" ], "description": "Standard Entry Class code" } } }, "billing_address": { "type": "object", "description": "Billing address information", "properties": { "first_name": { "type": "string", "description": "First name" }, "last_name": { "type": "string", "description": "Last name" }, "company": { "type": "string", "description": "Company name" }, "address1": { "type": "string", "description": "Address line 1" }, "address2": { "type": "string", "description": "Address line 2" }, "city": { "type": "string", "description": "City" }, "state": { "type": "string", "description": "State or province" }, "zip": { "type": "string", "description": "ZIP or postal code" }, "country": { "type": "string", "description": "Country code (ISO 3166-1 alpha-2)" }, "phone": { "type": "string", "description": "Phone number" }, "cell_phone": { "type": "string", "description": "Cell phone number" }, "email": { "type": "string", "format": "email", "description": "Email address" }, "fax": { "type": "string", "description": "Fax number" } } }, "shipping_address": { "type": "object", "description": "Shipping address information", "properties": { "first_name": { "type": "string", "description": "First name" }, "last_name": { "type": "string", "description": "Last name" }, "company": { "type": "string", "description": "Company name" }, "address1": { "type": "string", "description": "Address line 1" }, "address2": { "type": "string", "description": "Address line 2" }, "city": { "type": "string", "description": "City" }, "state": { "type": "string", "description": "State or province" }, "zip": { "type": "string", "description": "ZIP or postal code" }, "country": { "type": "string", "description": "Country code (ISO 3166-1 alpha-2)" }, "email": { "type": "string", "format": "email", "description": "Email address" }, "phone": { "type": "string", "description": "Phone number" }, "fax": { "type": "string", "description": "Fax number" } } }, "order_details": { "type": "object", "description": "Order details", "properties": { "order_id": { "type": "string", "description": "Order ID" }, "ip_address": { "type": "string", "description": "IP address of cardholder" }, "order_description": { "type": "string", "description": "Order description" }, "customer_id": { "type": "string", "description": "Customer ID" }, "customer_tax_id": { "type": "string", "description": "Customer tax ID" }, "tax": { "type": "string", "description": "Tax amount. Format: `x.xx`" }, "shipping": { "type": "string", "description": "Shipping amount. Format: `x.xx`" }, "discount_amount": { "type": "string", "description": "Discount amount. Format: `x.xx`" }, "surcharge": { "type": "string", "description": "Surcharge amount. Format: `x.xx`" }, "tip": { "type": "string", "description": "Tip amount. Format: `x.xx`" }, "po_number": { "type": "string", "description": "Purchase order number" }, "shipping_carrier": { "type": "string", "description": "Shipping carrier" }, "tracking_number": { "type": "string", "description": "Tracking number" }, "shipping_date": { "type": "string", "format": "date-time", "description": "Shipping date in UTC ISO 8601 format" } } }, "actions": { "type": "array", "description": "Array of actions for the payment", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Action ID" }, "type": { "type": "string", "description": "Action type" }, "amount": { "type": "string", "description": "Action amount. Format: `x.xx`" }, "success": { "type": "boolean", "description": "Whether the action was successful" }, "response": { "type": "string", "enum": [ "1", "2", "3" ], "description": "Response code: 1 = approved, 2 = declined, 3 = error" }, "response_text": { "type": "string", "description": "Response text" }, "response_code": { "type": "string", "description": "Response code" }, "auth_code": { "type": "string", "description": "Authorization code" }, "avs_response": { "type": "string", "description": "AVS response" }, "cvv_response": { "type": "string", "description": "CVV response" }, "processor_id": { "type": "string", "description": "Processor ID" }, "ip_address": { "type": "string", "description": "IP address" }, "user_id": { "type": "string", "description": "User ID who performed the action" }, "date": { "type": "string", "format": "date-time", "description": "Action date in UTC ISO 8601 format" }, "source": { "type": "string", "description": "Source of the action" } } } } }, "required": [ "object", "id" ] }, "ValidationErrorDetail": { "type": "object", "title": "Validation Error Detail", "description": "Validation error detail", "required": [ "fieldName", "message" ], "properties": { "fieldName": { "type": "string", "description": "Request field path." }, "message": { "type": "string", "description": "Human-readable validation message for the field." } }, "additionalProperties": false }, "ErrorResponse": { "type": "object", "title": "Error Response", "description": "Error response structure matching SecureApiErrorResponseFactory", "properties": { "type": { "type": "string", "description": "Error type (e.g., 'validationError', 'internalError', 'authenticationError')" }, "error_code": { "type": "string", "description": "Error code (e.g., 'E_INTERNAL', 'E_VALIDATION')" }, "message": { "type": "string", "description": "Human-readable error message" }, "ref_id": { "type": "string", "nullable": true, "description": "Reference ID for the error (transaction ID, etc.)" }, "details": { "type": "array", "nullable": true, "description": "Validation error details", "items": { "$ref": "#/components/schemas/ValidationErrorDetail" } } }, "required": [ "type", "error_code", "message" ] }, "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." } } } 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.