Increase Card Payments API
Card Payments group together interactions related to a single card payment, such as an authorization and its corresponding settlement.
OpenAPI Specification
openapi: 3.1.0
info:
description: Anything that you can achieve with PDFs, presence, and persistence in a bank branch you can do with our API. We've always wanted a fully programmatic bank so we built one. Our API faithfully exposes the data and capabilities of the Federal Reserve, Visa, The Clearing House, depository networks, and accounting tools. It's lovingly boring and exceptionally powerful. If you have any questions or want to get started, don't hesitate to ping us at sales@increase.com. We can't wait to see what you build!
title: Increase Account Numbers Card Payments API
version: 0.0.1
servers:
- url: https://api.increase.com
- url: https://sandbox.increase.com
security:
- bearerAuth: []
tags:
- description: Card Payments group together interactions related to a single card payment, such as an authorization and its corresponding settlement.
name: Card Payments
paths:
/card_payments:
get:
operationId: list_card_payments
parameters:
- in: query
name: cursor
required: false
schema:
description: Return the page of entries after this one.
type: string
x-documentation-priority: low
- in: query
name: limit
required: false
schema:
description: Limit the size of the list that is returned. The default (and maximum) is 100 objects.
minimum: 1
type: integer
x-documentation-priority: low
- example: account_in71c4amph0vgo2qllky
in: query
name: account_id
required: false
schema:
description: Filter Card Payments to ones belonging to the specified Account.
type: string
x-documentation-priority: default
x-id-reference-to: Accounts
- in: query
name: card_id
required: false
schema:
description: Filter Card Payments to ones belonging to the specified Card.
type: string
x-documentation-priority: default
x-id-reference-to: Cards
- in: query
name: created_at.after
required: false
schema:
description: Return results after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
format: date-time
type: string
x-documentation-priority: low
- in: query
name: created_at.before
required: false
schema:
description: Return results before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
format: date-time
type: string
x-documentation-priority: low
- in: query
name: created_at.on_or_after
required: false
schema:
description: Return results on or after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
format: date-time
type: string
x-documentation-priority: low
- in: query
name: created_at.on_or_before
required: false
schema:
description: Return results on or before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
format: date-time
type: string
x-documentation-priority: low
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_payment_list'
description: Card Payment List
4XX:
$ref: '#/components/responses/errorResponse'
5XX:
$ref: '#/components/responses/errorResponse'
summary: List Card Payments
x-sandbox-only: false
x-tag: Card Payments
tags:
- Card Payments
/card_payments/{card_payment_id}:
get:
operationId: retrieve_a_card_payment
parameters:
- example: card_payment_nd3k2kacrqjli8482ave
in: path
name: card_payment_id
required: true
schema:
description: The identifier of the Card Payment.
type: string
x-documentation-priority: default
x-id-reference-to: Card Payments
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_payment'
description: Card Payment
4XX:
$ref: '#/components/responses/errorResponse'
5XX:
$ref: '#/components/responses/errorResponse'
summary: Retrieve a Card Payment
x-sandbox-only: false
x-tag: Card Payments
tags:
- Card Payments
components:
schemas:
card_authorization:
additionalProperties: true
description: Card Authorizations are temporary holds placed on a customer's funds with the intent to later clear a transaction.
example:
actioner: increase
additional_amounts:
clinic: null
dental: null
original: null
prescription: null
surcharge:
amount: 10
currency: USD
total_cumulative: null
total_healthcare: null
transit: null
unknown: null
vision: null
amount: 100
card_payment_id: card_payment_nd3k2kacrqjli8482ave
currency: USD
digital_wallet_token_id: null
direction: settlement
expires_at: '2020-01-31T23:59:59Z'
id: card_authorization_6iqxap6ivd0fo5eu3i8x
merchant_acceptor_id: '5665270011000168'
merchant_category_code: '5734'
merchant_city: New York
merchant_country: US
merchant_descriptor: AMAZON.COM
merchant_postal_code: '10045'
merchant_state: NY
network_details:
category: visa
pulse: null
visa:
electronic_commerce_indicator: secure_electronic_commerce
point_of_service_entry_mode: manual
stand_in_processing_reason: null
terminal_entry_capability: magnetic_stripe
network_identifiers:
authorization_identification_response: null
retrieval_reference_number: '785867080153'
trace_number: '487941'
transaction_id: '627199945183184'
network_risk_score: 10
pending_transaction_id: null
physical_card_id: null
presentment_amount: 100
presentment_currency: USD
processing_category: purchase
real_time_decision_id: null
scheme_fees:
- amount: '0.137465'
created_at: '2020-01-31T23:59:59Z'
currency: USD
fee_type: visa_corporate_acceptance_fee
fixed_component: null
variable_rate: '0.0002'
terminal_id: RCN5VNXS
type: card_authorization
verification:
card_verification_code:
result: match
cardholder_address:
actual_line1: 33 Liberty Street
actual_postal_code: '94131'
provided_line1: 33 Liberty Street
provided_postal_code: '94132'
result: postal_code_no_match_address_match
cardholder_name: null
properties:
actioner:
description: Whether this authorization was approved by Increase, the card network through stand-in processing, or the user through a real-time decision.
enum:
- user
- increase
- network
type: string
x-documentation-priority: default
x-enum-descriptions:
- This object was actioned by the user through a real-time decision.
- This object was actioned by Increase without user intervention.
- This object was actioned by the network, through stand-in processing.
additional_amounts:
additionalProperties: false
description: Additional amounts associated with the card authorization, such as ATM surcharges fees. These are usually a subset of the `amount` field and are used to provide more detailed information about the transaction.
properties:
clinic:
anyOf:
- additionalProperties: false
description: The part of this transaction amount that was for clinic-related services.
properties:
amount:
description: The amount in minor units of the `currency` field. The amount is positive if it is added to the amount (such as an ATM surcharge fee) and negative if it is subtracted from the amount (such as a discount).
type: integer
x-documentation-priority: default
currency:
description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the additional amount's currency.
type: string
x-documentation-priority: default
required:
- amount
- currency
title: Card Authorization AdditionalAmounts AdditionalAmount
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: s
- type: 'null'
dental:
anyOf:
- additionalProperties: false
description: The part of this transaction amount that was for dental-related services.
properties:
amount:
description: The amount in minor units of the `currency` field. The amount is positive if it is added to the amount (such as an ATM surcharge fee) and negative if it is subtracted from the amount (such as a discount).
type: integer
x-documentation-priority: default
currency:
description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the additional amount's currency.
type: string
x-documentation-priority: default
required:
- amount
- currency
title: Card Authorization AdditionalAmounts AdditionalAmount
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: s
- type: 'null'
original:
anyOf:
- additionalProperties: false
description: The original pre-authorized amount.
properties:
amount:
description: The amount in minor units of the `currency` field. The amount is positive if it is added to the amount (such as an ATM surcharge fee) and negative if it is subtracted from the amount (such as a discount).
type: integer
x-documentation-priority: default
currency:
description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the additional amount's currency.
type: string
x-documentation-priority: default
required:
- amount
- currency
title: Card Authorization AdditionalAmounts AdditionalAmount
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: s
- type: 'null'
prescription:
anyOf:
- additionalProperties: false
description: The part of this transaction amount that was for healthcare prescriptions.
properties:
amount:
description: The amount in minor units of the `currency` field. The amount is positive if it is added to the amount (such as an ATM surcharge fee) and negative if it is subtracted from the amount (such as a discount).
type: integer
x-documentation-priority: default
currency:
description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the additional amount's currency.
type: string
x-documentation-priority: default
required:
- amount
- currency
title: Card Authorization AdditionalAmounts AdditionalAmount
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: s
- type: 'null'
surcharge:
anyOf:
- additionalProperties: false
description: The surcharge amount charged for this transaction by the merchant.
properties:
amount:
description: The amount in minor units of the `currency` field. The amount is positive if it is added to the amount (such as an ATM surcharge fee) and negative if it is subtracted from the amount (such as a discount).
type: integer
x-documentation-priority: default
currency:
description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the additional amount's currency.
type: string
x-documentation-priority: default
required:
- amount
- currency
title: Card Authorization AdditionalAmounts AdditionalAmount
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: s
- type: 'null'
total_cumulative:
anyOf:
- additionalProperties: false
description: The total amount of a series of incremental authorizations, optionally provided.
properties:
amount:
description: The amount in minor units of the `currency` field. The amount is positive if it is added to the amount (such as an ATM surcharge fee) and negative if it is subtracted from the amount (such as a discount).
type: integer
x-documentation-priority: default
currency:
description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the additional amount's currency.
type: string
x-documentation-priority: default
required:
- amount
- currency
title: Card Authorization AdditionalAmounts AdditionalAmount
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: s
- type: 'null'
total_healthcare:
anyOf:
- additionalProperties: false
description: The total amount of healthcare-related additional amounts.
properties:
amount:
description: The amount in minor units of the `currency` field. The amount is positive if it is added to the amount (such as an ATM surcharge fee) and negative if it is subtracted from the amount (such as a discount).
type: integer
x-documentation-priority: default
currency:
description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the additional amount's currency.
type: string
x-documentation-priority: default
required:
- amount
- currency
title: Card Authorization AdditionalAmounts AdditionalAmount
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: s
- type: 'null'
transit:
anyOf:
- additionalProperties: false
description: The part of this transaction amount that was for transit-related services.
properties:
amount:
description: The amount in minor units of the `currency` field. The amount is positive if it is added to the amount (such as an ATM surcharge fee) and negative if it is subtracted from the amount (such as a discount).
type: integer
x-documentation-priority: default
currency:
description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the additional amount's currency.
type: string
x-documentation-priority: default
required:
- amount
- currency
title: Card Authorization AdditionalAmounts AdditionalAmount
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: s
- type: 'null'
unknown:
anyOf:
- additionalProperties: false
description: An unknown additional amount.
properties:
amount:
description: The amount in minor units of the `currency` field. The amount is positive if it is added to the amount (such as an ATM surcharge fee) and negative if it is subtracted from the amount (such as a discount).
type: integer
x-documentation-priority: default
currency:
description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the additional amount's currency.
type: string
x-documentation-priority: default
required:
- amount
- currency
title: Card Authorization AdditionalAmounts AdditionalAmount
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: s
- type: 'null'
vision:
anyOf:
- additionalProperties: false
description: The part of this transaction amount that was for vision-related services.
properties:
amount:
description: The amount in minor units of the `currency` field. The amount is positive if it is added to the amount (such as an ATM surcharge fee) and negative if it is subtracted from the amount (such as a discount).
type: integer
x-documentation-priority: default
currency:
description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the additional amount's currency.
type: string
x-documentation-priority: default
required:
- amount
- currency
title: Card Authorization AdditionalAmounts AdditionalAmount
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: s
- type: 'null'
required:
- total_healthcare
- total_cumulative
- surcharge
- transit
- vision
- clinic
- dental
- prescription
- original
- unknown
title: Card Authorization AdditionalAmounts
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: s
amount:
description: The pending amount in the minor unit of the transaction's currency. For dollars, for example, this is cents.
type: integer
x-documentation-priority: default
card_payment_id:
description: The ID of the Card Payment this transaction belongs to.
type: string
x-documentation-priority: default
x-id-reference-to: Card Payments
currency:
description: The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code for the transaction's currency.
enum:
- USD
type: string
x-documentation-priority: default
x-enum-descriptions:
- US Dollar (USD)
digital_wallet_token_id:
anyOf:
- description: If the authorization was made via a Digital Wallet Token (such as an Apple Pay purchase), the identifier of the token that was used.
type: string
x-documentation-priority: default
x-id-reference-to: Digital Wallet Tokens
- type: 'null'
direction:
description: The direction describes the direction the funds will move, either from the cardholder to the merchant or from the merchant to the cardholder.
enum:
- settlement
- refund
type: string
x-documentation-priority: default
x-enum-descriptions:
- A regular card authorization where funds are debited from the cardholder.
- A refund card authorization, sometimes referred to as a credit voucher authorization, where funds are credited to the cardholder.
expires_at:
description: The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) when this authorization will expire and the pending transaction will be released.
format: date-time
type: string
x-documentation-priority: default
id:
description: The Card Authorization identifier.
type: string
x-documentation-priority: default
x-id-reference-to: Card Authorizations
merchant_acceptor_id:
description: The merchant identifier (commonly abbreviated as MID) of the merchant the card is transacting with.
type: string
x-documentation-priority: default
merchant_category_code:
description: The Merchant Category Code (commonly abbreviated as MCC) of the merchant the card is transacting with.
type: string
x-documentation-priority: default
merchant_city:
anyOf:
- description: The city the merchant resides in.
type: string
x-documentation-priority: default
- type: 'null'
merchant_country:
description: The country the merchant resides in.
type: string
x-documentation-priority: default
merchant_descriptor:
description: The merchant descriptor of the merchant the card is transacting with.
type: string
x-documentation-priority: default
merchant_postal_code:
anyOf:
- description: The merchant's postal code. For US merchants this is either a 5-digit or 9-digit ZIP code, where the first 5 and last 4 are separated by a dash.
type: string
x-documentation-priority: default
- type: 'null'
merchant_state:
anyOf:
- description: The state the merchant resides in.
type: string
x-documentation-priority: default
- type: 'null'
network_details:
additionalProperties: false
description: Fields specific to the `network`.
properties:
category:
description: The payment network used to process this card authorization.
enum:
- visa
- pulse
type: string
x-documentation-priority: default
x-enum-descriptions:
- Visa
- Pulse
pulse:
anyOf:
- additionalProperties: false
description: Fields specific to the `pulse` network.
properties: {}
title: Card Authorization NetworkDetails Pulse
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: true
x-title-plural: Pulses
- type: 'null'
visa:
anyOf:
- additionalProperties: false
description: Fields specific to the `visa` network.
properties:
electronic_commerce_indicator:
anyOf:
- description: For electronic commerce transactions, this identifies the level of security used in obtaining the customer's payment credential. For mail or telephone order transactions, identifies the type of mail or telephone order.
enum:
- mail_phone_order
- recurring
- installment
- unknown_mail_phone_order
- secure_electronic_commerce
- non_authenticated_security_transaction_at_3ds_capable_merchant
- non_authenticated_security_transaction
- non_secure_transaction
type: string
x-documentation-priority: default
x-enum-descriptions:
- 'Single transaction of a mail/phone order: Use to indicate that the transaction is a mail/phone order purchase, not a recurring transaction or installment payment. For domestic transactions in the US region, this value may also indicate one bill payment transaction in the card-present or card-absent environments.'
- 'Recurring transaction: Payment indicator used to indicate a recurring transaction that originates from an acquirer in the US region.'
- 'Installment payment: Payment indicator used to indicate one purchase of goods or services that is billed to the account in multiple charges over a period of time agreed upon by the cardholder and merchant from transactions that originate from an acquirer in the US region.'
- 'Unknown classification: other mail order: Use to indicate that the type of mail/telephone order is unknown.'
- 'Secure electronic commerce transaction: Use to indicate that the electronic commerce transaction has been authenticated using e.g., 3-D Secure'
- 'Non-authenticated security transaction at a 3-D Secure-capable merchant, and merchant attempted to authenticate the cardholder using 3-D Secure: Use to identify an electronic commerce transaction where the merchant attempted to authenticate the cardholder using 3-D Secure, but was unable to complete the authentication because the issuer or cardholder does not participate in the 3-D Secure program.'
- 'Non-authenticated security transaction: Use to identify an electronic commerce transaction that uses data encryption for security however, cardholder authentication is not performed using 3-D Secure.'
- 'Non-secure transaction: Use to identify an electronic commerce transaction that has no data protection.'
- type: 'null'
point_of_service_entry_mode:
anyOf:
- description: The method used to enter the cardholder's primary account number and card expiration date.
enum:
- unknown
- manual
- magnetic_stripe_no_cvv
- optical_code
- integrated_circuit_card
- contactless
- credential_on_file
- magnetic_stripe
- contactless_magnetic_stripe
- integrated_circuit_card_no_cvv
type: string
x-documentation-priority: default
x-enum-descriptions:
- Unknown
- Manual key entry
- Magnetic stripe read, without card verification value
- Optical code
- Contact chip card
- Contactless read of chip card
- Transaction initiated using a credential that has previously been stored on file
- Magnetic stripe read
- Contactless read of magnetic stripe data
- Contact chip card, without card verification value
- type: 'null'
stand_in_processing_reason:
anyOf:
- description: 'Only present when `actioner: network`. Describes why a card authorization was approved or declined by Visa through stand-in processing.'
enum:
- issuer_error
- invalid_physical_card
- invalid_cryptogram
- invalid_cardholder_authentication_verification_value
- internal_visa_error
- merchant_transaction_advisory_service_authentication_required
- payment_fraud_disruption_acquirer_block
- other
type: string
x-documentation-priority: default
x-enum-descriptions:
- Increase failed to process the authorization in a timely manner.
- The physical card read had an invalid CVV or dCVV.
- The card's authorization request cryptogram was invalid. The cryptogram can be from a physical card or a Digital Wallet Token purchase.
- The 3DS cardholder authentication verification value was invalid.
- An internal Visa error occurred. Visa uses this reason code for certain expected occurrences as well, such as Application Transaction Counter (ATC) replays.
- The merchant has enabled Visa's Transaction Advisory Service and requires further authentication to perform the transaction. In practice this is often utilized at fuel pumps to tell the cardholder to see the cashier.
- The transaction was blocked by Visa's Payment Fraud Disruption service due to fraudulent Acquirer behavior, such as card testing.
- An unspecific reason for stand-in processing.
- type: 'null'
terminal_entry_capability:
anyOf:
- description: The capability of the terminal being used to read the card. Shows whether a terminal can e.g., accept chip cards or if it only supports magnetic stripe reads. This reflects the highest capability of the terminal — for example, a terminal that supports both chip and magnetic stripe will be identified as chip-capable.
enum:
- unknown
- terminal_not_used
- magnetic_stripe
- barcode
- optical_character_recognition
- chip_or_contactless
- contactless_only
- no_capability
type: string
x-documentation-priority: default
x-enum-descriptions:
- Unknown
- No terminal was used for this transaction.
- The terminal can only read magnetic stripes and does not have chip or contactless reading capability.
- The terminal can only read barcodes.
- The terminal can only read cards via Optical Character Recognition.
- The terminal supports contact chip cards and can also read the magnetic stripe. If contact chip is supported, this value is used regardless of whether cont
# --- truncated at 32 KB (505 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/increase/refs/heads/main/openapi/increase-card-payments-api-openapi.yml