DOCS

Marqeta.com
Support
/
Guides
Core API Reference
DiVA API Reference
Core API Explorer
25 minute read
December 16, 2020

Transactions

The

/transactions
resource represents the electronic messages that carry information used for payment processing. A transaction usually originates when a cardholder attempts to make a payment online or at a physical point of sale.

You can receive information about transactions as they occur by configuring webhooks. Learn about configuring webhooks in the Webhooks Overview page. See the transaction events for which you can set up webhooks in the Event Types page.

You can also retrieve transactions associated with specific cards, merchants, and account holders using the endpoints described here.

Note
Use the
/transactions
endpoint to retrieve smaller datasets (up to one page). For best performance when requesting larger datasets, use the DiVA API.

For an overview of transactions and the

transaction
object, see About Transactions.

Retrieve transaction
Copy section link

Action:

GET

Endpoint:
/transactions/{token}

Sign in to use API widgets
GET

Retrieve a specific transaction. Include the

token
path parameter to identify the transaction.

Note
Transactions are not available in real time through this endpoint, but typically appear after 30 seconds. On occasion, however, a transaction may require up to four hours to appear.
URL path parameters
Copy section link
Fields Description

token

string
Required

Identifies the transaction to retrieve.

Allowable Values:

Existing transaction token
Transaction field descriptions
Copy section link

The following table contains a superset of possible response elements. Responses always include the

type
and
amount
fields. Other objects are conditionally returned. For more information about which objects may be returned based on the type of transaction, see the Transaction Types table.

Field Description

token

Unique identifier of the transaction, formatted as a UUID.

identifier

Sequential identifier of the transaction.

user_token

Unique identifier of the user who owns the account that funded the transaction; subsequent related transactions retain the same user_token even if the card used for the transaction moves to another user.

business_token

Unique identifier of the business that owns the account that funded the transaction.

acting_user_token

Unique identifier of the user who conducted the transaction. The user can be a child user configured to share its parent’s account balance.

card_token

Unique identifier of the card. Useful when a single account holder has multiple cards.

type

Represents the transaction type. For more information about the type field, see the "Transaction events" section on the Event Types page.

state

The current state of the transaction, either

PENDING
,
CLEARED
,
COMPLETION
,
DECLINED
or
ERROR
. For more information about the state field, see the "The transaction lifecycle" section on the About Transactions page.

network_reference_id

Network-assigned unique identifier of the transaction. Useful for settlement and reconciliation.

duration

Duration of the transaction on Marqeta servers, in milliseconds.

created_time

Date and time when the Marqeta platform created the transaction entry (for example, when the platform received an incoming message for a refund).

user_transaction_time

Date and time when the user initiated the transaction (for example, when a merchant entered a refund).

issuer_received_time

Date and time when the Marqeta platform received the transaction from the card network.

settlement_date

Date and time when funds were moved for a transaction (for example, in the case of a refund, when funds were credited to the cardholder).

issuer_payment_node

Identifier of the Marqeta platform server that received the transaction from the card network.

request_amount

Used for clearing/settling transactions to compare to the original authorization amount.

amount

Amount of the transaction.

cash_back_amount

Amount of cashback included in the total transaction amount. Only included in

pindebit.cashback
transactions.

currency_code

The three-character ISO 4217 currency type of the transaction.

approval_code

The unique ID assigned to a given authorization. Is printed on the receipt at point of sale.

response

Object containing information about the response, including the response code and response memo.

preceding_related_transaction_token

Returned for final transaction types.

Unique identifier of the preceding related transaction. Useful for identifying the temporary transaction completed by the current transaction.

For example,

authorization
, a temporary transaction type, precedes and is completed by
authorization.clearing
, a final transaction type. In this case, the
authorization
token is returned with this field. For which transaction types are temporary or final, see Transaction events in Event Types.

preceding_transaction

Returned for

authorization.clearing
transaction types following a financial advice.

Object containing the amount and token of the preceding

authorization
transaction.

amount_to_be_released

Returned for

authorization.clearing
transaction types following a financial advice.

Amount to release following an advice.

merchant

Object containing information about the merchant, including whether partial authorizations are allowed.

card_acceptor

Object containing information about the card acceptor, such as the MID, MCC, or MCC group.

gpa

Object containing information about the GPA balances and pending credits.

gpa_order_unload

Object containing information about a GPA order unload. A GPA order unload unloads funds from a card and returns it to the funding source.

gpa_order

Object containing information about a GPA order, including fees, funding sources, and addresses. See Orders for more information.

program_transfer

Object containing information about a program transfer.

fee_transfer

Object containing information about a fee transfer, including the amount, the currency code, and user or business token. See Transfers for more information.

peer_transfer

Object containing information about a peer transfer, including sender and recipient tokens, transfer amount and currency code. See Transfers for more information.

risk_assessment

Object containing information about risk assessments.

auto_reload

Object containing information about auto reloads. See Auto Reloads for more information.

direct_deposit

Object containing information about a direct deposit. See Direct Deposits for more information.

polarity

Object indicating whether the transaction is credit or debit.

real_time_fee_group

Object containing information about a realtime fee group.

fee

Object containing information about fees related to the transaction.

chargeback

Contains the chargeback object associated with this transaction if a chargeback has been initiated.

network

Indicates which card network was used for the transaction (DISCOVER, MASTERCARD, PULSE, VISA, and MARQETA).

subnetwork

Indicates which subnetwork was used for the transaction. Possible values include the following:

  • VISANET – Used for VisaNet signature-based transactions.

  • VISANETDEBIT – Used for VisaNet Debit PIN-based transaction.

  • VISAINTERLINK – Used for Visa Interlink PIN-based transactions.

  • VISAPLUS – Used for ATM withdrawals on Visa.

  • MAESTRO – Used for PIN-based transactions on Mastercard.

  • CIRRUS – Used for ATM withdrawals on Mastercard.

  • MASTERCARDDEBIT – Used for signature-based transactions on Mastercard.

  • GATEWAY_JIT – Used for Gateway JIT Funding transactions.

  • MANAGED_JIT – Used for Managed JIT Funding transactions or for transactions that occur while Commando Mode is enabled.

standin_approved_by

Indicates which party approved a transaction requiring stand-in processing or Commando Mode. Returned only when a transaction is approved.

standin_by

Indicates which party handled a transaction requiring stand-in processing or Commando Mode.

standin_reason

Indicates why the network handled a transaction requiring stand-in processing. Not returned unless transaction is declined.

acquirer_fee_amount

Indicates the amount of the acquirer fee. Account holders are sometimes charged an acquirer fee for card use at ATMs, fuel dispensers, etc.

user

Contains customer-injected metadata associated with the account holder who funded the transaction.

digital_wallet_token

Contains the entire digital_wallet_token object; present for all transactions funded by way of a digital wallet or related to digital wallet token provisioning.

network_fees

Contains card network fees assessed against the cardholder.

card_security_code_verification

Object containing information about a verification check performed on the card’s security code. The nested

type
field indicates the type of security code and can have these possible values:

  • CVV1 – the security code stored in the magnetic stripe on the card.

  • CVV2 – the security code printed on the card.

  • ICVV – the security code stored on the chip of the card.

  • DCVV – a dynamic security code used in some contactless payments when a card or device is tapped against the card reader.

The nested

response.code
field indicates whether the verification check passed and can have these possible values:

  • 0000 – passed

  • 0001 – did not pass

pos

Object containing information about the point of sale, including details about how the card was presented.

avs

Object containing Address Verification System (AVS) data provided by the merchant.

acquirer

Object containing information about the merchant’s financial institution.

transaction_metadata

Object containing merchant-provided metadata related to the transaction, including details about lodging and transit-related purchases.

fraud

Object containing one or more fraud determinations for the transaction and the cardholder’s account; this object can contain fraud determinations calculated by the card network and issuer-processor (Marqeta).

cardholder_authentication_data

Object containing 3D Secure verification data:

  • electronic_commerce_indicator
    – The level of verification performed.

  • verification_result
    – The result of the verification.

  • verification_value_created_by
    – The transaction participant who determined the verification result.

currency_conversion

Object containing information from the card network about currency conversion, including the original currency of the transaction, the amount of the transaction in the original currency, and the conversion rate.

original_credit

Object containing information about an original credit transaction (OCT), including the transaction type, source of funds, sender name, and screening score.
The currency_conversion object
Copy section link
Fields Description

network

object
Conditionally returned

Object containing information from the card network about currency conversion, including the original currency of the transaction, the amount of the transaction in the original currency, and the conversion rate.

Allowable Values:

See the currency_conversion.network object table.
The currency_conversion.network object
Copy section link
Fields Description

original_amount

decimal
Conditionally returned

Object containing information from the card network about currency conversion, including the original currency of the transaction, the amount of the transaction in the original currency, and the conversion rate.

Allowable Values:

Decimal amount.

conversion_rate

decimal
Conditionally returned

Conversion rate when clearing transactions in a currency different than billing currency.

Allowable Values:

Current conversion rate

Note: A value of 0 or 1 indicates no conversion; the currencies are the same.

original_currency_code

string
Conditionally returned

The original three-character ISO 4217 currency type of the transaction.

Allowable Values:

The three-character ISO 4217 currency type.

dynamic_currency_conversion

boolean
Conditionally returned

Indicates if currency conversion was performed at the point of sale.

Allowable Values:

true
,
false

Default value:

false

The following sample shows a

currency_conversion.network
object when the transaction currency is in EUR and the billing currency is in USD.

Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

List transactions
Copy section link

Action:

GET

Endpoint:
/transactions

Sign in to use API widgets
GET

List all transactions.

By default, this endpoint returns transactions conducted within the last 30 days. To return transactions older than 30 days, you must include the

start_date
and
end_date
query parameters in your request.

By default,

GET /transactions
returns transactions having
PENDING
or
COMPLETION
states.

This endpoint supports field filtering and pagination.

Query parameters
Copy section link
Fields Description

start_date

string
Optional

The starting date (or date-time) of a date range from which to return transactions.

To return transactions for a single day, enter the same date in both the

start_date
and
end_date
fields.

Allowable Values:

yyyy-MM-dd

OR

yyyy-MM-dd’T’HH:mm:ss.SSSZ

Default value:
Current date minus 30 days (the time of day is not factored in).

end_date

string
Optional

The ending date (or date-time) of a date range from which to return transactions.

To return transactions for a single day, enter the same date in both the

end_date
and
start_date
fields.

Allowable Values:

yyyy-MM-dd

Default value:
Current date (the time of day is not factored in).

type

string
Optional

Returns transactions of the specified types.

Allowable Values:

Comma-delimited list of transaction types.

To return all types, leave blank.

Default value:
All types (blank)

See Event Types for a list of transaction types.

state

string
Optional

Returns transactions of the specified state.

For more information about the state field, see the "The transaction lifecycle" section on the About Transactions page.

Allowable Values:

Comma-delimited list of transaction states:

PENDING
,
CLEARED
,
COMPLETION
,
DECLINED
,
ERROR
,
ALL

Default value:

PENDING
,
COMPLETION

user_token

string
Optional

Enter a user token to return transactions conducted by that user. In the case of a parent user, transactions conducted by the parent and all children configured to share the parent’s account balance are returned. Entering the token of a child user who is configured to share the parent’s account balances returns zero transactions.

Allowable Values:

Existing user token.

Send a

GET
request to
/users
to retrieve user tokens.

business_token

string
Optional

Enter a business token to return transactions conducted by that business' children and grandchildren users.

Allowable Values:

Existing business token.

Send a

GET
request to
/businesses
to retrieve business tokens.

acting_user_token

string
Optional

Enter a user token to return transactions conducted only by that user. This parameter is useful in the case of a parent with children configured to share the parent’s account balance. In this case, entering the parent’s user token returns only transactions conducted by the parent; entering a child’s user token returns only transactions conducted by the child.

Allowable Values:

Existing user token.

Send a

GET
request to
/users
to retrieve user tokens.

Note
This parameter does not accept business tokens.

card_token

string
Optional

Enter a card token to return transactions for a specific card.

Allowable Values:

Existing card token.

Send a

GET
request to
/cards/user/{token}
to retrieve card tokens for a specific user.

merchant_token

string
Optional

Enter a merchant token to return transactions for a specific merchant.

Allowable Values:

Existing merchant token.

Send a

GET
request to
/merchants
to retrieve merchant tokens.

campaign_token

string
Optional

Enter a campaign token to return transactions for a specific campaign.

Allowable Values:

Existing campaign token.

Send a

GET
request to
/campaigns
to retrieve campaign tokens.
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

List related transactions
Copy section link

Action:

GET

Endpoint:
/transactions/{token}/related

Sign in to use API widgets
GET

List all transactions related to the specified transaction.

By default, this endpoint returns transactions conducted within the last 30 days. To return transactions older than 30 days, you must include the

start_date
and
end_date
query parameters in your request.

By default, this endpoint returns transactions of any state. To return transactions in specific states, you must include the

state
query parameter in your request.

This endpoint supports field filtering and pagination.

URL path parameters
Copy section link
Fields Description

token

string
Required

Identifies the transaction whose related transactions you want to retrieve.

Allowable Values:

Existing transaction token
Query parameters
Copy section link
Fields Description

start_date

string
Optional

The starting date (or date-time) of a date range from which to return transactions.

To return transactions for a single day, enter the same date in both the

start_date
and
end_date
fields.

Allowable Values:

yyyy-MM-dd

OR

yyyy-MM-dd’T’HH:mm:ss.SSSZ

Default value:
Current date minus 30 days (the time of day is not factored in).

end_date

string
Optional

The ending date (or date-time) of a date range from which to return transactions.

To return transactions for a single day, enter the same date in both the

end_date
and
start_date
fields.

Allowable Values:

yyyy-MM-dd

Default value:
Current date (the time of day is not factored in).

type

string
Optional

Returns transactions of the specified types.

Allowable Values:

Comma-delimited list of transaction types.

To return all types, leave blank.

Default value:
All types (blank)

See Transaction Types for a list of transaction types.

state

string
Optional

Returns transactions of the specified state.

For more information about the state field, see the "The transaction lifecycle" section on the About Transactions page.

Allowable Values:

Comma-delimited list of transaction states:

PENDING
,
CLEARED
,
COMPLETION
,
DECLINED
,
ERROR
,
ALL
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Reverse authorization
Copy section link

Action:

POST

Endpoint:
/transactions/authorizationreversal

Sign in to use API widgets
POST

Reverse a pending authorization. Include the token identifying the transaction you want to reverse in JSON format in the body of the request.

Body field details
Copy section link
Fields Description

original_transaction_token

string
Required

Identifies the transaction to reverse.

Allowable Values:

Existing transaction token.

Send a

GET
request to
/transactions
to retrieve transaction tokens.
Sample request body
Copy section link
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Transaction response codes
Copy section link

You can use the

response.code
field to help understand the transaction. In general, the
type
field categorizes the attempted transaction type, and the
response.code
field describes the outcome of that attempt. For example:

  • A combination of

    type = authorization
    and
    response.code = 1001
    indicates a card authorization attempt that failed because the card was expired.

  • A combination of

    type = authorization
    or
    type = pindebit
    with a
    response.code
    of 0000, 0002, or 1830 indicates a successful transaction. All other response codes indicate failed transactions.

The following response codes table describes the possible values for the

response.code
field. For more information about the
type
field, see the "Transaction events" section on the Event Types page.

Response codes table
Copy section link
Code Description

0000

Transaction approved or completed successfully.

0002

Partially approved.

1001

Card expired.

1002

Card suspicious. Expiration mismatch.

1003

Card suspended.

1004

Card stolen - pickup.

1005

Card lost.

1011

Card not found.

1012

Cardholder not found. It is possible that the card is valid, but cardholder has not yet been created.

1014

Account not found. The account was not created for the currency in the transaction.

1015

Invalid request. Request cannot be parsed, or relevant data not found.

1016

Not sufficient funds. Funds in account are less than the auth amount.

1017

Previously reversed.

1018

Previously completed.

1019

Further activity prevents reversal.

1020

Further activity prevents void.

1021

Original transaction has been voided.

1022

No savings account.

1023

No checking account.

1802

Missing fields.

1803

Extra fields exist.

1804

Invalid card number. PAN information is missing from the request.

1806

Card not active.

1808

Card not configured.

1809

Incorrect PIN.

1810

Invalid amount. Amount field is null or less than zero.

1811

System error related to the database. This error is sent to the network.

1812

System error related to business logic. For example, the original transaction might not be found.

1813

Cardholder not active. Transaction occurs outside the card start and end dates.

1814

Cardholder not configured. Start and end dates have not been configured.

1815

Cardholder expired. Transaction date occurs after the cardholder’s end date.

1816

Original not found, and no pre-auth exists.

1817

Usage limit reached.

1818

Configuration error.

1819

Invalid terminal.

1820

Inactive terminal.

1821

Invalid merchant.

1822

Duplicate entity.

1823

Invalid acquirer.

1824

Accounting exception.

1825

Invalid CID. Card security code is invalid; CVV does not match.

1826

AVS decline. The address information submitted for the transaction failed AVS verification.

1827

AVS no info.

1828

Card is active.

1829

AVS match.

1830

Card account verification success.

1831

Card not present.

1832

Auth restriction found for given MID or MCC. Authorization control rules impose a restriction for this merchant ID or merchant category code.

1833

Cryptographic failure. The card was presented, and the chip failed a verification test because of an invalid cryptogram or ARPC verification failed HSM check.

1834

Transaction amount limit reached. It exceeds the weekly or monthly velocity control set for the program.

1835

Card product controls prevent transaction.

1836

JIT clearing failure.

1837

JIT refund failure.

1838

International transaction decline.

1839

JIT reversal failure.

1840

Real-time fee group not found.

1841

Exceeds max auth amount limit. The transaction amount exceeds the velocity control set for the transaction.

1842

Account load failed.

1843

Network loads not allowed.

1844

Issuer timeout advice. The card network has advised of a decline.

1845

Transactions other than ATM and e-commerce not allowed.

1846

ATM transactions not allowed.

1847

E-commerce transactions not allowed.

1848

Mail order transactions not allowed.

1849

Phone order transactions not allowed.

1850

Card not present.

1851

Cardholder not present.

1852

PIN not present.

1853

ICC not present.

1854

Card security code not present.

1855

Digital wallet token not found.

1856

Digital wallet token not active.

1857

Digital wallet token expired.

1858

Digital wallet token suspended.

1859

Digital wallet token not present.

1860

Digital wallet token suspicious.

1861

Transaction account management limit reached.

1862

Token activation request card product config decline.

1863

Additional identity verification required.

1864

Transactions not allowed from this country. International transaction blocked due to the country or currency.

1865

Insufficient funds in program reserve account.

1866

Invalid card service code.

1868

Quasi Cash txn not allowed (processing code 11).

1869

KYC is required.

1870

Reloads are disabled for entity.

1871

Push-to-Card disbursement error.

1872

Offline PIN try limit exceeded.

1873

Chip fallback not allowed.

1874

Card suspicious - Expiration mismatch.

1875

Partial JIT not allowed.

1876

Account funding transactions are unsupported.

1877

FraudStream decision declines transaction.

1878

Corresponding JIT load failure.

1879

Credit voucher not allowed.

1880

CAVV decline. Exceeds the maximum auth cashback amount limit.

1881

Exceeds max auth cashback amount limit.

1882

CVV attempt limit exceeded.

1883

JIT response invalid amount.

1884

JIT response not sufficient funds.

1885

JIT response transaction not permitted.

1886

JIT response suspected fraud.

1887

JIT response amount limit reached.

1888

JIT response usage limit reached.

1889

JIT response duplicate entry.

1890

Low device score.

1891

Strong Customer Authentication — SCA contactless cumulative amount exceeded.

1892

Strong Customer Authentication — SCA contactless transaction count limit exceeded.

1893

Strong Customer Authentication — SCA contactless transaction limit exceeded.

1894

Card account verification decline.
Related materials

Feedback on this page?

If you feel we can do anything better, please let our team know.

© 2021 Marqeta, Inc.

• Terms
 • API Terms
 • Privacy
 • Cookies