Guides

Getting Connected and Authenticated

A Guide for helping you authenticate and check your connection to the PaymentExpress APIs.

Environments

PaymentExpress provides three customer-accessible environments for integration and testing:

  • Beta (https://beta.gsg.tech/api/v1) - Used during early development phases. Supports credential validation and early system integration. Does not process real payments.
  • Demo (https://demo.gsg.tech/api/v1) - Mirrors Production behavior as closely as possible. Normally used for UAT and pre-deployment testing. Does not process real payments.
  • Production: (https://www.gsg.tech/api/v1) - Live production environment for processing real customer payments.

Any API request that contains payment tender data must use the Card Data Vault environment, which also has Beta, Demo, and Production equivalents:

If you are integrating with the Grant Street Windows Application, API access is local:

PaymentExpress IP Block

If your application limits inbound access from other applications, you will need to allowlist PaymentExpress’s IPs. This block is for production and non-production: 170.178.156.0/22

Getting an Authentication Token (JWT)

Authentication to the PaymentExpress API is accomplished with an OAuth2 client credentials JWT request. When you complete an authentication token request to the auth token API, you will receive a JWT (Javascript Web Token) per the OAuth2 standard. You should cache this token for the duration of its lifetime by using the expiration time returned in the token response, and reusing it for any requests made to the API during this time.

When requesting your JWT, you will need to request a set of scopes, which are the portions of the PaymentExpress API you are requesting permission to use with that token. Each token can have one or more scopes, and you should request the scopes that match the business processes for which you intend to use that token. The following scopes are available:

  • pay:carts - Scope required for doing online cart transactions
  • pay:carts:otc - Scope required for doing Hosted In Person cart transactions
  • pay:inperson - Scope required for doing Embedded In Person transactions
  • pay:voice - Scope required for doing Voice Cart transactions
  • pay:payments - Scope required for doing payment reconciliation tasks

Make Your Request

To make an auth token request, you will need to POST an OAuth2 client credentials request with a application/x-www-form-urlencoded encoded body, such as the example below.

POST /api/v1/auth/token

grant_type=client_credentials&scope=pay%3Acarts&client_id=(id)&client_secret=(password)

In the example above, you will provide the grant_type (which is always client_credentials) and the list of scopes you are requesting, space separated. The client_id and client_secret values can be provided either on the form body itself or using HTTP Basic Authentication. These credentials will have to be provided to you by your PaymentExpress Implementation Team.

🔐

PaymentExpress API Credentials

PaymentExpress will provide two separate PaymentExpress API credentials, one for accessing non-production environments (beta or demo) and one for production environments. PaymentExpress will send the values securely. Do not share these credentials in an insecure manner, such as through email or by storing them in plain text.

In the event that you have crafted a successful token request, you will receive an HTTP 200 response, which includes a JSON body formatted like the following:

{
  "access_token": "JSDKLF...",
  "expires_in": 3600,
  "scope": "client:clientcode pay:carts",
  "token_type": "Bearer"
}

The value in the access_token is your token to be attached to your further API requests, as explained below in "Using Your Authentication Token."

⏲️

Caching and Re-Use of JWTs

A JWT has a lifetime that can run from hours to days, which is provided in the expires_in field of the token request response. Once you have received a token, you are expected to cache the token and its expiration time, and reuse this token for as many subsequent requests as possible up until at least 80% of the expiration time of the JWT before fetching a new JWT.

Reusing JWTs ensures that your communication is resilient to failures and reduces the likelihood of hitting request volume limits. It can also protect you in the case of an authorization outage, as you can continue to reuse a cached JWT until its expiry, making the outage non-impactful.

For more details, please see the /auth/token endpoint documentation.

Using Your Authentication Token

To use your authentication token successfully in subsequent requests, you should add it as an HTTP Authorization header that is formatted like the following:

Authorization: Bearer JSDKLF...

Test Your Authentication Token

The PaymentExpress API provides another endpoint that is useful for both checking access to the API service and validating that you are holding a valid authentication token and supplying it correctly in your requests, without performing any business operations. This is the /ping endpoint.

To perform a ping request, simply send a GET request to /api/v1/ping. You may optionally include the Authorization header with your request; at this point, the API will also authenticate the provided JWT. The ping response will look like the following:

{
  "pong": true,
  "authed": true
}

The pong value will always be true so long as the service is available. If you have successfully provided the JWT, the authed value will also be true. If you have made a mistake with your Authorization header, other error responses may occur. Please see the /ping endpoint documentation for more details.

Updated 19 days ago

Did this page help you?