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

Step 1. Sign up for an account

Go to https://www.payfirma.com/signup or call 1 [phone] 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 TSL 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.