CardFlight SDK Docs logo

CardFlight API Introduction

The CardFlight Gateway API is designed to facilitate simple card present payment processing for you as a client, on behalf of your merchants.

Our RESTful API is centered around an asynchronous /transactions endpoint.

All endpoints described below are available at:
https://api.cardflight.com/

Onboarding A Merchant Account

A merchant account must be created on the CardFlight gateway to process credit transactions.

A VAR Sheet (tear sheet, parameter sheet) contains merchant account information, bank account information, processor information, etc. These details allow CardFlight to communicate with the merchant processor.

[1]While CardFlight supports all major Merchant Service Providers, the API currently supports First Data Omaha (merchant type: Restaurant).

Creating A Transaction

Once a merchant account is boarded on the CardFlight gateway, making a POST request to /transactions will create a new transaction.

The state parameter informs the gateway of the requested transaction type and the platform will proceed accordingly.

The amount parameter is how much money will be transacted.

The card parameter will provide the account information for a customer (cardholder) providing payment.

Transaction Type: SALE

A sale request will check the available funds of a Cardholder and if approved allocate the amount to the Merchant.

Transaction Type: AUTHORIZATION (Restaurant Only)

An authorization request will place a hold on the Cardholder’s available balance for the amount provided. A capture update must be performed to allocate the funds to the merchant.

Transaction Type: REFUND

A refund is a transfer of funds from a merchant to a Cardholder.

  • To create a refund make a POST request with the state PENDING_APPROVED, a negative amount, and an associated transaction.[1]

A PARTIAL REFUND transaction can be created for a negative amount less than the associated (original sale) transaction.

Multiple partial refund transactions may occur until the total amount of the original transaction has been refunded.

[1]Unattached refunds are not supported, all refunds require an associated transaction.

Fetching A Transaction

A transaction is sent to the CardFlight gateway in state PENDING_APPROVED (Sale, Refund) or PENDING_PRE_APPROVED (Authorization.)

The CardFlight gateway will update the state to PRE_APPROVED, APPROVED, or DECLINED if the request was a successful authorization, successful sale, or declined sale or authorization.

When creating a transaction, due to variation in the processing time, polling may be needed to see the state update made by the gateway.

Fetch the transaction to return the current state, transaction details, attached metadata, and more.

To fetch nested objects within the transaction as part of the same request, use the expand query parameter.

Updating A Transaction

CAPTURE

A capture updates an approved AUTHORIZATION (in state PRE_APPROVED) by scheduling settlement of the PENDING funds on a Cardholder’s account. A successful capture results in the Transaction state APPROVED.

  • To CAPTURE a Transaction in state PRE_APPROVED, make a PUT request updating the state parameter to PENDING_APPROVED.

VOID

A void removes the scheduled settlement of a Transaction with state APPROVED. (CAPTURE, SALE, REFUND)

A void on a Transaction with state PRE_APPROVED (AUTHORIZATION) removes the hold on Cardholder funds.

If a VOID is unsuccessful the Transaction will state will be set to its previous APPROVED or PRE_APPROVED state.

Transaction State Machine

The Transaction State Machine diagram exposes client requested states and states managed by the CardFlight Gateway.

State Name Description Valid Exit States
PENDING_PRE_APPROVED
(Client Request)		 AUTHORIZATION requested, awaiting result. PRE_APPROVED
DECLINED
PRE_APPROVED
(Gateway)		 AUTHORIZATION approved, cardholder statement shows funds as ‘PENDING’. PENDING_APPROVED
PENDING_VOID
PENDING_APPROVED
(Client Request)		 SALE, CAPTURE, or REFUND requested, awaiting result. APPROVED
DECLINED
APPROVED
(Gateway)		 SALE, CAPTURE, REFUND approved, funds to be moved between merchant and cardholder. PENDING_VOID
SETTLED
PENDING_VOID
(Client Request)		 VOID requested, awaiting result. VOIDED
PRE_APPROVED
APPROVED
VOIDED
(Gateway)		 Transaction voided, funds are released to cardholder and no money will move between cardholder and merchant. FINAL STATE
DECLINED
(Gateway)		 AUTHORIZATION, SALE, REFUND request declined. FINAL STATE
SETTLED
(Gateway)		 CAPTURE, SALE, REFUND settled.[1] FINAL STATE
UNKNOWN
(Gateway)		 An error has occurred, please contact CardFlight support. FINAL STATE

[1] The transfer of funds is managed by the Payment Processor. Once a transaction is ‘settled’ the CardFlight platform is no longer or in control of, or exposed to, the funding. A ‘settled’ transaction is complete and can not be voided.

Transaction State Diagram

The Merchant Account Object

Attribute Type Description
id string The unique (CardFlight) ID used to identify your merchant account when making other requests
createdAt string The date and time that the MerchantAccount was created
name string The name of the merchant account
processor enum The payment processor that your merchant uses to take payments (See Below)
address object A group of address fields (See Below)
industry enum The industry this merchant account serves (See Below)

First Data Omaha Attributes

Attribute Type Description
merchantId string The Merchant ID provided by First Data
terminalId string The Terminal ID provided by First Data
deviceId string The Device ID provided by First Data
localBatchTime string The batch close time

Must be provided on the hour or half hour in the following format: 1:00 AM or 12:30 PM
batchTimeZone enum The time zone for the localBatchTime parameter

Vantiv Attributes

Attribute Type Description
merchantId string The Merchant ID given to you by Vantiv
terminalId string The Terminal ID given to you by Vantiv
bankId string The Bank ID given to you by Vantiv

Tsys Attributes

Parameter Type Description
merchantId string The Merchant ID provided by Tsys
terminalId string The Terminal ID provided by Tsys
storeNumber string The store number povided by Tsys
terminalNumber string The terminal number provided by Tsys
locationNumber string The location number provided by Tsys
sicCode string The sic code provided by Tsys
agentNumber string The agent number provided by Tsys
chainNumber string The chain number provided by Tsys
cityCode string The zip code - will match the address zip field
bin string The bin provided by Tsys
industry enum The industry this merchant account serves (See Below)
localBatchTime string The batch close time

Must be provided on the hour or half hour in the following format: 1:00 AM or 12:30 PM
batchTimeZone enum The time zone for the localBatchTime parameter

Address Object

Attribute Type Description
streetAddress string yes
city string yes
state string yes
zip string yes

Enumerations

MerchantAccount: industry

Enum Description
RESTAURANT The merchant is a restaurant
RETAIL The merchant is a retail establishment

MerchantAccount: processor

Enum Description
FIRST_DATA_OMAHA First Data Omaha
VANTIV Vantiv

CardFlight is certified to accept payments on many processors. The API gateway will expose support for more processors in the future.

MerchantAccount: batchTimeZone

Enum Description
EASTERN U.S. Eastern time, adheres to day light savings.
CENTRAL U.S. Central time, adheres to day light savings.
MOUNTAIN U.S. Mountain time, adheres to day light savings.
PACIFIC U.S. Pacific time, adheres to day light savings.
ALASKA Time in Juneau, Alaska, adheres to day light savings.
HAWAII Time in Honolulu, Hawaii, adheres to day light savings.
UTC Standard time, does not alter with day light savings.

The Card Object

Card Request & Response objects are very different. This is because sensitive card data is required to create a card.

Card Request: KEY_ENTERED

Attribute Type Description
entryMethod enum See below
data encrypted string A JSON object containing ‘number’, ‘expirationMonth’, ‘expirationYear’ and ‘cvv’. This object MUST be encrypted using AES, and then Base64-encoded.
aesKey encrypted string The AES key generated as part of the encryption process. This key MUST be encrypted using the RSA public key for your account, and then Base64-encoded.
aesIv encrypted string The AES initialization vector generated as part of the encryption process. This iv MUST be encrypted using the RSA public key for your account, and then Base64-encoded.

Card Request: MAGNETIC_STRIPE_READ

Attribute Type Description
entryMethod enum See below
data encrypted string Encrypted track data, provided by the CardFlight SDK
aesKey encrypted string The AES key generated as part of the encryption process. This key MUST be encrypted using the RSA public key for your account, and then Base64-encoded.
aesIv encrypted string The AES initialization vector generated as part of the encryption process. This iv MUST be encrypted using the RSA public key for your account, and then Base64-encoded.

Card Request: KEY_ENTERED (Un-Encrypted)

Note: Sending unencrypted key-entered card data is useful for testing purposes, but we strongly encourage you to use AES encryption when sending key-entered data, as described above

Attribute Type Description
entryMethod enum See below
number string The card number
expirationMonth string A 2-digit expiration month
expirationYear string A 2-digit or 4-digit expiration year
cvv string the CVV on the back of the card

Card Request: MAGNETIC_STRIPE_READ (Un-Encrypted)

Note: While raw track data can be sent directly to the API, we strongly recommend taking advantage of the CardFlight SDK and accompanying hardware for higher security.

Attribute Type Description
entryMethod enum See below
readerType enum See below
data string The track data from the card

Card Response

Attribute Type Description
id string A unique identifier for the card
cardholderName string The name of the owner of the card
brand enum See below
last4 string The card number’s last 4 digits
expirationMonth string A 2-digit expiration month
expirationYear string A 2-digit expiration year
entryMethod enum See below
readerType enum See below
applicationId string A machine-readable identifier for the application run on an EMV chip
applicationPreferredName string The preferred mnemonic associated with the applicationId

Enumerations

Card: entryMethod

Enum Description
KEY_ENTERED Card was manually keyed in
MAGNETIC_STRIPE_READ Card was entered by swiping the magnetic stripe
TOKEN Card was read in a prior transaction, and is being re-used
CHIP_READ Card was entered by reading the EMV chip
CONTACTLESS_READ Card was read using NFC

Card: brand

Enum Reader used to read & encrypt card data
AMEX American Express
MASTER_CARD MasterCard
DISCOVER Discover
VISA VISA
JCB JCB
DINERS_CLUB Diner’s Club
UNKNOWN Unable to determine card brand

Card: readerType

Enum Reader used to read & encrypt card data
A100 Element A100 series
A200 Eclipse A200 series
A250 Eclipse A250 series
B200 Swift B200 series
B250 Swift B250 series
B500 Bold B500 series
B550 Bold B550 series
UNENCRYPTED The raw unencrypted track data is provided
SHUTTLE A LEGACY Reader
BTMAG A LEGACY Reader

The Transaction Object

Attribute Type Description
amount integer The amount in cents
id string A unique identifier of the transaction
state enum See State Machine
metadata object Custom data stored with a transaction

Returned on GET /transactions/{transactionId}
paymentType enum See below
message string Reserved for future use
callbackUrl string When provided a post request will be made to the URL upon transaction state change

Includes a full representation of the transaction in the body
merchantAccount object The Merchant Account used to process the transaction
card object The Card used to process the transaction
updates array A list of updates made to the transaction
associatedTransactionId string [REFUND ONLY] The ID of the original (sale) transaction

Only present on a transaction with a negative amount
associatedTransactions array Any subsequent refunds[1]

[1]Sale only

Enumerations

Transaction: paymentType

Enum Description
CARD Transaction made using card details
TOKEN Transaction made using a card id[1]

[1]Card detail are stored in CardFlight’s PCI compliant data storage facility.

The Update Object

Attribute Type Description
timestamp string The time the update was made to the transaction
amount attribute-update The old and new amount in cents (OPTIONAL)
state attribute-update The old and new state of the transaction

The Attribute-Update Object

Attribute Type Description
from * The old value of the attribute
to * The new value of the attribute

Note: The ‘from’ and ‘to’ attributes have the same type as the corresponding attribute on the Transaction Object.

The Signature Object

Attribute Type Description
id string A unique identifier of the signature

The External Token Object

Attribute Type Description
id string A unique identifier of the external token
value string The string used externally by the merchant’s payment processor to identify this token
state enum See the state diagram (right)
merchantAccount object The Merchant Account used to create the external token
card object The Card used to create the external token

External Token State Diagram

Merchant Accounts

The MerchantAccount resource facilitates the processing of Transactions with a Merchant Processor.

The Merchant Account object will store CardFlight Gateway details about the Merchant Account as well as VAR sheet details that vary by payment processor.

Methods

POST /merchantAccounts

Make a POST request to create a MerchantAccount on the CardFlight gateway.

Processor-specific parameters should be passed as top level attributes.

Headers

Parameter Type Description
X-Api-Key
REQUIRED		 string Client’s API Key

Body

Parameter Type Description
name
REQUIRED		 string The name of the merchant account
processor
REQUIRED		 enum The payment processor that your merchant uses to take payments (See Below)
address
REQUIRED		 object A group of address fields
industry
REQUIRED		 string The industry this merchant account serves

First Data Omaha Parameters

Parameter Type Description
merchantId
REQUIRED		 string The Merchant ID provided by First Data
terminalId
REQUIRED		 string The Terminal ID provided by First Data
deviceId
REQUIRED		 string The Device ID provided by First Data
localBatchTime
REQUIRED		 string The batch close time

Must be provided on the hour or half hour in the following format: 1:00 AM or 12:30 PM
batchTimeZone
REQUIRED		 enum The time zone for the localBatchTime parameter

Vantiv Parameters

Parameter Type Description
merchantId
REQUIRED		 string The Merchant ID given to you by Vantiv
terminalId
REQUIRED		 string The Terminal ID given to you by Vantiv
bankId
REQUIRED		 string The Bank ID given to you by Vantiv

Tsys Parameters

Parameter Type Description
merchantId
REQUIRED		 string The Merchant ID provided by Tsys
terminalId
REQUIRED		 string The Terminal ID provided by Tsys
storeNumber
REQUIRED		 string The store number povided by Tsys
terminalNumber
REQUIRED		 string The terminal number provided by Tsys
locationNumber
REQUIRED		 string The location number provided by Tsys
sicCode
REQUIRED		 string The sic code provided by Tsys
agentNumber
REQUIRED		 string The agent number provided by Tsys
chainNumber
REQUIRED		 string The chain number provided by Tsys
bin
REQUIRED		 string The bin provided by Tsys
industry
REQUIRED		 enum The industry this merchant account serves
localBatchTime
REQUIRED		 string The batch close time

Must be provided on the hour or half hour in the following format: 1:00 AM or 12:30 PM
batchTimeZone
REQUIRED		 enum The time zone for the localBatchTime parameter

Responses

Code Description
201 Merchant Account created successfully
400 The syntax of the request is invalid
404 Associated resource was not found

Occurs if you post a merchant account for an API key which cannot be found
500 ERROR - Please contact CardFlight support
Request
POST /merchantAccounts HTTP/1.1
Host: api.cardflight.com
X-Api-Key: myApiKey

{
  "name": "Mikes JellyFish Warehouse",
  "processor": "FIRST_DATA_OMAHA",
  "address":
  {
    "streetAddress": "123 JellyBelly Lane",
    "city": "New York",
    "state": "NY",
    "zip": "00000"
  },
  "merchantId": "1234567890",
  "terminalId": "1234",
  "deviceId": "JELL",
  "industry": "RESTAURANT",
  "localBatchTime": "1:00 AM",
  "batchTimeZone": "EASTERN"
}
Response
Connection: Keep-Alive
Content-Length: 313
Content-Type: application/json
Date: Wed, 08 Mar 2017 19:12:14 GMT

{
  "id": "acc_c0dd014dcd06fb56",
  "name": "Mikes JellyFish Warehouse",
  "createdAt": "2017-03-08T19:12:14Z",
  "processor": "FIRST_DATA_OMAHA",
  "address": {
    "streetAddress": "123 JellyBelly Lane",
    "city": "New York",
    "state": "NY",
    "zip": "00000"
  },
  "merchantId": "1234567890",
  "terminalId": "1234",
  "deviceId": "JELL",
  "industry": "RESTAURANT",
  "localBatchTime": "1:00 AM",
  "batchTimeZone": "EASTERN"
}

GET /merchantAccounts

Fetch Merchant Accounts for a specified API Key.

Headers

Parameter Type Description
X-Api-Key
REQUIRED		 string Client’s API Key

Query Parameters

Parameter Type Description
page integer The page to fetch
per_page integer The number of records to fetch per page
filter[name] string Filter by the name of a merchant account
filter[processor] enum Filter by the processor type for a merchant account
filter[industry] string Filter by the industry of a merchant account
filter[batchTimeZone] enum Filter by the time zone for a merchant account
filter[merchantId] string Filter by the MID for a merchant account
filter[terminalId] string Filter by the TID for a merchant account

Responses

Code Description
200 Merchant Accounts fetched successfully
404 Associated resource was not found
500 ERROR - Please contact CardFlight support
Request
GET /merchantAccounts?per_page=3&page=6&filter[merchantId]=1234567890 HTTP/1.1
Host: api.cardflight.com
X-Api-Key: myApiKey
Response
Connection: Keep-Alive
Content-Length: 282
Content-Type: application/json
Date: Wed, 08 Mar 2017 19:19:41 GMT

{
  "data": [
    {
      "id": "acc_c0dd014dcd06fb56",
      "name": "Mikes JellyFish Warehouse",
      "createdAt": "2017-03-08T19:12:14Z",
      "processor": "FIRST_DATA_OMAHA",
      "address": {
        "streetAddress": "123 JellyBelly Lane",
        "city": "New York",
        "state": "NY",
        "zip": "00000"
      },
      "merchantId": "1234567890",
      "terminalId": "1234",
      "deviceId": "JELL",
      "industry": "RESTAURANT",
      "localBatchTime": "1:00 AM",
      "batchTimeZone": "EASTERN"
    }
  ]
}

GET /merchantAccounts/{merchantAccountId}

Fetch a specified merchant account.

Headers

Parameter Type Description
X-Api-Key
REQUIRED		 string Client API Key

Path Parameters

Parameter Type Description
merchantAccountId
REQUIRED		 string The (CardFlight) ID of the MerchantAccount you wish to fetch

Responses

Code Description
200 Merchant Account fetched successfully
404 Associated resource was not found
500 ERROR - Please contact CardFlight support
Request
GET /merchantAccounts/acc_vweb32r1vw6d0 HTTP/1.1
Host: api.cardflight.com
X-Api-Key: myApiKey
Response
Connection: Keep-Alive
Content-Length: 282
Content-Type: application/json
Date: Wed, 08 Mar 2017 19:19:41 GMT

{
  "id": "acc_vweb32r1vw6d0",
  "name": "Test FDOD",
  "createdAt": "2016-08-29T19:04:11Z",
  "processor": "FIRST_DATA_OMAHA",
  "address": {
    "streetAddress": "123 Tester Lane",
    "city": "New York",
    "state": "NY",
    "zip": "10000"
  },
  "merchantId": "123456123456",
  "terminalId": "1234",
  "deviceId": "4321",
  "industry": "RETAIL",
  "localBatchTime": "1:00 AM",
  "batchTimeZone": "EASTERN"
}

GET /cards/{cardId}

Fetch a single Card.

Headers

Parameter Type Description
X-Api-Key
REQUIRED		 string Client’s API Key
X-Merchant-Account-Id
REQUIRED		 string The (CardFlight) ID of the merchant account for which you wish to fetch a Card

Path Parameters

Parameter Type Description
cardId
REQUIRED		 string The ID of the Card you wish to fetch

Responses

Code Description
200 Card fetched successfully
401 The request is not authorized

Occurs if the authentication parameters in the header are not valid
404 The Card or an associated resource was not found
500 ERROR - Please contact CardFlight support

Request

GET /cards/cf_ABC123 HTTP/1.1
Host: api.cardflight.com
Content-Type: application/json
X-Api-Key: myApiKey
X-Merchant-Account-Id: myMerchant

Response

Connection: Keep-Alive
Content-Length: 296
Content-Type: application/json
Date: Wed, 08 Mar 2017 00:37:51 GMT

{
    "id": "cf_ABC123",
    "cardholderName": "CUSTOMER/A",
    "brand": "VISA",
    "last4": "4242",
    "expirationMonth": "01",
    "expirationYear": "20",
    "entryMethod": "CHIP_READ",
    "readerType": "A200",
    "applicationId": "A3000101",
    "applicationPreferredName": "CREDITO DE VISA"
}

Transactions

Transactions facilitate moving funds between a cardholder and a merchant account.

Methods

POST /transactions

Create a transaction for a specified merchant account.

  • SALE
    • state: PENDING_APPROVED
  • PRE-AUTHORIZATION
    • state: PENDING_PRE_APPROVED
  • REFUND
    • state:PENDING_APPROVED
    • amount: negative, cannot be greater than the remaining balance of the original Transaction
    • associatedTransactionId - required
    • sdkData - refund transactions will not store sdkData

Headers

Parameter Type Description
X-Api-Key
REQUIRED		 string Client’s API Key
X-Merchant-Account-Id
REQUIRED		 string The (CardFlight) ID of the merchant account for which you wish to create a transaction

Body

Parameter Type Description
amount (in cents)
REQUIRED		 integer The amount in cents
state
REQUIRED		 enum The current state of the transaction (See State Machine)
paymentType enum See Transaction
metadata object Custom data stored with a transaction

Returned on GET /transactions/{transactionId}
associatedTransactionId string [REFUND ONLY] The ID of the original (sale) transaction
callbackUrl string When provided a post request will be made to the URL upon transaction state change

Includes a full representation of the transaction in the body
card
REQUIRED		 object A Card object (The format of this object is dependent on the entryMethod provided)
sdkData object A data object that allows clients to store sdk data as part of the transaction.

Card: KEY_ENTERED

Parameter Type Description
entryMethod
REQUIRED		 enum A input method for obtaining the Card object. The provided entryMethod will determine the format of the card object provided. (‘KEY_ENTERED’)
number
REQUIRED		 string The card number
expirationMonth
REQUIRED		 string A 2 digit expiration month
expirationYear
REQUIRED		 string A 2 or 4 digit expiration year
cvv string the CVV on the back of the card

Card: MAGNETIC_STRIPE_READ

Parameter Type Description
entryMethod
REQUIRED		 enum A input method for obtaining the Card object. The provided entryMethod will determine the format of the card object provided. (‘MAGNETIC_STRIPE_READ’)
readerType
REQUIRED		 enum The type of reader used to capture the card information
data
REQUIRED		 string The track data from the card

Responses

Code Description
201 Transaction created successfully
400 The syntax of the request is invalid
401 The request is not authorized

Occurs if the authentication parameters in the header are not valid
404 Associated resource was not found
500 ERROR - Please contact CardFlight support
Request
POST /transactions HTTP/1.1
Host: api.cardflight.com
Content-Type: application/json
X-Api-Key: myApiKey
X-Merchant-Account-Id: myMerchant

{
    "amount": 100,
    "state": "PENDING_APPROVED",
    "paymentType": "CARD",
    "metadata": {
        "key": "value"
    },
    "callbackUrl": "www.testcompany.com/transaction_callback",
    "card": {
        "entryMethod": "MAGNETIC_STRIPE_READ",
        "readerType": "UNENCRYPTED",
        "data": "%B424242424242^TEST CARD^251010012345678;"
    },
    "sdkData": {
        "key": "value"
    }
}
Response
Connection: Keep-Alive
Content-Length: 312
Content-Type: application/json
Date: Wed, 08 Mar 2017 00:28:37 GMT

{
  "id": "ch_zxfHnjyhtNhOePQf18AtFA",
  "amount": 100,
  "state": "PENDING_APPROVED",
  "paymentType": "CARD",
  "metadata": {
    "key": "value"
  },
  "message": null,
  "callbackUrl": null,
  "merchantAccount": {
    "id": "myMerchant"
  },
  "card": {
    "id": "cf_lNKCY8EU1aNpw2iJf8_BFg"
  },
  "associatedTransactionId": null,
  "associatedTransactions": [],
  "updates": [
    {"timestamp": "2017-01-01T00:00:00Z"}
  ],
  "sdkData": {
    "key": "value"
  }
}

GET /transactions

Fetch transactions for a specified merchant account.

Headers

Parameter Type Description
X-Api-Key
REQUIRED		 string Client’s API Key
X-Merchant-Account-Id
REQUIRED		 string The (CardFlight) ID of the merchant account for which you wish to return the transactions

Query Parameters

Parameter Type Description
page integer The page to fetch
per_page integer The number of transactions to fetch per page
filter[state] enum Filter by transaction state
filter[message] string Filter by transaction message
filter[paymentType] enum Filter by transaction payment type
filter[processorTransactionReference] string Filter by transaction processor reference

Responses

Code Description
200 Transactions returned successfully
400 The syntax of the request is invalid
401 The request is not authorized

Occurs when the authentication parameters in the header are not valid
404 An associated resource was not found
500 ERROR - Please contact CardFlight support
Request
GET /transactions?per_page=3&page=6&filter[paymentType]=CARD HTTP/1.1
Host: api.cardflight.com
Content-Type: application/json
X-Api-Key: myApiKey
X-Merchant-Account-Id: myMerchant
Response
Connection: Keep-Alive
Content-Length: 1009
Content-Type: application/json
Date: Tue, 07 Mar 2017 21:00:59 GMT

{
  "data": [
    {
      "id": "ch_ABC123",
      "amount": 100,
      "state": "APPROVED",
      "paymentType": "CARD",
      "metadata": {
        "key": "value",
        "anotherKey": "differentValue"
      },
      "message": "Approved.",
      "callbackUrl": null,
      "merchantAccount": {
        "id": "myMerchant"
      },
      "associatedTransactionId": null,
      "associatedTransactions": [],
      "updates": [
        {"timestamp": "2017-01-01T00:00:00Z"}
      ],
      "card": {
        "id": "cf_XYZ123"
      }
    }
  ]
}

GET /transactions/{transactionId}

Fetch a single transaction.

Headers

Parameter Type Description
X-Api-Key
REQUIRED		 string Client’s API Key
X-Merchant-Account-Id
REQUIRED		 string The (CardFlight) ID of the merchant account for which you wish to fetch a transaction

Path Parameters

Parameter Type Description
transactionId
REQUIRED		 string The ID of the transaction you wish to fetch

Query Parameters

Parameter Type Description
expand Comma-separated string A list of any nested objects you wish to expand.
Supported Expansions: card, updates

Responses

Code Description
200 Transaction fetched successfully
401 The request is not authorized

Occurs if the authentication parameters in the header are not valid
404 The transaction or an associated resource was not found
500 ERROR - Please contact CardFlight support

Request

GET /transactions/ch_ABC123 HTTP/1.1
Host: api.cardflight.com
Content-Type: application/json
X-Api-Key: myApiKey
X-Merchant-Account-Id: myMerchant

Response

Connection: Keep-Alive
Content-Length: 296
Content-Type: application/json
Date: Wed, 08 Mar 2017 00:37:51 GMT

{
  "id": "ch_ABC123",
  "amount": 100,
  "state": "APPROVED",
  "paymentType": "CARD",
  "metadata": {
    "key": "value"
  },
  "message": null,
  "callbackUrl": null,
  "merchantAccount": {
    "id": "myMerchant"
  },
  "card": {
    "id": "cf_XYZ123"
  },
  "associatedTransactionId": null,
  "associatedTransactions": [],
  "updates": [
    {"timestamp": "2017-01-01T00:00:00Z"}
  ]
}

Request

GET /transactions/ch_ABC123?expand=card,updates HTTP/1.1
Host: api.cardflight.com
Content-Type: application/json
X-Api-Key: myApiKey
X-Merchant-Account-Id: myMerchant

Response

Connection: Keep-Alive
Content-Length: 296
Content-Type: application/json
Date: Wed, 08 Mar 2017 00:37:51 GMT

{
  "id": "ch_ABC123",
  "amount": 100,
  "state": "APPROVED",
  "paymentType": "CARD",
  "metadata": {
    "key": "value"
  },
  "message": null,
  "callbackUrl": null,
  "merchantAccount": {
    "id": "myMerchant"
  },
  "card": {
    "id": "cf_XYZ123",
    "cardholderName": "CUSTOMER/A",
    "brand": "VISA",
    "last4": "4242",
    "expirationMonth": "01",
    "expirationYear": "20",
    "entryMethod": "CHIP_READ",
    "readerType": "A200",
    "applicationId": "A3000101",
    "applicationPreferredName": "CREDITO DE VISA"
  },
  "associatedTransactionId": null,
  "associatedTransactions": [],
  "updates": [
    {
      "timestamp": "2018-01-31T19:08:26.000Z",
      "state": {
        "from": null,
        "to": "PRE_APPROVED"
      },
      "amount": {
        "from": null,
        "to": 60
      }
    },
    {
      "timestamp": "2018-01-31T19:08:38.000Z",
      "state": {
        "from": "PRE_APPROVED",
        "to": "PENDING_APPROVED"
      },
      "amount": {
        "from": 60,
        "to": 100
      }
    },
    {
      "timestamp": "2018-01-31T19:08:40.000Z",
      "state": {
        "from": "PENDING_APPROVED",
        "to": "APPROVED"
      }
    }
  ]
}

PUT /transactions/{transactionId}

Modify a specified transaction.

  • CAPTURE
    • state - PENDING_APPROVED
      • Transaction must be in the state PRE_APPROVED
  • VOID
    • state - PENDING_VOID
      • Transaction must be in the state APPROVED or PRE_APPROVED

Update requests require only the attributes being changed.

We strongly recommend submitting a full representation of the Transaction. Server-side validation will confirm your current understanding of the Transaction attributes.

Headers

Parameter Type Description
X-Api-Key
REQUIRED		 string Client’s API Key
X-Merchant-Account-Id
REQUIRED		 string The (CardFlight) ID of the merchant account for which you wish to update a transaction

Path Parameters

Parameter Type Description
transactionId
REQUIRED		 string The ID of the transaction you wish to update.

Body

Parameter Type Description
id string The ID of the transaction
amount integer The amount in cents
state
REQUIRED		 enum The state of the transaction (See State Machine)
metadata object Custom data stored with a transaction

Returned on GET /transactions/{transactionId}
associatedTransactionId string [REFUND ONLY] The ID of the original (sale) transaction
callbackUrl string When provided a post request will be made to the URL upon transaction state change

Includes a full representation of the transaction in the body
card object A Card object (see below)

Cards

For an update request, a card must be passed in the following format:

Parameter Type Description
id
REQUIRED		 string The ID of the card used to create this transaction

Responses

Code Description
200 Transaction updated successfully
400 The syntax of the request is invalid
401 The request is not authorized

Occurs if the authentication parameters in the header are not valid
404 The Transaction or an associated resource was not found
500 ERROR - Please contact CardFlight support
Request
PUT /transactions/ch_ABC123 HTTP/1.1
Host: api.cardflight.com
Content-Type: application/json
X-Api-Key: myApiKey
X-Merchant-Account-Id: myMerchant

{
    "id": "ch_ABC123",
    "amount": 100,
    "state": "PENDING_VOID",
    "paymentType": "CARD",
    "metadata": {
        "key": "value"
    },
    "card": {
        "id": "cf_XYZ123"
    }
}
Response
Connection: Keep-Alive
Content-Length: 296
Content-Type: application/json
Date: Wed, 08 Mar 2017 00:37:51 GMT

{
  "id": "ch_ABC123",
  "amount": 100,
  "state": "PENDING_VOID",
  "paymentType": "CARD",
  "metadata": {
    "key": "value"
  },
  "message": null,
  "callbackUrl": null,
  "merchantAccount": {
    "id": "myMerchant"
  },
  "card": {
    "id": "cf_XYZ123"
  },
  "associatedTransactionId": null,
  "associatedTransactions": [],
  "updates": [
    {"timestamp": "2017-01-01T00:00:00Z"}
  ]
}

External Tokens

Methods

POST /externalTokens

Make a POST request to create an External Token on the CardFlight gateway.

CardFlight only supports External Token creation for Stripe and Braintree merchants.

For Braintree merchants only CardFlight associates the card with the specified customerId. If customerId is omitted, null or invalid, it assigns a new one that it returns with subsequent GET requests.

For Stripe merchants, customerId must be omitted or null.

Headers

Parameter Type Description
X-Api-Key
REQUIRED		 string Client’s API Key

Body

Parameter Type Description
state
REQUIRED		 string The current state of the external token
card
REQUIRED		 object A Card object (The format of this object is dependent on the entryMethod provided)
customerId string [BRAINTREE MERCHANTS ONLY] Optional customer ID to associate with the card

Responses

Code Description
201 External Token created successfully
400 The syntax of the request is invalid
404 Associated resource was not found

Occurs if you post an External Token for a MerchantAccount which cannot be found
500 ERROR - Please contact CardFlight support
Request
POST /externalTokens HTTP/1.1
Host: api.cardflight.com
X-Api-Key: myApiKey
X-Merchant-Account-Id: myMerchant

{
  "state": "PENDING_CREATED",
  "card": {
    "entryMethod": "KEY_ENTERED",
    "number": "4242424242424242",
    "expirationMonth": "06",
    "expirationYear": "25",
    "cvv": "123"
  },
  "customerId": null
}
Response
Connection: Keep-Alive
Content-Length: 313
Content-Type: application/json
Date: Wed, 08 Mar 2017 19:12:14 GMT

{
  "id": "et_748b4a34856c44b88c4cd42dc04bc1c0",
  "value": null,
  "card": {
    "id": "cf_Ytrp5Le8xRq9Yf8ildKBCg"
  },
  "merchantAccount": {
    "id": "myMerchant"
  },
  "state": "PENDING_CREATED",
  "customerId": null
}

GET /externalTokens/{externalTokenId}

Fetch a single External Token.

For Braintree merchants, CardFlight’s response includes the associated customerId. For Stripe merchants customerId is always null.

Headers

Parameter Type Description
X-Api-Key
REQUIRED		 string Client’s API Key
X-Merchant-Account-Id
REQUIRED		 string The (CardFlight) ID of the merchant account for which you wish to fetch an External Token

Path Parameters

Parameter Type Description
externalTokenId
REQUIRED		 string The ID of the External Token you wish to fetch

Responses

Code Description
200 External Token fetched successfully
401 The request is not authorized

Occurs if the authentication parameters in the header are not valid
404 The External Token or an associated resource was not found
500 ERROR - Please contact CardFlight support

Request

GET /externalTokens/et_ABC123 HTTP/1.1
Host: api.cardflight.com
Content-Type: application/json
X-Api-Key: myApiKey
X-Merchant-Account-Id: myMerchant

Response

Connection: Keep-Alive
Content-Length: 296
Content-Type: application/json
Date: Wed, 08 Mar 2017 00:37:51 GMT

{
  "id": "et_748b4a34856c44b88c4cd42dc04bc1c0",
  "value": "aeb3456klx",
  "card": {
    "id": "cf_Ytrp5Le8xRq9Yf8ildKBCg"
  },
  "merchantAccount": {
    "id": "myMerchant"
  },
  "state": "CREATED",
  "customerId": "123456789"
}

Signatures

Methods

POST transactions/{transactionId}/signatures

Create a signature.

Path Parameters

Parameter Type Description
transaction Id
REQUIRED		 string The ID of the transaction for which you wish to create a signature

Responses

Code Description
201 Signature created successfully
401 The request is not authorized

Occurs if the authentication parameters in the header are not valid
404 The Transaction was not found
500 ERROR - Please contact CardFlight support

Request

POST transactions/ch_ABC123/signatures HTTP/1.1
Host: api.cardflight.com
Content-Type: image/png

{BINARY IMAGE FILE}

Response

Content-Type: image/png
Location: 'https://api.cardflight.com/signatures/sig_123'

201 Created

GET /signatures/{signatureId}

Fetch a signature.

Path Parameters

Parameter Type Description
signatureId
REQUIRED		 string The ID of the Signature you wish to fetch

Responses

Code Description
200 Signature fetched successfully
404 The Signature was not found
500 ERROR - Please contact CardFlight support

Request

GET /signatures/sig_ABC123 HTTP/1.1
Host: api.cardflight.com
Content-Type: application/json

Response

Connection: Keep-Alive
Content-Length: 296
Content-Type: image/png
Date: Wed, 08 Mar 2017 00:37:51 GMT

{BINARY IMAGE FILE}

List of Enumerations

Some objects use enums for certain attributes. The following tables outline the possible values.