We've compiled the most frequently asked questions we've received from our integrators who use the Unified Payments REST API (formerly known as GP-API or UCP). If you don't see your question below, contact Integration Support.

Access Tokens

Time to live

Can I control when an access token expires?

Yes. You can set the interval_to_expire or the seconds_to_expire in the access token create call. The default is 24 hours, or 86,399 seconds. 

For steps on how to create an access token, see Access Tokens in API Definitions.

How long should an access token live for? 

The default on our system is 24 hours. We recommend never to go over that.

The shorter the time period, the less risk associated with a compromised token being used to execute actions. Some merchant integrations use a per-transaction interval. Some replace it every 30 minutes for up to 24 hours. However, it’s up to you to decide how long the access token should live.

Consider things like security requirements, customers, and the needs of your business. If you’re unsure, we recommend setting it for 1 hour or less. Whatever interval you choose, it’s important that your integration can automatically handle 401 Not Authenticated HTTP responses.

Authentication

What are the steps needed to make an online sale using 3D Secure?

For specific steps using either direct API integration or our Hosted Fields solution, see our Browser Authentication for 3D Secure article.

Here's the basic flow:

1. Tokenize card
2. Check version
3. Initiate authentication
4. Obtain result
5. Transaction authorization

Can the API handle all versions of 3D Secure?

Yes. Our Unified Payments REST API handles all versions of 3D Secure 2. This ensures that one integration works with whatever version is used in your region.

For more information, see our 3D Secure & SCA - Overview article.

Configuration

Accounts

What are accounts?

An account defines a configured capability a merchant has when using our API. Some examples of capabilities include Transaction Processing, Tokenization, Dispute Management, and Settlement Reporting.

What’s the significance of the account_name field required in each call?

The account_name field defines the merchant’s API configuration capability and identifies what data the API request can access.

Some examples of account_name field values include:

• transaction_processing
• tokenization
• dispute_managment
• settlement_reporting

Disputes

Settled versus real-time

What is the difference between settled disputes and real-time disputes?

Here’s how we define the two:

• Settled disputes are those disputes that directly affect your bank account and have a financial impact on you.
• Active disputes are a real-time view of your disputes and what status each one has. 

You can implement Dispute Management actions via the API to challenge, accept, and report on all your disputes. For more information, see our Disputes Management article.

Why is the settled disputes response structure different from active disputes?

Settled disputes and active disputes originate from different accounts. Therefore, the API endpoint and response structure is slightly different.

Integration

Process

What do I need to go to a live Production environment?

We’re happy to help you move from our Sandbox to Production. But first, there's some information we’ll need from you:

• Your Sandbox App ID
• The API capabilities you want to use
• Your Ecom API Client ID if you’re currently using Ecommerce XML API
• Whether you want to use Settlement Reporting and whether we are your Acquirer (required to use this capability)

Once you’ve provided us with the above information, we’ll take a look at your Sandbox activity. If everything looks good on your side and passes our validation checks, we’ll create API Production credentials for you and will be in touch to exchange them. In most cases, you’ll hear back from us within 24 hours. 

How do I create a real account, not a Sandbox account?

First, you’ll need to fill out a Merchant Service Agreement with us, which will enable you to get paid for transactions successfully processed via the API.

To get started, visit our main website: https://www.globalpaymentsinc.com/

Your integration will be validated based on the features you need. Once validation passes, we’ll contact you to exchange Production credentials. In most cases, you’ll hear back from us within 24 hours.

If you’re coding to implement customer-present transactions, please email certintake@globalpay.com to let us know.

What do I need to do once I go live?

First, congratulations on going live (or at least planning to)!

Second, you’ll need to do a little testing in Production and process a real transaction. Confirm that your integration works as expected and also that the merchant's funds are deposited into the correct bank account.

Settlement Reporting

Can I use Settlement Reporting in the API if I use another Acquirer?

No. It’s not possible for us to retrieve settlement data from another bank. You’ll need to use us as your Acquirer if you want to use this feature.

Why does Settlement Reporting return a list of test transactions instead of real ones?

In Sandbox, the settlement data is delivered via a standalone test harness, and reporting doesn’t generate from integration activity. In other words, the transactions you execute in Sandbox aren’t batched and flagged for settlement. However, the data does reflect Production. 

What’s the difference between Real-Time and Settlement Reporting?

Here’s how we define the two:

• Real-Time Reporting returns a report of all transactions done in real time for a merchant. A transaction can be seen in the report 5 seconds after the transaction is done. In order to use this API feature, the merchant must process their transactions through the API.
• Settlement Reporting returns a list of all transactions that have affected a merchant’s bank account for a certain period of time. This data is available the day after a transaction has been processed. In order to use this API feature, the merchant must use us as their Acquirer.

Specifications

OpenAPI Specification (OAS)

Where can I find a list of field definitions?

We’ve included a list of field definitions on this Developer Portal in the API Explorer (see API Definitions). 

Where can I find a list of all request and response parameters for each of the APIs?

We’ve included a list of request and response parameters in the payload of each of the APIs in the API Explorer.

• Access token
• Transactions
• Verifications
• Stored Payment Methods
• Deposits
• Disputes
• Actions
• Authentications

Transactions

Real-Time Reporting

Why aren’t successful transactions displayed on our reporting portal? 

Most likely it’s because you're using Sandbox and not Production. In Sandbox, the transactions are available via the Reporting API but not the portal. However, once an integration goes live, the transactions are available in the reporting portal.

What is the difference between Real-Time and Settlement Reporting?

See our answer in the Settlement Reporting section.