Get transaction

get https://api.privacy.com/v1/transactions/{transaction_token}

Get specific transaction.

Responses

Response body

object

acquirer_reference_number

string | null

A fixed-width 23-digit numeric identifier for the Transaction that may be set if the transaction originated from the Mastercard network. This number may be used for dispute tracking.

amount

integer

Authorization amount (in USD cents) of the transaction. This may change over time, and will represent the settled amount once the transaction is settled.

authorization_amount

integer

Authorization amount (in USD cents) of the transaction. This amount always represents the amount authorized for the transaction, unaffected by settlement.

cardholder_authentication

object | null

3ds_version

string | null

required

3-D Secure Protocol version. Possible values:

1: 3-D Secure Protocol version 1.x applied to the transaction.
2: 3-D Secure Protocol version 2.x applied to the transaction.
null: 3-D Secure was not used for the transaction

acquirer_exemption

string

required

Exemption applied by the ACS to authenticate the transaction without requesting a challenge. Possible values:

AUTHENTICATION_OUTAGE_EXCEPTION: Authentication Outage Exception exemption.
LOW_VALUE: Low Value Payment exemption.
MERCHANT_INITIATED_TRANSACTION: Merchant Initiated Transaction (3RI).
NONE: No exemption applied.
RECURRING_PAYMENT: Recurring Payment exemption.
SECURE_CORPORATE_PAYMENT: Secure Corporate Payment exemption.
STRONG_CUSTOMER_AUTHENTICATION_DELEGATION: Strong Customer Authentication Delegation exemption.
TRANSACTION_RISK_ANALYSIS: Acquirer Low-Fraud and Transaction Risk Analysis exemption.

Maps to the 3-D Secure transChallengeExemption field.

AUTHENTICATION_OUTAGE_EXCEPTION LOW_VALUE MERCHANT_INITIATED_TRANSACTION NONE RECURRING_PAYMENT SECURE_CORPORATE_PAYMENT STRONG_CUSTOMER_AUTHENTICATION_DELEGATION TRANSACTION_RISK_ANALYSIS

liability_shift

string

required

Indicates whether chargeback liability shift applies to the transaction. Possible values:

3DS_AUTHENTICATED: The transaction was fully authenticated through a 3-D Secure flow, chargeback liability shift applies.
ACQUIRER_EXEMPTION: The acquirer utilised an exemption to bypass Strong Customer Authentication (transStatus = N, or transStatus = I). Liability remains with the acquirer and in this case the acquirer_exemption field is expected to be not NONE.
NONE: Chargeback liability shift has not shifted to the issuer, i.e. the merchant is liable.
TOKEN_AUTHENTICATED: The transaction was a tokenized payment with validated cryptography, possibly recurring. Chargeback liability shift to the issuer applies.

3DS_AUTHENTICATED ACQUIRER_EXEMPTION NONE TOKEN_AUTHENTICATED

verification_attempted

string

required

Verification attempted values:

APP_LOGIN: Out-of-band login verification was attempted by the ACS.
BIOMETRIC: Out-of-band biometric verification was attempted by the ACS.
NONE: No cardholder verification was attempted by the Access Control Server (e.g. frictionless 3-D Secure flow, no 3-D Secure, or stand-in Risk Based Analysis).
OTHER: Other method was used by the ACS to verify the cardholder (e.g. Mastercard Identity Check Express, recurring transactions, etc.)
OTP: One-time password verification was attempted by the ACS.

APP_LOGIN BIOMETRIC NONE OTHER OTP

verification_result

string

required

This field partially maps to the transStatus field in the EMVCo 3-D Secure specification and Mastercard SPA2 AAV leading indicators.

Verification result values:

CANCELLED: Authentication/Account verification could not be performed, transStatus = U.
FAILED: Transaction was not authenticated. transStatus = N, note: the utilization of exemptions could also result in transStatus = N, inspect the acquirer_exemption field for more information.
FRICTIONLESS: Attempts processing performed, the transaction was not authenticated, but a proof of attempted authentication/verification is provided. transStatus = A and the leading AAV indicator was one of {kE, kF, kQ}.
NOT_ATTEMPTED: A 3-D Secure flow was not applied to this transaction. Leading AAV indicator was one of {kN, kX} or no AAV was provided for the transaction.
REJECTED: Authentication/Account Verification rejected; transStatus = R. Issuer is rejecting authentication/verification and requests that authorization not be attempted.
SUCCESS: Authentication verification successful. transStatus = Y and leading AAV indicator for the transaction was one of {kA, kB, kC, kD, kO, kP, kR, kS}.

Note that the following transStatus values are not represented by this field:

C: Challenge Required
D: Challenge Required; decoupled authentication confirmed
I: Informational only
S: Challenge using Secure Payment Confirmation (SPC)

CANCELLED FAILED FRICTIONLESS NOT_ATTEMPTED REJECTED SUCCESS

merchant_amount

integer

Analogous to the "amount" property, but represents the amount in the local currency at the time of the transaction.

merchant_authorization_amount

integer

Analogous to the "authorization_amount" property, but represents the amount in the local currency at the time of the transaction.

merchant_currency

string

3-digit alphabetic ISO 4217 code for the local currency of the transaction.

authorization_code

string

length between 6 and 6

A fixed-width 6-digit numeric identifier that can be used to identify a transaction with networks.

card

object

created

date-time

required

An ISO 8601 timestamp for when the card was created. UTC time zone.

cvv

string

length between 3 and 3

Three digit cvv printed on the back of the card.

funding

object

required

exp_month

string

length between 2 and 2

Two digit (MM) expiry month.

exp_year

string

length between 4 and 4

Four digit (yyyy) expiry year.

hostname

string

Hostname of card’s locked merchant (will be empty if not applicable).

last_four

string

required

length between 4 and 4

Last four digits of the card number.

memo

string

Friendly name to identify the card.

pan

string

length between 16 and 16

Primary Account Number (PAN) (i.e. the card number). Customers must be PCI compliant to have PAN returned as a field in production. Please contact support@privacy.com for questions.

spend_limit

integer

required

Amount (in cents) to limit approved authorizations. Transaction requests above the spend limit will be declined.

spend_limit_duration

string

required

Spend limit duration values:

ANNUALLY - Card will authorize transactions up to spend limit in a calendar year.
FOREVER - Card will authorize only up to spend limit for the entire lifetime of the card.
MONTHLY - Card will authorize transactions up to spend limit for the trailing month. Month is calculated as this calendar date one month prior.
TRANSACTION - Card will authorizate multiple transactions if each individual transaction is under the spend limit.

ANNUALLY FOREVER MONTHLY TRANSACTION

state

string

required

Card state values:

CLOSED - Card will no longer approve authorizations. Closing a card cannot be undone.
OPEN - Card will approve authorizations (if they match card and account parameters).
PAUSED - Card will decline authorizations, but can be resumed at a later time.
PENDING_FULFILLMENT - The initial state for cards of type PHYSICAL. The card is provisioned pending manufacturing and fulfillment. Cards in this state can accept authorizations for e-commerce purchases, but not for "Card Present" purchases where the physical card itself is present.
PENDING_ACTIVATION - Each business day at 2pm Eastern Time Zone (ET), cards of type PHYSICAL in state PENDING_FULFILLMENT are sent to the card production warehouse and updated to state PENDING_ACTIVATION . Similar to PENDING_FULFILLMENT, cards in this state can be used for e-commerce transactions. API clients should update the card's state to OPEN only after the cardholder confirms receipt of the card.

In sandbox, the same daily batch fulfillment occurs, but no cards are actually manufactured.

CLOSED OPEN PAUSED PENDING_ACTIVATION PENDING_FULFILLMENT

auth_rule_tokens

array of strings

List of identifiers for the Auth Rule(s) that are applied on the card.

auth_rule_tokens

token

uuid

required

Globally unique identifier.

type

string

required

Card types:

DIGITAL_WALLET - Cards that can be provisioned to a digital wallet like Google Pay or Apple Wallet.
MERCHANT_LOCKED - Card is locked to first merchant that successfully authorizes the card.
PHYSICAL - Manufactured and sent to the cardholder. We offer white label branding, credit, ATM, PIN debit, chip/EMV, NFC and magstripe functionality. Contact api@privacy.com for more information.
SINGLE_USE - Card will close shortly after the first transaction.
UNLOCKED - Card will authorize at any merchant. Creating these cards requires additional privileges.

DIGITAL_WALLET MERCHANT_LOCKED PHYSICAL SINGLE_USE UNLOCKED

created

date-time

Date and time when the transaction first occurred. UTC time zone.

events

array of objects

A list of all events that have modified this transaction.

events

object

amount

integer

required

Amount (in cents) of the transaction event.

created

date-time

required

ISO 8601 date and time this event entered the system. UTC time zone.

result

string

required

APPROVED or decline reason.

Result types:

ACCOUNT_STATE_TRANSACTION_FAIL - Contact support@privacy.com.
APPROVED - Transaction is approved.
BANK_CONNECTION_ERROR - Please reconnect a funding source.
BANK_NOT_VERIFIED - Please confirm the funding source.
CARD_CLOSED - Card state was closed at the time of authorization.
CARD_PAUSED - Card state was paused at the time of authorization.
FRAUD_ADVICE - Transaction declined due to risk.
GLOBAL_TRANSACTION_LIMIT - Platform spend limit exceeded, contact support@privacy.com.
GLOBAL_WEEKLY_LIMIT - Platform spend limit exceeded, contact support@privacy.com.
GLOBAL_MONTHLY_LIMIT - Platform spend limit exceeded, contact support@privacy.com.
INACTIVE_ACCOUNT - Account is inactive. Contact support@privacy.com.
INCORRECT_PIN - PIN verification failed.
INVALID_CARD_DETAILS - Incorrect CVV or expiry date.
INSUFFICIENT_FUNDS - Please ensure the funding source is connected and up to date.
MERCHANT_BLACKLIST - This merchant is disallowed on the platform.
SINGLE_USE_RECHARGED - Single use card attempted multiple times.
SWITCH_INOPERATIVE_ADVICE - Network error, re-attempt the transaction.
UNAUTHORIZED_MERCHANT - Merchant locked card attempted at different merchant.
UNKNOWN_HOST_TIMEOUT - Network error, re-attempt the transaction.
USER_TRANSACTION_LIMIT - User-set spend limit exceeded.

ACCOUNT_STATE_TRANSACTION APPROVED BANK_CONNECTION_ERROR BANK_NOT_VERIFIED CARD_CLOSED CARD_PAUSED FRAUD_ADVICE GLOBAL_TRANSACTION_LIMIT GLOBAL_WEEKLY_LIMIT GLOBAL_MONTHLY_LIMIT INACTIVE_ACCOUNT INCORRECT_PIN INVALID_CARD_DETAILS INSUFFICIENT_FUNDS MERCHANT_BLACKLIST SINGLE_USE_RECHARGED SWITCH_INOPERATIVE_ADVICE UNAUTHORIZED_MERCHANT UNKNOWN_HOST_TIMEOUT USER_TRANSACTION_LIMIT

token

uuid

required

Globally unique identifier.

type

string

required

Event types:

AUTHORIZATION - Authorize a transaction.
AUTHORIZATION_ADVICE - Advice on a transaction.
CLEARING - Transaction is settled.
RETURN - A return authorization.
VOID - Transaction is voided.
TRANSACTION_CORRECTION_DEBIT - Manual transaction correction (Debit).
TRANSACTION_CORRECTION_CREDIT - Manual transaction correction (Credit).

AUTHORIZATION AUTHORIZATION_ADVICE CLEARING RETURN VOID TRANSACTION_CORRECTION_DEBIT TRANSACTION_CORRECTION_CREDIT

funding

object

A list of objects that describe how this transaction was funded, with the amount represented in cents. A reference to the funding account for the card that made this transaction may appear here and the token will match the token for the funding account in the card field. If any promotional credit was used in paying for this transaction, its type will be PROMO.

amount

integer

Funding amount (in cents).

token

string

Funding account token.

type

string

Types of funding:

PROMO - Any promotional credit was used in paying for this transaction.

PROMO

merchant

object

acceptor_id

string

Unique identifier to identify the payment card acceptor.

city

string

length between 1 and 255

City of card acceptor.

country

string

length between 3 and 3

Uppercase country of card acceptor (see ISO 8583 specs).

descriptor

string

Short description of card acceptor.

mcc

string

length between 4 and 4

Merchant category code (MCC). A four-digit number listed in ISO 18245. An MCC is used to classify a business by the types of goods or services it provides.

state

string

length between 2 and 2

Geographic state of card acceptor (see ISO 8583 specs).

network

string

Card network of the authorization. Can be INTERLINK, MAESTRO, MASTERCARD, VISA, or UNKNOWN. Value is UNKNOWN when Privacy cannot determine the network code from the upstream provider.

INTERLINK MAESTRO MASTERCARD VISA UNKNOWN

result

string

APPROVED or decline reason. See Event result types

settled_amount

integer

Amount (in cents) of the transaction that has been settled. This may change over time.

status

string

Status types:

BOUNCED - There was an error settling the transaction against the funding source. Your API account may be disabled.
DECLINED - The transaction was declined.
PENDING - Authorization is pending completion from the merchant.
SETTLED - The transaction is complete.
SETTLING - The merchant has completed the transaction and the funding source is being debited.
VOIDED - The merchant has voided the previously pending authorization.

BOUNCED DECLINED PENDING SETTLED SETTLING VOIDED

token

uuid

Globally unique identifier.


User has not been authenticated	Invalid or missing API key
API key is not active	The API key used is no longer active
Could not find API key	The API key provided is not associated with any user
Please provide API key in Authorization header	The Authorization header is not in the request
Please provide API key in the form Authorization: api-key [api-key]	The Authorization header is not formatted properly
Insufficient privileges. Issuing API key required	Write access requires an Issuing API key. Please contact api@privacy.com
Insufficient privileges to create unlocked cards.	Creating unlocked cards requires an additional privilege


Rate limited, too many requests per second	User has exceeded their per second rate limit
Rate limited, reached daily limit	User has exceeded their daily rate limit
Rate limited, too many keys tried	One IP has queried too many different API keys

Language

Credentials

Header

URL


xxxxxxxxxx
1
curl --request GET \
2
     --url https://api.privacy.com/v1/transactions/transaction_token \
3
     --header 'accept: application/json'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200OK

400A parameter in the query given in the request does not match the valid queries for the endpoint.

404The specified resource was not found.