Recurly · Schema

Transaction

SubscriptionBillingPaymentsRecurring RevenueInvoicingDunningRevenue RecognitionChurnMCPShopifyWebhook

Properties

Name Type Description
id string
object string
uuid string The UUID is useful for matching data with the CSV exports and building URLs into Recurly's UI.
original_transaction_id string If this transaction is a refund (`type=refund`), this will be the ID of the original transaction on the invoice being refunded.
account object
initiator string Must be sent for one-time transactions in order to provide context on which entity is submitting the transaction to ensure proper fraud checks are observed, such as 3DS. If the customer is in session,
invoice object
merchant_reason_code string This conditional parameter is useful for merchants in specific industries who need to submit one-time Merchant Initiated transactions in specific cases. Not all gateways support these methods, but wil
voided_by_invoice object
subscription_ids array If the transaction is charging or refunding for one or more subscriptions, these are their IDs.
type string - `authorization` – verifies billing information and places a hold on money in the customer's account. - `capture` – captures funds held by an authorization and completes a purchase. - `purchase` – co
origin string Describes how the transaction was triggered.
currency string 3-letter ISO 4217 currency code.
description string The description that gets sent to the gateway.
amount number Total transaction amount sent to the payment gateway.
status string The current transaction status. Note that the status may change, e.g. a `pending` transaction may become `declined` or `success` may later become `void`.
success boolean Did this transaction complete successfully?
backup_payment_method_used boolean Indicates if the transaction was completed using a backup payment
refunded boolean Indicates if part or all of this transaction was refunded.
billing_address object
collection_method string The method by which the payment was collected.
payment_method object
payment_gateway_references array Array of Payment Gateway References captured at transaction time, each a reference to a third-party gateway object of varying types.
ip_address_v4 string IP address provided when the billing information was collected: - When the customer enters billing information into the Recurly.js or Hosted Payment Pages, Recurly records the IP address. - When the m
ip_address_country string
status_code string
status_message string For declined (`success=false`) transactions, the message displayed to the merchant.
customer_message string For declined (`success=false`) transactions, the message displayed to the customer.
customer_message_locale string
payment_gateway object
gateway_message string Transaction message from the payment gateway.
gateway_reference string Transaction reference number from the payment gateway.
gateway_approval_code string
gateway_response_code string
gateway_response_time number Time, in seconds, for gateway to process the transaction.
gateway_response_values object The values in this field will vary from gateway to gateway.
cvv_check string When processed, result from checking the CVV/CVC value on the transaction.
avs_check string When processed, result from checking the overall AVS on the transaction.
created_at string
updated_at string
voided_at string
collected_at string
action_result object Action result params to be used in Recurly-JS to complete a payment when using asynchronous payment methods, e.g., Boleto, iDEAL and Sofort.
vat_number string VAT number for the customer on this transaction. If the customer's Billing Info country is BR or AR, then this will be their Tax Identifier. For all other countries this will come from the VAT Number
fraud_info object
next_action object Next action values are used for any required customer follow-up action. Currently, this is supported for Ebanx when using Pix Automatico.
View JSON Schema on GitHub

JSON Schema

recurly-transaction-schema.json Raw ↑
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/recurly/json-schema/recurly-transaction-schema.json",
  "title": "Transaction",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/recurly-recover-openapi.yml#/components/schemas/Transaction",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "title": "Transaction ID",
      "maxLength": 13
    },
    "object": {
      "type": "string",
      "title": "Object type"
    },
    "uuid": {
      "type": "string",
      "title": "Recurly UUID",
      "description": "The UUID is useful for matching data with the CSV exports and building URLs into Recurly's UI.",
      "maxLength": 32
    },
    "original_transaction_id": {
      "type": "string",
      "title": "Original Transaction ID",
      "description": "If this transaction is a refund (`type=refund`), this will be the ID of the original transaction on the invoice being refunded.",
      "maxLength": 13
    },
    "account": {
      "$ref": "#/$defs/AccountMini"
    },
    "initiator": {
      "type": "string",
      "description": "Must be sent for one-time transactions in order to provide context on which entity is submitting the transaction to ensure proper fraud checks are observed, such as 3DS. If the customer is in session, send `customer`. If this is a merchant initiated one-time transaction, send `merchant`.",
      "enum": [
        "customer",
        "merchant"
      ]
    },
    "invoice": {
      "$ref": "#/$defs/InvoiceMini"
    },
    "merchant_reason_code": {
      "type": "string",
      "default": "none",
      "description": "This conditional parameter is useful for merchants in specific industries who need to submit one-time Merchant Initiated transactions in specific cases.\nNot all gateways support these methods, but will support a generic one-time Merchant Initiated transaction.\nOnly use this if the initiator value is \"merchant\". Otherwise, it will be ignored.\n  - Incremental: Send `incremental` with an additional purchase if the original authorization amount is not sufficient to cover the costs of your service or product. For example, if the customer adds goods or services or there are additional expenses.\n  - No Show: Send `no_show` if you charge customers a fee due to an agreed-upon cancellation policy in your industry.\n  - Resubmission: Send `resubmission` if you need to attempt collection on a declined transaction. You may also use the force collection behavior which has the same effect.\n  - Service Extension: Send `service_extension` if you are in a service industry and the customer has increased/extended their service in some way. For example: adding a day onto a car rental agreement.\n  - Split Shipment: Send `split_shipment` if you sell physical product and need to split up a shipment into multiple transactions when the customer is no longer in session.\n  - Top Up: Send `top_up` if you process one-time transactions based on a pre-arranged agreement with your customer where there is a pre-arranged account balance that needs maintaining. For example, if the customer has agreed to maintain an account balance of 30.00 and their current balance is 20.00, the MIT amount would be at least 10.00 to meet that 30.00 threshold.\n",
      "enum": [
        "incremental",
        "no_show",
        "resubmission",
        "service_extension",
        "split_shipment",
        "top_up"
      ]
    },
    "voided_by_invoice": {
      "$ref": "#/$defs/InvoiceMini"
    },
    "subscription_ids": {
      "type": "array",
      "title": "Subscription IDs",
      "description": "If the transaction is charging or refunding for one or more subscriptions, these are their IDs.",
      "items": {
        "type": "string",
        "title": "Subscription ID",
        "maxLength": 13
      }
    },
    "type": {
      "title": "Transaction type",
      "description": "- `authorization` – verifies billing information and places a hold on money in the customer's account.\n- `capture` – captures funds held by an authorization and completes a purchase.\n- `purchase` – combines the authorization and capture in one transaction.\n- `refund` – returns all or a portion of the money collected in a previous transaction to the customer.\n- `verify` – a $0 or $1 transaction used to verify billing information which is immediately voided.\n",
      "type": "string",
      "enum": [
        "authorization",
        "capture",
        "purchase",
        "refund",
        "verify"
      ]
    },
    "origin": {
      "title": "Origin of transaction",
      "description": "Describes how the transaction was triggered.",
      "type": "string",
      "enum": [
        "api",
        "chargeback",
        "external_recovery",
        "force_collect",
        "hpp",
        "merchant",
        "recurly_admin",
        "recurlyjs",
        "recurring",
        "refunded_externally",
        "transparent",
        "token_api",
        "api_force_collect",
        "api_sub_change",
        "api_verify_card",
        "refund_balance",
        "amazon_v2_ipn"
      ]
    },
    "currency": {
      "type": "string",
      "title": "Currency",
      "description": "3-letter ISO 4217 currency code.",
      "maxLength": 3
    },
    "description": {
      "type": "string",
      "title": "Description",
      "description": "The description that gets sent to the gateway."
    },
    "amount": {
      "type": "number",
      "format": "float",
      "title": "Amount",
      "description": "Total transaction amount sent to the payment gateway."
    },
    "status": {
      "title": "Transaction status",
      "description": "The current transaction status. Note that the status may change, e.g. a `pending` transaction may become `declined` or `success` may later become `void`.",
      "type": "string",
      "enum": [
        "chargeback",
        "declined",
        "error",
        "pending",
        "processing",
        "scheduled",
        "success",
        "void"
      ]
    },
    "success": {
      "type": "boolean",
      "title": "Success?",
      "description": "Did this transaction complete successfully?"
    },
    "backup_payment_method_used": {
      "type": "boolean",
      "title": "Backup Payment Method Used?",
      "description": "Indicates if the transaction was completed using a backup payment"
    },
    "refunded": {
      "type": "boolean",
      "title": "Refunded?",
      "description": "Indicates if part or all of this transaction was refunded."
    },
    "billing_address": {
      "$ref": "#/$defs/AddressWithName"
    },
    "collection_method": {
      "description": "The method by which the payment was collected.",
      "type": "string",
      "enum": [
        "automatic",
        "manual"
      ]
    },
    "payment_method": {
      "$ref": "#/$defs/PaymentMethod"
    },
    "payment_gateway_references": {
      "type": "array",
      "description": "Array of Payment Gateway References captured at transaction time, each a reference to a third-party gateway object of varying types.",
      "items": {
        "$ref": "#/$defs/PaymentGatewayReferences"
      }
    },
    "ip_address_v4": {
      "type": "string",
      "title": "IP address",
      "description": "IP address provided when the billing information was collected:\n\n- When the customer enters billing information into the Recurly.js or Hosted Payment Pages, Recurly records the IP address.\n- When the merchant enters billing information using the API, the merchant may provide an IP address.\n- When the merchant enters billing information using the UI, no IP address is recorded.\n"
    },
    "ip_address_country": {
      "type": "string",
      "title": "Origin IP address country, 2-letter ISO 3166-1 alpha-2 code, if known by Recurly."
    },
    "status_code": {
      "type": "string",
      "title": "Status code"
    },
    "status_message": {
      "type": "string",
      "title": "Status message",
      "description": "For declined (`success=false`) transactions, the message displayed to the merchant."
    },
    "customer_message": {
      "type": "string",
      "title": "Customer message",
      "description": "For declined (`success=false`) transactions, the message displayed to the customer."
    },
    "customer_message_locale": {
      "type": "string",
      "title": "Language code for the message"
    },
    "payment_gateway": {
      "type": "object",
      "x-class-name": "TransactionPaymentGateway",
      "properties": {
        "id": {
          "type": "string"
        },
        "object": {
          "type": "string",
          "title": "Object type"
        },
        "type": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "gateway_message": {
      "type": "string",
      "title": "Gateway message",
      "description": "Transaction message from the payment gateway."
    },
    "gateway_reference": {
      "type": "string",
      "title": "Gateway reference",
      "description": "Transaction reference number from the payment gateway."
    },
    "gateway_approval_code": {
      "type": "string",
      "title": "Transaction approval code from the payment gateway."
    },
    "gateway_response_code": {
      "type": "string",
      "title": "For declined transactions (`success=false`), this field lists the gateway error code."
    },
    "gateway_response_time": {
      "type": "number",
      "format": "float",
      "title": "Gateway response time",
      "description": "Time, in seconds, for gateway to process the transaction."
    },
    "gateway_response_values": {
      "type": "object",
      "title": "Gateway response values",
      "description": "The values in this field will vary from gateway to gateway."
    },
    "cvv_check": {
      "title": "CVV check",
      "description": "When processed, result from checking the CVV/CVC value on the transaction.",
      "type": "string",
      "enum": [
        "D",
        "I",
        "M",
        "N",
        "P",
        "S",
        "U",
        "X"
      ]
    },
    "avs_check": {
      "title": "AVS check",
      "description": "When processed, result from checking the overall AVS on the transaction.",
      "type": "string",
      "enum": [
        "A",
        "B",
        "C",
        "D",
        "E",
        "F",
        "G",
        "H",
        "I",
        "J",
        "K",
        "L",
        "M",
        "N",
        "O",
        "P",
        "Q",
        "R",
        "S",
        "T",
        "U",
        "V",
        "W",
        "X",
        "Y",
        "Z"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "title": "Created at"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "title": "Updated at"
    },
    "voided_at": {
      "type": "string",
      "format": "date-time",
      "title": "Voided at"
    },
    "collected_at": {
      "type": "string",
      "format": "date-time",
      "title": "Collected at, or if not collected yet, the time the transaction was created."
    },
    "action_result": {
      "type": "object",
      "description": "Action result params to be used in Recurly-JS to complete a payment when using asynchronous payment methods, e.g., Boleto, iDEAL and Sofort.",
      "title": "Action result"
    },
    "vat_number": {
      "type": "string",
      "description": "VAT number for the customer on this transaction. If the customer's Billing Info country is BR or AR, then this will be their Tax Identifier. For all other countries this will come from the VAT Number field in the Billing Info.",
      "title": "VAT Number"
    },
    "fraud_info": {
      "$ref": "#/$defs/TransactionFraudInfo"
    },
    "next_action": {
      "type": "object",
      "x-class-name": "TransactionNextAction",
      "description": "Next action values are used for any required customer follow-up action. Currently, this is supported for Ebanx when using Pix Automatico.",
      "properties": {
        "type": {
          "type": "string",
          "title": "Next action type",
          "description": "The type of next action required for the transaction.",
          "enum": [
            "qr_code"
          ]
        },
        "value": {
          "type": "string",
          "title": "Next action value",
          "description": "The value associated with the next action type."
        }
      },
      "title": "Next action"
    }
  },
  "$defs": {
    "AccountMini": {
      "type": "object",
      "title": "Account mini details",
      "properties": {
        "id": {
          "type": "string",
          "maxLength": 13,
          "readOnly": true
        },
        "object": {
          "type": "string",
          "title": "Object type",
          "readOnly": true
        },
        "code": {
          "type": "string",
          "description": "The unique identifier of the account.",
          "maxLength": 50
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "The email address used for communicating with this customer.",
          "maxLength": 255
        },
        "first_name": {
          "type": "string",
          "maxLength": 255
        },
        "last_name": {
          "type": "string",
          "maxLength": 255
        },
        "company": {
          "type": "string",
          "maxLength": 255
        },
        "parent_account_id": {
          "type": "string",
          "maxLength": 13
        },
        "bill_to": {
          "type": "string",
          "maxLength": 6
        },
        "dunning_campaign_id": {
          "type": "string",
          "title": "Dunning Campaign ID",
          "description": "Unique ID to identify a dunning campaign. Used to specify if a non-default dunning campaign should be assigned to this account. For sites without multiple dunning campaigns enabled, the default dunning campaign will always be used."
        }
      }
    },
    "Address": {
      "type": "object",
      "properties": {
        "phone": {
          "type": "string",
          "title": "Phone number"
        },
        "street1": {
          "type": "string",
          "title": "Street 1",
          "maxLength": 50
        },
        "street2": {
          "type": "string",
          "title": "Street 2",
          "maxLength": 50
        },
        "city": {
          "type": "string",
          "title": "City"
        },
        "region": {
          "type": "string",
          "title": "State/Province",
          "description": "State or province."
        },
        "postal_code": {
          "type": "string",
          "title": "Zip/Postal code",
          "description": "Zip or postal code."
        },
        "country": {
          "type": "string",
          "title": "Country",
          "description": "Country, 2-letter ISO 3166-1 alpha-2 code."
        },
        "geo_code": {
          "type": "string",
          "maxLength": 20,
          "description": "Code that represents a geographic entity (location or object). Only returned when Vertex or Avalara for Communications is enabled."
        }
      }
    },
    "AddressWithName": {
      "allOf": [
        {
          "$ref": "#/$defs/Address"
        }
      ],
      "type": "object",
      "properties": {
        "first_name": {
          "type": "string",
          "title": "First name"
        },
        "last_name": {
          "type": "string",
          "title": "Last name"
        }
      }
    },
    "FraudRiskRule": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "title": "The Kount rule number."
        },
        "message": {
          "type": "string",
          "title": "Description of why the rule was triggered"
        }
      }
    },
    "InvoiceMini": {
      "type": "object",
      "title": "Invoice mini details",
      "properties": {
        "id": {
          "type": "string",
          "title": "Invoice ID",
          "maxLength": 13
        },
        "object": {
          "type": "string",
          "title": "Object type"
        },
        "number": {
          "type": "string",
          "title": "Invoice number"
        },
        "business_entity_id": {
          "type": "string",
          "title": "Business Entity ID",
          "description": "Unique ID to identify the business entity assigned to the invoice. Available when the `Multiple Business Entities` feature is enabled."
        },
        "type": {
          "title": "Invoice type",
          "type": "string",
          "enum": [
            "charge",
            "credit",
            "legacy"
          ]
        },
        "state": {
          "title": "Invoice state",
          "type": "string",
          "default": "all",
          "enum": [
            "open",
            "pending",
            "processing",
            "past_due",
            "paid",
            "closed",
            "failed",
            "voided"
          ]
        }
      }
    },
    "PaymentGatewayReferences": {
      "type": "object",
      "title": "Payment Gateway References Object",
      "description": "Array of Payment Gateway References, each a reference to a third-party gateway object of varying types.",
      "properties": {
        "token": {
          "type": "string",
          "title": "Token",
          "description": "Reference value used when the external token was created. If a Stripe gateway or Ebanx gateway is used, this value will need to be accompanied by its reference_type."
        },
        "reference_type": {
          "type": "string",
          "title": "Reference Type",
          "description": "The type of reference token. The value can be omitted for gateways that only support one type of token.",
          "enum": [
            "stripe_confirmation_token",
            "upi_vpa"
          ]
        }
      }
    },
    "PaymentMethod": {
      "type": "object",
      "properties": {
        "object": {
          "type": "string",
          "enum": [
            "bacs",
            "amazon",
            "amazon_billing_agreement",
            "apple_pay",
            "apple_pay_merchant_token",
            "bank_account_info",
            "braintree_apple_pay",
            "check",
            "credit_card",
            "eft",
            "gateway_token",
            "google_pay",
            "google_pay_device_pan",
            "iban_bank_account",
            "money_order",
            "other",
            "paypal",
            "paypal_billing_agreement",
            "roku",
            "sepadirectdebit",
            "venmo",
            "wire_transfer",
            "braintree_v_zero",
            "boleto",
            "cash_app",
            "upi_autopay",
            "pix_automatico",
            "mercadopago",
            "klarna",
            "braintree_google_pay",
            "stripe_link"
          ]
        },
        "card_type": {
          "description": "Visa, MasterCard, American Express, Discover, JCB, etc.",
          "type": "string",
          "enum": [
            "American Express",
            "Dankort",
            "Diners Club",
            "Discover",
            "ELO",
            "Forbrugsforeningen",
            "Hipercard",
            "JCB",
            "Laser",
            "Maestro",
            "MasterCard",
            "Test Card",
            "Union Pay",
            "Unknown",
            "Visa",
            "Tarjeta Naranja"
          ]
        },
        "first_six": {
          "type": "string",
          "description": "Credit card number's first six digits.\n\nFor a tokenized wallet payment (`apple_pay`, `google_pay`, or\n`google_pay_device_pan`), this is the DPAN's (the wallet/device token's own\nnumber) first six digits, not the underlying card's (FPAN).\n",
          "maxLength": 6
        },
        "last_four": {
          "type": "string",
          "description": "Credit card number's last four digits. Will refer to bank account if payment\nmethod is ACH.\n\nFor a tokenized wallet payment (`apple_pay`, `google_pay`, or\n`google_pay_device_pan`), this is the DPAN's last four digits, not the\nunderlying card's (FPAN).\n",
          "maxLength": 4
        },
        "last_two": {
          "type": "string",
          "description": "The IBAN bank account's last two digits.",
          "maxLength": 2
        },
        "exp_month": {
          "type": "integer",
          "description": "Expiration month.",
          "maxLength": 2
        },
        "exp_year": {
          "type": "integer",
          "description": "Expiration year.",
          "maxLength": 4
        },
        "gateway_token": {
          "type": "string",
          "description": "A token used in place of a credit card in order to perform transactions.",
          "maxLength": 50
        },
        "cc_bin_country": {
          "type": "string",
          "description": "The 2-letter ISO 3166-1 alpha-2 country code associated with the card's issuer, if known."
        },
        "funding_source": {
          "description": "The funding source of the card, if known.",
          "type": "string",
          "enum": [
            "credit",
            "debit",
            "charge",
            "prepaid",
            "deferred_debit"
          ]
        },
        "gateway_code": {
          "type": "string",
          "description": "An identifier for a specific payment gateway.",
          "maxLength": 13
        },
        "gateway_attributes": {
          "type": "object",
          "description": "Gateway specific attributes associated with this PaymentMethod",
          "x-class-name": "GatewayAttributes",
          "properties": {
            "account_reference": {
              "type": "string",
              "description": "Used by Adyen and Braintree gateways. For Adyen the Shopper Reference value used when the external token was created. For Braintree the PayPal PayerID is populated in the response.",
              "maxLength": 264
            }
          }
        },
        "card_network_preference": {
          "description": "Represents the card network preference associated with the billing info for dual badged cards. Must be a supported card network.",
          "type": "string",
          "enum": [
            "Bancontact",
            "CartesBancaires",
            "Dankort",
            "MasterCard",
            "Visa"
          ]
        },
        "billing_agreement_id": {
          "type": "string",
          "description": "Billing Agreement identifier. Only present for Amazon or Paypal payment methods."
        },
        "name_on_account": {
          "type": "string",
          "description": "The name associated with the bank account."
        },
        "account_type": {
          "description": "The bank account type. Only present for ACH payment methods.",
          "type": "string",
          "enum": [
            "checking",
            "savings"
          ]
        },
        "routing_number": {
          "type": "string",
          "description": "The bank account's routing number. Only present for ACH payment methods."
        },
        "routing_number_bank": {
          "type": "string",
          "description": "The bank name of this routing number."
        },
        "username": {
          "type": "string",
          "description": "Username of the associated payment method. Currently only associated with Venmo."
        }
      }
    },
    "TransactionFraudInfo": {
      "type": "object",
      "title": "Fraud information",
      "readOnly": true,
      "properties": {
        "object": {
          "type": "string",
          "title": "Object type",
          "readOnly": true
        },
        "score": {
          "type": "integer",
          "title": "Kount score",
          "minimum": 1,
          "maximum": 99
        },
        "decision": {
          "title": "Kount decision",
          "maxLength": 10,
          "type": "string",
          "enum": [
            "approve",
            "decline",
            "escalate",
            "review"
          ]
        },
        "reference": {
          "type": "string",
          "title": "Kount transaction reference ID"
        },
        "risk_rules_triggered": {
          "type": "array",
          "title": "Risk Rules Triggered",
          "description": "A list of fraud risk rules that were triggered for the transaction.",
          "items": {
            "$ref": "#/$defs/FraudRiskRule"
          }
        }
      }
    }
  }
}

Work with this as data

Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for schemas

4 MCP tools reach this
  • find_json_schemasBrowse and filter every JSON Schema in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/recurly-transaction"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.