Update Subscription
PUT /v5/subscriptions/{subscription_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
Update an existing subscription's billing information. PUT /v5/subscriptions/{subscription_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. Save one valid request variant from the fields/examples below as request.json. Do not combine mutually exclusive variants. The payload is deliberately not fabricated from schema defaults. Node requires a runtime with fetch; PHP requires cURL. Generated source-based examples have not been executed against provider accounts. curl --request PUT \ --url 'https://sandbox.nmi.com/api/v5/subscriptions/{subscription_id}' \ --header 'Authorization: <merchantApiKey>' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' import { readFile } from 'node:fs/promises'; const body = await readFile('request.json', 'utf8'); const response = await fetch("https://sandbox.nmi.com/api/v5/subscriptions/{subscription_id}", { method: 'PUT', headers: { "Authorization": "<merchantApiKey>", "Content-Type": "application/json" }, body }); console.log(response.status, await response.text()); from urllib.request import Request, urlopen from urllib.error import HTTPError from pathlib import Path request = Request('https://sandbox.nmi.com/api/v5/subscriptions/{subscription_id}', method='PUT', headers={'Authorization': '<merchantApiKey>', 'Content-Type': 'application/json'}, data=Path('request.json').read_bytes()) 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/subscriptions/{subscription_id}") request = Net::HTTP::Put.new(uri) request["Authorization"] = "<merchantApiKey>" request["Content-Type"] = "application/json" request.body = File.binread('request.json') 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/subscriptions/{subscription_id}'); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => 'PUT', CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => ['Authorization: <merchantApiKey>', 'Content-Type: application/json'], CURLOPT_POSTFIELDS => file_get_contents('request.json') ]); $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 subscription_id path true integer The subscription ID to update [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The subscription ID to update" } ] true
Request body
Use the declared media type: application/json. Required flags below apply within the selected object or variant. Read the workflow notes before choosing a variant. Field Type Required Description Constraints plan_amount number no The plan amount to be charged each billing cycle. Format: `x.xx` minimum: 0 plan_payments integer no The number of payments before the recurring plan is complete. Use '0' for until canceled minimum: 0; maximum: 999 day_frequency integer no How often, in days, to charge the customer. Cannot be set with 'month_frequency' or 'day_of_month' minimum: 1 month_frequency integer no How often, in months, to charge the customer. Cannot be set with 'day_frequency'. Must be set with 'day_of_month' minimum: 1 day_of_month integer no The day that the customer will be charged. Cannot be set with 'day_frequency'. Must be set with 'month_frequency' minimum: 1; maximum: 31 paused_subscription boolean no If set to true, the subscription will be paused start_date string no The date the subscription's next/first charge occurs. Format: `YYYYMMDD` (optionally `YYYYMMDDHHMMSS`). minLength: 8; maxLength: 14; pattern: "^(\\d{8}|\\d{14})$" payment_details variant no Payment method details. Exactly one variant: raw card data, ACH (check) data, **payment_token**, wallet payloads, or **retail card-present** data from a card reader. Do not combine fields from different variants. payment_details.[Credit card].card_number string yes Credit card number payment_details.[Credit card].card_exp string yes Credit card expiration date. Format: `MMYY` payment_details.[Credit card].card_cvv string no The card security code. maxLength: 4 payment_details.[oneOf 2].track_1 string yes Raw magnetic stripe data. payment_details.[oneOf 2].track_2 string yes Raw magnetic stripe data. payment_details.[oneOf 2].track_3 string no Raw magnetic stripe data. payment_details.[oneOf 3].magnesafe_track_1 string yes Raw MagTek Magensa data. payment_details.[oneOf 3].magnesafe_track_2 string yes Raw MagTek Magensa data. payment_details.[oneOf 3].magnesafe_magneprint string no Raw MagTek Magensa data. payment_details.[oneOf 3].magnesafe_ksn string no Raw MagTek Magensa data. payment_details.[oneOf 3].magnesafe_magneprint_status string no Raw MagTek Magensa data. payment_details.[oneOf 4].encrypted_track_1 string yes Raw encrypted data. payment_details.[oneOf 4].encrypted_track_2 string yes Raw encrypted data. payment_details.[oneOf 4].encrypted_track_3 string no Raw encrypted data. payment_details.[oneOf 4].encrypted_ksn string no Raw encrypted data. payment_details.[oneOf 5].encrypted_data string yes Raw encrypted data. payment_details.[oneOf 6].entry_mode string yes The type of transaction data to be processed. enum: ["emv_icc"] payment_details.[oneOf 6].emv_auth_request_data string yes EMV data for the transaction as received from the EMV chip card SDK. payment_details.[oneOf 6].emv_device string yes The EMV-capable card reader. enum: ["ingenico_rba"] payment_details.[oneOf 6].verification_method string yes Method used to verify the EMV transaction. enum: ["signature", "offline_pin", "offline_pin_signature", "none"] payment_details.[oneOf 6].encrypted_ksn string yes Raw encrypted data. payment_details.[oneOf 6].encrypted_track_2 string yes Raw encrypted data. payment_details.[oneOf 7].entry_mode string yes The type of transaction data to be processed. enum: ["swiped", "swiped_emv_fallback"] payment_details.[oneOf 7].emv_device string yes The EMV-capable card reader. enum: ["ingenico_rba"] payment_details.[oneOf 7].encrypted_ksn string yes Raw encrypted data. payment_details.[oneOf 7].encrypted_track_1 string yes Raw encrypted data. payment_details.[oneOf 7].encrypted_track_2 string yes Raw encrypted data. payment_details.[oneOf 8].entry_mode string yes The type of transaction data to be processed. enum: ["nfc_msd"] payment_details.[oneOf 8].emv_device string yes The EMV-capable card reader. enum: ["ingenico_rba"] payment_details.[oneOf 8].encrypted_ksn string yes Raw encrypted data. payment_details.[oneOf 8].encrypted_track_2 string yes Raw encrypted data. payment_details.[oneOf 9].entry_mode string yes The type of transaction data to be processed. enum: ["keyed"] payment_details.[oneOf 9].emv_device string yes The EMV-capable card reader. enum: ["ingenico_rba"] payment_details.[oneOf 9].encrypted_ksn string yes Raw encrypted data. payment_details.[oneOf 9].encrypted_track_2 string yes Raw encrypted data. payment_details.[oneOf 10].encrypted_payment string yes Encrypted payment blob returned by the Mobile SDK. payment_details.[ACH / check].check_name string yes The name on the customer's ACH account maxLength: 50 payment_details.[ACH / check].check_aba number yes The customer's bank routing number payment_details.[ACH / check].check_account number yes The customer's bank account number payment_details.[ACH / check].account_type string yes The type of ACH account the customer has enum: ["checking", "savings"] payment_details.[ACH / check].account_holder_type string yes The type of ACH account the customer has enum: ["personal", "business"] payment_details.[ACH / check].sec_code string yes The Standard Entry Class code of the ACH transaction enum: ["PPD", "WEB", "TEL", "CCD", "POP", "RCK"] payment_details.[ACH / check].check_number string no Check number maxLength: 20 payment_details.[Payment token].payment_token string yes The tokenized version of the customer's card or check information payment_details.[Apple Pay].applepay_payment_data string yes The encrypted token created when integration directly to the Apple Pay SDK payment_details.[Google Pay].googlepay_payment_data string yes The encrypted token created when integration directly to the Google Pay SDK payment_details.[Decrypted Apple Pay].decrypted_applepay_data boolean yes Set to `true` when submitting merchant-decrypted Apple Pay data. enum: [true] payment_details.[Decrypted Apple Pay].card_number string yes Credit card number payment_details.[Decrypted Apple Pay].card_exp string yes Credit card expiration date. Format: `MMYY` payment_details.[Decrypted Google Pay].decrypted_googlepay_data boolean yes Set to `true` when submitting merchant-decrypted Google Pay data. enum: [true] payment_details.[Decrypted Google Pay].card_number string yes Credit card number payment_details.[Decrypted Google Pay].card_exp string yes Credit card expiration date. Format: `MMYY` billing_address object no Billing address for a payment transaction request. billing_address.method string no Recurring or installment classification for the processor. - `initial_recurring`: First transaction in a recurring sequence only. - `recurring`: Later charges in that sequence. - `installment`: Installment transactions; use `number` and `total` on supported processors. Which values apply depends on the processor. enum: ["initial_recurring", "recurring", "installment"] billing_address.number integer no Specify installment billing number, on supported processors. For use when `billing.method` is set to "installment" minimum: 0; maximum: 99 billing_address.total number no Specify installment billing total on supported processors. For use when `billing.method` is set to "installment" minimum: 0 billing_address.first_name string no Cardholder's first name maxLength: 50 billing_address.last_name string no Cardholder's last name maxLength: 50 billing_address.company string no Cardholder's company maxLength: 100 billing_address.address1 string no Card billing address maxLength: 100 billing_address.address2 string no Card billing address, line 2 maxLength: 100 billing_address.city string no Card billing city maxLength: 50 billing_address.state string no Card billing state. Format: `CC` maxLength: 50 billing_address.zip string no Card billing zip code maxLength: 20 billing_address.country string no Card billing country. Country codes are as shown in ISO 3166-1 alpha-2. Format: `CC` maxLength: 2 billing_address.phone string no Billing phone number billing_address.email string no Billing email address format: "email" billing_address.fax string no Billing fax number maxLength: 50 billing_address.cell_phone string no Billing cell phone number billing_address.website string no Website (invoice-specific field) maxLength: 255 billing_address.drivers_license_number string no Driver's license number maxLength: 20 billing_address.drivers_license_dob string no Driver's license date of birth. Format: `YYYY-MM-DD` pattern: "^\\d{4}-\\d{2}-\\d{2}$" billing_address.drivers_license_state string no Driver's license state. Format: `CC` maxLength: 2 billing_address.payment_details variant no Payment method details. Exactly one variant: raw card data, ACH (check) data, **payment_token**, wallet payloads, or **retail card-present** data from a card reader. Do not combine fields from different variants. billing_address.payment_details.[Credit card].card_number string yes Credit card number billing_address.payment_details.[Credit card].card_exp string yes Credit card expiration date. Format: `MMYY` billing_address.payment_details.[Credit card].card_cvv string no The card security code. maxLength: 4 billing_address.payment_details.[oneOf 2].track_1 string yes Raw magnetic stripe data. billing_address.payment_details.[oneOf 2].track_2 string yes Raw magnetic stripe data. billing_address.payment_details.[oneOf 2].track_3 string no Raw magnetic stripe data. billing_address.payment_details.[oneOf 3].magnesafe_track_1 string yes Raw MagTek Magensa data. billing_address.payment_details.[oneOf 3].magnesafe_track_2 string yes Raw MagTek Magensa data. billing_address.payment_details.[oneOf 3].magnesafe_magneprint string no Raw MagTek Magensa data. billing_address.payment_details.[oneOf 3].magnesafe_ksn string no Raw MagTek Magensa data. billing_address.payment_details.[oneOf 3].magnesafe_magneprint_status string no Raw MagTek Magensa data. billing_address.payment_details.[oneOf 4].encrypted_track_1 string yes Raw encrypted data. billing_address.payment_details.[oneOf 4].encrypted_track_2 string yes Raw encrypted data. billing_address.payment_details.[oneOf 4].encrypted_track_3 string no Raw encrypted data. billing_address.payment_details.[oneOf 4].encrypted_ksn string no Raw encrypted data. billing_address.payment_details.[oneOf 5].encrypted_data string yes Raw encrypted data. billing_address.payment_details.[oneOf 6].entry_mode string yes The type of transaction data to be processed. enum: ["emv_icc"] billing_address.payment_details.[oneOf 6].emv_auth_request_data string yes EMV data for the transaction as received from the EMV chip card SDK. billing_address.payment_details.[oneOf 6].emv_device string yes The EMV-capable card reader. enum: ["ingenico_rba"] billing_address.payment_details.[oneOf 6].verification_method string yes Method used to verify the EMV transaction. enum: ["signature", "offline_pin", "offline_pin_signature", "none"] billing_address.payment_details.[oneOf 6].encrypted_ksn string yes Raw encrypted data. billing_address.payment_details.[oneOf 6].encrypted_track_2 string yes Raw encrypted data. billing_address.payment_details.[oneOf 7].entry_mode string yes The type of transaction data to be processed. enum: ["swiped", "swiped_emv_fallback"] billing_address.payment_details.[oneOf 7].emv_device string yes The EMV-capable card reader. enum: ["ingenico_rba"] billing_address.payment_details.[oneOf 7].encrypted_ksn string yes Raw encrypted data. billing_address.payment_details.[oneOf 7].encrypted_track_1 string yes Raw encrypted data. billing_address.payment_details.[oneOf 7].encrypted_track_2 string yes Raw encrypted data. billing_address.payment_details.[oneOf 8].entry_mode string yes The type of transaction data to be processed. enum: ["nfc_msd"] billing_address.payment_details.[oneOf 8].emv_device string yes The EMV-capable card reader. enum: ["ingenico_rba"] billing_address.payment_details.[oneOf 8].encrypted_ksn string yes Raw encrypted data. billing_address.payment_details.[oneOf 8].encrypted_track_2 string yes Raw encrypted data. billing_address.payment_details.[oneOf 9].entry_mode string yes The type of transaction data to be processed. enum: ["keyed"] billing_address.payment_details.[oneOf 9].emv_device string yes The EMV-capable card reader. enum: ["ingenico_rba"] billing_address.payment_details.[oneOf 9].encrypted_ksn string yes Raw encrypted data. billing_address.payment_details.[oneOf 9].encrypted_track_2 string yes Raw encrypted data. billing_address.payment_details.[oneOf 10].encrypted_payment string yes Encrypted payment blob returned by the Mobile SDK. billing_address.payment_details.[ACH / check].check_name string yes The name on the customer's ACH account maxLength: 50 billing_address.payment_details.[ACH / check].check_aba number yes The customer's bank routing number billing_address.payment_details.[ACH / check].check_account number yes The customer's bank account number billing_address.payment_details.[ACH / check].account_type string yes The type of ACH account the customer has enum: ["checking", "savings"] billing_address.payment_details.[ACH / check].account_holder_type string yes The type of ACH account the customer has enum: ["personal", "business"] billing_address.payment_details.[ACH / check].sec_code string yes The Standard Entry Class code of the ACH transaction enum: ["PPD", "WEB", "TEL", "CCD", "POP", "RCK"] billing_address.payment_details.[ACH / check].check_number string no Check number maxLength: 20 billing_address.payment_details.[Payment token].payment_token string yes The tokenized version of the customer's card or check information billing_address.payment_details.[Apple Pay].applepay_payment_data string yes The encrypted token created when integration directly to the Apple Pay SDK billing_address.payment_details.[Google Pay].googlepay_payment_data string yes The encrypted token created when integration directly to the Google Pay SDK billing_address.payment_details.[Decrypted Apple Pay].decrypted_applepay_data boolean yes Set to `true` when submitting merchant-decrypted Apple Pay data. enum: [true] billing_address.payment_details.[Decrypted Apple Pay].card_number string yes Credit card number billing_address.payment_details.[Decrypted Apple Pay].card_exp string yes Credit card expiration date. Format: `MMYY` billing_address.payment_details.[Decrypted Google Pay].decrypted_googlepay_data boolean yes Set to `true` when submitting merchant-decrypted Google Pay data. enum: [true] billing_address.payment_details.[Decrypted Google Pay].card_number string yes Credit card number billing_address.payment_details.[Decrypted Google Pay].card_exp string yes Credit card expiration date. Format: `MMYY` billing_address.cardholder_auth object no Cardholder authentication data. Use the 3-D Secure variant for EMV authentication results. Use the Decrypted wallet variant for merchant-decrypted Apple Pay or Google Pay, which relays the cryptogram and ECI to the 3-D Secure fields. billing_address.cardholder_auth.[3-D Secure].status string yes Set 3D Secure condition. Value used to determine E-commerce indicator (ECI). enum: ["verified", "attempted"] billing_address.cardholder_auth.[3-D Secure].cavv string yes Cardholder authentication verification value from the 3-D Secure authentication response. Format: base64 encoded. maxLength: 50 billing_address.cardholder_auth.[3-D Secure].xid string no Cardholder authentication transaction id. Format: base64 encoded. maxLength: 50 billing_address.cardholder_auth.[3-D Secure].three_ds_version string no 3DSecure version (for example `2.1.0` or `2.2.0`). maxLength: 10 billing_address.cardholder_auth.[3-D Secure].directory_server_id string no Directory Server Transaction ID from 3DSecure 2.0 authentication. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx maxLength: 50 billing_address.cardholder_auth.[Decrypted wallet (Apple Pay / Google Pay)].cavv string yes Wallet payment cryptogram (submitted in the repurposed 3-D Secure `cavv` field). maxLength: 50 billing_address.cardholder_auth.[Decrypted wallet (Apple Pay / Google Pay)].eci string no Electronic Commerce Indicator from the wallet payment data (submitted in the repurposed 3-D Secure `eci` field). maxLength: 10 shipping_address object no Shipping address and information shipping_address.id string no Shipping address ID (max 32 characters). Generated if omitted on create. maxLength: 32 shipping_address.first_name string no Shipping first name maxLength: 50 shipping_address.last_name string no Shipping last name maxLength: 50 shipping_address.company string no Shipping company maxLength: 100 shipping_address.address1 string no Shipping address maxLength: 100 shipping_address.address2 string no Shipping address, line 2 maxLength: 100 shipping_address.city string no Shipping city maxLength: 50 shipping_address.state string no Shipping state. maxLength: 50 shipping_address.zip string no Shipping zip code maxLength: 20 shipping_address.country string no ISO 3166-1 alpha-2 country code. Example: `US` maxLength: 2 shipping_address.email string no Shipping email address format: "email" shipping_address.carrier string no Shipping carrier enum: ["ups", "fedex", "dhl", "usps"] order_details object no Order details and line items order_details.template_id string no Order template ID maxLength: 50 order_details.description string no Order description maxLength: 100 order_details.id string no Order ID (for payment requests) maxLength: 50 order_details.order_id string no Order ID (for invoice requests and responses) maxLength: 255 order_details.customer_id string no Customer ID (invoice-specific) maxLength: 255 order_details.customer_tax_id string no Customer tax ID (invoice-specific) maxLength: 255 order_details.tax number no Tax amount minimum: 0 order_details.shipping number no Shipping amount minimum: 0 order_details.po_number string no Purchase order number (maxLength 50 for payments, 255 for invoices) maxLength: 255 order_details.shipping_postal_code string no Shipping postal code maxLength: 20 order_details.ship_from_postal_code string no Ship from postal code maxLength: 20 order_details.summary_commodity_code string no Summary commodity code maxLength: 50 order_details.duty_amount number no Duty amount minimum: 0 order_details.discount_amount number no Discount amount minimum: 0 order_details.national_tax_amount number no National tax amount minimum: 0 order_details.alternate_tax_amount number no Alternate tax amount minimum: 0 order_details.alternate_tax_id string no Alternate tax ID maxLength: 50 order_details.vat_tax_amount number no VAT tax amount minimum: 0 order_details.vat_tax_rate number no VAT tax rate minimum: 0 order_details.vat_invoice_reference_number string no VAT invoice reference number maxLength: 50 order_details.customer_vat_registration string no Customer VAT registration maxLength: 50 order_details.merchant_vat_registration string no Merchant VAT registration maxLength: 50 order_details.order_date string no Order date format: "date" order_details.order_description string no Order description (maxLength 255 for both payments and invoices) maxLength: 255 order_details.ip_address string no IP address of cardholder (IPv4 or IPv6). Format validated as IP address order_details.line_items array no order_details.line_items[].product_code string no Product code maxLength: 50 order_details.line_items[].description string no Line item description maxLength: 255 order_details.line_items[].commodity_code string no Commodity code maxLength: 50 order_details.line_items[].unit_of_measure string no Unit of measure maxLength: 50 order_details.line_items[].unit_cost number no Unit cost minimum: 0 order_details.line_items[].quantity integer no Quantity minimum: 0; maximum: 999999 order_details.line_items[].total_amount number no Total amount minimum: 0 order_details.line_items[].tax_amount number no Tax amount minimum: 0 order_details.line_items[].tax_rate number no Tax rate minimum: 0 order_details.line_items[].discount_amount number no Discount amount minimum: 0 order_details.line_items[].discount_rate number no Discount rate minimum: 0 order_details.line_items[].tax_type string no Tax type maxLength: 50 order_details.line_items[].alternate_tax_id string no Alternate tax ID maxLength: 50 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 customer_vault variant no Either add a payment method to the vault, or use an existing vault record. customer_vault.[oneOf 1].add_to_vault boolean yes Set to `true` to store the payment method in the customer vault. customer_vault.[oneOf 1].id string no Optional custom customer vault ID (max 36 characters). Generated if omitted. maxLength: 36 customer_vault.[oneOf 2].id string yes Existing customer vault ID (max 36 characters). maxLength: 36 customer_vault.[oneOf 2].billing_id string no Billing profile ID to use. Defaults to the vault priority billing profile if omitted (max 32 characters). maxLength: 32 customer_vault.[oneOf 2].shipping_id string no Shipping profile ID to use. Defaults to the vault priority shipping profile if omitted (max 32 characters). maxLength: 32 cardholder_auth object no Cardholder authentication data. Use the 3-D Secure variant for EMV authentication results. Use the Decrypted wallet variant for merchant-decrypted Apple Pay or Google Pay, which relays the cryptogram and ECI to the 3-D Secure fields. cardholder_auth.[3-D Secure].status string yes Set 3D Secure condition. Value used to determine E-commerce indicator (ECI). enum: ["verified", "attempted"] cardholder_auth.[3-D Secure].cavv string yes Cardholder authentication verification value from the 3-D Secure authentication response. Format: base64 encoded. maxLength: 50 cardholder_auth.[3-D Secure].xid string no Cardholder authentication transaction id. Format: base64 encoded. maxLength: 50 cardholder_auth.[3-D Secure].three_ds_version string no 3DSecure version (for example `2.1.0` or `2.2.0`). maxLength: 10 cardholder_auth.[3-D Secure].directory_server_id string no Directory Server Transaction ID from 3DSecure 2.0 authentication. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx maxLength: 50 cardholder_auth.[Decrypted wallet (Apple Pay / Google Pay)].cavv string yes Wallet payment cryptogram (submitted in the repurposed 3-D Secure `cavv` field). maxLength: 50 cardholder_auth.[Decrypted wallet (Apple Pay / Google Pay)].eci string no Electronic Commerce Indicator from the wallet payment data (submitted in the repurposed 3-D Secure `eci` field). maxLength: 10 { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionUpdateRequest" } } } } 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 400 application/json Bad Request - Validation Error 401 No response media type declared Unauthorized 404 application/json Subscription not found { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "400": { "description": "Bad Request - Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Subscription 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: ["subscription"] id string yes Subscription ID created_date string no Date the subscription was created, in UTC ISO 8601 format format: "date-time" start_date string no Subscription start date in UTC ISO 8601 format format: "date-time" next_billing_date string no Next billing date in UTC ISO 8601 format format: "date-time" amount string no Subscription amount customer_vault_id string no Customer vault ID associated with the subscription delayed_condition string no Delayed condition paused_subscription integer no Whether the subscription is paused (0 = active, 1 = paused) enum: [0, 1] plan object no Associated plan plan.id string no Plan ID plan.plan_name string no Plan name plan.plan_amount string no Plan amount plan.plan_payments string no Number of payments (0 = until canceled) plan.day_frequency string no Day frequency (0 if not applicable) plan.month_frequency string no Month frequency (0 if not applicable) plan.day_of_month string no Day of month (empty if not applicable)
Response fields · 400 · 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.
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" } } }, "RetailUnencryptedMagneticStripe": { "type": "object", "title": "Retail unencrypted magnetic stripe", "description": "Card-present payment using raw magnetic stripe data from a card reader. Set `industry` to `retail` on the payment request.", "additionalProperties": false, "required": [ "track_1", "track_2" ], "properties": { "track_1": { "type": "string", "description": "Raw magnetic stripe data." }, "track_2": { "type": "string", "description": "Raw magnetic stripe data." }, "track_3": { "type": "string", "description": "Raw magnetic stripe data." } } }, "RetailMagTekMagensaEncryptedSwipe": { "type": "object", "title": "Retail MagTek Magensa encrypted swipe", "description": "Card-present payment using encrypted magnetic stripe data from a MagTek Magensa reader. Set `industry` to `retail` on the payment request.", "additionalProperties": false, "required": [ "magnesafe_track_1", "magnesafe_track_2" ], "properties": { "magnesafe_track_1": { "type": "string", "description": "Raw MagTek Magensa data." }, "magnesafe_track_2": { "type": "string", "description": "Raw MagTek Magensa data." }, "magnesafe_magneprint": { "type": "string", "description": "Raw MagTek Magensa data." }, "magnesafe_ksn": { "type": "string", "description": "Raw MagTek Magensa data." }, "magnesafe_magneprint_status": { "type": "string", "description": "Raw MagTek Magensa data." } } }, "RetailIdTechEncryptedSwipe": { "type": "object", "title": "Retail ID Tech M130 encrypted swipe", "description": "Card-present encrypted swipe data from an ID Tech M130 reader. Set `industry` to `retail` on the payment request.", "additionalProperties": false, "required": [ "encrypted_track_1", "encrypted_track_2" ], "properties": { "encrypted_track_1": { "type": "string", "description": "Raw encrypted data." }, "encrypted_track_2": { "type": "string", "description": "Raw encrypted data." }, "encrypted_track_3": { "type": "string", "description": "Raw encrypted data." }, "encrypted_ksn": { "type": "string", "description": "Raw encrypted data." } } }, "RetailIdTechEncryptedKeyed": { "type": "object", "title": "Retail ID Tech M130 encrypted keyed", "description": "Card-present encrypted keyed entry data from an ID Tech M130 reader. Set `industry` to `retail` on the payment request.", "additionalProperties": false, "required": [ "encrypted_data" ], "properties": { "encrypted_data": { "type": "string", "description": "Raw encrypted data." } } }, "RetailIngenicoChip": { "type": "object", "title": "Retail Ingenico Telium 2 chip (EMV)", "description": "Card-present EMV chip payment from an Ingenico Telium 2 reader. Set `industry` to `retail` on the payment request.", "additionalProperties": false, "required": [ "entry_mode", "emv_auth_request_data", "emv_device", "verification_method", "encrypted_ksn", "encrypted_track_2" ], "properties": { "entry_mode": { "type": "string", "enum": [ "emv_icc" ], "description": "The type of transaction data to be processed." }, "emv_auth_request_data": { "type": "string", "description": "EMV data for the transaction as received from the EMV chip card SDK." }, "emv_device": { "type": "string", "enum": [ "ingenico_rba" ], "description": "The EMV-capable card reader." }, "verification_method": { "type": "string", "enum": [ "signature", "offline_pin", "offline_pin_signature", "none" ], "description": "Method used to verify the EMV transaction." }, "encrypted_ksn": { "type": "string", "description": "Raw encrypted data." }, "encrypted_track_2": { "type": "string", "description": "Raw encrypted data." } } }, "RetailIngenicoSwipe": { "type": "object", "title": "Retail Ingenico Telium 2 swipe", "description": "Card-present encrypted swipe from an Ingenico Telium 2 reader. Set `industry` to `retail` on the payment request.", "additionalProperties": false, "required": [ "entry_mode", "emv_device", "encrypted_ksn", "encrypted_track_1", "encrypted_track_2" ], "properties": { "entry_mode": { "type": "string", "enum": [ "swiped", "swiped_emv_fallback" ], "description": "The type of transaction data to be processed." }, "emv_device": { "type": "string", "enum": [ "ingenico_rba" ], "description": "The EMV-capable card reader." }, "encrypted_ksn": { "type": "string", "description": "Raw encrypted data." }, "encrypted_track_1": { "type": "string", "description": "Raw encrypted data." }, "encrypted_track_2": { "type": "string", "description": "Raw encrypted data." } } }, "RetailIngenicoNfc": { "type": "object", "title": "Retail Ingenico Telium 2 NFC", "description": "Card-present NFC payment from an Ingenico Telium 2 reader. Set `industry` to `retail` on the payment request.", "additionalProperties": false, "required": [ "entry_mode", "emv_device", "encrypted_ksn", "encrypted_track_2" ], "properties": { "entry_mode": { "type": "string", "enum": [ "nfc_msd" ], "description": "The type of transaction data to be processed." }, "emv_device": { "type": "string", "enum": [ "ingenico_rba" ], "description": "The EMV-capable card reader." }, "encrypted_ksn": { "type": "string", "description": "Raw encrypted data." }, "encrypted_track_2": { "type": "string", "description": "Raw encrypted data." } } }, "RetailIngenicoKeyed": { "type": "object", "title": "Retail Ingenico Telium 2 keyed", "description": "Card-present encrypted keyed entry from an Ingenico Telium 2 reader. Set `industry` to `retail` on the payment request.", "additionalProperties": false, "required": [ "entry_mode", "emv_device", "encrypted_ksn", "encrypted_track_2" ], "properties": { "entry_mode": { "type": "string", "enum": [ "keyed" ], "description": "The type of transaction data to be processed." }, "emv_device": { "type": "string", "enum": [ "ingenico_rba" ], "description": "The EMV-capable card reader." }, "encrypted_ksn": { "type": "string", "description": "Raw encrypted data." }, "encrypted_track_2": { "type": "string", "description": "Raw encrypted data." } } }, "RetailMobileSdkEncryptedPayment": { "type": "object", "title": "Mobile SDK encrypted payment", "description": "RSA-encrypted card data from the NMI Mobile SDK (iOS/Android). Use in place of raw card number, expiration, and CVV. Set `industry` to `retail` on the payment request when processing as a card-present transaction.", "additionalProperties": false, "required": [ "encrypted_payment" ], "properties": { "encrypted_payment": { "type": "string", "description": "Encrypted payment blob returned by the Mobile SDK." } } }, "PaymentDetails": { "title": "Payment Details", "description": "Payment method details. Exactly one variant: raw card data, ACH (check) data, **payment_token**, wallet payloads, or **retail card-present** data from a card reader. Do not combine fields from different variants.", "oneOf": [ { "type": "object", "title": "Credit card", "description": "Non-tokenized credit card data.", "additionalProperties": false, "required": [ "card_number", "card_exp" ], "properties": { "card_number": { "type": "string", "description": "Credit card number" }, "card_exp": { "type": "string", "description": "Credit card expiration date. Format: `MMYY`" }, "card_cvv": { "type": "string", "maxLength": 4, "description": "The card security code." } } }, { "$ref": "#/components/schemas/RetailUnencryptedMagneticStripe" }, { "$ref": "#/components/schemas/RetailMagTekMagensaEncryptedSwipe" }, { "$ref": "#/components/schemas/RetailIdTechEncryptedSwipe" }, { "$ref": "#/components/schemas/RetailIdTechEncryptedKeyed" }, { "$ref": "#/components/schemas/RetailIngenicoChip" }, { "$ref": "#/components/schemas/RetailIngenicoSwipe" }, { "$ref": "#/components/schemas/RetailIngenicoNfc" }, { "$ref": "#/components/schemas/RetailIngenicoKeyed" }, { "$ref": "#/components/schemas/RetailMobileSdkEncryptedPayment" }, { "type": "object", "title": "ACH / check", "description": "Bank account (ACH) details for this transaction.", "additionalProperties": false, "required": [ "check_name", "check_aba", "check_account", "account_type", "account_holder_type", "sec_code" ], "properties": { "check_name": { "type": "string", "maxLength": 50, "description": "The name on the customer's ACH account" }, "check_aba": { "type": "number", "description": "The customer's bank routing number" }, "check_account": { "type": "number", "description": "The customer's bank account number" }, "account_type": { "type": "string", "enum": [ "checking", "savings" ], "description": "The type of ACH account the customer has" }, "account_holder_type": { "type": "string", "enum": [ "personal", "business" ], "description": "The type of ACH account the customer has" }, "sec_code": { "type": "string", "enum": [ "PPD", "WEB", "TEL", "CCD", "POP", "RCK" ], "description": "The Standard Entry Class code of the ACH transaction" }, "check_number": { "type": "string", "maxLength": 20, "description": "Check number" } } }, { "type": "object", "title": "Payment token", "description": "Single-use or vault token from [Payment Component](../docs/payment-component) or [Collect.js](https://secure.networkmerchants.com/merchants/resources/integration/integration_portal.php#cjs_methodology) (not Apple Pay / Google Pay).", "additionalProperties": false, "required": [ "payment_token" ], "properties": { "payment_token": { "type": "string", "description": "The tokenized version of the customer's card or check information" } } }, { "type": "object", "title": "Apple Pay", "description": "Encrypted payment data from the Apple Pay SDK.", "additionalProperties": false, "required": [ "applepay_payment_data" ], "properties": { "applepay_payment_data": { "type": "string", "description": "The encrypted token created when integration directly to the Apple Pay SDK" } } }, { "type": "object", "title": "Google Pay", "description": "Encrypted payment data from the Google Pay SDK.", "additionalProperties": false, "required": [ "googlepay_payment_data" ], "properties": { "googlepay_payment_data": { "type": "string", "description": "The encrypted token created when integration directly to the Google Pay SDK" } } }, { "type": "object", "title": "Decrypted Apple Pay", "description": "Merchant-decrypted Apple Pay payment data.", "additionalProperties": false, "required": [ "decrypted_applepay_data", "card_number", "card_exp" ], "properties": { "decrypted_applepay_data": { "type": "boolean", "enum": [ true ], "description": "Set to `true` when submitting merchant-decrypted Apple Pay data." }, "card_number": { "type": "string", "description": "Credit card number" }, "card_exp": { "type": "string", "description": "Credit card expiration date. Format: `MMYY`" } } }, { "type": "object", "title": "Decrypted Google Pay", "description": "Merchant-decrypted Google Pay payment data.", "additionalProperties": false, "required": [ "decrypted_googlepay_data", "card_number", "card_exp" ], "properties": { "decrypted_googlepay_data": { "type": "boolean", "enum": [ true ], "description": "Set to `true` when submitting merchant-decrypted Google Pay data." }, "card_number": { "type": "string", "description": "Credit card number" }, "card_exp": { "type": "string", "description": "Credit card expiration date. Format: `MMYY`" } } } ] }, "CardholderAuth": { "type": "object", "title": "Cardholder Authentication", "description": "Cardholder authentication data. Use the 3-D Secure variant for EMV authentication results. Use the Decrypted wallet variant for merchant-decrypted Apple Pay or Google Pay, which relays the cryptogram and ECI to the 3-D Secure fields.", "oneOf": [ { "type": "object", "title": "3-D Secure", "description": "EMV 3-D Secure authentication result fields.", "additionalProperties": false, "required": [ "status", "cavv" ], "properties": { "status": { "type": "string", "enum": [ "verified", "attempted" ], "description": "Set 3D Secure condition. Value used to determine E-commerce indicator (ECI)." }, "cavv": { "type": "string", "maxLength": 50, "description": "Cardholder authentication verification value from the 3-D Secure authentication response. Format: base64 encoded." }, "xid": { "type": "string", "maxLength": 50, "description": "Cardholder authentication transaction id. Format: base64 encoded." }, "three_ds_version": { "type": "string", "maxLength": 10, "description": "3DSecure version (for example `2.1.0` or `2.2.0`)." }, "directory_server_id": { "type": "string", "maxLength": 50, "description": "Directory Server Transaction ID from 3DSecure 2.0 authentication. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } } }, { "type": "object", "title": "Decrypted wallet (Apple Pay / Google Pay)", "description": "Wallet authentication for decrypted Apple Pay or Google Pay payments.", "additionalProperties": false, "required": [ "cavv" ], "properties": { "cavv": { "type": "string", "maxLength": 50, "description": "Wallet payment cryptogram (submitted in the repurposed 3-D Secure `cavv` field)." }, "eci": { "type": "string", "maxLength": 10, "description": "Electronic Commerce Indicator from the wallet payment data (submitted in the repurposed 3-D Secure `eci` field)." } } } ] }, "BillingAddressRest": { "type": "object", "title": "Billing Address & Information", "description": "Billing address for a payment transaction request.", "properties": { "method": { "type": "string", "enum": [ "initial_recurring", "recurring", "installment" ], "description": "Recurring or installment classification for the processor.\n\n- `initial_recurring`: First transaction in a recurring sequence only.\n- `recurring`: Later charges in that sequence.\n- `installment`: Installment transactions; use `number` and `total` on supported processors.\n\nWhich values apply depends on the processor." }, "number": { "type": "integer", "minimum": 0, "maximum": 99, "description": "Specify installment billing number, on supported processors. For use when `billing.method` is set to \"installment\"" }, "total": { "type": "number", "minimum": 0, "description": "Specify installment billing total on supported processors. For use when `billing.method` is set to \"installment\"" }, "first_name": { "type": "string", "maxLength": 50, "description": "Cardholder's first name" }, "last_name": { "type": "string", "maxLength": 50, "description": "Cardholder's last name" }, "company": { "type": "string", "maxLength": 100, "description": "Cardholder's company" }, "address1": { "type": "string", "maxLength": 100, "description": "Card billing address" }, "address2": { "type": "string", "maxLength": 100, "description": "Card billing address, line 2" }, "city": { "type": "string", "maxLength": 50, "description": "Card billing city" }, "state": { "type": "string", "maxLength": 50, "description": "Card billing state. Format: `CC`" }, "zip": { "type": "string", "maxLength": 20, "description": "Card billing zip code" }, "country": { "type": "string", "maxLength": 2, "description": "Card billing country. Country codes are as shown in ISO 3166-1 alpha-2. Format: `CC`" }, "phone": { "type": "string", "description": "Billing phone number" }, "email": { "type": "string", "format": "email", "description": "Billing email address" }, "fax": { "type": "string", "maxLength": 50, "description": "Billing fax number" }, "cell_phone": { "type": "string", "description": "Billing cell phone number" }, "website": { "type": "string", "maxLength": 255, "description": "Website (invoice-specific field)" }, "drivers_license_number": { "type": "string", "maxLength": 20, "description": "Driver's license number" }, "drivers_license_dob": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Driver's license date of birth. Format: `YYYY-MM-DD`" }, "drivers_license_state": { "type": "string", "maxLength": 2, "description": "Driver's license state. Format: `CC`" }, "payment_details": { "$ref": "#/components/schemas/PaymentDetails" }, "cardholder_auth": { "$ref": "#/components/schemas/CardholderAuth" } } }, "ShippingAddressRest": { "type": "object", "title": "Shipping Address & Information", "description": "Shipping address and information", "properties": { "id": { "type": "string", "maxLength": 32, "description": "Shipping address ID (max 32 characters). Generated if omitted on create." }, "first_name": { "type": "string", "maxLength": 50, "description": "Shipping first name" }, "last_name": { "type": "string", "maxLength": 50, "description": "Shipping last name" }, "company": { "type": "string", "maxLength": 100, "description": "Shipping company" }, "address1": { "type": "string", "maxLength": 100, "description": "Shipping address" }, "address2": { "type": "string", "maxLength": 100, "description": "Shipping address, line 2" }, "city": { "type": "string", "maxLength": 50, "description": "Shipping city" }, "state": { "type": "string", "maxLength": 50, "description": "Shipping state." }, "zip": { "type": "string", "maxLength": 20, "description": "Shipping zip code" }, "country": { "type": "string", "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code. Example: `US`" }, "email": { "type": "string", "format": "email", "description": "Shipping email address" }, "carrier": { "type": "string", "enum": [ "ups", "fedex", "dhl", "usps" ], "description": "Shipping carrier" } } }, "LineItem": { "type": "object", "title": "Line Item", "description": "Line item details for order details", "properties": { "product_code": { "type": "string", "maxLength": 50, "description": "Product code" }, "description": { "type": "string", "maxLength": 255, "description": "Line item description" }, "commodity_code": { "type": "string", "maxLength": 50, "description": "Commodity code" }, "unit_of_measure": { "type": "string", "maxLength": 50, "description": "Unit of measure" }, "unit_cost": { "type": "number", "minimum": 0, "description": "Unit cost" }, "quantity": { "type": "integer", "minimum": 0, "maximum": 999999, "description": "Quantity" }, "total_amount": { "type": "number", "minimum": 0, "description": "Total amount" }, "tax_amount": { "type": "number", "minimum": 0, "description": "Tax amount" }, "tax_rate": { "type": "number", "minimum": 0, "description": "Tax rate" }, "discount_amount": { "type": "number", "minimum": 0, "description": "Discount amount" }, "discount_rate": { "type": "number", "minimum": 0, "description": "Discount rate" }, "tax_type": { "type": "string", "maxLength": 50, "description": "Tax type" }, "alternate_tax_id": { "type": "string", "maxLength": 50, "description": "Alternate tax ID" } } }, "OrderDetailsRest": { "type": "object", "title": "Order Details", "description": "Order details and line items", "properties": { "template_id": { "type": "string", "maxLength": 50, "description": "Order template ID" }, "description": { "type": "string", "maxLength": 100, "description": "Order description" }, "id": { "type": "string", "maxLength": 50, "description": "Order ID (for payment requests)" }, "order_id": { "type": "string", "maxLength": 255, "description": "Order ID (for invoice requests and responses)" }, "customer_id": { "type": "string", "maxLength": 255, "description": "Customer ID (invoice-specific)" }, "customer_tax_id": { "type": "string", "maxLength": 255, "description": "Customer tax ID (invoice-specific)" }, "tax": { "type": "number", "minimum": 0, "description": "Tax amount" }, "shipping": { "type": "number", "minimum": 0, "description": "Shipping amount" }, "po_number": { "type": "string", "maxLength": 255, "description": "Purchase order number (maxLength 50 for payments, 255 for invoices)" }, "shipping_postal_code": { "type": "string", "maxLength": 20, "description": "Shipping postal code" }, "ship_from_postal_code": { "type": "string", "maxLength": 20, "description": "Ship from postal code" }, "summary_commodity_code": { "type": "string", "maxLength": 50, "description": "Summary commodity code" }, "duty_amount": { "type": "number", "minimum": 0, "description": "Duty amount" }, "discount_amount": { "type": "number", "minimum": 0, "description": "Discount amount" }, "national_tax_amount": { "type": "number", "minimum": 0, "description": "National tax amount" }, "alternate_tax_amount": { "type": "number", "minimum": 0, "description": "Alternate tax amount" }, "alternate_tax_id": { "type": "string", "maxLength": 50, "description": "Alternate tax ID" }, "vat_tax_amount": { "type": "number", "minimum": 0, "description": "VAT tax amount" }, "vat_tax_rate": { "type": "number", "minimum": 0, "description": "VAT tax rate" }, "vat_invoice_reference_number": { "type": "string", "maxLength": 50, "description": "VAT invoice reference number" }, "customer_vat_registration": { "type": "string", "maxLength": 50, "description": "Customer VAT registration" }, "merchant_vat_registration": { "type": "string", "maxLength": 50, "description": "Merchant VAT registration" }, "order_date": { "type": "string", "format": "date", "description": "Order date" }, "order_description": { "type": "string", "maxLength": 255, "description": "Order description (maxLength 255 for both payments and invoices)" }, "ip_address": { "type": "string", "description": "IP address of cardholder (IPv4 or IPv6). Format validated as IP address" }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/LineItem" } } } }, "CustomerVaultAdd": { "type": "object", "title": "Add payment method to customer vault", "description": "Store the inline `payment_details` from this request in the customer vault.", "additionalProperties": false, "required": [ "add_to_vault" ], "properties": { "add_to_vault": { "type": "boolean", "description": "Set to `true` to store the payment method in the customer vault." }, "id": { "type": "string", "maxLength": 36, "description": "Optional custom customer vault ID (max 36 characters). Generated if omitted." } } }, "CustomerVaultCharge": { "type": "object", "title": "Use existing customer vault", "description": "Charge or validate an existing customer vault record. Do not send `payment_details`.", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "maxLength": 36, "description": "Existing customer vault ID (max 36 characters)." }, "billing_id": { "type": "string", "maxLength": 32, "description": "Billing profile ID to use. Defaults to the vault priority billing profile if omitted (max 32 characters)." }, "shipping_id": { "type": "string", "maxLength": 32, "description": "Shipping profile ID to use. Defaults to the vault priority shipping profile if omitted (max 32 characters)." } } }, "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" ] }, "SubscriptionResponse": { "type": "object", "title": "Subscription Response", "description": "Subscription response matching SubscriptionRestSerializer structure", "properties": { "object": { "type": "string", "enum": [ "subscription" ], "description": "Resource type identifier" }, "id": { "type": "string", "description": "Subscription ID" }, "created_date": { "type": "string", "format": "date-time", "description": "Date the subscription was created, in UTC ISO 8601 format" }, "start_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Subscription start date in UTC ISO 8601 format" }, "next_billing_date": { "type": "string", "format": "date-time", "nullable": true, "description": "Next billing date in UTC ISO 8601 format" }, "amount": { "type": "string", "description": "Subscription amount" }, "customer_vault_id": { "type": "string", "description": "Customer vault ID associated with the subscription" }, "delayed_condition": { "type": "string", "description": "Delayed condition" }, "paused_subscription": { "type": "integer", "enum": [ 0, 1 ], "description": "Whether the subscription is paused (0 = active, 1 = paused)" }, "plan": { "type": "object", "nullable": true, "description": "Associated plan", "properties": { "id": { "type": "string", "description": "Plan ID" }, "plan_name": { "type": "string", "description": "Plan name" }, "plan_amount": { "type": "string", "description": "Plan amount" }, "plan_payments": { "type": "string", "description": "Number of payments (0 = until canceled)" }, "day_frequency": { "type": "string", "description": "Day frequency (0 if not applicable)" }, "month_frequency": { "type": "string", "description": "Month frequency (0 if not applicable)" }, "day_of_month": { "type": "string", "description": "Day of month (empty if not applicable)" } } } }, "required": [ "object", "id" ] }, "CustomerVault": { "title": "Customer Vault", "description": "Either add a payment method to the vault, or use an existing vault record.", "oneOf": [ { "$ref": "#/components/schemas/CustomerVaultAdd" }, { "$ref": "#/components/schemas/CustomerVaultCharge" } ] }, "SubscriptionUpdateRequest": { "title": "Subscription Update Request", "type": "object", "properties": { "plan_amount": { "type": "number", "minimum": 0, "description": "The plan amount to be charged each billing cycle. Format: `x.xx`" }, "plan_payments": { "type": "integer", "minimum": 0, "maximum": 999, "description": "The number of payments before the recurring plan is complete. Use '0' for until canceled" }, "day_frequency": { "type": "integer", "minimum": 1, "description": "How often, in days, to charge the customer. Cannot be set with 'month_frequency' or 'day_of_month'" }, "month_frequency": { "type": "integer", "minimum": 1, "description": "How often, in months, to charge the customer. Cannot be set with 'day_frequency'. Must be set with 'day_of_month'" }, "day_of_month": { "type": "integer", "minimum": 1, "maximum": 31, "description": "The day that the customer will be charged. Cannot be set with 'day_frequency'. Must be set with 'month_frequency'" }, "paused_subscription": { "type": "boolean", "description": "If set to true, the subscription will be paused" }, "start_date": { "type": "string", "minLength": 8, "maxLength": 14, "pattern": "^(\\d{8}|\\d{14})$", "description": "The date the subscription's next/first charge occurs. Format: `YYYYMMDD` (optionally `YYYYMMDDHHMMSS`)." }, "payment_details": { "$ref": "#/components/schemas/PaymentDetails" }, "billing_address": { "$ref": "#/components/schemas/BillingAddressRest" }, "shipping_address": { "$ref": "#/components/schemas/ShippingAddressRest" }, "order_details": { "$ref": "#/components/schemas/OrderDetailsRest" }, "merchant_defined_fields": { "$ref": "#/components/schemas/MerchantDefinedFields" }, "customer_vault": { "$ref": "#/components/schemas/CustomerVault" }, "cardholder_auth": { "$ref": "#/components/schemas/CardholderAuth" } } }, "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.