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:
Authorization
<p>
Request a Bearer Token for your merchant account to include in the header of all your requests
to the other services.
</p>
<p>
<a
target="_self"
rel="noopener noreferrer nofollow"
class="text-sm"
href="/payhq/api/tag/authorization">
View endpoints →
</a>
</p>
Customer
<p>
Create customer objects and use them to store credit card information or set them up on
subscription plans.
</p>
<p>
<a
target="_self"
rel="noopener noreferrer nofollow"
class="text-sm"
href="/payhq/api/tag/customer">
View endpoints →
</a>
</p>
Plan
<p>Set up and manage multiple recurring payment plans so you can create subscriptions.</p>
<p>
<a
target="_self"
rel="noopener noreferrer nofollow"
class="text-sm"
href="/payhq/api/tag/plan">
View endpoints →
</a>
</p>
Transactions
<p>
Make different credit card payments, including sales and refunds, and get information on those
transactions.
</p>
<p>
<a
target="_self"
rel="noopener noreferrer nofollow"
class="text-sm"
href="/payhq/api/tag/transaction">
View endpoints →
</a>
</p>
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 2024)
| 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.
Sign up for an account
<p>
Sign up online, or call 1 (800) 747-6883 and ask for a Payment Advisor to set up a Demo
Account for you.
</p>
<p>
<a
target="_self"
rel="noopener noreferrer nofollow"
class="text-sm"
href="https://www.payfirma.com/signup">
Go to signup page →
</a>
</p>
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
<strong>Settings</strong>
–
<strong>eCommerce</strong>
within your PayHQ account.
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.
Set up your SSL or TSL certificate
<p>
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.
</p>
<p>
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.
</p>
<p>
<a
target="_self"
rel="noopener noreferrer nofollow"
class="text-sm"
href="https://merrco.com/">
Merrco →
</a>
<a
target="_self"
rel="noopener noreferrer nofollow"
class="text-sm"
href="https://www.payfirma.com/">
Payfirma →
</a>
</p>
Develop with a demo account
<p>
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
<code spellcheck="false">4111-1111-1111-1111</code>
and
<code spellcheck="false">4242-4242-4242-4242</code>
will be accepted as long as they have a valid expiry month, expiry year, and CVV/CVC.
</p>
<p>
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.
</p>
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.
