Transactions

The Transaction endpoints retrieve historical transaction data. Use them for reporting, reconciliation, and transaction lookup.

Read Transaction

Retrieves the full details of a single transaction by its id.

Read transaction

get

/api/v2/transaction/{id}

Get a transaction

Authorizations

AuthorizationstringRequired

Path parameters

idstringRequired

transaction id

Example: 76944d4b-89e6-48d2-ac04-675383c3eedf

Responses

200

Transaction

application/json

idstringOptional

The unique transaction id. This is the identifier to be used for locating the transaction and for reconciliation and auditing.

Example: 63bbc548-d2de-4546-b106-880a5018461c

amountstringOptional

Amount including decimal place.

acquirer_authorizing_network_idstringOptional

The Network ID returned in the original authorization response.

acquirer_authorizing_network_id_descriptorstringOptional

The name or descriptor that corresponds with the acquirer_authorizing_network_id returned in the original authorization response.

acquirer_response_codestring · max: 4Optional

Acquirer response returned during the authorisation.

Example: 0000

acquirer_response_messagestringOptional

The response description generated by the acquirer corresponding to the acquirer response code.

currency_codestring · enumOptional

Three-letter ISO 4217 alphabetical currency code. e.g. USD. Values correspond to ISO 4217.

Possible values:

citystringOptional

The city resolved from the customer's ip address.

country_codestringOptional

The country code resolved from the customer's ip address.

created_atstringOptional

The time at which the transaction was created

customerstringOptional

The ID of a customer.

customer_ipstring · max: 45Optional

The IP Address v4 where the event originated.

dynamic_descriptorstringOptional

A short reference / descriptor that will show up on the customers bank statement. Please refer to the card payment integration guide for the format requirements, which are specific per card processor.

geo_locationstring[]Optional

The latitude / longitude resolved from the customer's ip address.

payment_productstringOptional

The payment product corresponding to this transaction.

payment_product_typestring · enumOptional

The payment product type corresponding to this transaction. Fees applied to the transaction, is based on the payment product

Default: UnknownPossible values:

processor_referencestringOptional

Reference identifying the transaction, as provided by the processor.

statusstringOptional

Display transaction type and status, including if partial, of the related order transaction. E.g. 'PARTIAL CAPTURE AUTHORIZED'.

Example: REFUND AUTHORIZED

transaction_typestring · enumOptional

A type indicator for the main operation or service that was performed as part of the transaction event.

Possible values:

transaction_statusstring · enumOptional

This represents the available states that a transaction may have. At any given point it may only have a single state.

Possible values:

parent_idstringOptional

The transaction id of a parent transaction, where the current transaction is an action based on a previous transactions.

Example: 63bbc548-d2de-4546-b106-880a5018461c

reason_codestring · max: 4Optional

A reason code assigned by the acquiring platform; '0000' in case of success.

card_brandstringOptional

Represents a Card type or brand. It should correspond to a consistent name, the list of standard names is as follows:

Value	Description
AMEX	American Express
CB	Carte Bancaires
DINERS	Diners Club International
DISCOVER	Diners Club Discover
JCB	Japan Credit Bureau
MAESTRO	Multi-national Debit (MasterCard)
MASTERCARD	MasterCard
VISA	Visa
UPI	Union Pay International
GIFT_CARD	Gift Card (Generic)
PLCC	Private Label Credit Card
Other local schemes as applicable. Enter a pre-defined name to represent the scheme or type.
Note: 1. For gift cards, card brand is mandatory and the value should be GIFT_CARD.

This parameter is mandatory for dual branded cards.

merchant_referencestring · max: 50Optional

A reference specified by the merchant to identify the transaction.

user_agentstringOptional

The full user agent string of the device the customer used to submit the transaction.

arnstringOptional

Acquirer reference number. Generated by the Acquirer at the time of clearing for card transactions.

authorization_codestringOptional

An authorization code assigned by the processing platform.

avs_resultstring · enumOptional

Address verification services result, which provides information about the outcome of the AVS check. The full list of codes and descriptions can be found here

Example: APossible values:

created_bystringOptional

The ID of the user who initiated the transaction. Only set when shopper_interaction = moto, mail_order or telephone_order.

cvv_presentbooleanOptional

True if the card was used with a cvv.

cvv_resultstring · enumOptional

CVV verification result, as returned by the processor. Refer to Key Concepts->Cards for understanding of the values.

Possible values:

processor_payer_idstringOptional

This is the id used by the processor (e.g. an APM provider) for the payer.

Example: MLVAJGLDHNZ3G

pos_device_idstringOptional

dentifier of the POS device used for the transaction.

rrnstringOptional

Retrieval Reference Number, is a transaction identifying reference number that is designated by the card acceptor system.

shopper_interactionstring · enumOptional

Determines the point of sale of a customer. Possible values: pos, moto, mail_order, telephone_order, ecommerce and cont_auth.

Possible values:

stanstring · max: 40Optional

A number assigned by a transaction initiator(originator) to assist in identifying a transaction uniquely. The trace identifier remains unchanged for all messages within a two-message exchange, e.g. request/repeat and response. This property can be used to store the System trace audit number (STAN) as used in the ISO8583 specification (DE 11). Note the contents of this field are mandatory in many specifications - ISO8583, AS2805 (DE11) and are often related to the Retrieval Reference Number (RRN) as also specified in ISO8583. Unfortunately due to the usage in these earlier specifications, a STAN was limited to 6 digits which means that it cannot be utilised as a general purpose unique id. In addition, this entry is often printed on the receipt at a POI. ISO8583 DE11.

masked_card_numberstring · max: 16Optional

Masked PAN number, the first 6 and last 4 digits of the card.

promo_codestringOptional

A code defined by the merchant that affects the calculation of the total amount.

entity_idstring · uuid-flexibleOptional

The identifier of merchant entity you want to process the transaciton is already processed.

Example: 30b8bec8-5042-4e67-939c-5453fbe41711

acquirer_merchant_idstring · max: 36Optional

The Code identifying the card acceptor as issued by the Acquiring Institution. This may not be unique across institutions. Also referred to as the MID. ISO8583 - DE 42. This field is for the MID used between VF and a 3rd party acquirer or processor.

descriptionstringOptional

The description/message associated with this transaction. This will contain the refund reason for refunds.

400

Bad Request

application/json

401

Unauthorised

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get

/api/v2/transaction/{id}

GET /oidc/api/v2/transaction/{id} HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Basic username:password
Accept: */*

{
  "id": "63bbc548-d2de-4546-b106-880a5018461c",
  "amount": "text",
  "acquirer_authorizing_network_id": "text",
  "acquirer_authorizing_network_id_descriptor": "text",
  "acquirer_response_code": "0000",
  "acquirer_response_message": "text",
  "currency_code": "AED",
  "city": "text",
  "country_code": "text",
  "created_at": "text",
  "customer": "text",
  "customer_ip": "text",
  "dynamic_descriptor": "text",
  "geo_location": [
    "text"
  ],
  "payment_product": "text",
  "payment_product_type": "Unknown",
  "processor_reference": "text",
  "status": "REFUND AUTHORIZED",
  "transaction_type": "AUTHORISATION",
  "transaction_status": "APPROVED",
  "parent_id": "63bbc548-d2de-4546-b106-880a5018461c",
  "reason_code": "text",
  "card_brand": "text",
  "customer_details": {
    "title": "text",
    "first_name": "text",
    "middle_name": "text",
    "last_name": "text",
    "company_name": "text",
    "phone_number": "text",
    "email_address": "name@gmail.com",
    "shipping": {
      "address": "3732  Metz Lane",
      "city": "West Roxbury",
      "country": "US",
      "postal_code": "1114",
      "email": "name@gmail.com",
      "first_name": "Thelma",
      "last_name": "Tatro",
      "phone": "8577532706",
      "state": "MA"
    },
    "billing": {
      "address_1": "text",
      "address_2": "text",
      "address_3": "text",
      "city": "text",
      "country": "ZZ",
      "phone": "text",
      "postal_code": "text",
      "state": "text"
    },
    "language": "text"
  },
  "merchant_reference": "text",
  "user_agent": "text",
  "arn": "text",
  "authorization_code": "text",
  "avs_result": "A",
  "created_by": "text",
  "cvv_present": true,
  "cvv_result": "0",
  "processor_payer_id": "MLVAJGLDHNZ3G",
  "pos_device_id": "text",
  "rrn": "text",
  "shopper_interaction": "ecommerce",
  "stan": "text",
  "threed_authentication": {
    "eci_flag": "00",
    "enrolled": "text",
    "cavv": "text",
    "cavv_algorithm": "text",
    "pares_status": "text",
    "xid": "text",
    "ds_transaction_id": "text",
    "threeds_version": "1.0.2"
  },
  "masked_card_number": "text",
  "promo_code": "text",
  "payment_summary": {
    "captured_amount": "text"
  },
  "token_details": {
    "reuse_token_type": "INTERNAL",
    "reuse_token": "text",
    "analytics_token": "text"
  },
  "entity_id": "30b8bec8-5042-4e67-939c-5453fbe41711",
  "acquirer_merchant_id": "text",
  "description": "text",
  "detailed_amount": {
    "gratuity_amount": "text",
    "cashback_amount": "text",
    "donation_amount": "text",
    "tax_amount": "text",
    "surcharge_amount": "text"
  }
}

List Transactions

Returns a paginated array of transactions matching the supplied filters. Defaults to the last 7 days when no date range is specified. The maximum queryable range is 1 month.

Use transaction_status and transaction_type instead of the deprecated status parameter.

List transactions

get

/api/v2/transactions

List of transactions

Authorizations

AuthorizationstringRequired

Query parameters

acquirer_merchant_idstringOptional

amountnumberOptional

Amount of the transaction.

created_atstringOptional

The time at which the transaction was created.

created_startstringOptional

The start time range for when the transaction was created, specified in UTC. Use this in conjunction with created_end to query for a time range. A maximum range of 1 month of transactions can be queried at a time. Note: If this is not specified it will default to the current date/time - 7 days.

created_endstringOptional

The end time range for when a transaction was created, specified in UTC. Use this in conjunction with created_start to query for a time range. A maximum range of 1 month of transactions can be queried at a time. Note: If this is not specified it will default to the current date/time.

country_codestringOptional

The country code resolved from the customer's ip address.

currency_codestringOptional

Three-letter ISO 4217 alphabetical currency code. e.g. USD.

customerstringOptional

The ID of a customer.

enity_idstringOptional

The identifier of merchant entity you want to process the transaciton is already processed.

invoice_numberstring · max: 127Optional

The invoice number used to track the order for POS transactions. For Ecommerce, use merchant_reference.

merchant_referencestring · max: 50Optional

A reference specified by the merchant to identify the transaction.

Example: 7a1db7a8-6f24-4bc5-a51b-cef33fc05140

payment_product_typestring · enumOptional

Fees applied to the transaction, based on the payment product. e.g. For card transactions - interchange fees

Possible values:

shopper_interactionstring · enumOptional

Determines the point of sale of a customer.

Possible values:

statusstring · enumOptionalDeprecatedPossible values:

transaction_typestring · enumOptional

A type indicator for the main operation or service that was performed as part of the transaction event.

Possible values:

transaction_statusstring · enumOptional

This represents the available states that a transaction may have. At any given point it may only have a single state.

Possible values:

_sortstring · enumOptional

Sorts the results by ascending order according to the provided field. If the field is prefixed with dash (e.g. -created_at), the order is descending.

Possible values:

_skipnumberOptional

Skips a number of pages.

_limitnumber · min: 1 · max: 10000OptionalDefault: 50

reason_codestringOptional

A reason code assigned by the acquiring platform; '00' in case of success.

rrnstringOptional

Retrieval Reference Number, is a transaction identifying reference number that is designated by the card acceptor system.

pos_device_idnumberOptional

Identifier of the POS device used for the transaction.

stannumberOptional

System Trace Audit Number.

idstringOptional

The ID of the transaction

x-vfi-api-idempotencykeystringOptional

Unique transaction identifier

Responses

200

Transactions

application/json

idstringOptional

The unique transaction id. This is the identifier to be used for locating the transaction and for reconciliation and auditing.

Example: 63bbc548-d2de-4546-b106-880a5018461c

amountnumberOptional

Amount including decimal place.

acquirer_authorizing_network_idstringOptional

The Network ID returned in the original authorization response.

acquirer_authorizing_network_id_descriptorstringOptional

The name or descriptor that corresponds with the acquirer_authorizing_network_id returned in the original authorization response.

acquirer_response_codestring · max: 4Optional

Acquirer response returned during the authorisation.

Example: 0000

acquirer_response_messagestringOptional

The response description generated by the acquirer corresponding to the acquirer response code.

currency_codestring · enumOptional

Three-letter ISO 4217 alphabetical currency code. e.g. USD. Values correspond to ISO 4217.

Possible values:

citystringOptional

The city resolved from the customer's ip address.

country_codestringOptional

The country code resolved from the customer's ip address.

created_atstringOptional

The time at which the transaction was created

customerstringOptional

The ID of a customer.

customer_ipstring · max: 45Optional

The IP Address v4 where the event originated.

dynamic_descriptorstringOptional

geo_locationstring[]Optional

The latitude / longitude resolved from the customer's ip address.

payment_account_referencestringOptional

Payment Account Reference is a unique non-sensitive reference to the cardholder PAN.

payment_productstringOptional

The payment product corresponding to this transaction.

payment_product_typestring · enumOptional

The payment product type corresponding to this transaction. Fees applied to the transaction, is based on the payment product

Default: UnknownPossible values:

processor_referencestringOptional

Reference identifying the transaction, as provided by the processor.

statusstringOptional

Display transaction type and status, including if partial, of the related order transaction. E.g. 'PARTIAL CAPTURE AUTHORIZED'.

Example: REFUND AUTHORIZED

transaction_typestring · enumOptional

A type indicator for the main operation or service that was performed as part of the transaction event.

Possible values:

transaction_statusstring · enumOptional

This represents the available states that a transaction may have. At any given point it may only have a single state.

Possible values:

parent_idstringOptional

The transaction id of a parent transaction, where the current transaction is an action based on a previous transactions.

Example: 63bbc548-d2de-4546-b106-880a5018461c

reason_codestring · max: 4Optional

A reason code assigned by the acquiring platform; '0000' in case of success.

card_brandstringOptional

Represents a Card type or brand. It should correspond to a consistent name, the list of standard names is as follows:

Value	Description
AMEX	American Express
CB	Carte Bancaires
DINERS	Diners Club International
DISCOVER	Diners Club Discover
JCB	Japan Credit Bureau
MAESTRO	Multi-national Debit (MasterCard)
MASTERCARD	MasterCard
VISA	Visa
UPI	Union Pay International
GIFT_CARD	Gift Card (Generic)
PLCC	Private Label Credit Card
Other local schemes as applicable. Enter a pre-defined name to represent the scheme or type.
Note: 1. For gift cards, card brand is mandatory and the value should be GIFT_CARD.

This parameter is mandatory for dual branded cards.

merchant_referencestring · max: 50Optional

A reference specified by the merchant to identify the transaction.

user_agentstringOptional

The full user agent string of the device the customer used to submit the transaction.

arnstringOptional

Acquirer reference number. Generated by the Acquirer at the time of clearing for card transactions.

authorization_codestringOptional

An authorization code assigned by the processing platform.

avs_resultstring · enumOptional

Address verification services result, which provides information about the outcome of the AVS check. The full list of codes and descriptions can be found here

Example: APossible values:

created_bystringOptional

The ID of the user who initiated the transaction. Only set when shopper_interaction = moto, mail_order or telephone_order.

cvv_presentbooleanOptional

True if the card was used with a cvv.

cvv_resultstring · enumOptional

CVV verification result, as returned by the processor. Refer to Key Concepts->Cards for understanding of the values.

Possible values:

processor_payer_idstringOptional

This is the id used by the processor (e.g. an APM provider) for the payer.

Example: MLVAJGLDHNZ3G

pos_device_idstringOptional

dentifier of the POS device used for the transaction.

rrnstringOptional

Retrieval Reference Number, is a transaction identifying reference number that is designated by the card acceptor system.

shopper_interactionstring · enumOptional

Determines the point of sale of a customer. Possible values: pos, moto, mail_order, telephone_order, ecommerce and cont_auth.

Possible values:

stanstring · max: 40Optional

masked_card_numberstring · max: 16Optional

Masked PAN number, the first 6 and last 4 digits of the card.

promo_codestringOptional

A code defined by the merchant that affects the calculation of the total amount.

entity_idstring · uuid-flexibleOptional

The identifier of merchant entity you want to process the transaciton is already processed.

Example: 30b8bec8-5042-4e67-939c-5453fbe41711

acquirer_merchant_idstring · max: 36Optional

descriptionstringOptional

The description/message associated with this transaction. This will contain the refund reason for refunds.

400

Bad Request

application/json

401

Unauthorised

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get

/api/v2/transactions

GET /oidc/api/v2/transactions HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Basic username:password
Accept: */*

[
  {
    "id": "63bbc548-d2de-4546-b106-880a5018461c",
    "amount": 1,
    "acquirer_authorizing_network_id": "text",
    "acquirer_authorizing_network_id_descriptor": "text",
    "acquirer_response_code": "0000",
    "acquirer_response_message": "text",
    "currency_code": "AED",
    "city": "text",
    "country_code": "text",
    "created_at": "text",
    "customer": "text",
    "customer_ip": "text",
    "dynamic_descriptor": "text",
    "geo_location": [
      "text"
    ],
    "payment_account_reference": "text",
    "payment_product": "text",
    "payment_product_type": "Unknown",
    "processor_reference": "text",
    "status": "REFUND AUTHORIZED",
    "transaction_type": "AUTHORISATION",
    "transaction_status": "APPROVED",
    "parent_id": "63bbc548-d2de-4546-b106-880a5018461c",
    "reason_code": "text",
    "card_brand": "text",
    "customer_details": {
      "title": "text",
      "first_name": "text",
      "middle_name": "text",
      "last_name": "text",
      "company_name": "text",
      "phone_number": "text",
      "email_address": "name@gmail.com",
      "shipping": {
        "address": "3732  Metz Lane",
        "city": "West Roxbury",
        "country": "US",
        "postal_code": "1114",
        "email": "name@gmail.com",
        "first_name": "Thelma",
        "last_name": "Tatro",
        "phone": "8577532706",
        "state": "MA"
      },
      "billing": {
        "address_1": "text",
        "address_2": "text",
        "address_3": "text",
        "city": "text",
        "country": "ZZ",
        "phone": "text",
        "postal_code": "text",
        "state": "text"
      },
      "language": "text"
    },
    "merchant_reference": "text",
    "user_agent": "text",
    "arn": "text",
    "authorization_code": "text",
    "avs_result": "A",
    "created_by": "text",
    "cvv_present": true,
    "cvv_result": "0",
    "processor_payer_id": "MLVAJGLDHNZ3G",
    "pos_device_id": "text",
    "rrn": "text",
    "shopper_interaction": "ecommerce",
    "stan": "text",
    "threed_authentication": {
      "eci_flag": "00",
      "enrolled": "text",
      "cavv": "text",
      "cavv_algorithm": "text",
      "pares_status": "text",
      "xid": "text",
      "ds_transaction_id": "text",
      "threeds_version": "1.0.2"
    },
    "masked_card_number": "text",
    "promo_code": "text",
    "payment_summary": {
      "captured_amount": 1
    },
    "entity_id": "30b8bec8-5042-4e67-939c-5453fbe41711",
    "acquirer_merchant_id": "text",
    "description": "text",
    "detailed_amount": {
      "gratuity_amount": "text",
      "cashback_amount": "text",
      "donation_amount": "text",
      "tax_amount": "text",
      "surcharge_amount": "text"
    }
  }
]

Count Transactions

Returns the count of transactions matching the supplied filters without returning full transaction objects. Useful for pagination or dashboard totals.

Count transactions

get

/api/v2/transactions/count

Count transactions

Authorizations

AuthorizationstringRequired

Query parameters

acquirer_merchant_idstringOptional

amountnumberOptional

Amount of the transaction.

created_atstringOptional

The time at which the transaction was created.

country_codestringOptional

The country code resolved from the customer's ip address.

currency_codestringOptional

Three-letter ISO 4217 alphabetical currency code. e.g. USD.

customerstringOptional

The ID of a customer.

enity_idstringOptional

The identifier of merchant entity you want to process the transaciton is already processed.

invoice_numberstring · max: 127Optional

The invoice number used to track the order for POS transactions. For Ecommerce, use merchant_reference.

merchant_referencestring · max: 50Optional

A reference specified by the merchant to identify the transaction.

Example: 7a1db7a8-6f24-4bc5-a51b-cef33fc05140

payment_product_typestring · enumOptional

Fees applied to the transaction, based on the payment product. e.g. For card transactions - interchange fees

Possible values:

shopper_interactionstring · enumOptional

Determines the point of sale of a customer.

Possible values:

statusstring · enumOptionalDeprecatedPossible values:

transaction_typestring · enumOptional

A type indicator for the main operation or service that was performed as part of the transaction event.

Possible values:

transaction_statusstring · enumOptional

This represents the available states that a transaction may have. At any given point it may only have a single state.

Possible values:

reason_codestringOptional

A reason code assigned by the acquiring platform; '00' in case of success.

rrnstringOptional

Retrieval Reference Number, is a transaction identifying reference number that is designated by the card acceptor system.

pos_device_idnumberOptional

Identifier of the POS device used for the transaction.

stannumberOptional

System Trace Audit Number.

idstringOptional

The ID of the transaction

Responses

200

Count transactions

application/json

countnumberOptional

count of transaction

Example: 0

400

Bad Request

application/json

401

Unauthorised

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get

/api/v2/transactions/count

GET /oidc/api/v2/transactions/count HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Basic username:password
Accept: */*

{
  "count": 0
}

Key Response Fields

GatewayTransaction (single read)
  ├── id                    ← unique transaction identifier
  ├── transaction_type      ← AUTHORISATION, CAPTURE, REFUND, VOID, etc.
  ├── transaction_status    ← AUTHORISED, SETTLED, DECLINED, CANCELLED, etc.
  ├── status                ← display string (e.g. "PARTIAL CAPTURE AUTHORIZED")
  ├── amount                ← string with decimal (e.g. "150.00")
  ├── parent_id             ← ID of the parent transaction (for captures, refunds, etc.)
  ├── authorization_code
  ├── rrn                   ← Retrieval Reference Number (ISO8583 DE37)
  ├── arn                   ← Acquirer Reference Number
  ├── masked_card_number    ← first 6 + last 4 digits
  └── token_details         ← reuse_token and analytics_token if tokenisation was used

PreviousPayment Modifications NextToken Management

Was this helpful?