/
Transactions Endpoints - POS API

Transactions Endpoints - POS API

These are all of the necessary endpoints required for Transactions (purchases, authorizations, captures, releases, returns).

POST /client-id/{client_id}/transactions

https://{posapi_url}/flexiti/pos-api/v2.5.1/client-id/{client_id}/transactions?lang=en

This service is the one used to post Deposits, In-Store Payments or Trade-Ins on the Customer Account.

You can post a transaction using one of the following: FlexitiCard number (VCC), Account number, or Customer ID.

Request Parameters:

Type

Parameter

Required

Details

Type

Parameter

Required

Details

HEADER

authorization

Yes

  • ASCII string (1000)

  • This is the word “Bearer” with a space and then the access_token given in oauth/token API response

  • Default value: Bearer {insert_bearer_token_from_oauth_here/token_api}

HEADER

x-reference-id

Yes

  • ASCII string (32)

  • GUID

  • Unique identifier for the flow for traceability purposes

HEADER

x-idempotency-key

No

  • ASCII string

  • When provided, this field will be used to identify a merchant-managed (and incremented) idempotency key. When provided, the endpoint will behave in idempotent manner. Should Flexiti receive multiple transactions with the same idempotency key, only the first one will be processed, while subsequent (duplicated) requests will return the previously successful response.

HEADER

x-context-hash

No

  • ASCII string

  • This header will only be meaningful when X-Idempotency-Key header is also provided. The context hash value should be generated by the merchant using the request body. When provided, this key acts as a safety mechanism to inform the merchants with proper warning that the request body has changed, if Flexiti receives two requests with the same Idempotency key but with different context hash.

PATH

client_id

Yes

  • ASCII string (100)

  • This is the Client ID given in the Developer User Account section

QUERY

lang



  • ASCII string (5)

  • Customer Preferred language

  • Available values: (en=English) or (fr=French)

  • Default value: en

BODY

transaction_type


Yes

  • ASCII string

  • This is the Transaction Type:

    • for Deposits, use "deposit”;

    • for In-Store Payments, use "instore_payment”;

    • for Trade-In, please use "tradein".

BODY

amount



  • number (18,2)

  • the Transaction Amount

  • this applies for all transaction types

BODY

vcc_number



  • number (16)

  • The Flexiti Card Number provided by the Customer

  • This is the FlexitiCard number (VCC)

BODY

account_number



  • number (14)

  • Flexiti Account Number retrieved from the /client-id/{client_id}/customers/lookup or the /client-id/{client_id}/customers/search endpoints

  • This is not the FlexitiCard number (VCC) or the Customer ID

BODY

customer_id



  • string (12)

  • Flexiti Customer ID

  • This is not the FlexitiCard number (VCC) or the Customer ID

BODY

verification_code

Yes

  • number (4)

  • Verification number provided in the Customer Verification service from the /account/{account_number}/verify endpoint

BODY

request_id

Yes for in-store channel

  • ASCII string (150)

  • This is the identifier for a verification to application/transaction/authorization flow.

BODY

external_location_id

Yes for in-store channel

  • ASCII string (100)

  • Used in the In-store channel

  • This is the merchant’s own location reference

BODY

external_employee_id

Yes for in-store channel

  • ASCII string (100)

  • Used in the In-store channel

  • This is the merchant’s own employee reference

Example Request:

Deposit

{ "verification_code": 1234, "transaction_type": "deposit", "amount": "10.00", "account_number": "20076677", "request_id": "34561234", //if in-store channel "external_location_id" : "00-12345", //if in-store channel "external_employee_id" :"12345-SMITH" //if in-store channel }

 

In-store Payment

{ "verification_code": 1234, "transaction_type": "instore_payment", "amount": "120.05", "account_number": "20076677", "request_id": "34561234", //if in-store channel "external_location_id" : "00-12345", //if in-store channel "external_employee_id" :"12345-SMITH" //if in-store channel }

 

Trade-In

{ "verification_code": 1234, "validation": 390903, "transaction_type": "tradein", "amount": "120.05", "account_number": "20076677", "request_id": "34561234", //if in-store channel "external_location_id" : "00-12345", //if in-store channel "external_employee_id" :"12345-SMITH" //if in-store channel }

Success Response:

200 - Success - Deposit
{   "payment_protection": false,   "transaction_id": 167638,   "apr": 37.24,   "available_credit": 3528.93,   "term": "",   "admin_fee": 0,   "balance_after_purchase": 3528.88,   "payment_value": "0.05",   "promotional_amount": 0.05,   "air": 37.24,   "customer_confirmed": false,   "plan_id": 0,   "verified": true   }
200 - Success - In-Store payment & Trade-in
{   "transaction_id": "696952",   "customer_name": "John",   "customer_lname": "Smith",   "total_amount": "120.05000",   }

 

POST /client-id/{client-id}/authorization

https://{posapi_url}/flexiti/pos-api/v2.5.1/client-id/{client_id}/authorization

NOTE: the /authorization endpoint has been updated to version 2.5.1, reflected in the URI.

This endpoint to creates a credit authorization for a customer from a specific Merchant.

Credit authorizations could be for:

  • promotional purchases

  • regular purchase

Request Parameters:

Type

Parameter

Required

Details

Type

Parameter

Required

Details

HEADER

authorization

Yes

  • ASCII string (1000)

  • This is the word “Bearer” with a space and then the access_token given in oauth/token API response

  • Default value: Bearer {insert_bearer_token_from_oauth_here/token_api}

HEADER

x-reference-id

Yes

  • ASCII string (32)

  • GUID

  • Unique identifier for the flow for traceability purposes

HEADER

x-idempotency-key

No

  • ASCII string

  • When provided, this field will be used to identify a merchant-managed (and incremented) idempotency key. When provided, the endpoint will behave in idempotent manner. Should Flexiti receive multiple transactions with the same idempotency key, only the first one will be processed, while subsequent (duplicated) requests will return the previously successful response.

HEADER

x-context-hash

No

  • ASCII string

  • This header will only be meaningful when X-Idempotency-Key header is also provided. The context hash value should be generated by the merchant using the request body. When provided, this key acts as a safety mechanism to inform the merchants with proper warning that the request body has changed, if Flexiti receives two requests with the same Idempotency key but with different context hash.

PATH

client_id

Yes

  • ASCII string (100)

  • This is the Client ID given in the Developer User Account section

QUERY

lang



  • ASCII string (5)

  • Language the message and description parameters on the response will be displayed in

  • Available values: (en=English) or (fr=French)

  • Default value: en

BODY

account_number

Yes

  • number (14)

  • Flexiti Account Number retrieved from the /client-id/{client_id}/customers/lookup or the /client-id/{client_id}/customers/search endpoints

  • This is not the FlexitiCard number (VCC) or the Customer ID

BODY

vcc_number


No

  • ASCII string(16)

  • The Flexiti Card Number provided by the Customer

  • This is the FlexitiCard number (VCC)

  • To be used in a Business Card’s authorized User’s purchase, sent with the Master Account number

BODY

reference

No

  • ASCII String (40)

  • Merchant Order ID to be saved within the credit authorization

BODY

financing_option.transaction_type

Yes

  • ASCII String (20)

  • Type of transaction

  • Available values: promotional_purchase, regular_purchase

BODY

financing_option.plan_id

Yes for transaction_type = promotional_purchase

  • number (3)

  • Only applicable to Promotional Purchases

  • Plan ID

BODY

financing_option.term


Yes for transaction_type = promotional_purchase

  • number (3)

  • Only applicable to Promotional Purchases

  • Term

BODY

amount


Yes

  • number (18,2)

  • the Transaction Amount

  • this applies for all transaction types

BODY

auto_capture

Yes

  • boolean

  • This determines if an actual authorization occurs or a purchase (autorization and capture at the same time)

BODY

verification_code

Yes for in-store POS integrations.

Not to be passed for Online implementations using the Widget

  • number (4)

  • Verification number provided in the Customer Verification service from the /account/{account_number}/verify endpoint

BODY

sku_data.purchase_order

No

  • ASCII string (10)

  • This data is provided by a Merchant. If passed as part of the request, it will be displayed on the customer’s statement. We do not validate this data and assume you are passing an accurate representation of the transactions details.

  • Purchase Number For the Merchant

BODY

sku_data.shipping_total

No

  • number (18,2)

  • This data is provided by a Merchant. If passed as part of the request, it will be displayed on the customer’s statement. We do not validate this data and assume you are passing an accurate representation of the transactions details.

  • the Shipping total amount to be displayed, if applicable

BODY

sku_data.register_id

No

  • ASCII string (50)

  • This data is provided by a Merchant. If passed as part of the request, it will be displayed on the customer’s statement. We do not validate this data and assume you are passing an accurate representation of the transactions details.

  • The cashier machine where the transaction was placed

BODY

sku_data.transaction_discount_total

No

  • Integer (12,2)

  • This data is provided by a Merchant. If passed as part of the request, it will be displayed on the customer’s statement. We do not validate this data and assume you are passing an accurate representation of the transactions details.

  • Sum of all discounts on the order

BODY

sku_data.transaction_subtotal

No

  • Integer (12,2)

  • This data is provided by a Merchant. If passed as part of the request, it will be displayed on the customer’s statement. We do not validate this data and assume you are passing an accurate representation of the transactions details.

  • Sum of all totals for all items

BODY

sku_data.gst_hst

No

  • Number (18,2)

  • This data is provided by a Merchant. If passed as part of the request, it will be displayed on the customer’s statement. We do not validate this data and assume you are passing an accurate representation of the transactions details.

  • Goods and Services Tax (GST) and the Harmonized Sales Tax (HST)

BODY

sku_data.pst

No

  • Number (18,2)

  • This data is provided by a Merchant. If passed as part of the request, it will be displayed on the customer’s statement. We do not validate this data and assume you are passing an accurate representation of the transactions details.

  • Provincial Sales Tax applied to the order

BODY

sku_data.transaction_total

No

  • Number (18,2)

  • This data is provided by a Merchant. If passed as part of the request, it will be displayed on the customer’s statement. We do not validate this data and assume you are passing an accurate representation of the transactions details.

  • transaction_total = transaction_subtotal + gst_hst + pst

BODY

sku_data.products.sku_id

No

  • ASCII string (150)

  • This data is provided by a Merchant. If passed as part of the request, it will be displayed on the customer’s statement. We do not validate this data and assume you are passing an accurate representation of the transactions details.

  • Unique Identifier of the product SKU (Stock Keeping Unit)

BODY

sku_data.products.category

No

  • ASCII string (30)

  • This data is provided by a Merchant. If passed as part of the request, it will be displayed on the customer’s statement. We do not validate this data and assume you are passing an accurate representation of the transactions details.

  • Category for the product

BODY

sku_data.products.description

No

  • ASCII string (150)

  • This data is provided by a Merchant. If passed as part of the request, it will be displayed on the customer’s statement. We do not validate this data and assume you are passing an accurate representation of the transactions details.

  • Business-friendly description of the product

BODY

sku_data.products.quantity

No

  • Number (5)

  • This data is provided by a Merchant. If passed as part of the request, it will be displayed on the customer’s statement. We do not validate this data and assume you are passing an accurate representation of the transactions details.

  • The quantity of the items for the SKU array

    • Positive integer for sales

    • Negative - integer for a return

BODY

sku_data.products.unit_price

No

  • Number (18,2)

  • This data is provided by a Merchant. If passed as part of the request, it will be displayed on the customer’s statement. We do not validate this data and assume you are passing an accurate representation of the transactions details.

  • The price for a single SKU item

BODY

sku_data.products.extended_price

No

  • Number (18,2)

  • This data is provided by a Merchant. If passed as part of the request, it will be displayed on the customer’s statement. We do not validate this data and assume you are passing an accurate representation of the transactions details.

  • extended_price = [(unit_price x quantity) - discount_price] for this particular SKU array

BODY

billing_information.first_name

Yes if Online Channel

  • ASCII string (80)

  • Information used to match/verify the Account details on file

  • Billing Address Customer’s First Name

BODY

billing_information.last_name

Yes if Online Channel

  • ASCII string (130)

  • Information used to match/verify the Account details on file

  • Billing Address Customer’s Last Name

BODY

billing_information.address_1

Yes if Online Channel

  • ASCII string (250)

  • Information used to match/verify the Account details on file

  • Billing Address Line 1

BODY

billing_information.address_2

Yes if Online Channel

  • ASCII string (100)

  • Information used to match/verify the Account details on file

  • Billing Address Line 2

BODY

billing_information.city

Yes if Online Channel

  • ASCII string (100)

  • Information used to match/verify the Account details on file

  • Billing address city

BODY

billing_information.province

Yes if Online Channel

  • ASCII string (2)

  • Information used to match/verify the Account details on file

  • Billing Address Province (2 character syntax, ex. ON for Ontario)

  • Available values: AB, BC, MB, NB, NL, NS, NT, NU, ON, PE, QC, SK, YT.

BODY

billing_information.postal_code

Yes if Online Channel

  • ASCII string (10)

  • Information used to match/verify the Account details on file

  • Billing Address Postal Code

BODY

shipping_information.first_name

Yes if Online Channel

  • ASCII string (80)

  • Information used to match/verify the Account details on file

  • Shipping Address Customer’s First Name

BODY

shipping_information.last_name

Yes if Online Channel

  • ASCII string (130)

  • Information used to match/verify the Account details on file

  • Shipping Address Customer’s Last Name

BODY

shipping_information.address_1

Yes if Online Channel

  • ASCII string (250)

  • Information used to match/verify the Account details on file

  • Shipping Address Line 1

BODY

shipping_information.address_2

Yes if Online Channel

  • ASCII string (100)

  • Information used to match/verify the Account details on file

  • Shipping Address Line 1

BODY

shipping_information.city

Yes if Online Channel

  • ASCII string (100)

  • Information used to match/verify the Account details on file

  • Shipping Address City

BODY

shipping_information.province

Yes if Online Channel

  • ASCII string (2)

  • Information used to match/verify the Account details on file

  • Shipping Address Province (2 character syntax, ex. ON for Ontario)

  • Available values: AB, BC, MB, NB, NL, NS, NT, NU, ON, PE, QC, SK, YT.

BODY

shipping_information.postal_code

Yes if Online Channel

  • ASCII string (10)

  • Information used to match/verify the Account details on file

  • Shipping Address Postal Code

BODY

widget_session_id

Yes if Online Channel

  • string (24)

  • Used in the Online channel

  • This widget unique session ID is inserted as part of the redirect_url of the POST /client-id/{clientId}/widget/init response.

  • It will be included on the events that are being triggered by the Widget.

BODY

request_id

Yes for in-store channel

  • ASCII string (150)

  • This is the identifier for a verification to application/transaction/authorization flow.

  • Ideally, this field’s value can uniquely identify each transaction

BODY

external_location_id

Yes for In-store channel

  • ASCII string (100)

  • Used in the In-store channel

  • This is the merchant’s own location reference

BODY

external_employee_id

Yes for In-store channel

  • ASCII string (100)

  • Used in the In-store channel

  • This is the merchant’s own employee reference

Example Request - Auto Capture with SKU items:

{ "vcc_number": "1234567890123456", "account_number": 1234567, "reference": "orderid-12345", "widget_session_id": "12345678901234567890", //if Online channel "request_id": "12345678901234567890", //if in-store channel "external_location_id" : "00-12345", //if in-store channel "external_employee_id" :"12345-SMITH" //if in-store channel "financing_option": { "transaction_type": "promotional_purchase", "plan_id": 5, "term": 6 }, "amount": 5000.12, "auto_capture": true, "verification_code": 9999, "billing_information": { "first_name": "John", "last_name": "Smith", "address_1": "1234 Main Street", "address_2": "", "city": "Toronto", "postal_code": "M1M1M1", "country": "CA", "province": "ON" }, "shipping_information": { "first_name": "John", "last_name": "Smith", "address_1": "1234 Main Street", "address_2": "", "city": "Toronto", "postal_code": "M1M1M1", "country": "CA", "province": "ON" }, "sku_data":{ { "purchase_order": "100001234", "register_id": "1A45", "transaction_discount_total": -125.08, "transaction_subtotal": 821.17, "transaction_total": 1026.47, "gst_hst": 133.45, "pst": 71.85, "products":[ { "sku_id": "100xx4567", "category": "electronics", "description": "Apple Macbook 16-inch", "quantity": 1, "unit_price": 1000, "extended_price": 984.35 }, { "sku_id": "20bb3457", "category": "office supplies", "description": "24lb Multiuse Paper, White", "quantity": 1, "unit_price": 33.99, "extended_price": 42.12 } ] }