Introduction


This reference introduces the various concepts around online payments and describes the usage of all endpoints that make up the API, along with data structure, error messages and supported message formats. API v1 is a standard REST-style API that accepts/returns JSON requests and is located at:

https://api.flexpay.io/v1/



  Authentication

To initiate a request to any of FlexPay.io’s endpoints, the 'Authorization' field of your HTTPS header request must include your API key.


Example Header Request


curl "https://api.flexpay.io/v1/transactions”

-H "Authorization: Basic kIqCBL40PaoL2Tg28hUxVgtqKgYDTSLnl5J3iwptJHA="


The API keys provided to you can be used in either Sandbox or Live mode. Remember that a different set of keys is required for each business channel.


Transactions

Every action performed against the FlexPay API is captured as a transaction. Transactions can represent local actions, such as storing a payment method, or an external action, such as performing a purchase against a gateway.



List


Returns a list of transactions that were processed. All transactions are returned in sorting order (paginated list) in the authenticated account.


GET /v1/transactions

URL Parameters

Parameter
Description
orderThe sorting order of the returned list. The default is asc, which returns the oldest records first. To list newer records first, use desc.
sinceTransactionIdThe transaction id of the item to start from (e.g., the last transaction id received in the previous list if iterating through records)
countThe number of transactions to return. By default, returns 20, maximum allowed is 100.



Response Body

Notable response elements include:

ElementDescription
transactionsRoot element
❯ transactionId
The transaction id uniquely identifying the transaction at FlexPay
❯ transactionDate
Processing host date stamp.
❯ transactionStatusIndicates the result of the transaction: 1 = Approved, 2 = Declined, 3 = Error
❯ messageResponse description returned from issuing institution. This message should not display on any cardholder facing materials
❯ transactionTypeThe type of transaction, e.g., AUTHORIZE, CAPTURE, CHARGE, REFUND, VOID
❯ GatewayElement
❯❯ token



This field is the gateway associated with a merchant account against which the request is made.
❯❯ gatewayTypeCode to identify on which gateway the transaction has been attempt (e.g. Vantiv)
❯❯ nameThe human readable name of the gateway
❯❯ referenceIdReference the merchant account used for the transaction


Show

Get the transaction with the given transaction id.




GET /v1/transactions/<transactionId>

URL Parameters

ParameterDescription
transactionIdThe transaction id identifying this transaction at FlexPay



Response Body

Notable response elements include:

Element
Description
transaction
Root element
❯ PaymentMethod
Payment method elememt
❯❯ gatewayPaymentMethodId
3rd party token that identifies a payment method stored in other vaults
❯❯ merchantAccountReferenceId
Gateway identifier at the CRM level
❯❯ firstSixDigits
First six digits of the payment method stored in the 3rd party vault.
❯❯ lastFourDigits
Last four digits of the payment method stored in the 3rd party vault
❯ References
Reference Element
❯❯ PreviousTransaction
Previous transaction element
❯❯❯ merchantAccountReferenceId
Gateway identifier at the CRM level
❯❯❯ gatewayCode
Gateway code returned for previous transaction
❯❯❯ gatewayMessage
Gateway messaged returned for previous transaction
❯❯❯ transactionDate
The date of the previous transaction

Payment Methods

Create credit card

Create a credit card payment method in the FlexPay vault to be used later on.



POST v1/paymentmethods

Request Body

ELEMENT
TYPE
REQUIRED
DESCRIPTION

paymentMethod


Root object
❯ customerId
String (50)
No
Merchant-defined, unique identifier to represent the customer associated with the transaction.  Required if the email is not provided. Otherwise, a new customer id is created and return.
❯ creditCard
Element
Yes
Credit card element
❯❯ creditCardNumber



String (22)
Yes
This field is the card number you are charging for this transaction.
❯❯ expiryMonth



String (2)
Yes
Card expiry month expressed as MM (e.g. 06 for June)
❯❯ expiryYear



String (4)
Yes
Card expiry year expressed as YYYY (e.g. 2017)
❯❯ cvv



String (4)
No
This is the 3- or 4-digit security code that appears on the back of the card of a credit card following the card number.  This code does not appear on imprints.
❯❯ firstName



String (50)
Yes
This field contains the first name of the customer associated with the billing address for the transaction.
❯❯ lastName



String (50)
Yes
This field contains the last name of the customer associated with the billing address for the transaction.
❯❯ fullName
String (100)
No
The full name of the cardholder.
❯❯ address1



String (255)
Yes
Contains the address line 1 of the customer associated with the billing address for the transaction.
❯❯ address2



String (255)
No
Contains the address line 2 of the customer associated with the billing address for the transaction.
❯❯ postalCode



String (100)
Yes
Contains the postal code (ZIP code if in the US) of the customer associated with the billing address for the transaction.
❯❯ city



String (100)
Yes
The field contains the city of the customer associated with the billing address for the transaction.
❯❯ state



String (100)
Yes
The field contains the state of the customer associated with the billing address for the transaction. Any valid two characters’ state code or full state name.
❯❯ country



String (3)
Yes
The field contains the country of the customer associated with the billing address for the transaction.  Three-letter country codes defined in ISO 3166-1
❯❯ email
String (100)
No
Cardholder's email address.
❯❯ phoneNumber
String (100)
No
Cardholder's phone number.



Response Body

Notable response elements include:

Element
Description
paymentMethod
Payment Method core object



List

Retrieve an ordered and paginated list of all payment methods in the authenticated account.



GET v1/paymentmethods

URL Parameters

Parameter
Description
order
The sorting order of the returned list. The default is asc, which returns the oldest records first. To list newer records first, use desc.
sincePaymentMethodId
The payment method id of the item to start from (e.g., the last payment method id received in the previous list if iterating through records)
count
The number of payment methods to return. By default, returns 20, maximum allowed is 100.



Response Body

Notable response elements include:

Element
Description
paymentMethods
Root element
❯ paymentMethodId
The identifier of the payment method
❯ creditCardNumber
The card number of the transaction
❯ expiryMonth
Card expiry month expressed as MM (e.g. 06 for June)
❯ expiryYear
Card expiry year expressed as YYYY (e.g. 2017)
❯ cvv
This is the 3- or 4-digit security code that appears on the back of the card of a credit card following the card number.  This code does not appear on imprints.
❯ firstName
This field contains the first name of the customer associated with the billing address for the transaction.
❯ lastName
This field contains the last name of the customer associated with the billing address for the transaction.
❯ fullName
The full name of the cardholder.
❯ customerId
The token of the parent customer
❯ address1
Contains the address line 1 of the customer associated with the billing address for the transaction.
❯ address2
Contains the address line 2 of the customer associated with the billing address for the transaction.
❯ postalCode
Contains the postal code (ZIP code if in the US) of the customer associated with the billing address for the transaction.
❯ city
The field contains the city of the customer associated with the billing address for the transaction.
❯ state
The field contains the state of the customer associated with the billing address for the transaction. Any valid two characters’ state code or full state name.
❯ country
The field contains the country of the customer associated with the billing address for the transaction.  Three-letter country codes defined in ISO 3166-1
❯ email
Cardholder's email address.
❯ phoneNumber
Cardholder's phone number.
❯ paymentMethodType
The payment method type : “CreditCard”



Show

Get the payment method with the given transaction id.


GET v1/paymentmethods/<paymentMethodId>

URL Parameters

Parameter
Description
paymentMethodId
The id identifying this payment method at FlexPay



Response Body

Notable response elements include:

Element
Description
paymentMethod
Payment method core object element



Update

Update non sensitive information of an existing payment method stored in FlexPay vault.


PUT v1/paymentmethods/<paymentMethodId>

URL Parameters

Parameter
Description
paymentMethodId
The id identifying this payment method at FlexPay



Request Body

Element
Type
REQUIRED
Description
paymentMethod


Root object
❯ expiryMonth



String (2)
No
Card expiry month expressed as MM (e.g. 06 for June). Do not send this field if you do not want to update it.
❯ expiryYear



String (4)
No
Card expiry year expressed as YYYY (e.g. 2017). Do not send this field if you do not want to update it.
❯ firstName



String (50)
No
This field contains the first name of the customer associated with the billing address for the transaction. ). Do not send this field if you do not want to update it.
❯ lastName



String (50)
No
This field contains the last name of the customer associated with the billing address for the transaction. ). Do not send this field if you do not want to update it.
❯ fullName
String (100)
No
The full name of the cardholder. ). Do not send this field if you do not want to update it.
❯ address1



String (255)
No
Contains the address line 1 of the customer associated with the billing address for the transaction. ). Do not send this field if you do not want to update it.
❯ address2



String (255)
No
Contains the address line 2 of the customer associated with the billing address for the transaction. ). Do not send this field if you do not want to update it.
❯ postalCode



String (100)
No
Contains the postal code (ZIP code if in the US) of the customer associated with the billing address for the transaction. ). Do not send this field if you do not want to update it.
❯ city



String (100)
No
The field contains the city of the customer associated with the billing address for the transaction. ). Do not send this field if you do not want to update it.
❯ state



String (100)
No
The field contains the state of the customer associated with the billing address for the transaction. Any valid two characters’ state code or full state name. ). Do not send this field if you do not want to update it.
❯ country



String (3)
No
The field contains the country of the customer associated with the billing address for the transaction.  Three-letter country codes defined in ISO 3166-1). Do not send this field if you do not want to update it.
❯ email
String (100)
No
Cardholder's email address. ). Do not send this field if you do not want to update it.
❯ phoneNumber
String (100)
No
Cardholder's phone number). Do not send this field if you do not want to update it.



Response Body

Notable response elements include:

Element
Description
paymentMethod
Payment method core object element



Redact

Redact (strip of any sensitive information) a payment method stored in the vault.


PUT v1/paymentmethods/<paymentMethodId>/redact

URL Parameters

Parameter
Description
paymentMethodId
The id identifying this payment method at FlexPay



Response Body

Notable response elements include:

Element
Description
paymentMethod
Payment method core object element



Recache

Update a credit card’s verification value (CVV) so the card can be transacted against.



PUT v1/paymentmethods/<paymentMethodId>/recache

URL Parameters

Parameter
Description
paymentMethodId
The id identifying this payment method at FlexPay



Request Body

Element
Type
REQUIRED
Description
paymentMethod


Root object
❯ cvv



String (4)
Yes
This is the 3- or 4-digit security code that appears on the back of the card of a credit card. Use recache method to update payment method stored in FlexPay vault.



Response Body

Notable response elements include:

Element
Description
paymentMethod
Payment method core object element




Charge

Tokenized payment method

Pass a charge request using a payment method stored in the vault.



POST /v1/gateways/charge

Request Body

Element
Type
Required
Description
1. transaction2.
3.
4. Root element
❯ merchantTransactionId
String (256)
Yes
This field is your unique ID number associated with each transaction request.  You create this value and submit it with the transaction.
❯ orderId



String (50)
Yes
Merchant-assigned order identification number.
❯ description



String (255)
No
Describe the transaction to help reconciliation.
❯ customerId


String (50)
No
Merchant-defined, unique identifier to represent the customer associated with the transaction.  Required if the email is not provided. Otherwise, a new customer id is created and return.
❯ currencyCode



String (3)
Yes
Three-digit currency code (e.g. USD, CAD).   ISO 4217 Currency Codes
❯ amount



Integer
Yes
Amount in cents (e.g. 1957 is equivalent to 19.57)
❯ paymentMethodId
String (50)
Yes
The id of the payment method in vault.
❯ customerIp



String (15)
No
IP address of the customer initiating the transaction. The required format is 255.255.255.255.
❯ shippingAddress



❯❯ address1



String (255)
No
Contains the address line 1 of the customer associated with the shipping address for the transaction.
❯❯ address2



String (255)
No
Contains the address line 2 of the customer associated with the shipping address for the transaction.
❯❯ postalCode



String (100)
No
Contains the postal code (ZIP code if in the US) of the customer associated with the shipping address for the transaction.
❯❯ city



String (100)
No
The field contains the city of the customer associated with the shipping address for the transaction.
❯❯ state



String (100)
No
The field contains the state of the customer associated with the shipping address for the transaction. Any valid two characters’ state code or full state name.
❯❯ country



String (50)
No
The field contains the country of the customer associated with the shipping address for the transaction.  Three-letter, Two-letter or name of the country defined in ISO 3166-1
❯ assignedGatewayToken



String (50)
No
This field is the gateway associated with a merchant account against which the request will be made on a next attempt.
❯ paymentPlan


Element related to a recurring payment
❯❯ sku
String (150)
No
The field contains the unique product identifier (SKU).
❯❯ category
String (150)
No
Contains the primary category code associated with the product.
❯❯ billingPlan
String (50)
No
Contains the code associated with the billing plan.
❯❯ billingCycle
Integer
No
When the transaction is for a recurring payment, the field contains billing cycle number. Start at 1
❯ retryCount


Integer
Yes
The field contains the number of retry of the billing cycle.  The initial attempt is 0 and all others retries will increase the count by 1.
❯ dateFirstAttempt



DateTime
No
The field contains the date of the first transaction attempt for this billing cycle. The date is required when the retry count is greater than 1.  UTC and date format(Iso 8601)  YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.45+01:00)
❯ referenceData



String (512)
No
Reference data received from the gateway when a payment failed.  Return this data on retry transaction for the same payment.
❯ disableCustomerRecovery
boolean
No
Default value is false and it’s usually turned to true in case of a new sale
❯ customVariable1


String (50)
No
Optional user defined string value.
❯ customVariable2


String (50)
No
Optional user defined string value.
❯ customVariable3


String (50)
No
Optional user defined string value.
❯ customVariable4


String (50)
No
Optional user defined string value.
❯ customVariable5


String (50)
No
Optional user defined string value.

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             

❯ References


Reference elements
❯❯ PreviousTransaction


Element relation to previous transaction details
❯❯❯ merchantAccountReferenceId
String (512)
See note
Required if gatewayCode, gatewayMessage or transactionDate provided.
> Gateway identified at the CRM level.

❯❯❯ gatewayCode
String (50)
No
Gateway code returned for previous transaction.
❯❯❯ gatewayMessage
String (256)
No
Gateway messaged returned for previous transaction.
❯❯❯ transactionDate
DateTime (ISO 8601)

Required if gatewayCode or gatewayMessage is set.

The date of the previous transaction.




Response Body

Notable response elements include:

Element
Type
Description
transaction

Transaction Core object element. See the description below.



Pass-in credit card

Pass a credit card payment method directly into the charge request. If the card is valid, it will automatically be tokenized if retain on success  = true, before sending to the gateway.



POST /v1/gateways/charge

Request Body

Element
Type
Required
Description
transaction


Root element
❯ merchantTransactionId
String (256)
Yes
This field is your unique ID number associated with each transaction request.  You create this value and submit it with the transaction.
❯ orderId



String (50)
Yes
Merchant-assigned order identification number.
❯ description



String (255)
No
Describe the transaction to help reconciliation.
❯ customerId


String (50)
No
Merchant-defined, unique identifier to represent the customer associated with the transaction.  Required if the email is not provided. Otherwise, a new customer id is created and return.
❯ currencyCode



String (3)
Yes
Three-digit currency code (e.g. USD, CAD).   ISO 4217 Currency Codes
❯ amount



Integer
Yes
Amount in cents (e.g. 1957 is equivalent to 19.57)
❯ retainOnSuccess
Boolean
Yes
Retain payment method in vault if transaction is successful.
❯ paymentMethod
String (22)
Yes
Element
❯❯ creditCardNumber



String (22)
Yes
This field is the card number you are charging for this transaction.
❯❯ expiryMonth



String (2)
Yes
Card expiry month expressed as MM (e.g. 06 for June)
❯❯ expiryYear



String (4)
Yes
Card expiry year expressed as YYYY (e.g. 2017)
❯❯ cvv



String (4)
No
This is the 3- or 4-digit security code that appears on the back of the card of a credit card following the card number.  This code does not appear on imprints.
❯❯ firstName



String (50)
Yes
Contains the first name of the customer associated with the billing address for the transaction.
❯❯ lastName



String (50)
Yes
Contains the last name of the customer associated with the billing address for the transaction.
❯❯ fullName
String (100)
Yes
The full name of the cardholder. If provided, will be parsed to determine firstName and lastName.
either fullName or both firstName and lastName are required
❯❯ address1



String (255)
No
Contains the address line 1 of the customer associated with the billing address for the transaction.
❯❯ address2



String (255)
No
Contains the address line 2 of the customer associated with the billing address for the transaction.
❯❯ postalCode



String (100)
Yes
Contains the postal code (ZIP code if in the US) of the customer associated with the billing address for the transaction.
❯❯ city



String (100)
Yes
The field contains the city of the customer associated with the billing address for the transaction.
❯❯ state



String (100)
Yes
The field contains the state of the customer associated with the billing address for the transaction. Any valid two characters’ state code or full state name.
❯❯ country



String (50)
No
The field contains the country of the customer associated with the shipping address for the transaction.  Three-letter, Two-letter or name of the country defined in ISO 3166-1
❯❯ email
String (100)
No
Cardholder's email address.
❯❯ phoneNumber


Cardholder's phone number.
❯ customerIp



String (15)
No
IP address of the customer initiating the transaction. The required format is 255.255.255.255.
❯ shippingAddress



❯❯ address1



String (255)
No
Contains the address line 1 of the customer associated with the shipping address for the transaction.
❯❯ address2



String (255)
No
Contains the address line 2 of the customer associated with the shipping address for the transaction.
❯❯ postalCode



String (100)
No
Contains the postal code (ZIP code if in the US) of the customer associated with the shipping address for the transaction.
❯❯ city



String (100)
No
The field contains the city of the customer associated with the shipping address for the transaction.
❯❯ state



String (100)
No
The field contains the state of the customer associated with the shipping address for the transaction. Any valid two characters’ state code or full state name.
❯❯ country



String (50)
No
The field contains the country of the customer associated with the shipping address for the transaction.  Three-letter, Two-letter or name of the country defined in ISO 3166-1
❯ assignedGatewayToken



String (50)
No
This field is the gateway associated with a merchant account against which the request will be made on a next attempt.
❯ paymentPlan


Element related to a recurring payment
❯❯ sku
String (150)
No
The field contains the unique product identifier (SKU).
❯❯ category
String (150)
No
Contains the primary category code associated with the product.
❯❯ billingPlan
String (50)
No
Contains the code associated with the billing plan.
❯❯ billingCycle
Integer
No
When the transaction is for a recurring payment, the field contains billing cycle number. Start at 1
❯ retryCount


Integer
Yes
The field contains the number of retry of the billing cycle.  The initial attempt is 0 and all others retries will increase the count by 1.
❯ dateFirstAttempt



DateTime
No
The field contains the date of the first transaction attempt for this billing cycle. The date is required when the retry count is greater than 1.  UTC and date format(Iso 8601)  YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.45+01:00)
❯ referenceData



String (512)
No
Reference data received from the gateway when a payment failed.  Return this data on retry transaction for the same payment.
❯ disableCustomerRecovery
boolean
No
Default value is false and it’s usually turned to true in case of a new sale
❯ customVariable1


String (50)
No
Optional user defined string value.
❯ customVariable2


String (50)
No
Optional user defined string value.
❯ customVariable3


String (50)
No
Optional user defined string value.
❯ customVariable4


String (50)
No
Optional user defined string value.
❯ customVariable5


String (50)
No
Optional user defined string value.


❯ References


Reference elements
❯❯ PreviousTransaction


Element relation to previous transaction details
❯❯❯ merchantAccountReferenceId
String (512)
See note
Required if gatewayCode, gatewayMessage or transactionDate provided.
> Gateway identified at the CRM level

❯❯❯ gatewayCode
String (50)
No
Gateway code returned for previous transaction
❯❯❯ gatewayMessage
String (256)
No
Gateway messaged returned for previous transaction
❯❯❯ transactionDate
DateTime (ISO 8601)
No
Required if gatewayCode or gatewayMessage is set.

The date of the previous transaction



Response Body

Notable response elements include:

Element
Type
Description
transaction

Transaction Core object element. See the description below.





Pass-in Payment Gateway Method

For subscription systems that have the cards stored in the vault of other payment gateways, it is now possible to pass the 3rd party payment method token. It becomes possible not to pass credit card number and cvv and do transactions for payment methods which do not exist in the Flexpay system.



POST /v1/gateways/charge

Request Body


Element
Type
Required
Description
transaction


Root element
❯ merchantTransactionId
String (256)
Yes
This field is your unique ID number associated with each transaction request. You create this value and submit it with the transaction.
❯ orderId
String (50)
Yes
Merchant-assigned order identification number.
❯ description
String (255)
No
Describe the transaction to help reconciliation
❯ customerId
String (50)
No
Merchant-defined, unique identifier to represent the customer associated with the transaction. Required if the email is not provided. Otherwise, a new customer id is created and return.
❯ currencyCode
String (3)
Yes
Three-digit currency code (e.g. USD, CAD). ISO 4217 Currency Codes
❯ amount
Integer
Yes
Amount in cents (e.g. 1957 is equivalent to 19.57)
❯ paymentMethod
String (22)
Yes
Element
❯❯gatewayPaymentMethodId
String (256)
Optional,required if credit Card Number not passed
3rd party token that identifies a payment method stored in other vaults


❯❯merchantAccountReferenceId
String (512)
Optional, required if gateway PaymentMethodId passed
Gateway identifier at the CRM level.
❯❯ firstSixDigits
String (6)
Optional, required if gateway PaymentMethodId passed
First six digits of the paymentmethod stored in the 3rd partyvault.
❯❯ lastFourDigits
String (4)
Optional, required if gateway PaymentMethodId passed
Last four digits of the payment method stored in the 3rd party vault.
❯❯ firstName
String (50)
Yes
Contains the first name of the customer associated with the billing address for the transaction.
❯❯ lastName
String (50)
Yes
Contains the last name of the customer associated with the billing address for the transaction.
❯❯ fullName
String (100)
Yes
The full name of the cardholder.If provided, will be parsed to determine first Name and last Name.either full Name or both first Name and last Name are required
❯❯ address1
String (255)
No
Contains the address line 1 of the customer associated with the billing address for the transaction.
❯❯ address2
String (255)
No
Contains the address line 2 of the customer associated with the billing address for the transaction.
❯❯ postalCode
String (100)
Yes
Contains the postal code (ZIP code if in the US) of the customer associated with the billing address for the transaction.
❯❯ city
String (100)
Yes
The field contains the city of the customer associated with the billing address for the transaction


❯❯ state
String (100)
Yes
The field contains the state of the customer associated with the billing address for the transaction. Any valid two characters’ state code or full state name
❯❯ country
String (50)
No
The field contains the country of the customer associated with the shipping address for the transaction. Three-letter, Two letter or name of the country defined in ISO 3166-1
❯❯ email
String (100)
No
Cardholder's email address.
❯❯ phoneNumber


Cardholder's phone number
❯ customerIp
String (15)
No
IP address of the customer initiating the transaction. The required format is 255.255.255.255.
❯ shippingAddress



❯❯ address1
String (255)
No
Contains the address line 1 of the customer associated with the shipping address for the transaction.
❯❯ address2
String (255)
No
Contains the address line 2 of the customer associated with the shipping address for the transaction.
❯❯ postalCode
String (100)
No
Contains the postal code (ZIP code if in the US) of the customer associated with the shipping address for the transaction.
❯❯ city
String (100)
No
The field contains the city of the customer associated with the shipping address for the transaction.


❯❯ state
String (100)
No
The field contains the state of the customer associated with the shipping address for the transaction. Any valid two characters’ state code or full state name.
❯❯ country
String (50)
No
The field contains the country of the customer associated with the shipping address for the transaction. Three-letter, Two letter or name of the country defined in ISO 3166-1
❯ assignedGatewayToken
String (50)
No
This field is the gateway associated with a merchant account against which the request will be made on a next attempt.
❯ paymentPlan


Element related to a recurring payment
❯❯ sku
String (150)
No
The field contains the unique product identifier (SKU).
❯❯ category
String (150)
No
Contains the primary category code associated with the product.
❯❯ billingPlan
String (50)
No
Contains the code associated with the billing plan.
❯❯ billingCycle
Integer
No
When the transaction is for a recurring payment, the field contains billing cycle number.Start at 1
❯ retryCount
Integer
Yes
The field contains the number of retry of the billing cycle. The initial attempt is 0 and all others retries will increase the count by 1.
❯ dateFirstAttempt
DateTime
No
The field contains the date of the first transaction attempt for this billing cycle. The date is required when the retry count is greater than 1. UTC and date format(Iso 8601) YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.45+01:00)


❯ referenceData
String (512)
No
Reference data received from the gateway when a payment failed.Return this data on retry transaction for the same payment
❯ disableCustomerRecovery
boolean
No
Default value is false and it’s usually turned to true in case of anew sale
❯ customVariable1
String (50)
No
Optional user defined string value
❯ customVariable2
String (50)
No
Optional user defined string value.
❯ customVariable3
String (50)
No
Optional user defined string value.
❯ customVariable4
String (50)
No
Optional user defined string value.
❯ customVariable5
String (50)
No
Optional user defined string value.
❯ References


Reference elements
❯❯ PreviousTransaction


Element relation to previous transaction details
❯❯❯merchantAccountReferenceId
String (512)
See note
Required if gatewayCode,gatewayMessage ortransactionDate provided.> Gateway identified at the CRM level.


❯❯❯ gatewayCode
String (50)
No
Gateway code returned for previous transaction.
❯❯❯ gatewayMessage
String (256)
No
Gateway messaged returned for previous transaction.
❯❯❯ transactionDate
DateTime (ISO8601)
No
Required if gatewayCode or gatewayMessage is set. The date of the previous transaction.


Response Body

Notable response elements include:

ElementTypeDescription
transaction

Transaction Core object element. See the description below.





Authorize

Tokenized payment method

Pass an authorize request using a payment method stored in the vault.



POST /v1/gateways/authorize

Request Body

Element
Type
Required
Description
transaction


Root element
❯ merchantTransactionId
String (256)
Yes
This field is your unique ID number associated with each transaction request.  You create this value and submit it with the transaction.
❯ orderId



String (50)
Yes
Merchant-assigned order identification number.
❯ description



String (255)
No
Describe the transaction to help reconciliation.
❯ customerId


String (50)
No
Merchant-defined, unique identifier to represent the customer associated with the transaction.  Required if the email is not provided. Otherwise, a new customer id is created and return.
❯ currencyCode



String (3)
Yes
Three-digit currency code (e.g. USD, CAD).   ISO 4217 Currency Codes
❯ amount



Integer
Yes
Amount in cents (e.g. 1957 is equivalent to 19.57)
❯ paymentMethodId
String(50)
Yes
The id of the payment method in vault.
❯ customerIp



String (15)
No
IP address of the customer initiating the transaction. The required format is 255.255.255.255.
❯ shippingAddress



❯❯ address1



String (255)
No
Contains the address line 1 of the customer associated with the shipping address for the transaction.
❯❯ address2



String (255)
No
Contains the address line 2 of the customer associated with the shipping address for the transaction.
❯❯ postalCode



String (100)
No
Contains the postal code (ZIP code if in the US) of the customer associated with the shipping address for the transaction.
❯❯ city



String (100)
No
The field contains the city of the customer associated with the shipping address for the transaction.
❯❯ state



String (100)
No
The field contains the state of the customer associated with the shipping address for the transaction. Any valid two characters’ state code or full state name.
❯❯ country



String (50)
No
The field contains the country of the customer associated with the shipping address for the transaction.  Three-letter, Two-letter or name of the country defined in ISO 3166-1
❯ assignedGatewayToken



String (50)
No
This field is the gateway associated with a merchant account against which the request will be made on a next attempt.
❯ paymentPlan


Element related to a recurring payment
❯❯ sku
String (150)
No
The field contains the unique product identifier (SKU).
❯❯ category
String (150)
No
Contains the primary category code associated with the product.
❯❯ billingPlan
String (50)
No
Contains the code associated with the billing plan.
❯❯ billingCycle
Integer
No
When the transaction is for a recurring payment, the field contains billing cycle number. Start at 1
❯ retryCount


Integer
Yes
The field contains the number of retry of the billing cycle.  The initial attempt is 0 and all others retries will increase the count by 1.
❯ dateFirstAttempt



DateTime
No
The field contains the date of the first transaction attempt for this billing cycle. The date is required when the retry count is greater than 1.  UTC and date format(Iso 8601)  YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.45+01:00)
❯ referenceData



String (512)
No
Reference data received from the gateway when a payment failed.  Return this data on retry transaction for the same payment.
❯ disableCustomerRecovery
boolean
No
Default value is false and it’s usually turned to true in case of a new sale
❯ customVariable1


String (50)
No
Optional user defined string value.
❯ customVariable2


String (50)
No
Optional user defined string value.
❯ customVariable3


String (50)
No
Optional user defined string value.
❯ customVariable4


String (50)
No
Optional user defined string value.
❯ customVariable5


String (50)
No
Optional user defined string value.


❯ References

Reference elements
❯❯ PreviousTransaction

Element relation to previous transaction details
❯❯❯merchantAccountReferenceIdString (512)See noteRequired if gatewayCode,gatewayMessage or transactionDate provided.> Gateway identified at the CRM level.
❯❯❯ gatewayCodeString (50)NoGateway code returned for previous transaction.
❯❯❯ gatewayMessageString (256)NoGateway messaged returned for previous transaction.
❯❯❯ transactionDateDateTime(ISO8601)NoRequired if gatewayCode or gatewayMessage is set. The date of the previous transaction.



Response Body

Notable response elements include:

Element
Type
Description
transaction

Transaction Core object element




Pass-in credit card

Pass a credit card payment method directly into for an authorize request. If the card is valid, it will automatically be tokenized if retain on success  = true, before sending to the gateway.



POST /v1/gateways/authorize

Request Body

Element
Type
Required
Description
transaction


Root element
❯ merchantTransactionId
String (256)
Yes
This field is your unique ID number associated with each transaction request.  You create this value and submit it with the transaction.
❯ orderId



String (50)
Yes
Merchant-assigned order identification number.
❯ description



String (255)
No
Describe the transaction to help reconciliation.
❯ customerId


String (50)
No
Merchant-defined, unique identifier to represent the customer associated with the transaction.  Required if the email is not provided. Otherwise, a new customer id is created and return.
❯ currencyCode



String (3)
Yes
Three-digit currency code (e.g. USD, CAD).   ISO 4217 Currency Codes
❯ amount



Integer
Yes
Amount in cents (e.g. 1957 is equivalent to 19.57)
❯ retainOnSuccess
Boolean
Yes
Retain payment method in vault if transaction is successful.
❯ paymentMethod


Element
❯❯ creditCardNumber



String (22)
Yes
This field is the card number you are charging for this transaction.
❯❯ expiryMonth



String (2)
Yes
Card expiry month expressed as MM (e.g. 06 for June)
❯❯ expiryYear



String (4)
Yes
Card expiry year expressed as YYYY (e.g. 2017)
❯❯ cvv



String (4)
No
This is the 3- or 4-digit security code that appears on the back of the card of a credit card following the card number.  This code does not appear on imprints.
❯❯ firstName



String (50)
Yes
This field contains the first name of the customer associated with the billing address for the transaction.
❯❯ lastName



String (50)
Yes
This field contains the last name of the customer associated with the billing address for the transaction.
❯❯ fullName
String (100)
No
The full name of the cardholder.
❯❯ address1



String (255)
Yes
Contains the address line 1 of the customer associated with the billing address for the transaction.
❯❯ address2



String (255)
No
Contains the address line 2 of the customer associated with the billing address for the transaction.
❯❯ postalCode



String (100)
Yes
Contains the postal code (ZIP code if in the US) of the customer associated with the billing address for the transaction.
❯❯ city



String (100)
Yes
The field contains the city of the customer associated with the billing address for the transaction.
❯❯ state



String (100)
Yes
The field contains the state of the customer associated with the billing address for the transaction. Any valid two characters’ state code or full state name.
❯❯ country



String (3)
Yes
The field contains the country of the customer associated with the billing address for the transaction.  Three-letter country codes defined in ISO 3166-1
❯❯ email
String (100)
No
Cardholder's email address.
❯❯ phoneNumber
String (100)
No
Cardholder's phone number.
❯ customerIp



String (15)
No
IP address of the customer initiating the transaction. The required format is 255.255.255.255.
❯ shippingAddress



❯❯ address1



String (255)
No
Contains the address line 1 of the customer associated with the shipping address for the transaction.
❯❯ address2



String (255)
No
Contains the address line 2 of the customer associated with the shipping address for the transaction.
❯❯ postalCode



String (100)
No
Contains the postal code (ZIP code if in the US) of the customer associated with the shipping address for the transaction.
❯❯ city



String (100)
No
The field contains the city of the customer associated with the shipping address for the transaction.
❯❯ state



String (100)
No
The field contains the state of the customer associated with the shipping address for the transaction. Any valid two characters’ state code or full state name.
❯❯ country



String (50)
No
The field contains the country of the customer associated with the shipping address for the transaction.  Three-letter, Two-letter or name of the country defined in ISO 3166-1
❯ assignedGatewayToken



String (50)
No
This field is the gateway associated with a merchant account against which the request will be made on a next attempt.
❯ paymentPlan


Element related to a recurring payment
❯❯ sku
String (150)
No
The field contains the unique product identifier (SKU).
❯❯ category
String (150)
No
Contains the primary category code associated with the product.
❯❯ billingPlan
String (50)
No
Contains the code associated with the billing plan.
❯❯ billingCycle
Integer
No
When the transaction is for a recurring payment, the field contains billing cycle number. Start at 1
❯ retryCount


Integer
Yes
The field contains the number of retry of the billing cycle.  The initial attempt is 0 and all others retries will increase the count by 1.
❯ dateFirstAttempt



DateTime
No
The field contains the date of the first transaction attempt for this billing cycle. The date is required when the retry count is greater than 1.  UTC and date format(Iso 8601)  YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.45+01:00)
❯ referenceData



String (512)
No
Reference data received from the gateway when a payment failed.  Return this data on retry transaction for the same payment.
❯ disableCustomerRecovery
boolean
No
Default value is false and it’s usually turned to true in case of a new sale
❯ customVariable1


String (50)
No
Optional user defined string value.
❯ customVariable2


String (50)
No
Optional user defined string value.
❯ customVariable3


String (50)
No
Optional user defined string value.
❯ customVariable4


String (50)
No
Optional user defined string value.
❯ customVariable5


String (50)
No
Optional user defined string value.


❯ References

Reference elements
❯❯ PreviousTransaction

Element relation to previous transaction details
❯❯❯merchantAccountReferenceIdString (512)See noteRequired if gatewayCode,gatewayMessage or transactionDate provided.> Gateway identified at the CRM level.
❯❯❯ gatewayCodeString (50)NoGateway code returned for previous transaction.
❯❯❯ gatewayMessageString (256)NoGateway messaged returned for previous transaction.
❯❯❯ transactionDateDateTime (ISO8601)NoRequired if gatewayCode or gatewayMessage is set. The date of the previous transaction.




Third Party Token

Third party token payment method uses external third party tokens directly into the charge request.


POST /v1/gateways/authorize

Request Body

ElementTypeRequiredDescription
transaction


Root element
❯ merchantTransactionId
String (256)
Yes
This field is your unique ID number associated with each transaction request. You create this value and submit it with the transaction.
❯ orderId
String (50)
Yes
Merchant-assigned order identification number.
❯ description
String (255)
No
Describe the transaction to help reconciliation.
❯ customerId
String (50)
No
Merchant-defined,unique identifier to represent the customer associated with the transaction. Required if the email is not provided. Otherwise, a new customer id is created and return.
❯ currencyCode
String (3)
Yes
Three-digit currency code (e.g. USD, CAD). ISO4217 Currency Codes
❯ amount
Integer
Yes
Amount in cents(e.g. 1957 is equivalent to 19.57)
❯ retainOnSuccess
Boolean
Yes
Retain payment method in vault if transaction is successful.
❯ paymentMethod


Element


❯❯gatewayPaymentMethodId
String (256)
Optional,
required if
credit Card Number not passed
3rd party token that identifies a payment method stored in other vaults
❯❯merchantAccountReferenceId
String (512)
Optional,
required if gatewayPayment
MethodId passed
Gateway identifier at the CRM level.
❯❯ firstSixDigits
String (6)
Optional,
required if gatewayPayment
MethodId passed
First six digits of the payment method stored in the 3rd party vault.
❯❯ lastFourDigits
String (4)
Optional,
required if gatewayPayment
MethodId passed
Last four digits of the payment method stored in the 3rd party vault.
❯❯ firstName
String (50)
Yes
This field contains the first name of the customer associated with the billing address for the transaction.
❯❯ lastName
String(50)
Yes
This field contains the last name of the customer associated with the billing address for the transaction
❯❯ fullName
String (100)
No
The full name of the cardholder.
❯❯ address1
String (255)
Yes
Contains the address line 1 of the customer associated with the billing address for the transaction.
❯❯ address2
String (255)
No
Contains the address line 2 of the customer associated with the billing address for the transaction.
❯❯ postalCode
String (100)
Yes
Contains the postal code (ZIP code if in the US) of the customer associated with the billing address for the transaction.


❯❯ postalCode
String(100)
Yes
Contains the postal code (ZIP code if in the US) of the customer associated with the billing address for the transaction.
❯❯ city
String(100)
Yes
The field contains the city of the customer associated with the billing address for the transaction.
❯❯ state
String(100)
Yes
The field contains the state of the customer associated with the billing address for the transaction. Any valid two characters’ state code or full state name.
❯❯ country
String(3)
Yes
The field contains the country of the customer associated with the billing address for the transaction.Three-letter country codes defined in ISO 3166-1
❯❯ email
String(100)
No
Cardholder's email address
❯❯ phoneNumber
String(100)
No
Cardholder's phone number.
❯ customerIp
String(15)
No
IP address of the customer initiating the transaction. The required format is 255.255.255.255.
❯ shippingAddress



❯❯ address1
String(255)
No
Contains the address line 1 of the customer associated with the shipping address for the transaction.
❯❯ address2
String(255)
No
Contains the address line 2 of the customer associated with the shipping address for the transaction.


❯❯ postalCode
String(100)
No
Contains the postal code (ZIP code if in the US) of the customer associated with the shipping address for the transaction.
❯❯ city
❯❯ city
No
The field contains the city of the customer associated with the shipping address for the transaction.
❯❯ state
String(100)
No
The field contains the state of the customer associated with the shipping address for the transaction.Any valid two characters’ state code or full state name.
❯❯ country
String(50)
No
The field contains the country of the customer associated with the shipping address for the transaction.Three-letter, Two letter or name of the country defined in ISO 3166-1
❯ assignedGatewayToken
String(50)
No
This field is the gateway associated with a merchant account against which the request will be made on a next attempt.
❯ paymentPlan


Element related to a recurring payment
❯❯ sku
String(150)
No
The field contains the unique product identifier (SKU).
❯❯ category
String(150)
No
Contains the primary category code associated with the product.
❯❯ billingPlan
String(50)
No
Contains the code associated with the billing plan.
❯❯ billingCycle
Integer
No
When the transaction is for a recurring payment,the field contains billing cycle number. Start at 1


❯ retryCount
Integer
Yes
The field contains the number of retry of the billing cycle.The initial attempt is 0 and all others retries will increase the count by 1.
❯ dateFirstAttempt
DateTime
No
The field contains the date of the first transaction attempt for this billing cycle.The date is required when the retry count is greater than 1. UTC and date format(Iso 8601) YYYY-MM-DDThh:mm:ss.sTZD(eg 1997-07-16T19:20:30.45+01:00)
❯ referenceData
String(512)
No
Reference data received from the gateway when a payment failed.Return this data on retry transaction for the same payment.
❯disableCustomerRecovery
boolean
No
Default value is false and it’s usually turned to true in case of a new sale
❯ customVariable1
String(50)
No
Optional user defined string value.
❯ customVariable2
String(50)
No
Optional user defined string value.
❯ customVariable3
String(50)
No
Optional user defined string value.
❯ customVariable4
String(50)
No
Optional user defined string value.
❯ customVariable5
String(50)
No
Optional user defined string value.
❯ References


❯ References


❯❯ PreviousTransaction


Element relation to previous transaction details
❯❯❯merchantAccountReferenceId
String(512)
See note
Required if gatewayCode,gatewayMessage or transactionDate provided.> Gateway identified at the CRM level.
❯❯❯ gatewayCode
String(50)
No
Gateway code returned for previous transaction.
❯❯❯ gatewayMessage
String(256)
No
Gateway messaged returned for previous transaction.

❯❯❯ transactionDate
DateTime (ISO8601)
No
Required if gatewayCode orgatewayMessage is set.The date of the previous transaction.



Response Body

Notable response elements include:

Element
Type
Description
transaction

Transaction Core object element




Capture

Full amount

Capture all funds previously reserved via an authorize.



POST /v1/transactions/<transaction Id >/capture

URL Parameter

Parameter 
Required
Description
transactionId
Yes
The transaction id identifying the original authorize transaction



Request Body

Element
Type
Required
Description
transaction


Root element
❯ amount
Integer
No
Amount in cents (e.g. 1957 is equivalent to 19.57).

If this amount is not provided or is zero, the full amount will be charged. Any other value set in this field will be used to charge.
❯ merchantTransactionId
String (256)
Yes
This field is your unique ID number associated with each transaction request.  You create this value and submit it with the transaction.
❯ disableCustomerRecovery
boolean
No
Default value is false and it’s usually turned to true in case of a new sale



Response Body

Notable response elements include:

Element
Type
Description
transaction

Transaction Core object element



Void

Cancel an authorization transaction. This API call can also be used to cancel a capture/purchase transaction that hasn’t yet settled at the merchant account.



POST /v1/transactions/<transaction Id >/void

URL Parameter

Parameter
Required
Description
transactionId
Yes
The transaction id identifying the original authorize transaction



Request Body

Element
Type
Required
Description
transaction


Root element
❯ merchantTransactionId
String (256)
Yes
This field is your unique ID number associated with each transaction request.  You create this value and submit it with the transaction.
❯ disableCustomerRecovery
boolean
No
Default value is false and it’s usually turned to true in case of a new sale



Response Body

Notable response elements include:

Element
Type
Description
transaction

Transaction Core object element


Refund

Full amount

Refund the full amount of purchase.


POST /v1/transactions/< transactionId >/refund

URL Parameter

Parameter
Required
Description
transactionId
Yes
The transaction id identifying the original authorize transaction



Request Body

Element
Type
Required
Description
transaction


Root element
❯ merchantTransactionId
String (256)
Yes
This field is your unique ID number associated with each transaction request.  You create this value and submit it with the transaction.
❯ disableCustomerRecovery
boolean
No
Default value is false and it’s usually turned to true in case of a new sale



Response Body

Notable response elements include:

Element
Type
Description
transaction

Transaction Core object element




Partial Amount

Refund the partial amount of purchase.



POST /v1/transactions/< transactionId >/refund

URL Parameter

Parameter
Required
Description
transactionId
Yes
The transaction id identifying the original authorize transaction



Request Body

Element
Type
Required
Description
transaction


Root element
❯ merchantTransactionId
String (256)
Yes
This field is your unique ID number associated with each transaction request.  You create this value and submit it with the transaction.
❯ disableCustomerRecovery
boolean
No
Default value is false and it’s usually turned to true in case of a new sale
❯ amount


Integer
Yes
Amount in cents (e.g. 1957 is equivalent to 19.57). If 0 is passed, the full amount will be refunded



Response Body

Notable response elements include:

Element
Type
Description
transaction

Transaction Core object element




Response Core API objects

Transaction core object

Element
Type
Description
Transaction

Root element
❯ merchantTransactionId
String (256)
This data is typically used to reference transactions on the host systems and must display on any receipt presented to the customer.
This information is to be stored by the merchant.
❯ transactionStatus
Integer
Indicates the result of the transaction: 1 = Approved, 2 = Declined, 3 = Error
❯ responseCode


String (6)
Transaction Response Code
❯ message
String (500)
Response description returned from issuing institution. This message should not display on any cardholder facing materials
❯ transactionId
String (50)
The transaction ID uniquely identifying the transaction at FlexPay
❯ transactionDate
DateTime
Processing host date stamp.
❯ response


❯❯ avsCode
String (1)
Indicates the address verification result code
❯❯ avsMessage
String (250)
Indicates the address verification result message
❯❯ cvvCode
String (15)
Indicates the CVV verification result code
❯❯ cvvMessage
String (250)
Indicates the CVV verification result message
❯❯ errorCode
String (15)
Indicates the error code
❯❯ errorDetail
String (250)
Indicates the error details
❯ currencyCode



String (3)
Three-digit currency code (e.g. USD, CAD).   ISO 4217 Currency Codes
❯ amount



Integer
Amount in cents (e.g. 1957 is equivalent to 19.57)
❯ gatewayToken



String (50)
This field is the gateway associated with a merchant account against which the request is made.
❯ gatewayType
String (50)
Code to identify on witch gateway the transaction has been attempt (e.g. Vantiv)
❯ gatewayTransactionId


String (50)
Gateway transaction ID -- Gateway return Transaction ID
❯ merchantAccountReferenceId
String (50)
Reference the merchant account used for the transaction
❯ customerId


String (50)
Merchant-defined, unique identifier to represent the customer associated with the transaction.  Required if the email is not provided. Otherwise, a new customer id is created and return.
❯ assignedGatewayToken
String (50)
This field is the gateway associated with a merchant account against which the request will be made on a next attempt.
❯ orderId



String (50)
Return the merchant-assigned order identification number from the request.
❯ retryDate


DateTime
Indicates the date and time when the transaction should be retried.
❯ retryCount


Integer
The field contains the number of retry of the billing cycle.  The initial attempt is 0 and all others retries will increase the count by 1.
❯ dateFirstAttempt


DateTime
The field contains the date of the first transaction attempt for this billing cycle. Date Format Iso 8601 and is UTC
❯ paymentMethod
element
Payment Method core object element
❯❯gatewayPaymentMethodID
string (256)
3rd party token that identifies a payment method stored in other vaults
❯❯merchantAccountReferenceId
string (512)
optional, required if gatewayPaymentMethodId is provided.
Gateway identified within CRM and FlexPay (must be identical in both)
❯❯firstSixDigit
string (6)
First six digits of the payment method stored in the 3rd party vault
❯❯lastfourDigit
string (4)
Last four digits of the payment method stored in the 3rd party vault
❯ customerIp
String (15)
IP address of the customer initiating the transaction. The required format is 255.255.255.255.


❯ shippingAddress
element
Shipping address core object element
❯ referenceData



String (512)
Reference data received from the gateway when a payment failed.  Return this data on retry transaction for the same payment.


❯ description



String (255)
Describe the transaction to help reconciliation.
❯ disableCustomerRecovery
boolean
Default value is false and it’s usually turned to true in case of a new sale


❯ customVariable1


String (50)
Optional user defined string value.
❯ customVariable2


String (50)
Optional user defined string value.
❯ customVariable3


String (50)
Optional user defined string value.
❯ customVariable4


String (50)
Optional user defined string value.
❯ customVariable5


String (50)
Optional user defined string value.
❯ References


Reference elements
❯❯ PreviousTransaction


Element relation to previous transaction details
❯❯❯ merchantAccountReferenceId
String (512)
See note
Required if gatewayCode, gatewayMessage or transactionDate provided.
> Gateway identified at the CRM level
❯❯❯ gatewayCode
String (50)
No
Gateway code returned for previous transaction
❯❯❯ gatewayMessage
String (256)
No
Gateway messaged returned for previous transaction.
❯❯❯ transactionDate
DateTime (ISO 8601)
No
Required if gatewayCode or gatewayMessage is set.
The date of the previous transaction.



Payment Method core object

Element
Type
Description
paymentMethodId
String (50)
The identifier of the payment method
creditCardNumber
String (22)
The card number of the transaction
expiryMonth
String (2)
Card expiry month expressed as MM (e.g. 06 for June)
expiryYear
String (4)
Card expiry year expressed as YYYY (e.g. 2017)
cvv
String(4)
This is the 3- or 4-digit security code that appears on the back of the card of a credit card following the card number.  This code does not appear on imprints.
gatewayPayment
 MethodId
String (256)3rd party token that identifies a payment method stored in other vaults
merchantAccount
 ReferenceId
merchantAccount
 ReferenceId
merchantAccount
 ReferenceId
firstSixDigitsString (6)First six digits of the payment method stored in the 3rd party vault
lastFourDigitslastFourDigitsLast four digits of the payment method stored in the 3rd party vault
firstName
String (50)
This field contains the first name of the customer associated with the billing address for the transaction.
lastName
String (50)
This field contains the last name of the customer associated with the billing address for the transaction.
fullName
String (101)
The full name of the cardholder.
customerId
String (50)
The token of the parent customer
address1
String (255)
Contains the address line 1 of the customer associated with the billing address for the transaction.
address2
String (255)
Contains the address line 2 of the customer associated with the billing address for the transaction.
postalCode
String (100)
Contains the postal code (ZIP code if in the US) of the customer associated with the billing address for the transaction.
city
String (100)
The field contains the city of the customer associated with the billing address for the transaction.
state
String (100)
The field contains the state of the customer associated with the billing address for the transaction. Any valid two characters’ state code or full state name.
country
String (3)
The field contains the country of the customer associated with the billing address for the transaction.  Three-letter country codes defined in ISO 3166-1
email
String (100)
Cardholder's email address.
phoneNumber
String (100)
Cardholder's phone number.
paymentMethodType
String (100)
The payment method type : “CreditCard”
fingerprint
String (100)
A value that uniquely identifies a payment method number.
lastFourDigits
String (4)
The last four digits of the credit card number.
firstSixDigits
String (6)
The first six digits of the credit card number.
cardType
String (50)
The brand identifier of the credit card.
Brand
Identifier
Visa
VISA
MasterCard
MASTERCARD
American Express
AMERICAN EXPRESS
Discover
DISCOVER
JCB
JCB
Diners Club
DINERS CLUB INTERNATIONAL
 




Shipping Address core object

Element
Type
Description
address1



String (255)
Contains the address line 1 of the customer associated with the shipping address for the transaction.
address2



String (255)
Contains the address line 2 of the customer associated with the shipping address for the transaction.
postalCode



String (100)
Contains the postal code (ZIP code if in the US) of the customer associated with the shipping address for the transaction.
city



String (100)
The field contains the city of the customer associated with the shipping address for the transaction.
state



String (100)
The field contains the state of the customer associated with the shipping address for the transaction. Any valid two characters’ state code or full state name.
country



String (3)
The field contains the country of the customer associated with the shipping address for the transaction.  Three-letter country codes defined in ISO 3166-1




Order and Pagination

Order

Ordered responses are sorted by the dateCreated attribute, oldest first. In the case where multiple timestamps are the same, those records are then sorted alphabetically on the token attribute to give a consistent ordering.

Use the order parameter to reverse the list order to most recent first. Here is an example of sorting transactions in descending order.



GET /v1/transactions?order=desc

URL Parameter

Element
Description
order
The order of the returned list. The default is asc, which returns the oldest records first. To list newer records first, use desc.




Pagination

By default, unbounded lists are returned in groups of 20 items. If there are more than 20 items in the list, use pagination to retrieve the next set of 20.

To enforce determinism in a real-time system, pagination is indexed based on a specific record (as opposed to just a page number as is common in many web apps). To paginate to the next page, simply pass in the token of the last record in the current result set.

For instance, if the token of the last gateway in the initial set of twenty transactions returned is JZE57KX6PMSU7MZLAFNIBQWJEQ, use that as the sinceToken parameter to get the next set of 20 starting after that gateway.



GET /v1/transactions?sinceToken=<transactionId>

URL Parameter

Element
Description
sinceToken
The token of the item to start from (e.g., the last token received on the previous page if iterating through records)



Response Codes

An API call’s HTTP response code can indicate an error state or some other degradation of service. See the following response codes and corresponding response bodies for common causes.


API response

CODE
DESCRIPTION
400
Bad request. The request, as submitted, is not valid. The request should not be retried.
401
Unauthorized. No HTTP basic authentication was specified or API key is invalid
404
Not found. The requested item was not found. The request should not be retried.
500
Internal Server Error. FlexPay experienced an error processing the request.











Transaction Response

Fields
Code Range
Description
Approved
10000
The request was successful.
Soft Decline
20000
The request declined, though subsequent attempts may be successful.
Hard Decline


30000
The request declined. Most hard declines require the Issuer or Cardholder to rectify the outstanding issue(s) before a subsequent attempt can be made.
Risk Responses
40000
The request triggered a risk response. The status of the response (responseCode and status) will depend on the action specified in your risk settings on your gateway.
API Validation
50000
The request failed API validation and was not successful due to the error

















Approved

CODE
Description
10000
Approved
10001
The reversal was processed successfully.








Soft Decline

CODE
DESCRIPTION
20000
You need to refer to the Card Issuer
20002
Invalid or inactive merchant
20003
Declined - do not honor
20012
Re-enter transaction or transaction has been expired
20013
Invalid response
20018
Completed Partially
20022
Bank decline
20023
The card has been declined due to insufficient funds.
20039
Response timeout
20043
Transaction cannot be completed
20046
System error
20047
Other / Unidentified responses
20048
Unable to authorize
20050
Over daily limit
20056
Customer token/Id is incorrect or invalid
20057
Your merchant account authentication failed
20068
Invalid API access token
20073
Batch data is missing or Invalid
20075
Transaction limit for merchant exceeded
20076
Transaction required data are missing or invalid
20077
RETRY -  Not a credit account
20078
RETRY -  Not a cheque account
20079
RETRY -  Not a savings account
20080
RETRY -  Expired card
20081
RETRY -  Limit exceeded. Enter a lesser value.
20082
RETRY -  Invalid transaction date
20083
RETRY -  Invalid expiry date format
20084
RETRY -  You submitted an unsupported card type with your request.
20085
RETRY -  Gateway declined - Invalid transaction
20086
RETRY -  Billing address is missing
20087
RETRY -  Gateway declined - Blacklist transaction cannot be processed
20088
RETRY -  Gateway declined - Postal code failed The card’s postal code failed validation.
20089
RETRY -  Gateway declined - Missing required data. Please make sure all required data is sent, such as: CVV, Expiry date, Cardholder name, Billing address, Postalcode etc.
20090
RETRY -  Declined - AVS(Address) not matched the transaction payment method.
20091
RETRY -  Mismatch - Shipping to billing shipping country does not match billing country.
20092
RETRY -  Mismatch - Shipping to BIN shipping country does not match bin country.
20093
RETRY -  Mismatch - Shipping to IP shipping country does not match IP country.
20094
RETRY -  Mismatch - Billing to BIN billing country does not match bin country.
20095
RETRY -  Mismatch - Billing to IP billing country does not match IP country.
20096
RETRY -  Mismatch - BIN to IP BIN country does not match IP country.
20097
RETRY -  Gateway declined - Card number is blacklisted
20098
RETRY -  Gateway declined - IP address is blacklisted
20099
RETRY -  Gateway declined - Email is blacklisted
20100
RETRY -  Gateway declined - Phone number is Blacklisted
20101
RETRY -  The bank has requested that you retrieve the card from the cardholder - validate with the bank.
20102
RETRY -  Expired Card - Pick Up
20103
RETRY - Invalid card number
20104    
RETRY - No gateways are configured to process the submitted card type
































































































Hard Decline

CODE
DESCRIPTION
30000
The bank has requested that you retrieve the card from the cardholder - validate with the bank.
30001
The bank has requested that you retrieve the card from the cardholder - it may be a lost or stolen card.
30002
Invalid card: Luhn algorithm failed (MOD - 10)
30003
Expired Card - Pick Up
30004
Suspected Fraud - Pick Up
30006
Restricted Card - Pick Up
30008
The bank has requested that you retrieve the card from the cardholder - it may be a lost card.
30009
The bank has requested that you retrieve the card from the cardholder - it may be a stolen card.
30010
The void request failed.
30011
Invalid transaction
30012
Invalid card number
30013
The reversal request failed.
30015
The external gateway has reported that you have submitted an invalid amount with your request.
30016
Error / Invalid parameters in the request
30017
Format Error
30019
Not a credit account
30024
Not a cheque account
30025
Not a savings account
30026
Expired card
30029
Transaction not permitted to that cardholder
30031
Suspected fraud
30034
Restricted card
30044
Duplicate transaction
30049
Decline for CVV2 failure
30051
Limit exceeded. Enter a lesser value.
30052
Invalid transaction date
30053
Card not supported
30055
Invalid expiry date format
30058
You submitted an unsupported card type with your request.
30059
Gateway declined - Invalid transaction
30061
The external gateway has reported that you have submitted an invalid currency with your request.
30062
Billing address is missing
30064
Authorisation already reversed (voided) or capture is larger than initial authorised value.
30065
Authorization is completed.
30066
Transaction already reversed
30071
Invalid API version
30074
Invalid customer/user
30077
This processor does not accept partial reversals.
30078
Original transaction for reversal not found.
30079
This transaction has already been captured.
30080
DO NOT RETRY - You need to refer to the Card Issuer
30081
DO NOT RETRY - Invalid or inactive merchant
30082
DO NOT RETRY - Do not honor
30083
DO NOT RETRY -  Re-enter transaction or transaction has been expired
30084
DO NOT RETRY -  Invalid response
30085
DO NOT RETRY -  Completed partially
30086
DO NOT RETRY -  Bank decline
30087
DO NOT RETRY -  The card has been declined due to insufficient funds
30088
DO NOT RETRY -  Response timeout
30089
DO NOT RETRY -  Transaction cannot be completed
30090
DO NOT RETRY -  System error
30091
DO NOT RETRY -  Other / Unidentified responses
30092
DO NOT RETRY -  Over daily limit
30093
DO NOT RETRY - Customer token/Id is incorrect or invalid
30094
DO NOT RETRY - Customer token/Id is incorrect or invalid
30095
DO NOT RETRY - Your merchant account authentication failed
30096
DO NOT RETRY - Invalid API access token
30097
DO NOT RETRY - Batch data is missing or Invalid
30098
DO NOT RETRY - Transaction limit for merchant exceeded
30099
DO NOT RETRY - Transaction required data are missing or invalid
30100
DO NOT RETRY - Retry limit reached

















































































































Risk Responses

CODE 
DESCRIPTION
40000
Risk Blocked Transaction refused due to risk model
40002
Gateway declined - Blacklist transaction cannot be processed
40003
Gateway declined - CVV is missing or incorrect. The merchant’s configuration requires a CVV to be entered, but no CVV was provided with this transaction or CVV is incorrect.
40004
Gateway declined - Postal code failed The card’s postal code failed validation.
40005
Gateway declined - Missing required data. Please make sure all required data is sent, such as: CVV, Expiry date, Cardholder name, Billing address, Postalcode etc.
40006
Declined – AVS (Address) not matched the transaction payment method.
40007
Mismatch - Shipping to billing shipping country does not match billing country.
40008
Mismatch - Shipping to BIN shipping country does not match bin country.
40009
Mismatch - Shipping to IP shipping country does not match IP country.
40010
Mismatch - Billing to BIN billing country does not match bin country.
40011
Mismatch - Billing to IP billing country does not match IP country.
40012
Mismatch - BIN to IP BIN country does not match IP country.
40030
Gateway declined - Card number is blacklisted
40031
Gateway declined - IP address is blacklisted
40032
Gateway declined - Email is blacklisted
40033
Gateway declined - Phone number is Blacklisted







































Validation Responses

CODE
DESCRIPTION
50000
Validation error
50002
An error was experienced while parsing the payload. Please ensure that the structure is correct.
50003
No parameters were found
50005
Authorization has been denied for this request.
50014
Invalid 'CustomerToken' length
50015
Invalid 'Email' length              
50020
Invalid 'PhoneNumber' length    
50028
Invalid 'FullName' length
50029
Invalid 'ProvinceStateCode' length
50037
Invalid 'CustomerIp' length    
50039
Invalid value for 'CountryCode'
50045
Field 'CurrencyCode' is required
50048
Field 'CustomerToken' or 'email' are required
50055
Field 'Month' is required
50056
Invalid value for 'Month'
50057
Field 'Year' is required
50058
Invalid value for 'Year'
50059
Field 'CreditCardNumber' is required
50060
Invalid 'CreditCardNumber' Length
50068
Invalid 'MerchantDescriptor' length    
50073
Invalid 'CurrencyCode' length
50088
Field 'FirstName' is required
50089
Field 'LastName' is required
50090
Fields 'FullName' or 'FirstName' and 'LastName' are required
50091
Invalid 'FirstName' length
50092
Invalid 'LastName' length
50093
Field 'CountryCode' is required
50094
Field 'PostalCode' is required
50095
Invalid 'PostalCode' length
50096
Field 'ProvinceStateCode' is required
50097
Field 'City' is required
50098
Invalid 'City' length
50099
Field 'Address1' is required
50100
Invalid 'Address1' length
50103
Field 'MerchantTransactionReferenceId' is required                    
50104
Invalid 'MerchantTransactionReferenceId' length                    
50105
Invalid 'TransactionType'                        
50106
Invalid 'CustomField1' length                    
50107
Invalid 'CustomField2' length                    
50108
Invalid 'CustomField3' length                    
50109
Invalid 'CustomField4' length                    
50110
Invalid 'CustomField5' length                    
50111
Invalid 'ReferenceData' length                    
50112
Invalid 'ShippingPhoneNumber' length                    
50113
Invalid 'ShippingCountryCode' length                    
50114
Invalid 'ShippingPostalCode' length                    
50115
Invalid 'ShippingProvinceStateCode' length                    
50116
Invalid 'ShippingCity' length                    
50117
Invalid 'ShippingAddress2' length                    
50118
Invalid 'ShippingAddress1' length                    
50119
Invalid 'Address2' length                        
50120
Invalid 'BillingPlanCode' length                    
50121
Invalid 'ProductCategoryName' length                    
50122
Invalid 'ProductSku' length                      
50123
Invalid 'MerchantLocation' length                    
50124
Invalid 'Description' length                      
50125
invalid 'GatewayTransactionToken' length
50126
Field 'OrderId' is required
50127
Invalid 'OrderId' length
50128
Invalid 'GatewayToken' length
50129
Field 'MerchantTransactionReferenceId' must be unique
50130
No gateways are configured to process the submitted card type.
50131
Original transaction not found using the field ‘TransactionReferenceId'.
50132
Invalid value for 'ReferenceData'
50133
Field 'PaymentToken' is required
50134
Invalid value for 'PaymentToken'
50135
Fields 'PaymentToken' or 'PaymentMethod' values are required
50136
Invalid PaymentMethod values
50138
Missing value for 'gatewayPaymentMethodId'