Guide: Getting Started

Introduction

The Merrco Payfirma API is a RESTful web service that uses HTTP GET & POST transfer methods with JSON messaging format for all requests to and responses from the server.

There are four(4) services within the API:

Step 1. Authorization : - Request a Bearer Token for your merchant account to include in the header of all your requests to the other services.

Step 2. Customer : - Create customer objects and use them to store credit card information or set them up on subscription plans.

Step 3. Plan : - Set up and manage multiple recurring payment plans so you can create subscriptions.

Step 4. Transactions : - Make different credit card payments, including sales and refunds, and get information on those transactions.

Errors

Our API uses HTTP response codes for all requests. Response codes in the 2xx range indicate success; codes in the the 4xx range indicate that there is something either missing in or wrong with the parameters of the request, and those in the 5xx range indicate a server error from the API. Each response code contains a message with more information to help diagnose the cause of the error.

However, not all errors map cleanly onto HTTP response codes. When a request is valid but does not complete successfully, we return a 402 error code.

PCI Compliance

When you process payments with our API, you can rest assured it’s secure and PCI-compliant. Sensitive customer data is always tokenized to reduce your PCI scope. We require that all traffic to our API is with a secured and current SSL certificate, and we recommend that you never store credit card data (i.e. credit card number, expiry month, expiry year and CVV/CVC) anywhere other than with the Customer Service.

PCI DSS V3.2 Overview (April 2016)

Build and Maintain a Secure Network and Systems	Install and maintain a firewall configuration to protect cardholder data Do not use vendor-supplied defaults for system passwords and other security parameters
Protect Cardholder Data	Protect stored cardholder data Encrypt transmission of cardholder data across open, public networks
Maintain a Vulnerability Management Program	Protect all systems against malware and regularly update anti-virus software or programs Develop and maintain secure systems and applications
Implement Strong Access Control Measures	Restrict access to cardholder data by business need to know Identify and authenticate access to system components Restrict physical access to cardholder data
Regularly Monitor and Test Networks	10. Track and monitor all access to network resources and cardholder data 11. Regularly test security systems and processes
Maintain an Information Security Policy	12. Maintain a policy that addresses information security for all personnel

Checklist

To develop with the Merrco Payfirma API, there are some things you need to do.

Step 1. Sign up for an account

Go to https://www.payfirma.com/signup or call 1 (800) 747-6883 and ask for a Payment Advisor to set up a Demo Account for you.

Step 2. Create your Client ID & Client Secret

You’re going to need a set of credentials to send to our authorization service in order to identify your account. These credentials are your client ID and client secret, which you can create and manage in "Settings – eCommerce" within your PayHQ account.

Step 3. Review the guide and API reference

Our guide is designed to help you plan out your project and understand which functions of the API you’ll need to use to build out the different use cases. The API Reference provides the request and response structures with detailed code examples in 10 languages.customert Advisors by calling 1-800-747-6883, and you’ll need to get access to the production PayHQ account for the primary experience that you’re looking for.

Step 4. Set up your SSL or TLS certificate

We require a Secure Socket Layer (SSL) or Transport Layer Security (TSL) certificate for use with all of our API. This allows you to protect customer data as it is being transmitted to and from the web server. These certificates can be purchased from a variety of vendors, including your service provider or host, as well as other hosting domains and locations.

All server-side communication must be conducted using the HTTPS protocol and enabled by an SSL or TSL certificate so that Merrco Payfirma and PayHQ can handle PCI compliance.

Step 5. Develop with a demo account

Please also note that your account will be configured such that odd dollar amounts for all transactions will be approved, and all transactions with even dollar amounts will be declined. Fake card numbers like 4111-1111-1111-1111 and 4242-4242-4242-4242 will be accepted as long as they have a valid expiry month, expiry year, and CVV/CVC.

Your demo accounts is connected to a live mail server so any emails included in your transaction requests will receive emailed receipts unless you specify otherwise in your requests.

Step 6. Move to production

The primary owner of the business will need to set up a merchant account with one of our payment advisors by calling 1-800-747-6883, and you’ll need to get access to the production PayHQ account from the primary business owner. You should then reconfirm that the client ID & client secret matches your production account.

Guide: Walkthrough

Traffic Authentication

The Authorization Service requires the Basic Token in the header while the Transaction, Customer and Plan Services require a Bearer Token. All requests to the Authorization Service will need to point to the root endpoint or url https://auth.payfirma.com and requests to the other services will be addressed to https://apigateway.payfirma.com.

Get your Bearer Token

Step 1. Get your Client ID & Client Secret from your PayHQ account by going to Settings – eCommerce.

Step 2. Using Base64 encoding, combine the Client ID & Client Secret together with a colon in between to acquire your Basic Token for your header.

Step 3. Use your Basic Token with your Client ID and Client Secret to get your Bearer Token from the Client Credentials Grant.

Step 4. Set up a recurring request to get your Bearer Token based on the validity timeframe that you set for your Client ID & Client Secret. The default validity that we recommend is 12 hours. This can be changed in Settings - eCommerce when you create or edit a Client ID and Client Secret.

Step 3. 
curl https://auth.payfirma.com/oauth/token  
--request POST  
--header "Content-Type: application/x-www-form-urlencoded"  
--header "Authorization: Basic {BASIC_TOKEN}"  
--data "grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}"

Get your Merchants Bearer Token

Step 1. Set up your Partner OAuth flow with PayHQ by sending us your selected business name, an image url for your business with a square format, and the callback URI to your Merrco or Payfirma point of contact.

Step 2. Set up an invokable Authorization function in your application to get the short-lived authorization code when your Merchants complete the sign-in and authorization process.

Step 3. Make an Authorization Code Grant request with the Authorization code from Step 2

Step 4. Store the Bearer and Refresh Tokens for each Merchant

Step 5. Use the Token Refresh Grant to request a new Access Token either based of receiving a 401 error for an invalid token, or based off the time validity of the Bearer Token. Please note that Bearer Tokens are valid for 12 hours and the Refresh Token can only be used to refresh the Bearer token once with a new Refresh token provided with a successful Refresh Token Grant request.

Step 3. 
curl https://auth.payfirma.com/oauth/token?grant_type=authorization_code&code=Grf5pV&redirect_uri=https%3A%2F%2Fwww.example.com&state=xyzABC123  
--request POST  
--header "Content-Type: application/x-www-form-urlencoded"  
--header "Authorization: Basic {BASIC_TOKEN}"  
Step 4. 
{"access_token":"{BEARER_TOKEN}","token_type": "Bearer","refresh_token": "955d8714-f1d6-49d6-830a-2d221631a2b3", "expires_in": 1199, "merchant_id": "01234abcde", "scope": "invoice ecom"}
Step 5. 
curl https://auth.payfirma.com/oauth/token?grant_type=refresh_token&refresh_token=41c128f2-b2e2-4d85-9443-b6e37d02a482&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}   
--request POST  
--header "Content-Type: application/x-www-form-urlencoded"

Simple Transactions

Sales and Authorizations can be completed on their own, while a Capture transaction requires an Authorization transaction and a Refund requires either a Sale or Capture.

Charge a card

Step 1. Use the Bearer Token as your Authorization header and make sure to provide all the card parameters required for a regular sale transaction along with the different request URL.

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

Authorize a hold and then capture the payment

Step 1. Use the Bearer Token as your Authorization header and make sure to provide all the card parameters required for a regular sale transaction along with the different request URL. The hold will stay on the card for between 5-30 business days depending on the policy of the cardholder’s bank.

Step 2. Use the ID field from the transaction response to finalize the payment and request funds. You will still be able to request a payment even if the hold has expired, but you run the risk of the funds not being available for the payment.

Step 1
curl https://apigateway.payfirma.com/transaction-service/authorize 
--request POST 
--header "Content-Type: application/json" 
--header "Authorization: Bearer {BEARER_TOKEN}" 
--data "{
           "amount": 10.99,
           "currency": "CAD",
           "card_expiry_month": 11,
           "card_expiry_year": 16,
           "card_number":"4111111111111111",
           "cvv2": 595
         }"
Step 2
curl https://apigateway.payfirma.com/transaction-service/capture/{ID} 
--request POST 
--header "Content-Type: application/json" 
--header "Authorization: Bearer {BEARER_TOKEN}" 
--data "{"amount": 10.99,}"

Refund a payment

Option 1. Log into PayHQ and select My Transactions to view the complete list of transaction available for review. With each transaction, you have the control to refund the transaction and send a receipt for the refund to the email of your preference.

Option 2. Build the API request to ask for a refund by using the ID from the original sale or capture transaction. Authorization transactions cannot be refunded because no funds have been requested or transferred.

curl " https://apigateway.payfirma.com/transaction-service/refund/{ID} " 
--header "Content-Type: application/json" 
--header "Authorization: Bearer {BEARER_TOKEN}"
--data "{"amount": 10.99,}"
curl 
--include     
--request POST      
--header "Content-Type: application/json"     
--header "Authorization: Bearer {BEARER_TOKEN}"      
--data-binary "{ "amount": 10.99,  "test_mode": true}" 
"https://apigateway.payfirma.com/transaction-service/refund/1234567"

Encrypt credit card as a token

The Payfirma Card Encryption Javascript library generates a secure and encrypted card token to be used with any of our transaction methods.

How to use this library

This library was developed specifically for client use.

Within your HTML page, include the following inside the head tab. Alternatively, you can import/require the script from your code base.

src="https://www.payfirma.com/payfirma-card-encryption-min.js"

You can access and reference the library from inside your Javascript file.

let PayfirmaCardEncryption = window.PayfirmaCardEncryption;

Your public encryption key requires to be sent as an alphanumeric string.

let publicEncryptionKey = "2d2d2d2d2d424547494e205055424c4943204b45592d2d2";

Make sure all your card parameters are sent as numeric strings. Numbers or objects will not be accepted.

let cardNumber = "1234567890123456";
let cardMonth = "12";
let cardYear = "34";
let cardCvv2 = "123"

Generate an encoded token using the the encode function. It requires Public Encryption Key, Card Number, Card Month, Card Year, CVV2 as parameters.

let encryptedCard = PayfirmaCardEncryption(publicEncryptionKey, cardNumber, cardMonth, cardYear, cardCvv2);

Use the encoded token within the body of your transaction request.

let transactionObject = {
amount: 1.00,
currency: "CAD",
token: encryptedCard,
email: "goku.son@payfirma.com",
first_name: "Goku",
last_name: "Son",
company: "Capsule Corporation",
telephone: "123-456-7890"
};

Post your first transaction!

let request = new XMLHttpRequest();
request.open("POST", "https://apigateway.payfirma.com/transaction-service/sale");
request.setRequestHeader("Content-Type", "application/json");
request.setRequestHeader("Authorization", bearerToken);
request.onreadystatechange = function () {
if (this.readyState === 4) {
console.log("Something went wrong");
} else {
console.log("Success!");}
};
request.send(stringifyTransaction(transactionObject));

Example:

let publicEncryptionKey = "2d2d2d2d2d424547494e205055424c4943204b45592d2d2";
let cardNumber = "1234567890123456";
let cardMonth = "01";
let cardYear = "23";
let cardCvv2 = "045"
let encryptedCard = window.PayfirmaCardEncryption(publicEncryptionKey, cardNumber, cardMonth, cardYear, cardCvv2);
let transactionObject = {
    amount: 0.01,
    currency: "CAD",
    token: encryptedCard,
    email: "goku.son@payfirma.com",
    first_name: "Goku",
    last_name: "Son",
    company: "Capsule Corporation",
    telephone: "123-456-7890"
};

Future Payments

The Customer and Transaction Services can be used together to store cards and make payments on those stored cards.The Customer and Plan Services can be used together to set up recurring payment plans called subscriptions.

Storing a credit card

Step 1. Create a customer with all the key details that you want to store in the PayHQ database.

Step 2. Use the Customer_Lookup_ID for the customer you just created to save a card to that customer.

Step 1.
curl "https://apigateway.payfirma.com/customer-service/customer" 
--request POST  
--header "Content-Type: application/json"       
--header "Authorization: Bearer {BEARER_TOKEN}"      
--data "{  
         "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"}"
Step 2. 
curl "https://apigateway.payfirma.com/customer-service/customer/{CUSTOMER_LOOKUP_ID/card/"
--request POST  
--header "Content-Type: application/json"  
--header "Authorization: Bearer {BEARER_TOKEN}"  
--data {
       "card_expiry_month": 11,
       "card_expiry_year": 16,
       "card_number": "4111111111111111",
       "cvv2": "595",
       "is_default": true,
       "card_description": 
       "test card" }

Making a payment on a stored card

Step 1. Use the Customer_Lookup_ID to make a payment with the default card.

Step 2. Use the Customer_Lookup_ID and the Card_Lookup_ID to make a payment with a card other than the default card stored for that customer.

Step 1.
curl "https://apigateway.payfirma.com/customer-service/customer/{CUSTOMER_LOOKUP_ID/card/" 
--request POST  
--header "Content-Type: application/json"      
--header "Authorization: Bearer {BEARER_TOKEN}"    
--data " {  "amount": 10.99,"currency": "CAD" }
Step 2. 
curl "https://apigateway.payfirma.com/customer-service/customer/{CUSTOMER_LOOKUP_ID/card/{CARD_LOOKUP_ID}/" 
--request POST      
--header "Content-Type: application/json"      
--header "Authorization: Bearer {BEARER_TOKEN}"      
--data " {   "amount": 10.99,"currency": "CAD"}

Subscribe a customer with a stored card

Step 1. Create a plan with the key payment details.

Step 2. Make sure that you have a saved customer with a stored card.

Step 3. Create a subscription based on a plan for customer with a stored card.

Step 1.
curl " https://apigateway.payfirma.com/plan-service/plan/"
--request POST      
--header "Content-Type: application/json"     
--header "Authorization: Bearer {BEARER_TOKEN}"      
--data " {  
"name": "Sample Daily Plan",  
"amount": 10.99,  
"currency": "CAD",  
"frequency": "DAILY",  
"number_of_payments": 10,  
"send_receipt": false 
}"
Step 3. 
curl " https://apigateway.payfirma.com/customer-service/customer/{CUSTOMER_LOOKUP_ID}/subscription "
--request POST      
--header "Content-Type: application/json"   
--data  {
"plan_lookup_id": "{PLAN_LOOKUP_ID}",
"card_lookup_id": "{CARD_LOOKUP_ID}",
"amount": 10.99,
"start_date": 1467760023000,
"email": "brandon@stark.com"
"description": "My test subscription"
} ”

Reporting

Transaction reporting can be accessed through the PayHQ web application or through the PayHQ API.

Get your transactions

Option 1. Log into PayHQ and select "My Transactions" to view the complete list of transaction available for review. There is also the option to export the transaction list to a .csv file.

Option 2. Build the API call to request the full list of transactions according to whatever parameters you specify.

curl " https://apigateway.payfirma.com/transaction-service/transaction?limit=10000"  
--request POST      
--header "Authorization: Bearer {BEARER_TOKEN}"

Get your merchant's transactions

Request the full list of transactions according to whatever parameters you specify and please note that the account data will be based off the Bearer token.

curl " https://apigateway.payfirma.com/transaction-service/transaction?limit=10000"  
--request POST      
--header "Authorization: Bearer {BEARER_TOKEN}"

Glossary

Authorization is a financial transaction that places a hold on the credit or debit card for the amount you specify. This hold will last 10-20 business days depending on the cardholder’s bank policy. Please see Capture for how to receive money from this hold. This term can also refer to the class of token for the Basic and Bearer Tokens.

Authorization Service the part of the API that grants access tokens to the Transaction Service.

Basic Token is an encoded version of your Client ID & Client Secret in Base64 format using UTF-8 encoding that you’ll use for most requests to the Authorization service. Use the tool of your choice and encode the Client ID & Client Secret together with a colon in between both values to get your Basic Token.

Here is an example in bash:

echo -n "{CLIENT_ID}:{CLIENT_SECRET}" | base64

Bearer Token is a token that you’ll receive from the authorization service to use in the header for all requests to the Customer, Plan, and Transaction services. The Bearer Token lasts for 20 minutes.

Capture is a financial transaction that collects the payment after a hold has been placed on a credit or debit card. This transfer of funds is entirely dependent on a successful Authorization transaction.

Cards refer to the unique object that is created when you store a credit or debit card in our tokenized card vault.

Client ID & Client Secret are a set of unique account credentials that you generate in your PayHQ account to begin working with our API and should only be shared with team members or colleagues who are going to be working directly with your code base.

Customer is an object in our Customer Service that you create to be able to store customer information, store the Cards of that customer, and create Subscriptions on those cards.

Customer Service the group of API operations that allows developers to create customer objects, store sensitive card data by creating tokens and create subscription payments

Password is the secure, private key that you established with your PayHQ login. This field is only used for the Password Grant Operation and should be managed as privately as possible; only you or people accessing your code should have access to it.

Plans are payment templates that you can create with the Plan Service and are the base object needed for a Subscription payment.

Plan Service the set of operations used for creating recurring payment plans used to create subscription objects.

Refund is a reverse of a Sale or Capture transaction that will send the money from the merchant account back to the account of the cardholder.

Sale is the straightforward purchase transaction to charge a credit or debit card.

Subscription payments are created when a Plan is used to bill the stored Card of a Customer. Subscriptions do not have to be an exact copy of a Plan and can be updated at the time of creation as needed.

Transaction Service the set of transaction and reporting functions, other than subscription payments, for the API.

Username is the email address associated with your PayHQ login. This field is only used for the Password Grant Operation.

AUTHORIZATION

Authorize

Use your Client ID and Client Secret, along with a Basic Token in your header, to get Bearer Token needed for the header of all requests to the Customer, Plan and Transaction Services

BASE URI

https://auth.payfirma.com/oauth

Authorization

This flow generates a one-time authorization code used to obtain the OAuth access token. The authorization code is obtained by using an authorization server as an intermediary between the client (you) and the resource owner (your Merchants).

HTTPS GET

/authorize{?response_type,client_id,redirect_uri}

URI Parameters

response_type

required

Value must be set to ‘code’.

client_id

required

The client identifier issued to the client during the registration process.

redirect_uri

required

URL to redirect back to after completing its interaction with the resource owner. The redirection endpoint URI must be an absolute URI.

Example Request:

curl --include \
     --header "Content-Type: application/x-www-form-urlencoded" \
  "https://auth.payfirma.com/oauth/authorize?response_type="code"&client_id="aaabbbere05a7986b850b1933d91f33399"&redirect_uri="https:///www.example.com""

Example Response Body:

{
  'Location': 'https:///www.example.com&code=Xdfsdf82F',
}

Grant

Use the authorization code from each of your merchants to get access credentials.

BASE URI

https://auth.payfirma.com/oauth

Authorization code grant

The authorization code grant type is used to obtain both access tokens and refresh tokens by presenting a one-time authorization code obtained from Payfirma’s authorization server during the authorization request.

HTTPS POST

/token{?grant_type,code,redirect_uri,state}

URI Parameters
grant_type REQUIRED	Value must be set to ‘authorization_code’.
code REQUIRED	Short-lived and one-time authorization code, received from Payfirma’s authorization server.
redirect_uri	URL to redirect back to after completing its interaction with the resource owner. The redirection endpoint URI must be an absolute URI.
state	RECOMMENDED. An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHOULD be used for preventing cross-site request forgery

Response Attributes
access_token string	A Payfirma access token is a JWT format string representing an authorization issued to the client (you) from the user (the Merchant) to access their protected Payfirma resources.
token_type string	General identifier for the OAuth token.
refresh_token string	Refresh token is issued to the client by Payfirma authorization server and is used to obtain a new access token when the current access token becomes invalid or expires. The refresh token never expires and can be used only once. It becomes invalid when the access token is revoked.
expires_in number	The lifetime in seconds of the access token. The default setting for the access token default is to expire in 20 minutes (1200 seconds).
merchant_id string	Unique identifier for the merchant.
scope string	The list of different services that have been authorized for access.

Example Request:

curl --include \
       --request POST \
       --header "Content-Type: application/x-www-form-urlencoded" \
       --header "Authorization: Basic "ZmM0N2E0ZGMxZWMzODFjMzIxZjk4MzEyZmUwNDQ0YzA6NjI3YWE3NTE1MzNiMW1234567890123=" \
   "https://auth.payfirma.com/oauth/token?grant_type=authorization_code&code=Grf5pV&redirect_uri=https%3A%2F%2Fwww.example.com&state=xyzABC123"

Example Response Body:

{
  'access_token': 'eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU',
  'token_type': 'Bearer',
  'refresh_token': '955d8714-f1d6-49d6-830a-2d221631a2b3',
  'expires_in': 1199,
  'merchant_id': '01234abcde',
  'scope': 'invoice ecom',
}

Client Credentials Grant

The client credentials grant uses client id and client secret as an authorization grant when the authorization scope is limited to the protected resources under the control of the client. Client credentials are used as an authorization grant typically when the client is acting on its own behalf (the client is also the resource owner)

HTTPS POST

/token{?grant_type,client_id,client_secret}

URI Parameters

grant_type

REQUIRED

Value must be set to refresh_token.

client_id

REQUIRED

The client identifier issued to the client during the registration process.

client_secret

REQUIRED

The client secret issued to the client during the registration process.

Response Attributes
access_token string	A Payfirma access token is a JWT format string representing an authorization issued to the client (you) from the user (the Merchant) to access their protected Payfirma resources.
token_type string	General identifier for the OAuth token.
expires_in number	The lifetime in seconds of the access token. The default setting for the access token default is to expire in 20 minutes (1200 seconds).
merchant_id string	Unique identifier for the merchant.
scope string	The list of different services that have been authorized for access.

Example Request:

curl --include \
     --request POST \
     --header "Content-Type: application/x-www-form-urlencoded" \
     --header "Authorization: Basic ZmM0N2E0ZGMxZWMzODFjMzIxZjk4MzEyZmUwNDQ0YzA6NjI3YWE3NTE1MzNiMW1234567890123==" \
  "https://auth.payfirma.com/oauth/token?grant_type=client_credentials&client_id=UGF5ZmlybWEgdGVzdCAwOSBjbGllbnQgSUQ%3D&client_secret=Q2xpZW50IHNlY3JldCBmb3IgUGF5ZmlybWEgdGVzdCAwOQ%3D%3D"

Example Response Body:

{
  'access_token': 'eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU',
  'token_type': 'Bearer',
  'expires_in': 1199,
  'merchant_id': '01234abcde',
  'scope': 'invoice ecom',
}

Refresh token grant

The client can request a new access token by authenticating with the Payfirma authorization server and then presenting the refresh token.

HTTPS POST

/token{?grant_type,refresh_token,client_id,client_secret}

URI Parameters
grant_type REQUIRED	Value must be set to refresh_token.
refresh_token REQUIRED	Refresh token is issued to the client by Payfirma authorization server and is used to obtain a new access token when the current access token becomes invalid or expires. The refresh token never expires and can be used only once. It becomes invalid when the access token is revoked.
client_id REQUIRED	The client identifier issued to the client during the registration process.
client_secret REQUIRED	The client secret issued to the client during the registration process.

Response Attributes
access_token string	A Payfirma access token is a JWT format string representing an authorization issued to the client (you) from the user (the Merchant) to access their protected Payfirma resources.
token_type string	General identifier for the OAuth token.
refresh_token string	Refresh token is issued to the client by Payfirma authorization server and is used to obtain a new access token when the current access token becomes invalid or expires. The refresh token never expires and can be used only once. It becomes invalid when the access token is revoked.
expires_in number	The lifetime in seconds of the access token. The default setting for the access token default is to expire in 20 minutes (1200 seconds).
merchant_id string	Unique identifier for the merchant.
scope string	The list of different services that have been authorized for access.

Example Request:

curl --include \
     --request POST \
     --header "Content-Type: application/x-www-form-urlencoded" \
  "https://auth.payfirma.com/oauth/token?grant_type=refresh_token&refresh_token=41c128f2-b2e2-4d85-9443-b6e37d02a482&client_id=UGF5ZmlybWEgdGVzdCAwOSBjbGllbnQgSUQ%3D&client_secret=Q2xpZW50IHNlY3JldCBmb3IgUGF5ZmlybWEgdGVzdCAwOQ%3D%3D"

Example Response Body:

{
  'access_token': 'eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU',
  'token_type': 'Bearer',
  'refresh_token': '955d8714-f1d6-49d6-830a-2d221631a2b3',
  'expires_in': 1199,
  'merchant_id': '01234abcde',
  'scope': 'invoice ecom',
}

Revoke

Invalidate an authorization code

BASE URI

https://auth.payfirma.com/oauth

Revoke token

A revocation request will invalidate the token passed through the authorization header, revoking both the access token and refresh token.

HTTPS DELETE

/revoke_token

CUSTOMER

Customer

Set up customer profiles. You will need these profiles to store credit cards and use those credit cards for different payment types.

BASE URI

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

Create a customer

Create a new customer profile using provided information

HTTPS POST

/customer

Request Arguments
email REQUIRED	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.

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
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	Customer’s 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. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
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.
cards array	All the non-PCI card details stored with a customer profile.
subscriptions array	All the subscription info for the subscriptions stored with a customer profile.

Example Request:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"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\"
}" \
"https://apigateway.payfirma.com/customer-service/customer"

Example Response Body:

{
  'id': 2992429,
  'lookup_id': 'NV0B6eZB06',
  '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',
  'cards':[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],
  'subscriptions':[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}],
}

Retrieve a specific customer

Get all the attributes of a specific customer profile by using their lookup_id.

HTTPS GET

/customer/{customer_lookup_id}

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

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
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	Customer’s 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. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
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.
cards array	All the non-PCI card details stored with a customer profile.
subscriptions array	All the subscription info for the subscriptions stored with a customer profile.

Example Request:

curl --include \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
  "https://apigateway.payfirma.com/customer-service/customer/NV0B6eZB06"

Example Response Body:

{
  'id': 2992429,
  'lookup_id': 'NV0B6eZB06',
  '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',
  'cards':[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],
  'subscriptions':[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}],
}

Retrieve all customers for a specific account

Requests a list of all customers according to the parameters you specify.

HTTPS GET

/customer{?limit,before,after,email_address,first_name,last_name,company,with_subscription}

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.
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.
company	Business name associated with customer.
with_subscription	A boolean identity for whether customers have subscriptions.

Response Attributes
entities array	The stored customer information that was associated with each transaction.
paging object	Parameter to view multiple pages on large queries.
cursors object	Set the boundaries for displayed results.
before string	The begginning of the page cursor. One can use this cursor with a query parameter to get the page before this page.
after string	The end of the page cursor. One can use this cursor with an after query parameter to get the page after this page.

Example Request:

curl --include \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
  "https://apigateway.payfirma.com/customer-service/customer?limit=100&before=%273X67XWEE%27&after=%27XWERE836%27&email_address=%27brandon%40stark.com%27&first_name=%27Brandon%27&last_name=%27Stark%27&company=Payfirma&with_subscription=true"

Example Response Body:

{
  'entities':[{"id":2992429,"lookup_id":"NV0B6eZB06","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","cards":[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],"subscriptions":[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}]}],
  'paging': {"cursors":{"before":"51pmdq8z5rdbRWoKYrje","after":"xv9Aq54WEy3RyWEBXypK"}},
}

Retrieve plan's customers

Query all customers who subscribed to a given plan lookup Id

HTTPS GET

/customer/plan/{plan_lookup_id}/{?limit,before,after,email_address,first_name,last_name,company}

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.
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.
company	Business name associated with customer.
with_subscription	A boolean identity for whether customers have subscriptions.

Response Attributes
entities array	The stored customer information that was associated with each transaction.
paging object	Parameter to view multiple pages on large queries.
cursors object	Set the boundaries for displayed results.
before string	The begginning of the page cursor. One can use this cursor with a query parameter to get the page before this page.
after string	The end of the page cursor. One can use this cursor with an after query parameter to get the page after this page.

Example Request:

curl --include \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
  "https://apigateway.payfirma.com/customer-service/customer/plan/99ffb59876mnb?limit=100&before="3X67XWEE"&after="XWERE836"&email_address="brandon@stark.com"&first_name="Brandon"&last_name="Stark"&company=Payfirma"

Example Response Body:

{
  'entities':[{"id":2992429,"lookup_id":"NV0B6eZB06","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","cards":[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],"subscriptions":[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}]}],
  'paging': {"cursors":{"before":"51pmdq8z5rdbRWoKYrje","after":"xv9Aq54WEy3RyWEBXypK"}},
}

Update a customer

Change the attributes of a customer profile using their customer lookup_id.

HTTPS PUT

/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
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.

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
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	Customer’s 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. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
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.
cards array	All the non-PCI card details stored with a customer profile.
subscriptions array	All the subscription info for the subscriptions stored with a customer profile.

Example Request:

curl --include \
     --request PUT \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"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\"
}" \
"https://apigateway.payfirma.com/customer-service/customer/NV0B6eZB06"

Example Request Body:

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

Example Response Body:

{
  'id': 2992429,
  'lookup_id': 'NV0B6eZB06',
  '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',
  'cards':[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],
  'subscriptions':[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}],
}

Card

Store a credit card with a customer profile and update the card object as needed.

BASE URI

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

Add a new card

Store a new credit card to a customer profile.

HTTPS POST

/customer/{customer_lookup_id}/card

URI Parameters

customer_lookup_id

REQUIRED

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

Request Arguments
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.
currency	DEFAULT is true for first card and false for the rest.

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
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	Customer’s 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. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
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.
cards array	All the non-PCI card details stored with a customer profile.
subscriptions array	All the subscription info for the subscriptions stored with a customer profile.

Example Request:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"card_expiry_month\": 11,
  \"card_expiry_year\": 16,
  \"card_number\": \"4111111111111111\",
  \"cvv2\": \"595\",
  \"is_default\": true,
  \"card_description\": \"test card\"
}" \
"https://apigateway.payfirma.com/customer-service/customer/NV0B6eZB06/card"

Example Request Body:

{
  'card_expiry_month': 11,
  'card_expiry_year': 16,
  'card_number': '4111111111111111',
  'cvv2': '595',
  'is_default': true,
  'card_description': 'test card',
}

Example Response Body:

{
  'id': 2992429,
  'lookup_id': 'NV0B6eZB06',
  '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',
  'cards':[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],
  'subscriptions':[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}],
}

Update a card

Update an existing credit card object.

HTTPS PATCH

/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
is_default	DEFAULT is true for first card and false for the rest.
card_description	A description you can define for each card to help with card management and tracking.

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
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	Customer’s 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. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
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.
cards array	All the non-PCI card details stored with a customer profile.
subscriptions array	All the subscription info for the subscriptions stored with a customer profile.

Example Request:

curl --include \
     --request PATCH \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"is_default\": true,
  \"card_description\": \"test card\"
}" \
"https://apigateway.payfirma.com/customer-service/customer/NV0B6eZB06/card/34cvb54564dfc"

Example Request Body:

{
  'is_default': true,
  'card_description': 'test card',
}

Example Response Body:

{
  'id': 2992429,
  'lookup_id': 'NV0B6eZB06',
  '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',
  'cards':[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],
  'subscriptions':[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}],
}

Remove a card

Remove a credit card from a customer’s profile.

HTTPS DELETE

/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.

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
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	Customer’s 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. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
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.
cards array	All the non-PCI card details stored with a customer profile.
subscriptions array	All the subscription info for the subscriptions stored with a customer profile.

Example Request:

curl --include \
     --request DELETE \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
  "https://apigateway.payfirma.com/customer-service/customer/NV0B6eZB06/card/34cvb54564dfc"

Example Response Body:

{
  'id': 2992429,
  'lookup_id': 'NV0B6eZB06',
  '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',
  'cards':[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],
  'subscriptions':[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}],
}

Subscription

Use stored customer profiles and cards to set up subscription payments based off your recurring plans

BASE URI

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

Add a new subscription

Subscribe a given customer to a plan

HTTPS POST

/customer/subscription

Request Arguments
plan_lookup_id REQUIRED	A hashed version of the plan_id used to identify the plan in the customer & plan service.
card_lookup_id REQUIRED	Credit card Lookup ID from Customer Vault.
amount	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
start_date REQUIRED	UNIX time representation of the start date for a subscription, represented in milliseconds. It should be in future.
email	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
bcc_emails	Additional email the receipt should be sent to for expense tracking or accounting needs.
description	An open field to record any information about the payment you want to appear in the customer’s receipt.

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
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	Customer’s 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. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
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.
cards array	All the non-PCI card details stored with a customer profile.
subscriptions array	All the subscription info for the subscriptions stored with a customer profile.

Example Request:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"plan_lookup_id\": \"99ffb59876mnb\",
  \"card_lookup_id\": \"34cvb54564dfc\",
  \"amount\": 10.99,
  \"start_date\": 1467760023000,
  \"email\": \"brandon@stark.com\",
  \"bcc_emails\": \"nedd@stark.com, robb@stark.com\",
  \"description\": \"My test plan\"
}" \
"https://apigateway.payfirma.com/customer-service/customer/NV0B6eZB06/subscription"

Example Request Body:

{
  'plan_lookup_id': '99ffb59876mnb',
  'card_lookup_id': '34cvb54564dfc',
  'amount': 10.99,
  'start_date': 1467760023000,
  'email': 'brandon@stark.com',
  'bcc_emails': 'nedd@stark.com, robb@stark.com',
  'description': 'My test plan',
}

Example Response Body:

{
  'id': 2992429,
  'lookup_id': 'NV0B6eZB06',
  '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',
  'cards':[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],
  'subscriptions':[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}],
}

Update a subscription

Update a subscription: Update the details of a subscription for a given customer lookup_id and a subscription lookup_id.

HTTPS PATCH

/customer/customerLookupId/subscription/subscriptionLookupId

Request Arguments
status	ACTIVE, CANCELED, PAUSED
card_lookup_id	Credit card Lookup ID from Customer Vault.
amount	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
email	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
bcc_emails	Additional email the receipt should be sent to for expense tracking or accounting needs.
description	An open field to record any information about the payment you want to appear in the customer’s receipt.

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
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	Customer’s 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. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
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.
cards array	All the non-PCI card details stored with a customer profile.
subscriptions array	All the subscription info for the subscriptions stored with a customer profile.

Example Request:

curl --include \
     --request PATCH \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"card_lookup_id\": \"34cvb54564dfc\",
  \"amount\": 10.99,
  \"email\": \"brandon@stark.com\",
  \"bcc_emails\": \"nedd@stark.com, robb@stark.com\",
  \"description\": \"My test plan\"
}" \
"https://apigateway.payfirma.com/customer-service/customer/NV0B6eZB06/subscription/34cvb54564dfc"

Example Request Body:

{
  'card_lookup_id': '34cvb54564dfc',
  'amount': 10.99,
  'status': 'PAUSED',
  'email': 'brandon@stark.com',
  'bcc_emails': 'nedd@stark.com, robb@stark.com',
  'description': 'My test plan',
}

Example Response Body:

{
  'id': 2992429,
  'lookup_id': 'NV0B6eZB06',
  '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',
  'cards':[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],
  'subscriptions':[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}],
}

Cancel a subscription

Cancel a subscription: Cancel all future payments scheduled on a subscription plan by changing the status of the subscription

HTTPS PATCH

/customer/customerLookupId/subscription/subscriptionLookupId

Request Arguments
status	CANCELLED

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
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	Customer’s 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. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
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.
cards array	All the non-PCI card details stored with a customer profile.
subscriptions array	All the subscription info for the subscriptions stored with a customer profile.

Example Request:

curl --include \
     --request PATCH \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"card_lookup_id\": \"34cvb54564dfc\",
  \"amount\": 10.99,
  \"email\": \"brandon@stark.com\",
  \"bcc_emails\": \"nedd@stark.com, robb@stark.com\",
  \"description\": \"My test plan\"
}" \
"https://apigateway.payfirma.com/customer-service/customer/NV0B6eZB06/subscription/34cvb54564dfc"

Example Request Body:

{
  'status': 'CANCELLED',
}

Example Response Body:

{
  'id': 2992429,
  'lookup_id': 'NV0B6eZB06',
  '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',
  'cards':[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],
  'subscriptions':[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}],
}

PLAN

Plan

Create and manage the plans that you will need to set up your customers on subscription payments.

BASE URI

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

Create a plan

Create a new plan

HTTPS POST

/plan

Request Arguments
name REQUIRED	The title you give to each plan, which should be unique for each plan.
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.
frequency REQUIRED	The cycle of how often the card will be charged on the subscription or plan. Choices are: DAILY, WEEKLY, MOTHLY, QUARTERLY, or ANNUALLY.
number_of_payments	The total number of payments within this plan.
send_receipt	Sets whether receipt should be sent after transaction. Default is false.

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
name string	The title you give to each plan, which should be unique for each plan.
amount number	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
currency string	Transaction currency, in currency type, e.g. USD, CAD.
frequency string	The cycle of how often the card will be charged on the subscription or plan. Choices are: DAILY, WEEKLY, MOTHLY, QUARTERLY, or ANNUALLY.
number_of_payments number	The total number of payments within this plan.
send_receipt boolean	Sets whether receipt should be sent after transaction. Default is false.
total_subscriptions number	Total number of subscriptions under this plan.
current_subscriptions number	Current number of subscriptions as ACTIVE, RETRY, SUSPENDED and PAUSED.

Example Request:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"name\": \"Sample Daily Plan\",
  \"amount\": 10.99,
  \"currency\": \"CAD\",
  \"frequency\": \"DAILY\",
  \"number_of_payments\": 10,
  \"send_receipt\": false
}" \
"https://apigateway.payfirma.com/plan-service/plan"

Example Response Body:

{
  'id': 2992429,
  'lookup_id': '99ffb59876mnb',
  'name': 'Sample Daily Plan',
  'amount': 10.99,
  'currency': 'CAD',
  'frequency': 'DAILY',
  'number_of_payments': 10,
  'send_receipt': false,
  'total_subscriptions': 10,
  'current_subscriptions': 2,
}

Retrieve all plans

Request the list of all plans that are active

HTTPS GET

/plan{?limit,before,after,plan_name,min_amount,max_amount,frequency,min_number_of_total_subscriptions,max_number_of_total_subscriptions,min_number_of_current_subscriptions,max_number_of_current_subscriptions}

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.
plan_name	The name established for the plan.
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.
frequency	The cycle of how often the card will be charged on the subscription or plan. Choices are: DAILY, WEEKLY, MOTHLY, QUARTERLY, or ANNUALLY.
min_number_of_total_subscriptions	Returns all plans with total number of subscriptions less or equal than the given minimum number.
max_number_of_total_subscriptions	Returns all plans with total number of subscriptions greater or equal than the given maximum number.
min_number_of_current_subscriptions	Returns all plans with current number of subscriptions less or equal than the given minimum number.
max_number_of_current_subscriptions	Returns all plans with current number of subscriptions greater or equal than the given maximum number.

Response Attributes
entities array	The stored customer information that was associated with each transaction.
paging object	Parameter to view multiple pages on large queries.
cursors object	Set the boundaries for displayed results.
before string	The beginning of the page cursor. One can use this cursor with a query parameter to get the page before this page.
after string	The end of the page cursor. One can use this cursor with an after query parameter to get the page after this page.

Example Request:

curl --include \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
  "https://apigateway.payfirma.com/plan-service/plan?limit=100&before=%273X67XWEE%27&after=%27XWERE836%27&plan_name=%27Sample%20Daily%20Plan%27&min_amount=7.89&max_amount=799.89&frequency=frequency&min_number_of_total_subscriptions=7&max_number_of_total_subscriptions=70&min_number_of_current_subscriptions=2&max_number_of_current_subscriptions=20"

Example Response Body:

{
  'plans':[{"id":2992429,"lookup_id":"99ffb59876mnb","name":"Sample Daily Plan","amount":10.99,"currency":"CAD","frequency":"DAILY","number_of_payments":10,"send_receipt":false,"total_subscriptions":10,"current_subscriptions":2}],
  'paging': {"cursors":{"before":"51pmdq8z5rdbRWoKYrje","after":"xv9Aq54WEy3RyWEBXypK"}},
}

Retrieve a plan

Query a specific plan using the plan lookup_id

HTTPS GET

/plan/{plan_lookup_id}

URI Parameters
plan_lookup_id	A hashed version of the plan_id used to identify the plan in the customer & plan service.

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
name string	The title you give to each plan, which should be unique for each plan.
amount number	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
currency string	Transaction currency, in currency type, e.g. USD, CAD.
frequency string	The cycle of how often the card will be charged on the subscription or plan. Choices are: DAILY, WEEKLY, MOTHLY, QUARTERLY, or ANNUALLY.
number_of_payments number	The total number of payments within this plan.
send_receipt boolean	Sets whether receipt should be sent after transaction. Default is false.
total_subscriptions number	Total number of subscriptions under this plan.
current_subscriptions number	Current number of subscriptions as ACTIVE, RETRY, SUSPENDED and PAUSED.

Example Request:

curl --include \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
  "https://apigateway.payfirma.com/plan-service/plan/99ffb59876mnb"

Example Response Body:

{
  'id': 2992429,
  'lookup_id': '99ffb59876mnb',
  'name': 'Sample Daily Plan',
  'amount': 10.99,
  'currency': 'CAD',
  'frequency': 'DAILY',
  'number_of_payments': 10,
  'send_receipt': false,
  'total_subscriptions': 10,
  'current_subscriptions': 2,
}

Update a plan

Update plan attributes using the plan lookup_id. Active subscriptions for this plan will continue with the previous attributes and net new subscriptions will use the new attributes.

HTTPS PUT

/plan/{plan_lookup_id}

URI Parameters
plan_lookup_id	A hashed version of the plan_id used to identify the plan in the customer & plan service.

Request Arguments
name REQUIRED	The title you give to each plan, which should be unique for each plan.
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.
frequency REQUIRED	The cycle of how often the card will be charged on the subscription or plan. Choices are: DAILY, WEEKLY, MOTHLY, QUARTERLY, or ANNUALLY.
number_of_payments	The total number of payments within this plan.
send_receipt	Sets whether receipt should be sent after transaction. Default is false.

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
name string	The title you give to each plan, which should be unique for each plan.
amount number	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
currency string	Transaction currency, in currency type, e.g. USD, CAD.
frequency string	The cycle of how often the card will be charged on the subscription or plan. Choices are: DAILY, WEEKLY, MOTHLY, QUARTERLY, or ANNUALLY.
number_of_payments number	The total number of payments within this plan.
send_receipt boolean	Sets whether receipt should be sent after transaction. Default is false.
total_subscriptions number	Total number of subscriptions under this plan.
current_subscriptions number	Current number of subscriptions as ACTIVE, RETRY, SUSPENDED and PAUSED.

Example Request:

curl --include \
     --request PUT \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"name\": \"Sample Daily Plan\",
  \"amount\": 10.99,
  \"currency\": \"CAD\",
  \"frequency\": \"DAILY\",
  \"number_of_payments\": 10,
  \"send_receipt\": false
}" \
"https://apigateway.payfirma.com/plan-service/plan/99ffb59876mnb"

Example Response Body:

{
  'id': 2992429,
  'lookup_id': '99ffb59876mnb',
  'name': 'Sample Daily Plan',
  'amount': 10.99,
  'currency': 'CAD',
  'frequency': 'DAILY',
  'number_of_payments': 10,
  'send_receipt': false,
  'total_subscriptions': 10,
  'current_subscriptions': 2,
}

Remove a plan

Delete a plan using the plan lookup_id. Active subscriptions for the deleted plan will continue.

HTTPS DELETE

/plan

URI Parameters
plan_lookup_id	A hashed version of the plan_id used to identify the plan in the customer & plan service.

curl --include \
     --request DELETE \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
  "https://apigateway.payfirma.com/plan-service/plan/99ffb59876mnb"

TRANSACTION

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

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

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

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.
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
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': '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 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': '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 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': '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 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.
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/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': 'PENDING',
  'transaction_message': 'Insufficient funds',
  '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.
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/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': 'PENDING',
  'transaction_message': 'Insufficient funds',
  '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.
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/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': 'PENDING',
  'transaction_message': 'Insufficient funds',
  '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.
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:

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

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

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

Hosted Payment Page

Steps to setup HPP on PayHQ

Basic requirements for integrating with PayHQ Hosted Payment Page

Setup your hosted payment page
Provide the domain name and return page URL
Generate your access token
Use this access token to send payment request to the hosted payment page endpoint

Customer Vault Feature - If you would like to enable the customer vault feature for Hosted Payment Page (HPP), please inform our team and we will configure it from our admin side. With this feature, customers who have at least one card saved in the PayHQ will be able to make transactions using their saved card details.

Follow these steps to get started with HPP setup

Login to your merchant account
Open settings and select hosted payment page
Enter your domain, return URL and callback URL(optional) to setup your hosted payment page
Once you enter this your hosted payment page will get set up and you will notice that you have been provided the init endpoint to send transaction requests to.
But before you can start using the hosted payment page you will need the access token in order to get access to the backend functionality.
Click on Generate Token button to generate your access token
At this point you are all set to start integrating with our hosted payment page
Additionally if you are interested in collecting billing and shipping information on the hosted payment page then you can select the capture billing address and capture shipping address options. You can select both or just one of these options, depending on your requirements.
At this point you are done with creating your hosted payment page settings.
Next step is to use these settings in your e-commerce application.

Using the sample application

Clone the sample application
Open App.js and replace ENDPOINT, DOMAIN and TOKEN values with the InitEndpoint, domain entered in your HPP settings page and the access token respectively.
Open the package.json file and change the HTTPS and port settings as per your requirements

Run and test this demo application

Additional info:

Please note that if your platform will not be using PayHQ’s HPP module, then your company will need to complete the PCI DSS questionnaire for Service Providers to validate your adherence to PCI DSS with a Qualified Security Assessor (QSA)
▪ You can find a list of approved QSAs here: https://www.pcisecuritystandards.org/assessors_and_solutions/qualified_security_assessors

iFrame Integration

Basic requirements for integrating with PayHQ iFrame

Enable iFrame from your PayHQ account
Generate your iFrame access token
Use this access token in your iFrame integration code
Request payment token for your transaction
Exchange the payment token to complete the transaction

Before you start

Please make sure you have access to PayHQ Sandbox account
Go to https://www.payfirma.com/signup or call 1 (800) 747-6883 and ask for a Payment Advisor to set up a Demo / Sandbox Account for you.

iFrame in action

You can visit https://payhq-iframe-test-demo.firebaseapp.com/ to see the iFrame in action. You can use the test card data mentioned on this page to complete a test transaction.

Important URL

Sandbox – https://sandbox.payfirma.com

Test – https://test.payfirma.com

Production – https://hq.payfirma.com

Developer portal – https://developers.payfirma.com

Integration Process

The integration process comprises of 3 stages

Stage 1 – Your team works on the integration work by using the Sandbox account
Stage 2 – After you finish your integration we will help you go through a certification process to make sure that your integration satisfies your end goal that you had for this integration.
Stage 3 – Request a production PayHQ account. Make sure you change all the URLs in your code to point to the production environment before you go live with your code.

Enable iFrame and generate access token

Login to your merchant account
Click “Settings” on the top right menu
Select “Hosted Pay Page and iFrame” tab on settings page
At the top of the page that opens you will see the iFrame Settings

Click the create button on the right to generate your iFrame token

You will notice that the iFrame access token has been generated. You have an option to delete or refresh the access token as per your requirements
At this point you are ready to start writing your code to integrate iFrame into your web page.

Write your integration code

Link the PayHQ iFrame Javascript library in the webpage where you will be adding the iFrame. The URL of this library for the test environment is https://test-iframe.payfirma.com/payhq-js/payhq-iframe-lib-test.min.js
Add three placeholder div elements in your webpage to hold the iFrames for card number, expiry date and CVV. At this point it’s important to know that PayHQ iFrame is not a single iFrame that you add to your webpage. It comprises three different iFrames, one each for card number, expiry date and CVV. This gives you more flexibility to design your UI the way you want to.
You may choose to provide any id of your choice to the three placeholder divs you added in step 2
The next step is to write Javascript code to initialize the iFrame in your webpage. (See example below)
At this point you should be ready to run your webpage and see the iFrame in action.

Step 4 - script tag

START SCRIPT TAG
                    // 4.1 select the payfirma test environment
                    // LIVE, TEST, SANDBOX
                    const environment = 'TEST' 

                    // 4.2 set apiKey for authorization token
                    const apiKey = "iframe access token";
                    
                    // 4.3 set options
                    var options = {
                      fields: {
                        cardNumber: {
                          selector: "#cardNumber_container",
                          placeholder: "Credit Card *",
                        },
                        cardExpiry: {
                          selector: "#cardExpiry_container",
                          placeholder: "Expires (MM/YY) *"
                        },
                        cardCvv: {
                          selector: "#cardCvv_container",
                          placeholder: "CVV *"
                        }
                      },
                      // set the CSS styles to apply to the payment fields
                      // camelCases instead dash-separated CSS attributes  
                      style: {
                        input: {
                                "fontFamily": "robotoregular,Helvetica,Arial,sans-serif",
                                "fontWeight": "700",
                                "fontSize": "1em",
                                "color": "#ff0000",
                                "backgroundColor": "#a2d157",
                        }
                      } 
                    };

                    // 4.4 init payfirma object
                    const payfirmaObject= Payfirma.payfirmaInit(environment, apiKey,options);
                      payfirmaObject.NumberField().render(options.fields.cardNumber.selector);
                      payfirmaObject.ExpiryField().render(options.fields.cardExpiry.selector);
                      payfirmaObject.CVVField().render(options.fields.cardCvv.selector);
                 
                    // 4.5 set button event 
                    document.querySelector('button#payNow').addEventListener('click', () => {
                      // 4.6 Get Form fields data
                      const formData = {first_name,last_name,email,amount}
      
                      // 4.7 get card token  
                      payfirmaObject.tokenize().then((response)=>{
                          // Set result
                          document.querySelector('#cardtoken-result').innerText = response.payment_token;

                          // If you need to check payment token expiry, 
                          // you need to make a logic with response.expires_in
                          // console.log('payment token will expire in ',response.expires_in + " seconds")
                          
                          // 4.8 Make a sale transaction with card token.
                          makeSaleRequest(response.payment_token, formData);
      
                      }).catch(error => {
                        // There was an error tokenizing your card data
                        console.log('error from server')
                        console.log(error);
                      })
                    });

                  END SCRIPT TAG

Request payment token

In the code shared above the payfirmaObject.tokenize() is responsible for submitting the card details to PayHQ backend and receive a payment token.

Complete the sale

The payment token received in the previous step can be used to complete the sale
Finally call the makeSaleRequest method to complete the sale. This method will make an API call to PayHQ backend and complete the sale
The response of the final sale method contains the lookup ID of the transaction. This lookup ID should be saved for performing refund operations in future.

PayHQ Plugin - WooCommerce

Installation

The first step in your integration will be installing WooCommerce to your WordPress storefront.

Once you’ve logged into your WordPress account, you’ll be able to find the Plugins category in the main menu to the left side of the page, commonly just below Appearance. Click on

Plugins to expand available options before clicking on the revealed option Add New.

Under the Install Plugins header, you’ll find several options; the second, Upload, will enable you to select your .zip of the Payfirma WooCommerce plugin. Click on the Choose File button, and find your .zip of the Payfirma WooCommerce plugin.

Once your plugin is selected, click on Install Now. The plugin will install itself automatically, and after your installation is finished, click on Activate Plugin, just beneath the notification.

Configuration

One of our mandatory requirements for PayHQ is an SSL connection for credit card transactions. To force this, select your newly accessible WooCommerce option in the main menu on the left side of the page. Once the WooCommerce options have expanded in the menu, click on Settings.

From the Settings page, you will automatically be brought to the General Settings Tab. Ensure your Base Location and Currency are set.

Go to the Payments tab within Settings,

Go to Manage

This is where you will be able to enter your assigned Iframe Access Token, as provided through PayHQ Settings.

PayHQ Settings

To get Iframe Access Token

Please, Login at PayHQ and go to Settings. PayHQ Settings

Create Iframe Access Token

GitHub - Reference:

GitHub - Payfirma/New_Payfirma_Woo_Gateway

Download plugin:

https://github.com/Payfirma/New_Payfirma_Woo_Gateway/blob/master/download/Payfirma_Woo_Gateway.zip

Shopify

Configuration

Install the app

Shopify Settings
Select Payments
Select Search by Provider
Search for “Merrco Payments”
Select Merrco Payments Activate and Connect

Connect to PayHQ

Select settings within the Merrco Payments app
Enter your PayHQ login credentials
Enable both capture billing and shipping address
Select Activate

API - All pages

Guide: Getting Started

Introduction

Errors

PCI Compliance

Checklist

Step 1. Sign up for an account

Step 2. Create your Client ID & Client Secret

Step 3. Review the guide and API reference

Step 4. Set up your SSL or TLS certificate

Step 5. Develop with a demo account

Step 6. Move to production

Guide: Walkthrough

Traffic Authentication

Get your Bearer Token

Get your Merchants Bearer Token

Simple Transactions

Charge a card

Authorize a hold and then capture the payment

Refund a payment

Encrypt credit card as a token

Future Payments

Storing a credit card

Making a payment on a stored card

Subscribe a customer with a stored card

Reporting

Get your transactions

Get your merchant's transactions

Glossary

AUTHORIZATION

Authorize

Authorization

Grant

Authorization code grant

Client Credentials Grant

Refresh token grant

Revoke

Revoke token

CUSTOMER

Customer

Create a customer

Retrieve a specific customer

Retrieve all customers for a specific account

Retrieve plan's customers

Update a customer

Card

Add a new card

Update a card

Remove a card

Subscription

Add a new subscription

Update a subscription

Cancel a subscription

PLAN

Plan

Create a plan

Retrieve all plans

Retrieve a plan

Update a plan

Remove a plan

TRANSACTION

Sale

Create a sale

Create a sale with a customer profile using a new card

Create a sale with a customer profile using the default card

Create a sale with a customer profile using a stored card

Authorize

Create an authorization

Create an authorization with a customer profile using a new card

Create an authorization with a customer profile using the default card

Create an authorization with a customer profile using a stored card

Capture

Capture transaction with original Id

Refund

Create a refund

Transaction

Retrieve all transactions for a specific account

Retrieve all transactions for a specific user

Retrieve individual transaction

Hosted Payment Page