Running the API in Postman

To help you get started with your integration, you can use the sample CardPointe Gateway API Integration Postman Collection, which includes a template of the API service endpoints.

The CardPointe Gateway API Integration collection also includes a sample Environment to help you get familiar with the API. See Configuring Your Postman Environment, below, for more information.

Click the button below to download the CardPointe Gateway API Integration collection:

Configuring Your Postman Environment

Environment variables allow you to autofill select fields with pre-configured values. For example, instead of manually specifying your merchant ID in the body of each request, you can set the {{merchantid}} variable to your specific MID.

Once you have received API credentials , you can configure the following variables to auto-fill your merchant-specific data in requests to the CardPointe Gateway API:

• site - Set this value to the site for the test or production environment.
• url - The {{url}} variable is used to set the base url (https://{{site}}.cardconnect.com/cardconnect/rest/) for the CardPointe Gateway RESTful web services. {{site}} is populated with the value you set for that variable.
• csurl - The {{csurl}} variable is used to set the url  (https://{{site}}.cardconnect.com/cardsecure/api/v1/ccn/tokenize) for the CardSecure tokenize REST web service. {{site}} is populated with the value you set for that variable.
• Authorization - Set this value to the Base64-encoded API credentials that you received. The {{Authorization}} variable is used in the header of every request.
• merchid - Set this value to your merchant ID (MID). The {{merchid}} variable is used in the body of most requests.

These variables are required in the header and body of most requests. The sample environment includes additional variables that you can configure when testing your integration.

Additionally, the sample collection includes test scripts, which gather specific values (such as token) from the response body, and dynamically update the corresponding environment variable.

To configure environment variables, do the following in Postman:

1. Click the gear icon to open the Manage Environments menu.

2. On the Manage Environments menu, enter your merchant-specific values for each variable.

3. Click Update.

Testing Your Integration

This guide provides information to help you develop and test your integrated application. Whether you are developing a new application, or maintaining an existing one, you should incorporate continuous testing in your SDLC.

Understanding the UAT Environment

You use the UAT (user acceptance testing) sandbox environment to test and validate your application. When you begin your application development and integration, you connect to the UAT instance of the CardPointe Gateway.

To connect to the UAT environment, your application uses the following URL:

https://<site>-uat.cardconnect.com/cardconnect/rest/<endpoint>

where <site> is the site name provided to you, and <endpoint> is a CardPointe Gateway service endpoint.

The UAT environment includes emulators that simulate the payment processing activities that occur in production. In this environment, you test with dummy data that is never sent to the payment processor. You should use test card numbers (for example, 4111 1111 1111 1111 or 4444 3333 2222 1111) and physical test cards. 

UAT Request Rate Limiting

In the UAT environment, requests to the following endpoints are rate-limited: 

• funding

• inquire

• profile

• settlestat

Requests to these UAT endpoints are limited to 20 transactions per minute (TPM), by IP address.

Responses from these endpoints in the UAT environment include the following rate-limit header fields:

• X-Rate-Limit-Retry-After-Seconds: - Returned for unsuccessful HTTP 429 Too Many Requests responses when the limit has been reached. Specifies the seconds remaining before the limit resets.
• X-Rate-Limit-Remaining: - Returned for successful HTTP 200 OK responses. Specifies the number of requests available before the limit is reached.

Understanding UAT Responses

Data that you transmit to the UAT environment is never sent to the payment processing networks; instead, the CardPointe Gateway communicates with an emulator that simulates the payment processor that your merchant ID uses to process payments. The emulator mimics the behavior of the given processing host, and returns a response similar to what you would receive for a live transaction in the production environment.

CardPointe Gateway API responses returned in the UAT environment include fields and arrays in a randomized order. Additionally, UAT responses include dummy fields, arrays, and values. This is intended to help clients develop integrated software that dynamically parses the response data, rather than expecting fields to be present in static positions within the response object. 

Some specific situations, such as a network timeout and specific decline scenarios, require specific input to initiate. See Test Cases, below, for more information on these specific scenarios.

See Gateway Response Codes for a complete list of all possible response codes for the CardPointe Gateway and each processor.

Getting Started

To get started, contact integrationdelivery@fiserv.com to request the following test account details:

• UAT Merchant ID (MID) - A UAT test MID that you will use to authenticate requests and access the CardPointe dashboard for reporting.
• UAT API Credentials - A set of API credentials provisioned for your UAT MID, which you will use to authenticate your API requests.
• UAT API URL - A UAT CardPointe Gateway API URL that you will use to test your API requests.

Using Test Payment Accounts

When testing in the UAT environment, you must use test cards (either physical cards or test card numbers).

UAT Test Card Data

The UAT Merchant ID is boarded to the First Data North UAT environment. If you are testing with this MID, or your own MID that is boarded to the North or Rapid Connect platform, you can use the following test card data to test card-not-present transactions.

The UAT Test Zip Codes section below contains information on testing AVS responses for First Data North, Rapid Connect, and additional platforms.

Physical Test Cards

Physical test cards allow you to test card-present payments.

You can obtain a complete set of EMV test cards from B2 Payment Solutions at the following URL:

https://b2ps.com/product-category/b2-payment-testing-products/

Test Cases

The following topics provide information for testing specific features to obtain responses that are otherwise not returned in the UAT environment.

Testing with Amount-Driven Response Codes

When testing your CardPointe Gateway or CardPointe Integrated Terminal integration in the UAT environment, you can use amount-driven response codes to emulate processor-specific authorization responses that you might encounter in the production environment. This allows you to receive and handle response codes that you would not otherwise encounter in your test environment.

All response codes returned in the production environment are received directly from the processor.

To return a specific response code, you make an authorization request with an amount in the $1000-$1999 range. You specify the desired response code using the last three digits (with a leading 0 for 2-digit response codes) of the whole-dollar amount (the amount excluding cents). For example, if you want to return RPCT respcode 332, "Account locked," make an authorization request for $1332.

The following example illustrates an authorization request for $1116.95. The amount value specified is 111695 (with the decimal implied), therefore, the whole-dollar amount is $1116.

The response includes the RPCT respcode 116, which indicates that the transaction was declined due to insufficient funds.

Testing Refund Authorizations

You can simulate a refund authorization response on the following UAT emulators:

• First Data North (FNOR)
• First Data Rapid Connect (RPCT)
• Chase Paymentech (PMT)

Similarly to testing specific authorization response scenarios using amount-driven responses, you can test individual refund response codes, by sending a partial refund request using an amount value that includes the desired response code.

To test a refund decline, do the following:

1. Run an authorization request including "capture":"y" and "amount":"2000.00" or greater.
2. Run a refund request including the retref from the authorization response and "amount":"1nnn.00", where nnn is the 2 (including leading 0) or 3-digit decline response code you want to receive.
   
   For example, to return a RPCT 500 "Decline" response, include "amount":"1500.00" in the refund request.

Testing Partial Authorizations 

You can simulate a partial authorization response on the following UAT emulators:

• First Data North (FNOR)
• First Data Rapid Connect (RPCT)
• Paymentech (Paymentech)
• Paymentech Tampa (PTAM)
• Vantiv (VANT)
• Worldpay (VPS)

To simulate a partial authorization, submit an authorization request using "account":"4387750101010101" and "amount":"6.00" or greater.

The following responses are returned:

For example:

Testing AVS Response Codes

In order to test AVS response codes that you will encounter in the production environment, the UAT environment is configured to simulate various AVS responses when the last three characters of the postal code matches a specific value.

To force a specific AVS response, review the UAT Test Zip Codes available in the UAT Test Card Data section of this guide. Then submit an authorization request using the last three characters of the postal code meant to generate that AVS response. To illustrate this, the example below uses a zip code ending in 112 to emulate "avsresp": "N" in the response.

Testing CardPointe Gateway Timeouts

Because the UAT environment does not communicate with the processing hosts, your application can not encounter a time out scenario. In production, when the CardPointe Gateway communication with the processor times out, the Gateway returns an auth response object that includes "respcode":"62" and "resptext":"Timed out"

If you want to test your application's ability to handle a time out response, you can send an auth request using one of the following test card numbers:

• Visa: 4999006200620062
• MC: 5111006200620062
• Discover: 6465006200620062

The response includes the PPS respcode 62, which indicates that the transaction was declined due to a communication timeout between the CardPointe Gateway and processor host.

Processing ACH Payments

This guide provides guidance for accepting Automated Clearing House (ACH) payments using the CardPointe Gateway API. ACH payments, also called e-check payments, are a common payment method for recurring payments as well as telephone and mail orders.

Unlike credit card payments, when a customer authorizes an ACH payment, the funds are withdrawn directly from his or her bank account. This process can take several days, so you should include a monitoring process in your integration to verify the status of the transaction.

To accept ACH payments, you must capture and handle the customer's bank account and routing number. While you can capture this information and pass it directly to the CardPointe Gateway in an authorization request, it is a best practice to instead capture this information and tokenize it using a CardSecure-integrated web form.

Using a Web Form to Gather and Tokenize ACH Payment Data

To ensure the security of your customers' data, as well as your PCI compliance, it is recommended that you use a customer-facing web form, integrated with CardSecure, to capture and tokenize bank account and routing information.

When using a web form to capture and tokenize customer bank account information, include separate fields for the routing number and account number. Send these fields in a CardSecure tokenization request in the format
"account" : "<routing number>/<account number>"

For example:

"account" : "123456789/1234123412341234"

CardSecure returns a token representing the ACH account information, which you can then use to make an authorization request to the CardPointe Gateway.

Making an ACH Authorization Request

To process an ACH payment, you make an authorization request using the CardPointe Gateway API. In addition to the fields required for all authorization requests, you must include the following information:

The following example illustrates an ACH authorization request and response:

Verifying ACH Transactions

ACH transactions typically take several business days to process and settle, therefore, it is a best practice to periodically check the status of the transaction to ensure that it is successfully processed and that you are credited for the authorized amount.

You can use the CardSecure Gateway API to programmatically verify the transaction status using the inquire and funding service endpoints.

Using the Inquire Endpoint

The inquire endpoint provides information on completed authorizations.

You can use the inquire endpoint if you have the retrieval reference number (retref) from the authorization response. If you don't have the retref, but you included a unique order ID in the authorization request, then you can use the inquireByOrderId endpoint instead.

The inquire response includes a settlement status (setlstat) field that displays the settlement status of the transaction. Note that the settlement status initially displays "Queued for Capture" for ACH transactions, and the value is updated once the batch is transmitted. If "setlstat" : "rejected" you can use the funding endpoint to gather more detailed information.

Using the Funding Endpoint

The funding endpoint provides additional useful information for ACH transactions. Specifically, you can use the funding endpoint to retrieve an ACH return code (achreturncode), which provides additional information for rejected ACH transactions.

To use the funding endpoint, you make a request using the merchant ID and the date of the funding event that included the transaction. The funding endpoint returns an array of transaction details for that date.

Use the retref for the ACH transaction to locate it in the txns node of the response data. For ACH transactions, the response includes an achreturncode field that includes a specific code that explains the reason for the rejection.

The following table describes the possible ACH return code values.

Testing ACH Authorizations

To test ACH authorizations, you can use the test Merchant ID (MID) 496160873888 in the CardPointe Gateway's UAT environment. This MID uses a routing rule to detect when "accttype" : "ECHK" and then routes ACH transactions through a separate, linked MID, 542041.

This configuration allows you to dedicate separate merchant accounts to processing credit/debit and ACH transactions, which can be helpful for testing and reporting purposes. Contact Support if you want to configure a dedicated MID for processing ACH transactions.

Scheduling Recurring Payments

This guide provides information for extending your existing CardPointe Gateway API integration to add recurring billing to your payment methods.

To do this, you can use an application scheduler, like Cron, to create a schedule to run recurring transactions. The scheduled job can initiate an authorization request to the CardPointe Gateway using tokenized payment data or a stored profile.

This method gives you complete control over your recurring payment schedule with a simple API integration.

How it Works

The following process provides a general overview of the steps required to set up a recurring payment schedule using the CardPointe Gateway. depending on your integration and business needs, your procedure may vary.

Ensure that you review and comply with the card brand requirements for obtaining consent to store and reuse cardholder data. See the Visa and Mastercard Stored Credential Framework Mandate guide for detailed information.

1. Tokenize the customer's payment data.
   
   Depending on your existing integration, there are several ways to tokenize payment data.
   
   For example, you can:
   • Use the customer’s clear PAN or ACH payment data to make a CardPointe Gateway API authorization request. The response returns a token for the account.
     
     Note: You should only programmatically handle and tokenize clear payment account numbers (PANs) if your business is a registered PCI Level 1 or Level 2 certified merchant. If you are not already certified for compliance with the Payment Card Industry's standards and guidelines for handling sensitive account data, see https://www.pcisecuritystandards.org/ for more information.
     
     Optionally, do the following: 

     • Include ”capture” : “y” to accept an initial payment.
     • include ”profile” : “y” to store the customer’s data in a profile to use in future requests.
   • Gather and tokenize the payment card data using the Hosted iFrame Tokenizer.
   • Use a CardPointe Integrated Terminal and the Terminal API readCard or readManual service endpoint.
2. Store the token for reuse.
   
   You can either store tokens and customer data in your own database, or you can use the CardPointe Gateway API’s profile service endpoint to create and store customer profiles in the CardPointe Gateway's secure vault. You can skip this step if you created a profile in step 1.
   
   
3. Gather your billing requirements.
   
   Determine the start date and length of the billing plan, the payment amount and frequency, and any additional information that you'll need to include in your requests.
   
   
4. Build your Cron job to schedule authorization requests to the CardPointe Gateway API.

Printing Receipts Using Authorization Data

This guide provides information for integrators who want to use authorization response data to print receipts from an integrated POS printer.

Receipt Rules and Requirements

This topic provides general best practices and integration details for printing receipts and capturing cardholder signature data; however, each card brand provides specific rules and requirements. You should understand and follow the receipt guidelines for the card brands that you accept.

Consult the following card brand guidelines for detailed information:

• MasterCard: https://www.mastercard.us/content/dam/mccom/global/documents/transaction-processing-rules.pdf
• Visa: https://usa.visa.com/dam/VCOM/download/about-visa/visa-rules-public.pdf

Additionally, receipt requirements vary depending on the card type. For example, receipts generated for EMV (chip and contactless) card transactions must include specific EMV tag data returned in the authorization response. Ensure that you understand the requirements for accepting both EMV and MSR (magnetic-stripe) cards as determined by the card brands.

Understanding Receipt Data

When an authorization is successfully approved and processed by the CardPointe Gateway, the authorization response payload includes important transaction details that you can capture and print on a receipt.

In general, a receipt must include:

• transaction details from the authorization response
• merchant account information and additional transaction details returned in the receipt object
• EMV tag data returned in the EMV tag object, if the card used was an EMV (chip or contactless) card.

Authorization Response Data

A successful authorization response includes the following fields. You should include the highlighted fields on your receipts.

EMV Tag Data

If the card used in the authorization request was an EMV (chip or contactless) card, then the response data includes an emvTagData object with the following fields:

Receipt Data

The receipt object is an optional set of fields that provides additional merchant and order details in the authorization response. 

The merchant account information is populated using the merchant properties configured for the MID.

Additionally, this object includes additional transaction details from the authorization response. You can optionally include a custom order note (orderNote) and item details (items), by including a userFields object in the authorization request.

You can specify the following fields in a userFields object to include an order note or item details, or to override the merchant properties:

Each value can be any string and the total length of user defined fields (URL/JSON-encoded) is limited to 4000 bytes. See the description of userFields in the CardPointe Gateway API documentation for more information.

A successful authorization response includes a receipt object with the following fields:

Printing a Receipt

To print a receipt from your custom integration, use the fields described in Understanding Receipt Data to build your receipt template.

The following example illustrates a receipt template (left) and a receipt populated with data retrieved from the authorization response (right).

Handling Timed-out Transactions

This guide provides best practices for handling CardPointe Gateway API timeout errors. The Gateway API supports synchronous communication; therefore, your application must make requests and expect responses in sync with the CardPointe Gateway services.

If you are a developer integrating your point-of-sale software with the CardPointe Gateway API, it is important for you to understand how long the steps of the payment process can take, so your software can interact accordingly. The following information should guide you on how long to wait for a response, and actions to take if one is not returned.

CardPointe Gateway Authorization Timeout (32 Seconds)

When you use the CardPointe Gateway API's auth endpoint, to make an authorization request, the Gateway sends the request to the payment processing network and allows 31 seconds for a response. If the Gateway does not receive a response, then the request times out at the 32 second mark and returns a "Timed Out" response.

Handling CardPointe Gateway Timeouts

Whether your application is using the Terminal API authCard request, or the CardPointe Gateway API auth request, it should be designed to handle the following scenarios:

1. A "Timed out" response returned successfully (HTTP 200) from the CardPointe Gateway auth endpoint or the Terminal API authCard endpoint.
2. No response returned successfully from the CardPointe Gateway auth endpoint.

In this case, a response, including a retref for the transaction, is returned. The response includes "respstat": "B" which always means "Retry." The transaction attempt should be tried again.

If you need to reference the details of any particular transaction attempt, supply valid retref and merchid values in an inquire request.

In some cases, retry attempts will also fail. In the event of multiple retry failures, check status.cardconnect.com for reports of system-wide issues.

No Response Returned

This scenario may include, but is not limited to, an HTTP Status 408 Request Timeout.

In this case, your application can not determine whether or not the transaction was successful.

As a safeguard against losing record of the transaction attempt from your system, it is strongly recommended that you supply a unique order ID for every authorization request made to the API.

If you included an order ID in the original authorization request, then you can use the following Gateway API service endpoints to inquire on or void the transaction record:

• inquireByOrderid
  
  The inquireByOrderid endpoint is used to look up a transaction record using the order ID supplied in the original authorization request. If the supplied order ID is found, then the same payload returned in the inquire response is provided.
  
  If the original authorization request was successful, the response includes the transaction details, including the retref. You can then use the retref to make a subsequent void or capture call.
  
  If the original authorization request was unsuccessful, the response includes PPS respcode 29, Txn not found. This response indicates that the authorization request timed out before being processed by the CardPointe Gateway, and you should retry the authorization request. 
  
  
• voidByOrderId
  
  The voidByOrderId endpoint is used to look up and void a transaction record using the order ID supplied in the original authorization request. If the supplied order ID matches a transaction record, the authorization is voided and a void response is returned. See the voidByOrderId description for more information.
  
  voidByOrderId should be used in the event that no response is returned by an inquireByOrderId request, or if no look up is required at all.
  
  Note: You should attempt the voidByOrderid request three times (3x) to ensure that the transaction is voided, despite not receiving a response to indicate that the request was successful.

See the CardPointe Gateway API for information on the inquireByOrderid, voidByOrderId, and capture service endpoints.

Manually Managing Gateway Batches

This guide provides information for using the CardPointe Gateway API's openbatch and closebatch service endpoints to manually open and close Gateway batches, and the settlestatByBatchSource endpoint to retrieve settlement details for a batch. 

Using the openbatch Endpoint

A call to the openbatch service endpoint opens a new batch associated with the supplied merchid. The batchsource is used to supply a batch identifier to logically link multiple batches together across merchant IDs. A batch contains one merchid.

Exercise caution when specifying a batchsource value. The CardPointe Gateway does not validate or use the value and it is possible for more batches to be grouped if the same batchsource is used by mistake; therefore it is a best practice to use unique batch source values, and to develop a system for categorizing grouped transactions accurately.

Additionally, the batchsource value in an openbatch request must match the batchsource value in the authorization or capture request for the transaction that you want to include in the created batch.

openbatch URL

openbatch Request

Fields in bold are required.

openbatch Response

Using the closebatch Endpoint

A call to the closebatch service endpoint attempts to close the batch identified by the merchid and batchid. Provide a batchid to attempt to close a specific batch. If no batchid is supplied, the open batch with the lowest batchid is closed.

closebatch URL

closebatch Request

Fields in bold are required.

closebatch Response

Using the settlestatByBatchSource Endpoint

A call to the settlestatByBatchSource service endpoint returns the settlement status and details for all transactions in a given batch, identified by the batchsource.

settlestatByBatchSource URL

settlestatByBatchSource Request

Fields in bold are required.

settlestatByBatchSource Response