Guides

Getting Connected and Authenticated

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

Suggest Edits

Environments

PaymentExpress provides three customer-accessible environments to facilitate your integration and testing:

  • Beta (https://beta.gsg.tech/api/v1) - Earliest access non-production environment to be used during early phases of integration for testing credentials, client system development, etc. Does not accept real payment tenders and does not make any real charges on payment networks.
  • Demo (https://demo.gsg.tech/api/v1) - Most stable non-production environment which should mirror the production environment, except that, like Beta, does not accept real payment tenders and does not make any real charges on payment networks.
  • Production: (https://www.gsg.tech/api/v1) - Live production environment which takes real payment tenders and will make real financial transactions.

In addition to these three production environments for our standard APIs, any API requests that will contain payment tender information go to our Card Data Vault environment, which also has 3 available environments, matching those of the standard API environments:

Finally, for integrations which use our Grant Street Windows Application, the API is available on your locally installed instance of GWA at:

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 (which is generally 8 hours - the expiration time is returned in the token response), and re-use 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 value 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

You will be provided with two separate sets of PaymentExpress API credentials. One of these pairs of credentials is to be used when accessing non-production environments such as beta or demo, and one is to be used exclusively in the production PaymentExpress environment.

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.

Re-using JWTs will both ensure that your communication is resilient to failures, but also ensure that you are less likely to hit request volume limits.

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 both for checking access to the API service, but also for 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 which point the API will also authenticate your 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. In the event that you have successfully provided the JWT, the authed value will also be true. In the event that you have made a mistake with your Authorization header, other error responses are possible. Please see the /ping endpoint documentation for more details.

Updated 2 months ago