A Transaction object is created when you authorize or capture an invoice during payment.
You cannot change the fields of the object yourself, but ProcessOut will update the status and other fields automatically as the transaction progresses. An event is fired whenever the status of a transaction changes. You can receive notification of the event using webhooks.

For any fields that refer to an amount of money (such as amount and authorized_amount), you should specify the amount in the major unit of the currency rather than the minor unit (so this would mean dollars rather than cents if the currency is USD, for example).

Note that the metadata field of a Transaction object is simply copied from the Invoice object that was used for the payment. You cannot set or update the metadata as you can with other objects.

Transaction object

List of fields

📘
While the transaction object may seem to contain many parameters, only a handful are useful to merchants. Other may be used under specific scenarios as ProcessOut is fully transparent with the data it gathers. The following list contains most parameters that may be useful to merchants

Field	Type	Description
id	string	String value that uniquely identifies the transaction.
status	string	Status of the transaction (see Transaction status codes below.
project_id (Expandable)	string	Project that the transaction belongs to.
invoice_id (Expandable)	string	Invoice used to create the transaction.
customer_id (Expandable)	string	Customer linked to the transaction.
token_id (Expandable)	string	Token used to capture the transaction.
card_id (Expandable)	string	Card used to capture the transaction.
gateway_configuration_id (Expandable)	string	Gateway configuration that was eventually used to process the transaction.
operations (Expandable)	string	Sequence of operations (pending, failed or successful) made on the transactions, such as `authorization`, `capture` and `refund`. See operation object attributes
name	string	Name of the transaction.
amount	string	Amount requested when creating the transaction.
authorized_amount	string	Amount that was authorized for the transaction.
captured_amount	string	Amount that was captured for the transaction.
refunded_amount	string	Amount that was refunded for the transaction.
available_amount	string	Amount available for the transaction (captured - refunded).
card_checks	object	Object containing the CVC and AVS checks See card checks attributes
external_details (Expandable)	object	Object containing customer and shipping information, which is returned from the PSP. This is used when the customer enters the shipping/customer details directly on the PSPs site. See External details attributes
currency	string	Currency of the transaction.
authorized	boolean	Denotes whether or not the transaction was authorized.
captured	boolean	Denotes whether or not the transaction was captured.
refunded	boolean	Denotes whether or not the transaction was refunded.
voided	boolean	Denotes whether or not the transaction was voided.
chargedback	boolean	Denotes whether or not the transaction was charged back.
received_fraud_notification	boolean	Denotes whether or not the transaction received a fraud notification event.
received_retrieval_request	boolean	Denotes whether or not the transaction received a retrieval request event.
gateway_name	string	Name of the last gateway where the transaction was attempted. The `operations` list has the complete history of the transaction.
error_code	string	Transaction error code (`null` if the transaction was successful).
error_message	string	Transaction error message (`null` if the transaction was successful).
metadata	object	Metadata copied from the transaction’s invoice, in the form of key-value pairs (string - string).
sandbox	boolean	Denotes whether or not this transaction was created in the sandbox testing environment.
created_at	date	Date and time when this transaction was created.

Operation object

Field	Type	Description
type	string	Type of the operation. Can be `request`, `three_d_s_check`, `authorization`, `capture`, `void`, `refund`, or `chargeback`.
is_attempt	boolean	Denotes whether or not the operation is an attempt.
has_failed	boolean	Denotes whether or not the operation has failed. Typically, `has_failed` will only be set when `is_attempt` is `false` (the operation only gets its results back after first attempting something).
is_accountable	boolean	Denotes whether or not the operation amount should be used to compute the actual amount of the transaction.
error_code	string	Operation error code, typically set when `has_failed` is true.
error_message	string	Operation error message (`null` if the operation was successful).
gateway_operation_id	string	ID number assigned by the Payment Service Provider for the operation they performed.
metadata	Object	Context related to the transaction’s invoice, key-value pair (string - string).
created_at	date	Date and time when this operation was created.

Card checks object

Field	Type	Description
cvc_check	string	CVC check status. Can be `pending`, `unavailable`, `unknown`, `failed`, or `passed`.
avs_check	string	AVS check status. Can be `pending`, `unavailable`, `unknown`, `failed`, `failed-name`, `failed-address`, `failed-postal`, `failed-address-passed-postal`, `failed-postal-passed-address`, or `passed`.
avs_postal_check	string	AVS postal check status. Can be `pending`, `unavailable`, `unknown`, `failed`, or `passed`.
avs_street_check	string	AVS street check status. Can be `pending`, `unavailable`, `unknown`, `failed`, or `passed`.
avs_name_check	string	AVS name check status. Can be `pending`, `unavailable`, `unknown`, `failed`, or `passed`.

External Details object

Field	Type	Description
customer	object	Contains details relating to the customer's information submitted directly to the external provider. See Customer external details attributes.
shipping	object	Contains details relating to the shipping information submitted directly to the external provider. See Shipping external details attributes.

Customer External Details object

Field	Type	Description
address1	string	Address line one of the customer's address
address2	string	Address line two of the customer's address
city	string	City of the customer's address
state	string	State of the customer's address
country_code	string	Country code of the customer's address
zip	string	ZIP code of the customer's address
email	string	The customer's email address
phone_number	string	The customer's phone number
first_name	string	The customer's first name
last_name	string	The customer's last name

Shipping External Details object

Field	Type	Description
address1	string	Address line one of the shipping address
address2	string	Address line two of the shipping address
city	string	City of the shipping address
state	string	State of the shipping address
country_code	string	Country code of the shipping address
zip	string	ZIP code of the shipping address

JSON object

{
  "success": true,
  "transaction": {
    "id": "tr_msUOyQgmJp8UduKANzblNwa5hrjQGag5",
    "project_id": "proj_IFCgGTmyClrgTOzsschN1y7GJttHVQ7S",
    "customer_id": "cust_D5BDaQQ8XL4xoUfKRjpBQjoEIwMA6asA",
    "routing_tags": null,
    "fraud_service_results": null,
    "operations": [
      {
        "id": "tr_op_EVh8Ss7qmnWTVqna1CaU7HHbVopVdx1k",
        "transaction_id": "tr_msUOyQgmJp8UduKANzblNwa5hrjQGag5",
        "authenticated_transaction_id": "5196843282",
        "authorization_code": null,
        "gateway_configuration_id": "gway_conf_c23e011db34f4bac44e051840dfa3783",
        "token_id": null,
        "card_id": "card_DOekWV1nHVVloKxjqDOuZFr4CmSGj5rx",
        "amount": "29",
        "amount_local": "32.17985203",
        "currency": "EUR",
        "is_attempt": false,
        "has_failed": false,
        "is_accountable": false,
        "type": "request",
        "metadata": {
          "is_sale": "false"
        },
        "error_code": null,
        "error_message": null,
        "payment_type": "card",
        "acquirer_name": null,
        "payment_data_three_d_s_request": null,
        "payment_data_network_authentication": null,
        "payment_data_three_d_s_authentication": null,
        "payment_data_three_d_s_2_authentication": null,
        "eci": null,
        "mcc": null,
        "merchant_account_id": null,
        "is_on_us": null,
        "arn": null,
        "rrn": null,
        "scheme_id": "5196843282",
        "initial_scheme_transaction_id": "",
        "card_checks": {
          "cvc_check": "unavailable",
          "cvc_check_reason": null,
          "avs_check": "",
          "avs_postal_check": "unavailable",
          "avs_postal_check_reason": null,
          "avs_street_check": "unavailable",
          "avs_street_check_reason": null,
          "avs_name_check": "unavailable",
          "avs_name_check_reason": null
        },
        "gateway_operation_id": "",
        "gateway_data": {
          "token": "test-valid"
        },
        "chargeback_reason": null,
        "created_at": "2023-04-22T15:19:13.048677422Z",
        "merchant_advice_code": null,
        "merchant_advice_reason": null,
        "recommendation_code": null,
        "recommendation_reason": null,
        "challenge_indicator": "no-preference",
        "sca_exemption_reason": ""
      },
      {
        "id": "tr_op_mk6jIB4Hd5IVTe58s5D2yoTVCch8WVx4",
        "transaction_id": "tr_msUOyQgmJp8UduKANzblNwa5hrjQGag5",
        "authenticated_transaction_id": "5196843282",
        "authorization_code": null,
        "gateway_configuration_id": "gway_conf_c23e011db34f4bac44e051840dfa3783",
        "token_id": null,
        "card_id": "card_DOekWV1nHVVloKxjqDOuZFr4CmSGj5rx",
        "amount": "29",
        "amount_local": "32.17985203",
        "currency": "EUR",
        "is_attempt": true,
        "has_failed": false,
        "is_accountable": false,
        "type": "authorization",
        "metadata": {
          "is_sale": "false"
        },
        "error_code": null,
        "error_message": null,
        "payment_type": "card",
        "acquirer_name": null,
        "payment_data_three_d_s_request": null,
        "payment_data_network_authentication": null,
        "payment_data_three_d_s_authentication": null,
        "payment_data_three_d_s_2_authentication": null,
        "eci": null,
        "mcc": null,
        "merchant_account_id": null,
        "is_on_us": null,
        "arn": null,
        "rrn": null,
        "scheme_id": "5196843282",
        "initial_scheme_transaction_id": "",
        "card_checks": {
          "cvc_check": "unavailable",
          "cvc_check_reason": null,
          "avs_check": "",
          "avs_postal_check": "unavailable",
          "avs_postal_check_reason": null,
          "avs_street_check": "unavailable",
          "avs_street_check_reason": null,
          "avs_name_check": "unavailable",
          "avs_name_check_reason": null
        },
        "gateway_operation_id": "test-valid-17584ad826c34212",
        "gateway_data": {
          "token": "test-valid"
        },
        "chargeback_reason": null,
        "created_at": "2023-04-22T15:19:13.048722723Z",
        "merchant_advice_code": null,
        "merchant_advice_reason": null,
        "recommendation_code": null,
        "recommendation_reason": null,
        "challenge_indicator": "no-preference",
        "sca_exemption_reason": ""
      },
      {
        "id": "tr_op_WVcMoRwE3QFv5FpQf3xEwjoTqrwLUzVv",
        "transaction_id": "tr_msUOyQgmJp8UduKANzblNwa5hrjQGag5",
        "authenticated_transaction_id": "5196843282",
        "authorization_code": null,
        "gateway_configuration_id": "gway_conf_c23e011db34f4bac44e051840dfa3783",
        "token_id": null,
        "card_id": "card_DOekWV1nHVVloKxjqDOuZFr4CmSGj5rx",
        "amount": "29",
        "amount_local": "32.17985203",
        "currency": "EUR",
        "is_attempt": false,
        "has_failed": false,
        "is_accountable": false,
        "type": "authorization",
        "metadata": {
          "is_sale": "false"
        },
        "error_code": null,
        "error_message": null,
        "payment_type": "card",
        "acquirer_name": null,
        "payment_data_three_d_s_request": null,
        "payment_data_network_authentication": null,
        "payment_data_three_d_s_authentication": null,
        "payment_data_three_d_s_2_authentication": null,
        "eci": null,
        "mcc": null,
        "merchant_account_id": null,
        "is_on_us": null,
        "arn": null,
        "rrn": null,
        "scheme_id": "5196843282",
        "initial_scheme_transaction_id": "",
        "card_checks": {
          "cvc_check": "passed",
          "cvc_check_reason": "",
          "avs_check": "",
          "avs_postal_check": "passed",
          "avs_postal_check_reason": "",
          "avs_street_check": "passed",
          "avs_street_check_reason": "",
          "avs_name_check": "passed",
          "avs_name_check_reason": ""
        },
        "gateway_operation_id": "test-valid-17584ad826c34212",
        "gateway_data": {
          "token": "test-valid"
        },
        "chargeback_reason": null,
        "created_at": "2023-04-22T15:19:13.04876542Z",
        "merchant_advice_code": null,
        "merchant_advice_reason": null,
        "recommendation_code": null,
        "recommendation_reason": null,
        "challenge_indicator": "no-preference",
        "sca_exemption_reason": ""
      }
    ],
    "name": "Amazing Product",
    "currency": "EUR",
    "details": {
      "country": "GB"
    },
    "metadata": {
      "fruit": "banana"
    },
    "sandbox": true,
    "created_at": "2023-04-22T15:19:08.653492Z",
    "invoice_id": "iv_cyxGn7nrOHuqQO4X5jbbwv16eN7GkZvB",
    "gateway_name": "sandbox",
    "status": "authorized",
    "three_d_s_status": "unchecked",
    "three_d_s_version": null,
    "gateway_configuration_id": "gway_conf_c23e011db34f4bac44e051840dfa3783",
    "token_id": null,
    "card_id": "card_DOekWV1nHVVloKxjqDOuZFr4CmSGj5rx",
    "error_code": null,
    "error_message": null,
    "three_d_s": null,
    "payment_type": "card",
    "eci": null,
    "mcc": null,
    "merchant_account_id": null,
    "cvc_check": "passed",
    "avs_check": "passed",
    "card_checks": {
      "cvc_check": "passed",
      "cvc_check_reason": null,
      "avs_check": "passed",
      "avs_postal_check": "passed",
      "avs_postal_check_reason": null,
      "avs_street_check": "passed",
      "avs_street_check_reason": null,
      "avs_name_check": "passed",
      "avs_name_check_reason": null
    },
    "amount": "29",
    "amount_local": "32.17985203",
    "authorized_amount": "29",
    "authorized_amount_local": "32.17985203",
    "captured_amount": "0",
    "captured_amount_local": "0",
    "available_amount": "0",
    "available_amount_local": "0",
    "incremented_amount": "0",
    "incremented_amount_local": "0",
    "refunded_amount": "0",
    "refunded_amount_local": "0",
    "currency_fee": null,
    "gateway_fee": "0",
    "gateway_fee_local": "0",
    "authorized_at": "2023-04-22T15:19:13.04876542Z",
    "captured_at": null,
    "refunded_at": null,
    "voided_at": null,
    "chargedback_at": null,
    "received_fraud_notification": false,
    "received_retrieval_request": false,
    "acquirer_name": null,
    "attempts_count": 1,
    "authorized": true,
    "captured": false,
    "refunded": false,
    "voided": false,
    "chargedback": false,
    "merchant_advice_code": null,
    "merchant_advice_reason": null,
    "recommendation_code": null,
    "recommendation_reason": null,
    "scheme_id": "5196843282",
    "initial_scheme_transaction_id": null,
    "sca": {
      "scope": "out-of-scope",
      "out_of_scope_reason": "mit",
      "inscope_compliance": "not-applicable",
      "challenge_result": "honoured",
      "exemption_result": "no-exemption-reason-set"
    },
    "subscription_cycle": null,
    "error_recommendations": [],
    "gateway_fee_details": {
      "processing_fee": "0",
      "exchange_fee": "0",
      "refund_fee": "0",
      "interchange_fee": "0",
      "scheme_fee": "0",
      "markup_fee": "0",
      "interchange_fee_estimate": "0",
      "scheme_fee_estimate": "0"
    },
    "external_details": {
      "customer": {
        "last_name": "",
        "first_name": "",
        "address1": "",
        "address2": "",
        "state": "",
        "city": "",
        "zip": "",
        "country_code": "",
        "phone_number": "",
        "email": ""
      },
      "shipping": {
        "address1": "",
        "address2": "",
        "state": "",
        "city": "",
        "zip": "",
        "country_code": ""
      }
    },
    "estimated_fee": "1.17",
    "refunds": null,
    "buyer": {
      "name": "",
      "email": "",
      "address": "",
      "phone": ""
    },
    "is_on_us": null,
    "processout_fee": "0",
    "subscription_id": null,
    "duplicate_distance_seconds": null
  }
}

Transaction status codes

The status field of the Transaction object contains a code that represents the current status of the transaction. This gets updated automatically as the transaction progresses (from authorization to capture for example).

The table below shows all the status codes along with their meanings.

Status	Description
waiting	No payment has been placed yet.
pending	The payment is pending confirmation by the payment gateway.
authorized	The payment was authorized but has not yet been captured.
pending-capture	The payment gateway initiated a capture, but it has not been confirmed yet.
completed	The payment was successfully completed.
failed	The payment was placed, but has failed
voided	The payment was voided.
refunded	The transaction was refunded (totally or partially).
in-review	The transaction is pending fraud review.
blocked	The transaction was blocked by your blocking rules or by a fraud review.
retrieval-request	The payment was previously completed but the customer does not recognize the payment and is asking for information.
fraud-notification	The payment was previously completed but the bank is notifying you that a chargeback might happen.
chargeback-initiated	The payment was previously completed but the customer has filed a dispute against it.
solved	The previous dispute has been resolved in your favor.
reversed	The previous dispute has been resolved in your customer’s favor.