/
15 minute read
May 8, 2023

About Transactions

A transaction is an electronic message that carries information used for payment processing. Transactions usually originate when cardholders attempt payments, either at a physical point of sale or online.

The Marqeta platform, as an issuer processor, issues cards and processes transactions originated from these cards. A transaction on the Marqeta platform is represented by the transaction object.

At the end of this guide, you should understand:

  • The role transactions play in the payments ecosystem.

  • The use cases of transaction endpoints.

  • The transaction object on the Marqeta platform.

  • The response codes that describe transaction outcomes.

  • The transaction lifecycle.

Transactions in the payments ecosystem

In the payments ecosystem, transactions facilitate the following processes:

  • Authorization – The process of confirming whether a card is valid, business rules are met, and funds are sufficient, and then placing a temporary hold on those funds.

  • Clearing – The process of finalizing the hold on funds and posting the transaction on the cardholder’s account. This process is triggered by the merchant’s capture request.

  • Settlement – The process of transferring the funds between the merchant’s and the cardholder’s banks.

Consequently, the most common transaction types are authorizations and clearings.

Transactions can be authorized, cleared, and settled either as dual-message transactions or as single-message transactions. The processing method may vary depending upon the payment method issuer, the type of card, or the region in which the transaction takes place.

  • In a single-message transaction, the merchant submits a single electronic message containing all data required for the authorization, clearing, and settlement of the transaction.

  • In a dual-message transaction, at the time of purchase, the merchant submits an electronic message containing the information required for an authorization decision. At a later point in time, the merchant submits a second message containing additional data required for clearing and settlement.

Most transactions processed by merchants are dual-message transactions. Single-message transactions usually occur when a cardholder uses their PIN at a point of sale or at an ATM.

Besides authorizations and clearings, other common transaction types include:

  • PIN debit transactions – These transactions occur when a cardholder attempts to make a payment using their PIN. Such a transaction typically contains all information required for authorization and clearing in a single electronic message.

  • Reversals – These transactions occur when a merchant cancels a transaction after the authorization has succeeded but before the clearing has taken place. Reversals may also be partial, so that only part of the initial authorization hold is released.

  • Refunds – These transactions occur when a cardholder requests a merchant to return the funds for a transaction after the clearing has completed for it.

  • Chargebacks – These transactions occur when the issuer processor disputes a completed transaction on behalf of the cardholder.

Use cases of transaction endpoints

The Marqeta platform provides services for managing transactions on various granularity levels, from retrieving individual transactions that occurred within a limited time range to obtaining large aggregated transaction datasets. The following section describes common uses of transaction endpoints on the Marqeta platform.

Core API

You can use the Core API for performing operations on individual transactions. The use cases include investigation, reconciliation, and other operational needs. In particular, the Core API enables you to:

  • Retrieve a list of transactions associated with specific cards, campaigns, merchants, or account holders (users and businesses).

  • Retrieve information related to a specific transaction.

  • Retrieve the list of transactions related to a specific transaction.

  • Reverse an authorization for a specific transaction in a pending state.

If you are developing a financial mobile app, you might want to let your users view their transaction history in their profiles. In this case, you can call the /transactions endpoint and use the user_token query parameter to get transactions conducted by that user.

If you are building a customer support interface, you might want to provide the capability to review transactions and drill down to investigate what occurred with a given card. In this case, you can call the /transactions endpoint and use the card_token query parameter to get transactions for that specific card.

If you are creating an application for your accounting department, you might want to enable them to troubleshoot discrepancies and perform internal reconciliation. In this case, you can call the /transactions/{token}/related endpoint to list all transactions related to a specific transaction identified by the token path parameter.

For more information on the /transactions endpoint, see the Transactions page in the Core API reference.

Webhooks

Webhooks enable you to receive notifications about events as they occur in real time. The Marqeta platform sends event notifications to a webhook endpoint hosted in your environment.

You can use webhooks to receive notifications about transactions events, which include such information as the transaction type, amount, and how the transaction was funded.

For information on how to create and configure webhooks, see the Webhooks API reference page. See the transaction events for which you can set webhooks in the Event Types API reference page.

DiVA API

You can use the Data insights, Visualization, and Analytics (DiVA) API for performing aggregate operations on transactions. The use cases include reporting, analytics, and data-driven decision making. In particular, the DiVA API enables you to:

  • Retrieve authorization transaction data aggregated over the specific time period, such as day, week, or month.

  • Retrieve settlement transaction data at a specific aggregation level, such as day, week, or month.

  • Retrieve chargeback data aggregated by transaction.

  • Retrieve funding load transaction data at a specific aggregation level.

If you are building a utility for a business intelligence system, you might want to provide the capability to analyze the daily settlement file and daily total authorizations, in order to calculate the transactions volume. In this case, you can call the /views/authorizations and /views/settlements endpoints.

For more information on the /views/authorizations and /views/settlements endpoints, see the Authorizations and Settlements pages in the DiVA API reference.

JIT Funding

Just-in-Time (JIT) Funding is a mechanism provided by the Marqeta platform that enables you to automatically fund accounts in real time during the transaction process.

In JIT Funding, transactions are made against cardholder accounts that do not need to carry a balance. These transactions are usually dual-message transactions, where the first message is for loading funds and the second one is for spending them. You can monitor JIT-funded transactions as they occur and reconcile balances on cardholder accounts.

For more information on JIT Funding, see the About Just-in-Time Funding page in the guides collection.

Simulations

Transactions originate from outside of your system, usually when a purchaser uses a card at a point of sale. Therefore, in your Marqeta production environment transaction objects are created as a result of messages coming from the card network, rather than through API calls to the Marqeta platform. For testing purposes, you can simulate the creation of transaction objects in your public or private sandbox environment.

For more information on how to simulate the creation of transactions, see the Simulating Transactions page in the Core API reference.

The transaction object

On the Marqeta platform, transactions are represented by the transaction object. The Marqeta platform creates a separate transaction object for each transaction message received from the card network.

The attributes of a given transaction object depend on the transaction type. Some attributes are required for all transaction objects, such as:

  • type – Categorizes the transaction event. For the complete list of types, see the Transaction events section of the Event Types API reference page.

  • state – The current state of the transaction. This is the only field that can change after the transaction object has been created. For more information, see The transaction lifecycle section.

  • amount – Amount of the transaction.

Each transaction is associated with an owner of the account that funds the transaction. The account owner can be a user, a business, or both. Consequently, each transaction object contains the user_token and/or the business_token attributes. Dual-message transactions retain the original token in subsequent transaction messages even if the card used changes owners.

A transaction object also contains one or more timestamp attributes that represent the transaction timeline, such as:

  • created_time – The date and time when the Marqeta platform created the transaction entry.

  • user_transaction_time – The date and time when the user initiated the transaction.

  • settlement_date – The date and time when funds were moved for a transaction.

If transaction objects are related, such as when they are part of the same dual-message transaction, the relationship is indicated in the preceding_related_transaction_token attribute.

A transaction object may include embedded objects. For example, the gpa_order object describes how the transaction is funded. If the transaction is funded through Just-in-Time (JIT) Funding mechanism, gpa_order will contain the jit_funding object.

For the complete list of the transaction object’s attributes, see the Retrieve transaction section on the Transactions API reference page.

Transaction response codes

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 API reference page.

Response codes table

Code Description

0000

Transaction approved or completed successfully.

0002

Partially approved.

1001

Card expired.

1002

Card suspicious.

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

Real-Time Decisioning decline.

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.

1895

Token activation request — STIP decline.

1896

Token activation request card product config decline.

1897

SCA LVP cumulative amount exceeded.

1898

SCA LVP transaction count limit exceeded.

1899

SCA LVP transaction limit exceeded.

1900

Rejected response.

1901

Card not activated.

1902

JIT response invalid merchant.

1903

JIT response invalid card.

1904

JIT response no credit account.

1905

JIT response expired card.

1906

JIT response no checking account.

1907

JIT response no savings account.

1908

JIT response stop payment.

1909

JIT response revocation authorization order.

1910

JIT response revocation all authorization order.

1911

JIT response soft decline authentication required.

1912

JIT response closed account.

1913

Transaction not allowed in a limited state.

1914

Chip data missing required fields.

1915

Invalid CVV2.

1916

Consecutive CVV failure suspected fraud.

1918

JIT Response soft decline PIN required.

1919

Card terminated.

1920

Cardholder terminated.

1921

Digital wallet token terminated.

1922

Transaction cannot be completed.

1923

Not sufficient funds - no cached balance.

1924

Installment payment not supported in this region.

1925

JIT response card not active.

1926

JIT response cardholder not active.

1927

Account transfer not allowed

The transaction lifecycle

The Marqeta platform creates transaction objects as a result of electronic messages received from the card network. From the moment of their creation, transaction objects are immutable, with the exception of the state attribute.

How transactions transition through different states during their lifecycle depends on whether they are temporary or final transactions. Temporary and final transactions are closely related to single-message and dual-message transactions.

A dual-message transaction requires two or more transaction messages to complete, for example:

  • At the time of purchase, the merchant submits an electronic message containing the information required for an authorization decision.

  • At a later point in time, the merchant submits another electronic message containing additional data required for clearing and settlement.

In this scenario, the first message is a temporary transaction, which means it can be reversed. The last message is a final transaction.

Temporary transaction messages, such as authorizations, are handled synchronously, which means a transaction message flows in real time from the merchant to the issuer processor (such as Marqeta) and then back to the merchant. Final transaction messages are handled asynchronously, because capture requests can be submitted at a later time.

Some transactions, such as PIN debit transactions, contain all the information required for authorization and clearing in a single electronic message. These are typically final transactions that are handled synchronously.

On the Marqeta platform, temporary transaction types, such as authorizations, always start in a PENDING state and move to either a CLEARED state or a DECLINED state. Final transaction types, such as clearings, start and remain in a COMPLETION state.

Temporary transactions transition from one state to another during their lifecycle, as a result of transaction events coming from the card network. The following diagram illustrates state transitions of an authorization transaction that was partially cleared and partially reversed. The diagram depicts transaction objects that were created on the Marqeta platform during this chain of events and indicates relationships between these objects, as follows:

  • The card network sends an authorization message for $100 to the Marqeta platform. The Marqeta platform creates a transaction object A of type authorization in a PENDING state and puts a temporary hold on $100 for object A.

  • The card network sends a clearing message for $40 to the Marqeta platform. The Marqeta platform creates a transaction object B of type clearing in a COMPLETION state (related to the object A), puts a final hold on $40 for object B, and updates the temporary hold to $60 for object A.

  • The card network sends a clearing message for $20 to the Marqeta platform. The Marqeta platform creates a transaction object C of type clearing in a COMPLETION state (related to the objects A and B), puts a final hold on $20 for object C, and updates the temporary hold to $40 for object A.

  • The card network sends a reversal message for $40 to the Marqeta platform. The Marqeta platform creates a transaction object D of type reversal in a CLEARED state (related to the objects A, B, and C), releases the hold on $40 for object D, updates the temporary hold to $0 for object A, and transitions object A to a CLEARED state.

The lifecycle of transactions on the Marqeta platform

Is this helpful?

Yes
No

Subscribe to our developer newsletter