Dashboard ↗

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

FieldTypeDescription
idstringString value that uniquely identifies the transaction.
statusstringStatus of the transaction (see Transaction status codes below.
project_id (Expandable)stringProject that the transaction belongs to.
invoice_id (Expandable)stringInvoice used to create the transaction.
customer_id (Expandable)stringCustomer linked to the transaction.
token_id (Expandable)stringToken used to capture the transaction.
card_id (Expandable)stringCard used to capture the transaction.
gateway_configuration_id (Expandable)stringGateway configuration that was eventually used to process the transaction.
operations (Expandable)stringSequence of operations (pending, failed or successful) made on the transactions, such as authorization, capture and refund.
See operation object attributes
namestringName of the transaction.
amountstringAmount requested when creating the transaction.
authorized_amountstringAmount that was authorized for the transaction.
captured_amountstringAmount that was captured for the transaction.
refunded_amountstringAmount that was refunded for the transaction.
available_amountstringAmount available for the transaction (captured - refunded).
card_checksobjectObject containing the CVC and AVS checks
See card checks attributes
external_details (Expandable)objectObject 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
currencystringCurrency of the transaction.
authorizedbooleanDenotes whether or not the transaction was authorized.
capturedbooleanDenotes whether or not the transaction was captured.
refundedbooleanDenotes whether or not the transaction was refunded.
voidedbooleanDenotes whether or not the transaction was voided.
chargedbackbooleanDenotes whether or not the transaction was charged back.
received_fraud_notificationbooleanDenotes whether or not the transaction received a fraud notification event.
received_retrieval_requestbooleanDenotes whether or not the transaction received a retrieval request event.
gateway_namestringName of the last gateway where the transaction was attempted. The operations list has the complete history of the transaction.
error_codestringTransaction error code (null if the transaction was successful).
error_messagestringTransaction error message (null if the transaction was successful).
metadataobjectMetadata copied from the transaction’s invoice, in the form of key-value pairs (string - string).
sandboxbooleanDenotes whether or not this transaction was created in the sandbox testing environment.
created_atdateDate and time when this transaction was created.

Operation object

FieldTypeDescription
typestringType of the operation. Can be request, three_d_s_check, authorization, capture, void, refund, or chargeback.
is_attemptbooleanDenotes whether or not the operation is an attempt.
has_failedbooleanDenotes 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_accountablebooleanDenotes whether or not the operation amount should be used to compute the actual amount of the transaction.
error_codestringOperation error code, typically set when has_failed is true.
error_messagestringOperation error message (null if the operation was successful).
gateway_operation_idstringID number assigned by the Payment Service Provider for the operation they performed.
metadataObjectContext related to the transaction’s invoice, key-value pair (string - string).
created_atdateDate and time when this operation was created.

Card checks object

FieldTypeDescription
cvc_checkstringCVC check status. Can be pending, unavailable, unknown, failed, or passed.
avs_checkstringAVS 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_checkstringAVS postal check status. Can be pending, unavailable, unknown, failed, or passed.
avs_street_checkstringAVS street check status. Can be pending, unavailable, unknown, failed, or passed.
avs_name_checkstringAVS name check status. Can be pending, unavailable, unknown, failed, or passed.

External Details object

FieldTypeDescription
customerobjectContains details relating to the customer's information submitted directly to the external provider. See Customer external details attributes.
shippingobjectContains details relating to the shipping information submitted directly to the external provider. See Shipping external details attributes.

Customer External Details object

FieldTypeDescription
address1stringAddress line one of the customer's address
address2stringAddress line two of the customer's address
citystringCity of the customer's address
statestringState of the customer's address
country_codestringCountry code of the customer's address
zipstringZIP code of the customer's address
emailstringThe customer's email address
phone_numberstringThe customer's phone number
first_namestringThe customer's first name
last_namestringThe customer's last name

Shipping External Details object

FieldTypeDescription
address1stringAddress line one of the shipping address
address2stringAddress line two of the shipping address
citystringCity of the shipping address
statestringState of the shipping address
country_codestringCountry code of the shipping address
zipstringZIP 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.

StatusDescription
waitingNo payment has been placed yet.
pendingThe payment is pending confirmation by the payment gateway.
authorizedThe payment was authorized but has not yet been captured.
pending-captureThe payment gateway initiated a capture, but it has not been confirmed yet.
completedThe payment was successfully completed.
failedThe payment was placed, but has failed
voidedThe payment was voided.
refundedThe transaction was refunded (totally or partially).
in-reviewThe transaction is pending fraud review.
blockedThe transaction was blocked by your blocking rules or by a fraud review.
retrieval-requestThe payment was previously completed but the customer does not recognize the payment and is asking for information.
fraud-notificationThe payment was previously completed but the bank is notifying you that a chargeback might happen.
chargeback-initiatedThe payment was previously completed but the customer has filed a dispute against it.
solvedThe previous dispute has been resolved in your favor.
reversedThe previous dispute has been resolved in your customer’s favor.