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** | | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------- | |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': 'APPROVED', 'transaction_message': '\n', '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** | | | ------------------------------------------ | ------------------------------------------------------------------------------------------- | |customer\_lookup\_id
REQUIRED
| A hashed version of the customer\_id used to identify the customer in the customer service. | | **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** | | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |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': 'APPROVED', 'transaction_message': '\n', '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** | | | ------------------------------------------ | ------------------------------------------------------------------------------------------- | |customer\_lookup\_id
REQUIRED
| A hashed version of the customer\_id used to identify the customer in the customer service. | | **Request Arguments** | | | ---------------------------- | --------------------------------------------------------------------- | |amount
REQUIRED
| Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents. | | **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': 'APPROVED', 'transaction_message': '\n', '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** | | | ------------------------------------------ | ------------------------------------------------------------------------------------------- | |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** | | | ---------------------------- | --------------------------------------------------------------------- | |amount
REQUIRED
| Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents. | | **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. | |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': 'APPROVED', 'transaction_message': '\n', '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** | | | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |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** | | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |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: ``` 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/authorize" ``` Example Request Body: ``` { 'amount': 10.99, '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': 2992429, 'transaction_success': true, 'transaction_result': 'APPROVED', 'transaction_message': '\n', '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 an authorization with a customer profile using a new card Request a credit card payment **HTTPS POST** `/authorize/customer/{customer_lookup_id}` | **URI Parameters** | | | ------------------------------------------ | ------------------------------------------------------------------------------------------- | |customer\_lookup\_id
REQUIRED
| A hashed version of the customer\_id used to identify the customer in the customer service. | | **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** | | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |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: ``` 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/authorize/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': 'APPROVED', 'transaction_message': '\n', '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 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** | | | ------------------------------------------ | ------------------------------------------------------------------------------------------- | |customer\_lookup\_id
REQUIRED
| A hashed version of the customer\_id used to identify the customer in the customer service. | | **Request Arguments** | | | ---------------------------- | --------------------------------------------------------------------- | |amount
REQUIRED
| Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents. | | **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: ``` 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/authorize/customer/6Np3nqDgan635dRoz2lk" ``` 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': 'APPROVED', 'transaction_message': '\n', '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 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** | | | ------------------------------------------ | ------------------------------------------------------------------------------------------- | |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** | | | ---------------------------- | --------------------------------------------------------------------- | |amount
REQUIRED
| Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents. | | **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. | |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/authorize/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': 'APPROVED', 'transaction_message': '\n', 'transaction_time': 1467760023000, 'transaction_type': 'SALE', 'email': 'brandon@stark.com', 'first_name': 'Brandon', 'last_name': 'Stark', 'company': 'Payfirma', } ``` ## 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** | | | ------------------------------------- | ------------------------------------------------ | |transaction\_id
REQUIRED
| Unique identifier to track & query transactions. | | **Request Arguments** | | | ---------------------------- | --------------------------------------------------------------------- | |amount
REQUIRED
| Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents. | | **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. | |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/capture/1234567" ``` 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': 'APPROVED', 'transaction_message': '\n', 'transaction_time': 1467760023000, 'transaction_type': 'SALE', 'email': 'brandon@stark.com', 'first_name': 'Brandon', 'last_name': 'Stark', 'company': 'Payfirma', } ``` ## 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** | | | ------------------------------------- | ------------------------------------------------ | |transaction\_id
REQUIRED
| Unique identifier to track & query transactions. | | **Request Arguments** | | | ---------------------------- | --------------------------------------------------------------------- | |amount
REQUIRED
| Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents. | | **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. | |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/refund/1234567" ``` Example Request Body: ``` { 'amount': 10.99, } ``` Example Response Body: ``` { 'amount': 10.99, 'card_type': 'VISA', 'card_suffix': 1111, 'id': 1234567, 'transaction_success': true, 'transaction_result': 'APPROVED', 'transaction_message': '\n', 'transaction_time': 1467760023000, 'transaction_type': 'SALE', 'email': 'brandon@stark.com', 'first_name': 'Brandon', 'last_name': 'Stark', 'company': 'Payfirma', } ``` ## 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** | | | ----------------------- | ------------------------------------------------------------------------------------------------------------------- | | 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** | | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |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. | |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: ``` curl --include \ --header "Content-Type: application/json" \ --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \ "https://apigateway.payfirma.com/transaction-service/transaction?limit=100&before=3X67XWEE&after=XWERE836&from_date=2016-12-30&to_date=2016-12-30&transaction_status=transaction_status&channel=channel&min_amount=7.89&max_amount=799.89&email_address=brandon%40stark.com&first_name=Brandon&last_name=Stark" ``` Example Response Body: ``` { 'entities': [ { 'amount': 10.99, 'amount_refunded': 1.99, 'amount_tip': 1.99, 'amount_tax': 1.99, 'captured': false, 'currency': 'CAD', 'card_type': 'VISA', 'card_suffix': 1111, 'card_expiry': '11/19', 'user_id': 123456, 'id': 2992429, 'transaction_id': 'NV0B6eZB06', 'transaction_success': true, 'transaction_result': 'APPROVED', 'transaction_source': 'MOBILE', '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', 'invoice_id': 'InternalInvoice12', 'lookup_id': 32145, 'processor_auth_code': 'ABCDEF', 'processor_transaction_id': '123456789', 'test_mode': false, } ], 'paging': { 'cursors': { 'before':'51pmdq8z5rdbRWoKYrje', 'after':'xv9Aq54WEy3RyWEBXypK' } } } ``` ### 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** | | | ----------------------- | ------------------------------------------------------------------------------------------------------------------- | | 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** | | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |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. | |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: ``` curl --include \ --header "Content-Type: application/json" \ --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \ "https://apigateway.payfirma.com/transaction-service/transaction/user?limit=100&before=3X67XWEE&after=XWERE836&from_date=2016-12-30&to_date=2016-12-30&transaction_status=transaction_status&channel=channel&min_amount=7.89&max_amount=799.89&email_address=brandon%40stark.com&first_name=Brandon&last_name=Stark" ``` Example Response Body: ``` { 'entities': [ { 'amount': 10.99, 'amount_refunded': 1.99, 'amount_tip': 1.99, 'amount_tax': 1.99, 'captured': false, 'currency': 'CAD', 'card_type': 'VISA', 'card_suffix': 1111, 'card_expiry': '11/19', 'user_id': 123456, 'id': 2992429, 'transaction_id': 'NV0B6eZB06', 'transaction_success': true, 'transaction_result': 'APPROVED', 'transaction_source': 'MOBILE', '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', 'invoice_id': 'InternalInvoice12', 'lookup_id': 32145, 'processor_auth_code': 'ABCDEF', 'processor_transaction_id': '123456789', 'test_mode': false, } ], 'paging': { 'cursors': { 'before':'51pmdq8z5rdbRWoKYrje', 'after':'xv9Aq54WEy3RyWEBXypK' } } } ``` ### Retrieve individual transaction Query one transaction by providing the transaction ID **HTTPS GET** `/transaction/{transaction_id}` | **URI Parameters** | | | ------------------ | ------------------------------------------------ | | transaction\_id | Unique identifier to track & query transactions. | | **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. | |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: ``` curl --include \ --header "Content-Type: application/json" \ --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \ "https://apigateway.payfirma.com/transaction-service/transaction/1234567" ``` Example Response Body: ``` { 'amount': 1.99, 'amount_refunded': 1.99, 'amount_tip': 1.99, 'amount_tax': 1.99, 'captured': false, 'currency': 'CAD', 'card_type': 'VISA', 'card_suffix': 1111, 'card_expiry': '11/19', 'user_id': 123456, 'id': 1234567, 'transaction_success': true, 'transaction_result': 'APPROVED', 'transaction_source': 'MOBILE', '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', 'invoice_id': 'InternalInvoice12', 'lookup_id': 32145, 'processor_auth_code': 'ABCDEF', 'processor_transaction_id': '123456789', 'test_mode': false, } ```