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:

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/customer/6Np3nqDgan635dRoz2lk"

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 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:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"amount\": 10.99,
}" \
"https://apigateway.payfirma.com/transaction-service/sale/customer/6Np3nqDgan635dRoz2lk"

Example Response Body:

{
  'amount': 10.99,
}

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 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:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"amount\": 10.99,
}" \
"https://apigateway.payfirma.com/transaction-service/sale/customer/6Np3nqDgan635dRoz2lk/card/Nlc3NfdG9rZ"

Example Request Body:

{
  'amount': 10.99,
}

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',
}

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.

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