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.
- To create a Merchant Account make a POST request to /merchantAccounts with VAR sheet information that is specific to the merchant service provider.[1]
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.
- To create a sale make a POST request with the state
PENDING_APPROVED
.
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.
- To create an authorization make a POST request with the state
PENDING_PRE_APPROVED
.
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 a transaction make a GET request to /transactions/{transactionId}.
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 toPENDING_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.
- To VOID a Transaction make a PUT request updating the state parameter to
PENDING_VOID
.
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.
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 |
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
- Create a Merchant Account
- GET /merchantAccounts
- List all Merchant Account’s associated with a specified API Key
- GET /merchantAccounts/{merchantAccountId}
- Fetch single Merchant Account
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 transaction (SALE, REFUND, AUTHORIZATION)
- GET /transactions
- List all transactions for specified merchant account
- GET/ transactions/{transactionId}
- Fetch specified transaction
- PUT /transactions/{transactionId}
- Update specified transaction (VOID, CAPTURE)
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 TransactionassociatedTransactionId
- requiredsdkData
- 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
- Transaction must be in the state
- VOID
state
-PENDING_VOID
- Transaction must be in the state
APPROVED
orPRE_APPROVED
- Transaction must be in the state
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
- Create an External Token on the CardFlight gateway.
- GET /externalTokens
- Fetch a single External Token.
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 on the CardFlight gateway.
- GET /signatures/{signatureId}
- Fetch a single Signature.
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.