Swipes

Within Secure Payments, swipes are represented by the swipe entity. Swipes represent the transactions associated with a card to draw on a line of credit account. A swipe is generated when a card is used in a transaction.

Swipes are authorized via tokens. Without a token, attempting to create a swipe will result in an error. You can generate swipe tokens, retrieve your tokens, and revoke tokens.

You can also retrieve swipe information, create a swipe and create a swipe event.

Memos are associated with a swipe in a many to one relationship, but there is a max of 50 memos per swipe. You can create a swipe memo, update a memo, and delete a memo.

ENDPOINT

You will find the key-value pairs for swipes, swipe events, and swipe memos below.

Swipe Status

The swipe status determines how the amount of the swipe is calculated and the affect of the swipe in Secure Payments and LMS. Below is a list of swipe statuses, the rules that apply the status, and the order statuses are evaluated in from highest priority to lowest priority.

Evaluation Order:	Swipe Status:	Rule:
1	Dispute - Write off	This status is applied under the following conditions: > Swipe is associated with a `dispute-write-off` type swipe event
2	Dispute - Chargeback	This status is applied under the following conditions: > Swipe is associated with a `dispute-chargeback` type swipe event > AND Dispute Chargeback Amount > 0
3	Dispute - Under investigation	This status is applied under the following conditions: > Swipe is associated with a `dispute-provisional-credit` type swipe event > AND Dispute Denied Amount < Dispute Provisional Credit Amount
4	Dispute - Requested	This status is applied under the following conditions: > Dispute Requested Amount > 0 > AND Dispute Denied Amount < Dispute Requested Amount
5	Settled - Credit	This status is applied under the following conditions: > [Authorized Credit Amount > 0 OR (Force Clearing = True AND Credit Authorization = True)] > AND Authorized Amount <= Authorized Credit Amount > AND Cleared Credit Amount >= Authorized Credit Amount
6	Settled - Partial Credit	This status is applied under the following conditions: > Authorized Credit Amount > 0 > AND Authorized Amount > Authorized Credit Amount > AND Cleared Credit Amount >= Authorized Credit Amount
7	Settling - Credit	This status is applied under the following conditions: > Force Clearing = False > AND Requested Amount > 0 > AND Authorized Credit Amount > 0 > AND (Cleared Credit Amount + Voided Credit Amount) < Authorized Credit Amount > AND Cleared Credit Amount > 0
8	Settling - Partial Credit	This status is applied under the following conditions: > Authorized Credit Amount > 0 > AND Authorized Amount > Authorized Credit Amount > AND (Cleared Credit Amount + Voided Credit Amount) < Authorized Credit Amount > AND Cleared Credit Amount > 0
9	Pending - Credit	This status is applied under the following conditions: > Authorized Credit Amount > 0 > AND Authorized Amount <= Authorized Credit Amount > AND Cleared Credit Amount = 0 > AND Voided Credit Amount < Authorized Credit Amount
10	Pending - Partial Credit	This status is applied under the following conditions: > Authorized Credit Amount > 0 > AND Authorized Amount > Authorized Credit Amount > AND Cleared Credit Amount = 0 > AND Voided Credit Amount < Authorized Credit Amount
11	Voided - Credit	This status is applied under the following conditions: > Requested Amount > 0 > AND Voided Credit Amount > 0 > AND Cleared Credit Amount = 0 > AND Voided Credit Amount = Authorized Credit Amount
12	Declined	This status is applied under the following conditions: > [Force Clearing = False AND Requested Amount > 0 AND Authorized Amount = 0 AND Authorized Credit Amount = 0] > OR Issuer Decline = True
13	Pending	This status is applied under the following conditions: > Force Clearing = False > AND Requested Amount > 0 > AND Authorized Amount > 0 > AND (Authorized Amount - Voided Amount) > 0 > AND Cleared Amount = 0
14	Settling	This status is applied under the following conditions: > Force Clearing = False > AND Requested Amount > 0 > AND Authorized Amount > 0 > AND (Cleared + Voided Amount) < Authorized Amount > AND Cleared Amount > 0
15	Settled	This status is applied under the following conditions: > AND Requested Amount > 0 > AND Cleared Amount > 0 > AND (Cleared Amount + Voided Amount) >= Authorized Amount
16	Voided	This status is applied under the following conditions: > AND Requested Amount > 0 > AND Cleared Amount = 0 > AND Voided Amount = Authorized Amount.

Swipe flags

Swipe flags are attributes that characterize a transaction within LoanPro and determine which actions should occur.

Transaction information is passed to LoanPro's system via the POST create swipe request. Each transaction is characterized by seven possible boolean attributes within the payload and these attributes determine how a transaction is handled by LoanPro - including how transaction amounts are logged and updated. LoanPro uses the following seven flags to characterize a transaction:

Swipe flags:
`issuer-decline?`
`authorization-advice?`
`preauthorization?`
`force-clearing?`
`cash-advance?`
`credit-authorization?`
`sma?`

These flags can be used singularly or in combination to handle various types of transaction scenarios. Some scenarios require only one swipe flag, while others require two or three. For more information, see our Swipe Flag Scenarios.

Swipe events

Swipe events are a core component of the swipe lifecycle. When a borrower uses a credit card to make a purchase, a singular transaction can consist of multiple operations in the background. For example, when a cardholder uses their card to purchase an item, an authorization operation occurs to ensure the line of credit has sufficient fuds: later, when the transaction amount has been confirmed, a clearing operation occurs to finalize the transaction and draw on the account.

In LoanPro, a single swipe ID is used throughout the transaction's lifetime and swipe events are the actions that occur on the swipe. Each swipe event is represented by its own ID and is associated with a parent swipe. As a transaction is created, updated, cleared, voided, etc., swipe events are created to update the swipe. Swipe events also contain a swipe event-type. The event type determines the state of the swipe and how funding is allocated and authorized.

For a description of each swipe event type, see our Swipe Event Enumeration breakdown.

Key-value pairs

Swipes

Value:	Definition:
`swipe-id`	The unique identifier of a swipe. > This field is important for swipe authorization.
`card-uuid`	The unique identifier of the card used to initiate the swipe. > This field is important for swipe authorization.
`amount`	The dollar amount of the swipe.
`authorized-amount`	The amount authorized.
`cleared-amount`	The amount cleared.
`cleared-credit-amount`	The cleared credit amount.
`authorized-credit-amount`	The authorized credit amount.
`dispute-requested-amount`	The dispute requested amount.
`dispute-denied-amount`	The dispute denied amount.
`dispute-provisional-credit-amount`	The provisional dispute credit amount.
`dispute-write-off-amount`	The dispute write off amount.
`dispute-chargeback-amount`	The dispute chargeback amount.
`voided-amount`	The voided amount.
`voided-credit-amount`	The voided credit amount.
`merchant-name`	The merchant's name.
`merchant-descriptor`	The merchant's descriptor such as name and ID.
`merchant-longitude`	The merchant's longitude.
`merchant-latitude`	The merchant's latitude.
`merchant-country`	The merchant's country.
`merchant-state`	The merchant's state.
`merchant-city`	The merchant's city.
`merchant-address`	The merchant's street address.
`merchant-postal_code`	The merchant's postal code.
`merchant-currency`	The currency of the transaction, as request by the merchant. > This field is important for swipe authorization.
`merchant-rate`	A fee charged to the merchant for processing a transaction in the form of a percentage. > This field is important for swipe authorization.
`network-merchant-id`	Merchant IDs are often passed through with a transaction. This field is used to capture that information.
`network-tx-id`	The ID that is assigned to the transaction by the network.
`offline-pin`	Displays whether an offline PIN was the chosen method of cardholder verification.
`authorization-tolerance`	Used to track upcharge amounts that are added to the transaction.
`avs-result`	The result of the Address Verification Service (AVS) used on the swipe.
`transaction-fee-amount`	The dollar amount of the transaction fee charged on the swipe.
`updated`	The swipe's last updated date.
`created`	The swipe's creation date.
`ecommerce`	Determines whether the transaction was categorized as e-commerce.
`arqc`	The Authorization Request Cryptogram (ARQC) of the transaction. > This value is informational and it is generated before reaching Secure Payments.
`3ds`	Displays whether 3D Secure was the chosen method of cardholder verification.
`pin`	Displays whether a PIN was the chosen method of cardholder verification.
`status`	The swipe's status.
`emv-terminal`	Displays whether the swipe was initiated at a Europay, MasterCard, and Visa (EMV) terminal.
`network-risk-score`	A score assigned to the transaction that rates the riskiness of a transaction.
`network`	The card network that was used to initiate the swipe.
`card-present`	Determines whether the card was physically present during the swipe.
`cardholder-verified`	Determines whether the cardholder was verified during the swipe.
`cardholder-verification-method`	The method in which the cardholder was verified during the swipe.
`acq-method`	The acquisition method of the transaction. > This is information regarding how the swipe was made.
`cvv1`	Displays whether CCV1 was the chosen method of cardholder verification
`cvv2`	Displays whether CCV2 was the chosen method of cardholder verification
`cvv3`	Displays whether CCV3 was the chosen method of cardholder verification
`issuer-decline-reason`	The reason, if applicable, for declining the transaction as made by the issuer.
`issuer-transaction-id`	The ID that's assigned to the transaction by the issuer.
`issuer-decline?`	Determines whether the issuer declined the transaction. > This field is important for swipe handling, and it will affect the status and handling of funds.
`authorization-advice?`	Determines whether authorization advice was provided with the transaction. > This field is important for swipe handling, and it will affect the status and handling of funds.
`preauthorization?`	Determines whether the transaction received pre-authorization. > This field is important for swipe handling, and it will affect the status and handling of funds.
`force-clearing?`	Determines whether the merchant forced the clearing of the transaction. > This field is important for swipe handling, and it will affect the status and handling of funds.
`cash-advance?`	Determines whether the transaction was cash advance. > This field is important for swipe handling, and it will affect the status and handling of funds.
`credit-authorization?`	Determines whether the transaction included a return. This event occurs when goods are returned to the merchant and a separate transaction is made to send funds back to the borrower. > This field is important for swipe handling, and it will affect the status and handling of funds.
`sma?`	Determines whether Single Message Authorization (SMA) was used on the transaction. > This field is important for swipe handling, and it will affect the status and handling of funds.
`enriched_data` object	The swipe's enriched data. > For more information, see the `enriched_data` table below.
`attachments` object	The swipe's attachments. > For more information, see the `attachments` table below.
`memos` object	The swipe's memos. > For more information, see the `memos` table below.

Enriched data

The enriched_data entity is nested within the swipes entity. This feature is enabled in the programs entity and provides capturing additional information about the swipe, including location and merchant data.

Value:	Definition:
`description`	The swipe's description.
`category`	The swipe's category.
`logo_url`	The merchant's logo url.
`merchant_longitude`	The merchant's longitude.
`enriched_metadata`	Additional information regarding the swipe.
`parent_category`	The swipe's parent category.
`date_time`	The swipe's date time.
`merchant_latitude`	The merchant's latitude.
`merchant_country`	The merchant's country.
`merchant_city`	The merchant's city.
`is_subscription`	States whether the swipe is a subscription.
`merchant_website_url`	The merchant's website url.
`merchant_phone`	The merchant's phone number.
`merchant_name`	The merchant's name.
`merchant_address`	The merchant's address.
`merchant_state`	The merchant's state.
`merchant_postal_code`	The merchant's zip code.

Attachments

The attachments object is nested within the swipe entity. This object contains file and document information associated with the swipe.

Value:	Definition:
`id`	The attachments' ID.
`created`	The attachments' creation date.
`filename`	The attachments' file name.
`file_url`	The attachments' file url.
`bucket`	The attachments' bucket.
`key`	The attachments' key.

Swipe events

In LoanPro, a single swipe ID is used throughout a transaction's lifetime and swipe events are the actions that occur on the swipe. Each swipe event is represented by its own ID and is associated with a parent swipe.

Value:	Definition:
`event-id`	The event ID.
`swipe-id`	The swipe ID associated with the swipe event.
`card-uuid`	The card uuid associated with the swipe event.
`event-type`	The swipe event's type.
`amount`	The dollar amount of the swipe event.
`notes`	The swipe event's notes.
`metadata`	The swipe event's metadata.

Swipe memos

The memos object is nested within the swipe entity.

Value:	Definition
`id`	The memo's ID.
`memo`	The text field holding the contents of the memo. > Memos must be between 1 and 200 character
`created`	The memo's creation date.
`updated`	The memo's updated date.

Swipes

Swipe Status

Swipe flags

Swipe events

Key-value pairs

Swipes

Enriched data

Attachments

Swipe events

Swipe memos

Customers

Loans

Loan Servicing

Lines of Credit/Cards

Line of Credit Servicing

Custom Fields