Sale

Charge a credit card for a payment amount. You can also associate a customer profile with the sale and charge a stored credit card.

To encrypt your credit card information, use our Payfirma Card Encryption Javascript library to generate a secure and encrypted card token to be used with any of our transaction methods.

BASE URI

https://apigateway.payfirma.com/transaction-service

Create a sale

Request a credit card payment

HTTPS POST

/sale

Request Arguments

Request Arguments
amount REQUIRED	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
currency	Transaction currency, in currency type, e.g. USD, CAD.
card_expiry_month REQUIRED	The double-digit month the card expires, e.g. for August, use 08.
card_expiry_year REQUIRED	Expiry year - in double digits - of the associated credit card number, e.g. for 2017, use 17.
card_number REQUIRED	The credit card number (16 digits for most card brands and 15 digits for American Express).
cvv2 REQUIRED	A credit card’s verification code, otherwise known as CVC or CVV; the three or four-digit number on the back of most major cards, and the four digit number found on the front of American Express cards. We strongly recommend that you utilize the cvv2 field to help protect against fraud and charge-backs.
token	Secure and encrypted card token. You can use this instead of card_expiry_month, card_expiry_year, card_number and cvv2. If used with a credit card, 400 BAD_REQUEST is returned.
email	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name	The first name of the customer.
last_name	The customers last name.
company	Business name associated with customer.
bcc_emails	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone	Customer’s telephone number.
address1	First line of the customer address.
address2	Second line of the customer address.
city	The city where the customer is.
province	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country	The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
postal_code	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
custom_id	A description field to record any general customer identifying information.
invoice_id	An open description field to help with transaction tracking and reporting. If the Payfirma invoicing service is used, this number will be generated by the invoicing system.
sending_receipt	Whether or not a transaction will send a receipt to the customer email provided. Is set as true as the default option.

Response Attributes

Response Attributes
amount number	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
captured bolean	-
card_type string	The brand of the credit card, e.g. Visa, Mastercard, Amex
card_suffix number	The last 4 digits of the credit card.
id number	Internal ID representation.
transaction_success bolean	The boolean success response for each transaction.
transaction_result string	The success response for each transaction.
transaction_message string	Details on the transaction result.
transaction_time number	The UNIX time stamp that the transaction was processed, represented in milliseconds.
transaction_type string	Identifies what type of transaction request was made, e.g. sale, refund.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.
bcc_emails string	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone string	Customers telephone number.
address1 string	First line of the customer address.
address2 string	Second line of the customer address.
city string	The city where the customer is.
province string	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country string	The country where the customer is.
postal_code string	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
custom_id string	A description field to record any general customer identifying information.

Example Request:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"amount\": 10.99,
  \"currency\": \"CAD\",
  \"card_expiry_month\": 11,
  \"card_expiry_year\": 16,
  \"card_number\": \"4111111111111111\",
  \"cvv2\": 595,
}" \
"https://apigateway.payfirma.com/transaction-service/sale"

Example Request Body:

{
  'amount': 10.99,
  'currency': 'CAD',
  'card_expiry_month': 11,
  'card_expiry_year': 16,
  'card_number': '4111111111111111',
  'cvv2': 595,
}

Example Response Body:

{
  'amount': 10.99,
  'captured': false,
  'card_type': 'VISA',
  'card_suffix': 1111,
  'id': 1234567,
  'transaction_success': true,
  'transaction_result': 'PENDING',
  'transaction_message': 'Insufficient funds',
  'transaction_time': 1467760023000,
  'transaction_type': 'SALE',
  'email': 'brandon@stark.com',
  'first_name': 'Brandon',
  'last_name': 'Stark',
  'company': 'Payfirma',
  'bcc_emails': 'john.snow@stark.com',
  'telephone': '1234567891',
  'address1': 'No. 1 Road',
  'address2': 'Street 2',
  'city': 'Vancouver',
  'province': 'BC',
  'country': 'Canada',
  'postal_code': 'V6E 1B2',
  'custom_id': 'Internal456',
  'invoice_id': 'InternalInvoice12',
}

Create a sale with a customer profile using a new card

Request a credit card payment.

HTTPS POST

/sale/customer/{customer_lookup_id}

URI Parameters

URI Parameters

customer_lookup_id

REQUIRED

A hashed version of the customer_id used to identify the customer in the customer service.

Request Arguments

Request Arguments
amount REQUIRED	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
currency REQUIRED	Transaction currency, in currency type, e.g. USD, CAD.
card_expiry_month REQUIRED	The double-digit month the card expires, e.g. for August, use 08.
card_expiry_year REQUIRED	Expiry year - in double digits - of the associated credit card number, e.g. for 2017, use 17.
card_number REQUIRED	The credit card number (16 digits for most card brands and 15 digits for American Express).
cvv2 REQUIRED	A credit card’s verification code, otherwise known as CVC or CVV; the three or four-digit number on the back of most major cards, and the four digit number found on the front of American Express cards. We strongly recommend that you utilize the cvv2 field to help protect against fraud and charge-backs.
token	Secure and encrypted card token. You can use this instead of card_expiry_month, card_expiry_year, card_number and cvv2. If used with a credit card, 400 BAD_REQUEST is returned.

Response Attributes

Response Attributes
amount number	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
captured bolean	-
card_type string	The brand of the credit card, e.g. Visa, Mastercard, Amex
card_suffix number	The last 4 digits of the credit card.
id number	Internal ID representation.
transaction_success bolean	The boolean success response for each transaction.
transaction_result string	The success response for each transaction.
transaction_message string	Details on the transaction result.
transaction_time number	The UNIX time stamp that the transaction was processed, represented in milliseconds.
transaction_type string	Identifies what type of transaction request was made, e.g. sale, refund.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.
bcc_emails string	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone string	Customers telephone number.
address1 string	First line of the customer address.
address2 string	Second line of the customer address.
city string	The city where the customer is.
province string	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country string	The country where the customer is.
postal_code string	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
custom_id string	A description field to record any general customer identifying information.
invoice_id string	An open description field to help with transaction tracking and reporting. If the Payfirma invoicing service is used, this number will be generated by the invoicing system.

Example Request:

Example Request Body:

Example Response Body:

Create a sale with a customer profile using the default card

Request a credit card payment and associate it with a new or existing customer profile

HTTPS POST

/sale/customer/{customer_lookup_id}

URI Parameters

URI Parameters

customer_lookup_id

REQUIRED

A hashed version of the customer_id used to identify the customer in the customer service.

Request Arguments

Request Arguments

amount

REQUIRED

Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.

Response Attributes

Response Attributes
amount number	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
captured bolean	-
card_type string	The brand of the credit card, e.g. Visa, Mastercard, Amex
card_suffix number	The last 4 digits of the credit card.
transaction_id	-
transaction_success bolean	The boolean success response for each transaction.
transaction_result string	The success response for each transaction.
transaction_message string	Details on the transaction result.
transaction_time number	The UNIX time stamp that the transaction was processed, represented in milliseconds.
transaction_type string	Identifies what type of transaction request was made, e.g. sale, refund.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.
bcc_emails string	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone string	Customers telephone number.
address1 string	First line of the customer address.
address2 string	Second line of the customer address.
city string	The city where the customer is.
province string	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country string	The country where the customer is.
postal_code string	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
custom_id string	A description field to record any general customer identifying information.
invoice_id string	An open description field to help with transaction tracking and reporting. If the Payfirma invoicing service is used, this number will be generated by the invoicing system.

Example Response:

Example Response Body:

Create a sale with a customer profile using a stored card

Request a credit card payment based on the card information you stored with an existing customer profile

HTTPS POST

/sale/customer/{customer_lookup_id}/card/{card_lookup_id}

URI Parameters

URI Parameters

customer_lookup_id

REQUIRED

A hashed version of the customer_id used to identify the customer in the customer service.

card_lookup_id

REQUIRED

Credit card Lookup ID from Customer Vault.

Request Arguments

Request Arguments

amount

REQUIRED

Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.

Response Attributes

Response Attributes
amount number	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
captured bolean	-
card_type string	The brand of the credit card, e.g. Visa, Mastercard, Amex
card_suffix number	The last 4 digits of the credit card.
transaction_id	-
transaction_success bolean	The boolean success response for each transaction.
transaction_result string	The success response for each transaction.
transaction_message string	Details on the transaction result.
transaction_time number	The UNIX time stamp that the transaction was processed, represented in milliseconds.
transaction_type string	Identifies what type of transaction request was made, e.g. sale, refund.
email string	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.

Example Request:

Example Request Body:

Example Response Body:

Authorize

Put a hold on a credit card so that you can confirm the funds will be available for a future payment, using the capture operation.

BASE URI

https://apigateway.payfirma.com/transaction-service

Create an authorization

Put a hold on a credit card balance for a certain amount.

HTTPS POST

/authorize

Request Arguments

Request Arguments
amount REQUIRED	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
currency	Transaction currency, in currency type, e.g. USD, CAD.
card_expiry_month REQUIRED	The double-digit month the card expires, e.g. for August, use 08.
card_expiry_year REQUIRED	Expiry year - in double digits - of the associated credit card number, e.g. for 2017, use 17.
card_number REQUIRED	The credit card number (16 digits for most card brands and 15 digits for American Express).
cvv2 REQUIRED	A credit card’s verification code, otherwise known as CVC or CVV; the three or four-digit number on the back of most major cards, and the four digit number found on the front of American Express cards. We strongly recommend that you utilize the cvv2 field to help protect against fraud and charge-backs.
token	Secure and encrypted card token. You can use this instead of card_expiry_month, card_expiry_year, card_number and cvv2. If used with a credit card, 400 BAD_REQUEST is returned.
email	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name	The first name of the customer.
last_name	The customers last name.
company	Business name associated with customer.
bcc_emails	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone	Customer’s telephone number.
address1	First line of the customer address.
address2	Second line of the customer address.
city	The city where the customer is.
province	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country	The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
postal_code	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
custom_id	A description field to record any general customer identifying information.
invoice_id	An open description field to help with transaction tracking and reporting. If the Payfirma invoicing service is used, this number will be generated by the invoicing system.
sending_receipt	Whether or not a transaction will send a receipt to the customer email provided. Is set as true as the default option.

Response Attributes

Response Attributes
amount number	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
captured bolean	-
card_type string	The brand of the credit card, e.g. Visa, Mastercard, Amex
card_suffix number	The last 4 digits of the credit card.
transaction_id	-
transaction_success bolean	The boolean success response for each transaction.
transaction_result string	The success response for each transaction.
transaction_message string	Details on the transaction result.
transaction_time number	The UNIX time stamp that the transaction was processed, represented in milliseconds.
transaction_type string	Identifies what type of transaction request was made, e.g. sale, refund.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.
bcc_emails string	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone string	Customers telephone number.
address1 string	First line of the customer address.
address2 string	Second line of the customer address.
city string	The city where the customer is.
province string	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country string	The country where the customer is.
postal_code string	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
custom_id string	A description field to record any general customer identifying information.
invoice_id string	An open description field to help with transaction tracking and reporting. If the Payfirma invoicing service is used, this number will be generated by the invoicing system.

Example Request:

Example Request Body:

Example Response Body:

Create an authorization with a customer profile using a new card

Request a credit card payment

HTTPS POST

/authorize/customer/{customer_lookup_id}

URI Parameters

URI Parameters

customer_lookup_id

REQUIRED

A hashed version of the customer_id used to identify the customer in the customer service.

Request Arguments

Request Arguments
amount REQUIRED	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
currency REQUIRED	Transaction currency, in currency type, e.g. USD, CAD.
card_expiry_month REQUIRED	The double-digit month the card expires, e.g. for August, use 08.
card_expiry_year REQUIRED	Expiry year - in double digits - of the associated credit card number, e.g. for 2017, use 17.
card_number REQUIRED	The credit card number (16 digits for most card brands and 15 digits for American Express).
cvv2 REQUIRED	A credit card’s verification code, otherwise known as CVC or CVV; the three or four-digit number on the back of most major cards, and the four digit number found on the front of American Express cards. We strongly recommend that you utilize the cvv2 field to help protect against fraud and charge-backs.
token	Secure and encrypted card token. You can use this instead of card_expiry_month, card_expiry_year, card_number and cvv2. If used with a credit card, 400 BAD_REQUEST is returned.

Response Attributes

Response Attributes
amount number	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
captured bolean	-
card_type string	The brand of the credit card, e.g. Visa, Mastercard, Amex
card_suffix number	The last 4 digits of the credit card.
transaction_id	-
transaction_success bolean	The boolean success response for each transaction.
transaction_result string	The success response for each transaction.
transaction_message string	Details on the transaction result.
transaction_time number	The UNIX time stamp that the transaction was processed, represented in milliseconds.
transaction_type string	Identifies what type of transaction request was made, e.g. sale, refund.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.
bcc_emails string	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone string	Customers telephone number.
address1 string	First line of the customer address.
address2 string	Second line of the customer address.
city string	The city where the customer is.
province string	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country string	The country where the customer is.
postal_code string	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
custom_id string	A description field to record any general customer identifying information.
invoice_id string	An open description field to help with transaction tracking and reporting. If the Payfirma invoicing service is used, this number will be generated by the invoicing system.

Example Request:

Example Request Body:

Example Response Body:

Create an authorization with a customer profile using the default card

Put a hold on a credit card balance for a certain amount and associate it with a new or existing customer profile.

HTTPS POST

/authorize/customer/{customer_lookup_id}

URI Parameters

URI Parameters

customer_lookup_id

REQUIRED

A hashed version of the customer_id used to identify the customer in the customer service.

Request Arguments

Request Arguments

amount

REQUIRED

Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.

Response Attributes

Response Attributes
amount number	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
captured bolean	-
card_type string	The brand of the credit card, e.g. Visa, Mastercard, Amex
card_suffix number	The last 4 digits of the credit card.
transaction_id	-
transaction_success bolean	The boolean success response for each transaction.
transaction_result string	The success response for each transaction.
transaction_message string	Details on the transaction result.
transaction_time number	The UNIX time stamp that the transaction was processed, represented in milliseconds.
transaction_type string	Identifies what type of transaction request was made, e.g. sale, refund.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.
bcc_emails string	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone string	Customers telephone number.
address1 string	First line of the customer address.
address2 string	Second line of the customer address.
city string	The city where the customer is.
province string	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country string	The country where the customer is.
postal_code string	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
custom_id string	A description field to record any general customer identifying information.
invoice_id string	An open description field to help with transaction tracking and reporting. If the Payfirma invoicing service is used, this number will be generated by the invoicing system.

Example Request:

Example Request Body:

Example Response Body:

Create an authorization with a customer profile using a stored card

Put a hold on a credit card balance for a certain amount on a card that you stored with an existing customer profile.

HTTPS POST

/authorize/customer/{customer_lookup_id}/card/{card_lookup_id}

URI Parameters

URI Parameters

customer_lookup_id

REQUIRED

A hashed version of the customer_id used to identify the customer in the customer service.

card_lookup_id

REQUIRED

Credit card Lookup ID from Customer Vault.

Request Arguments

Request Arguments

amount

REQUIRED

Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.

Response Attributes

Response Attributes
amount number	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
captured bolean	-
card_type string	The brand of the credit card, e.g. Visa, Mastercard, Amex
card_suffix number	The last 4 digits of the credit card.
transaction_id	-
transaction_success bolean	The boolean success response for each transaction.
transaction_result string	The success response for each transaction.
transaction_message string	Details on the transaction result.
transaction_time number	The UNIX time stamp that the transaction was processed, represented in milliseconds.
transaction_type string	Identifies what type of transaction request was made, e.g. sale, refund.
email string	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.

Example Request:

Example Request Body:

Example Response Body:

Capture

Use the hold you put on a credit card to complete the payment and request the funds from the card.

BASE URI

https://apigateway.payfirma.com/transaction-service

Capture transaction with original Id

Release the hold you put on a credit card balance and request the final payment amount.

HTTP POST

/capture/{transaction_id}

URI Parameters

URI Parameters

transaction_id

REQUIRED

Unique identifier to track & query transactions.

Request Arguments

Request Arguments

amount

REQUIRED

Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.

Response Attributes

Response Attributes
amount number	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
captured bolean	-
card_type string	The brand of the credit card, e.g. Visa, Mastercard, Amex
card_suffix number	The last 4 digits of the credit card.
transaction_id	-
transaction_success bolean	The boolean success response for each transaction.
transaction_result string	The success response for each transaction.
transaction_message string	Details on the transaction result.
transaction_time number	The UNIX time stamp that the transaction was processed, represented in milliseconds.
transaction_type string	Identifies what type of transaction request was made, e.g. sale, refund.
email string	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.

Example Request:

Example Request Body:

Example Response Body:

Refund

Send the payment back to the credit card.

BASE URI

https://apigateway.payfirma.com/transaction-service

Create a refund

Refund a sale or capture transaction by using the transaction ID.

HTTPS POST

/refund/{transaction_id}

URI Parameters

URI Parameters

transaction_id

REQUIRED

Unique identifier to track & query transactions.

Request Arguments

Request Arguments

amount

REQUIRED

Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.

Response Attributes

Response Attributes
amount number	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
card_type string	The brand of the credit card, e.g. Visa.
card_suffix number	The last 4 digits of the credit card.
id string	Unique identifier to track & query transactions.
transaction_success boolean	The boolean success response for each transaction.
transaction_result string	The success response for each transaction.
transaction_message string	Details on the transaction result.
transaction_time number	The UNIX time stamp that the transaction was processed, represented in milliseconds.
transaction_type string	Identifies what type of transaction request was made, e.g. sale, refund.
email string	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.

Example Request:

Example Request Body:

Example Response Body:

Transaction

Get a list of all the transactions that have been made according to conditions you can specify.

BASE URI

https://apigateway.payfirma.com/transaction-service

Retrieve all transactions for a specific account

Request a list of all the successful and failed transactions that have been made with your account(s) according to parameters you specify.

HTTPS GET

/transaction{?limit,before,after,from_date,to_date,transaction_status,channel,min_amount,max_amount,email_address,first_name,last_name}

URI Parameters

URI Parameters
limit	The number of transactions to be displayed within each page.
before	The begginning of the page cursor. One can use this cursor with a query parameter to get the page before this page.
after	The end of the page cursor. One can use this cursor with an after query parameter to get the page after this page.
from_date	Optional start date for a date range filter. The format should be YYYY-MM-DD.
to_date	Optional end date for a date range filter. The format should be YYYY-MM-DD.
transaction_status	List of comma-separated statuses. Choices: PENDING, APPROVED, DECLINED.
channel	List of comma-separated channels. Choices are: VT, MOBILE, TABLET_POS, E_COMMERCE, RECURRING, or INVOICE.
min_amount	Filter all transactions below the given amount from the result set.
max_amount	Filter all transactions above the given amount from the result set.
email_address	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name	The first name of the customer.
last_name	The customers last name.

Response Attributes

Response Attributes
entities array	The stored customer information that was associated with each transaction.
paging object	Parameter to view multiple pages on large queries.
amount number	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
amount_refunded number	The refunded amount from this transaction, in dollars, e.g. 1.99 = 1 dollar and 99 cents
amount_tip number	The tip amount for this transaction, in dollars, e.g. 1.99 = 1 dollar and 99 cents
amount_tax number	The tax amount for this transaction, in dollars, e.g. 1.99 = 1 dollar and 99 cents
captured bolean	-
currency string	Transaction currency, in currency type, e.g. USD, CAD.
card_type string	The brand of the credit card, e.g. Visa, Mastercard, Amex
card_suffix number	The last 4 digits of the credit card.
card_expiry string	Expiration date of the card in MM/YY format. Eg. For January 2024 use 01/24.
user_id number	The user Id of staff associated with this transaction
id number	Internal ID representation.
transaction_success bolean	The boolean success response for each transaction.
transaction_result string	The success response for each transaction.
transaction_source string	-
transaction_time number	The UNIX time stamp that the transaction was processed, represented in milliseconds.
transaction_type string	Identifies what type of transaction request was made, e.g. sale, refund.
email string	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.
bcc_emails string	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone string	Customers telephone number.
address1 string	First line of the customer address.
address2 string	Second line of the customer address.
city string	The city where the customer is.
province string	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country string	The country where the customer is.
postal_code string	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
invoice_id string	An open description field to help with transaction tracking and reporting. If the Payfirma invoicing service is used, this number will be generated by the invoicing system.
lookup_id number	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
processor_auth_code	-
processor_transaction_id	-
test_mode	-

Example Request:

Example Response Body:

Retrieve all transactions for a specific user

Request a list of all the successful and failed transactions that have been made with your account(s) for one user according to parameters you specify.

HTTPS GET

/transaction/user{?limit,before,after,from_date,to_date,transaction_status,channel,min_amount,max_amount,email_address,first_name,last_name}

URI Parameters

URI Parameters
limit	The number of transactions to be displayed within each page.
before	The begginning of the page cursor. One can use this cursor with a query parameter to get the page before this page.
after	The end of the page cursor. One can use this cursor with an after query parameter to get the page after this page.
from_date	Optional start date for a date range filter. The format should be YYYY-MM-DD.
to_date	Optional end date for a date range filter. The format should be YYYY-MM-DD.
transaction_status	List of comma-separated statuses. Choices: PENDING, APPROVED, DECLINED.
channel	List of comma-separated channels. Choices are: VT, MOBILE, TABLET_POS, E_COMMERCE, RECURRING, or INVOICE.
min_amount	Filter all transactions below the given amount from the result set.
max_amount	Filter all transactions above the given amount from the result set.
email_address	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name	The first name of the customer.
last_name	The customers last name.

Response Attributes

Response Attributes
entities array	The stored customer information that was associated with each transaction.
paging object	Parameter to view multiple pages on large queries.
amount number	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
amount_refunded number	The refunded amount from this transaction, in dollars, e.g. 1.99 = 1 dollar and 99 cents
amount_tip number	The tip amount for this transaction, in dollars, e.g. 1.99 = 1 dollar and 99 cents
amount_tax number	The tax amount for this transaction, in dollars, e.g. 1.99 = 1 dollar and 99 cents
captured bolean	-
currency string	Transaction currency, in currency type, e.g. USD, CAD.
card_type string	The brand of the credit card, e.g. Visa, Mastercard, Amex
card_suffix number	The last 4 digits of the credit card.
card_expiry string	Expiration date of the card in MM/YY format. Eg. For January 2024 use 01/24.
user_id number	The user Id of staff associated with this transaction
id number	Internal ID representation.
transaction_success bolean	The boolean success response for each transaction.
transaction_result string	The success response for each transaction.
transaction_source string	-
transaction_time number	The UNIX time stamp that the transaction was processed, represented in milliseconds.
transaction_type string	Identifies what type of transaction request was made, e.g. sale, refund.
email string	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.
bcc_emails string	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone string	Customers telephone number.
address1 string	First line of the customer address.
address2 string	Second line of the customer address.
city string	The city where the customer is.
province string	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country string	The country where the customer is.
postal_code string	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
invoice_id string	An open description field to help with transaction tracking and reporting. If the Payfirma invoicing service is used, this number will be generated by the invoicing system.
lookup_id number	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
processor_auth_code	-
processor_transaction_id	-
test_mode	-

Example Request:

Example Response Body:

Retrieve individual transaction

Query one transaction by providing the transaction ID

HTTPS GET

/transaction/{transaction_id}

URI Parameters

URI Parameters
transaction_id	Unique identifier to track & query transactions.

Response Attributes

Response Attributes
entities array	The stored customer information that was associated with each transaction.
paging object	Parameter to view multiple pages on large queries.
amount number	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
amount_refunded number	The refunded amount from this transaction, in dollars, e.g. 1.99 = 1 dollar and 99 cents
amount_tip number	The tip amount for this transaction, in dollars, e.g. 1.99 = 1 dollar and 99 cents
amount_tax number	The tax amount for this transaction, in dollars, e.g. 1.99 = 1 dollar and 99 cents
captured bolean	-
currency string	Transaction currency, in currency type, e.g. USD, CAD.
card_type string	The brand of the credit card, e.g. Visa, Mastercard, Amex
card_suffix number	The last 4 digits of the credit card.
card_expiry string	Expiration date of the card in MM/YY format. Eg. For January 2024 use 01/24.
user_id number	The user Id of staff associated with this transaction
id number	Internal ID representation.
transaction_success bolean	The boolean success response for each transaction.
transaction_result string	The success response for each transaction.
transaction_source string	-
transaction_time number	The UNIX time stamp that the transaction was processed, represented in milliseconds.
transaction_type string	Identifies what type of transaction request was made, e.g. sale, refund.
email string	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.
bcc_emails string	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone string	Customers telephone number.
address1 string	First line of the customer address.
address2 string	Second line of the customer address.
city string	The city where the customer is.
province string	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country string	The country where the customer is.
postal_code string	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
invoice_id string	An open description field to help with transaction tracking and reporting. If the Payfirma invoicing service is used, this number will be generated by the invoicing system.
lookup_id number	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
processor_auth_code	-
processor_transaction_id	-
test_mode	-

Example Request:

Example Response Body:

API: Transaction

Sale

BASE URI

Create a sale

HTTPS POST

Request Arguments

Request Arguments

Response Attributes

Response Attributes

Create a sale with a customer profile using a new card

HTTPS POST

URI Parameters

URI Parameters

Request Arguments

Request Arguments

Response Attributes

Response Attributes

Create a sale with a customer profile using the default card

HTTPS POST

URI Parameters

URI Parameters

Request Arguments

Request Arguments

Response Attributes

Response Attributes

Create a sale with a customer profile using a stored card

HTTPS POST

URI Parameters

URI Parameters

Request Arguments

Request Arguments

Response Attributes

Response Attributes

Authorize

BASE URI

Create an authorization

HTTPS POST

Request Arguments

Request Arguments

Response Attributes

Response Attributes

Create an authorization with a customer profile using a new card

HTTPS POST

URI Parameters

URI Parameters

Request Arguments

Request Arguments

Response Attributes

Response Attributes

Create an authorization with a customer profile using the default card

HTTPS POST

URI Parameters

URI Parameters

Request Arguments

Request Arguments

Response Attributes

Response Attributes

Create an authorization with a customer profile using a stored card

HTTPS POST

URI Parameters

URI Parameters

Request Arguments

Request Arguments

Response Attributes

Response Attributes

Capture

BASE URI

Capture transaction with original Id

HTTP POST

URI Parameters

URI Parameters

Request Arguments

Request Arguments

Response Attributes

Response Attributes

Refund

BASE URI

Create a refund

HTTPS POST

URI Parameters