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 |
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. |