API - All pages
- 1 Guide: Getting Started
- 1.1 Introduction
- 1.2 Errors
- 1.3 PCI Compliance
- 1.4 Checklist
- 2 Guide: Walkthrough
- 2.1 Traffic Authentication
- 2.2 Simple Transactions
- 2.3 Future Payments
- 2.4 Reporting
- 2.5 Glossary
- 3 AUTHORIZATION
- 3.1 Authorize
- 3.1.1 Authorization
- 3.2 Grant
- 3.2.1 Authorization code grant
- 3.2.2 Client Credentials Grant
- 3.2.3 Refresh token grant
- 3.3 Revoke
- 3.3.1 Revoke token
- 3.1 Authorize
- 4 CUSTOMER
- 4.1 Customer
- 4.2 Card
- 4.2.1 Add a new card
- 4.2.2 Update a card
- 4.2.3 Remove a card
- 4.3 Subscription
- 4.3.1 Add a new subscription
- 4.3.2 Update a subscription
- 4.3.3 Cancel a subscription
- 5 PLAN
- 5.1 Plan
- 5.1.1 Create a plan
- 5.1.2 Retrieve all plans
- 5.1.3 Retrieve a plan
- 5.1.4 Update a plan
- 5.1.5 Remove a plan
- 5.1 Plan
- 6 TRANSACTION
- 6.1 Sale
- 6.2 Authorize
- 6.3 Capture
- 6.4 Refund
- 6.4.1 Create a refund
- 6.5 Transaction
- 7 Invoice
- 7.1 Invoice Solution API
- 7.2 How To: Retrieve a Set of Invoices
- 7.3 How To: Create a New Invoice
- 7.4 How To: Create a New Invoice (Draft)
- 7.5 How To: Retrieve Invoices for a Specific Customer
- 7.6 How To: Retrieve a Specific Invoice
- 7.7 How To: Send an Email
- 7.8 How To: Send an Email to a Specific Email Address
- 8 Card Terminal
- 9 Hosted Payment Page
- 10 iFrame Integration
- 10.1 Basic requirements for integrating with PayHQ iFrame
- 10.1.1 Before you start
- 10.1.2 iFrame in action
- 10.1.3 Important URL
- 10.2 Integration Process
- 10.1 Basic requirements for integrating with PayHQ iFrame
- 11 PayHQ Plugin - WooCommerce
- 11.1 Installation
- 11.2 Configuration
- 12 EFT
- 12.1 Base URL
- 12.2 Balance
- 12.2.1 Response
- 12.3 Incoming Request - EFT Debit
- 12.3.1 Response
- 12.4 Requesting Funds - EFT Credit
- 12.4.1 Request Body
- 12.4.2 Response
- 12.5 Bank Deposit:
- 12.5.1 Request Body
- 12.5.2 Response:
- 12.6 Send Funds - EFT Debit
- 12.6.1 Request Body
- 12.6.2 Response
- 13 Shopify
- 13.1 Configuration
- 13.1.1 Install the app
- 13.1.2 Connect to PayHQ
- 13.1 Configuration
- 14 Partner Integration
- 14.1 Partner Code:
- 14.2 Sandbox Environment:
- 14.2.1 Create a Sandbox Account:
- 14.2.2 Endpoints:
- 14.2.3 Test Processor:
- 14.2.4 Important info:
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 |
|
Protect Cardholder Data |
|
Maintain a Vulnerability Management Program |
|
Implement Strong Access Control Measures |
|
Regularly Monitor and Test Networks | 10. Track and monitor all access to network resources and cardholder data |
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 |
|
---|---|
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. |
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. |
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 |