Skip to main content

Online Payments

Rate this article:

Note! The expiration date of API Keys is one year from the date of activation. The system automatically sends email notifications every week during the last three months and every day during the last week before the expiration date.
 

Obtaining API Keys

In the recent update of Entity Service and Verifone Central, it is now possible to generate the API Keys directly in the Admin Panel. 

To obtain the keys, follow the steps below.

  1. Ensure the valid user logged into the necessary site.
     
  2. Navigate to the user settings at the top right corner, and select the "API Keys" option from the dropdown menu.

    API Keys Menu Icon

  3. On the API Keys page, click the "Create API Key" button.

    Create API key

  4. To copy the key, click the "Copy public key" button and paste it to a safe location. Once the key has been copied, the success message will appear at the right bottom corner of your screen. Note: Your API key expiration period is one year.

    API Key Created

    API Keys Page

  5. Navigate back to the "My Account" page.

    My Account

  6. Locate your "user-uid" by highlighting and copying the rest of the URL in your browser's address field. See the screenshot below.

    Locating user-uid

Encoding API Key

To encode API keys, follow the authentication method below.

  1. Indicate Authorization: Basic "user-uid:api key" in the header.
  2. Replace the "user-uid" and "api key" values with the necessary ones.
  3. Encode the whole string in base64.

For example:
The following "user-uid:api key" string 777c31b3-a85f-4823-93a5-9055d1b:cGEFFLjYuUCtmerXlhTfAdaPpYVnXDJZmg

results in a base64 Nzc3YzMxYjMtYTg1Zi00ODIzLTkzYTUtOTA1NWQxYjpjR0VGRkxqWXVVQ3RtZXJYbGhUZkFkYVBwWVZuWERKWm1n

Thus, the header should look like this:

Authorization: Basic Nzc3YzMxYjMtYTg1Zi00ODIzLTkzYTUtOTA1NWQxYjpjR0VGRkxqWXVVQ3RtZXJYbGhUZkFkYVBwWVZuWERKWm1n

 

Setting up Basic Auth in Postman

To set up Basic Auth in Postman, follow the steps below. Additionally, you can create a new collection by downloading our OpenAPI specification file available here.
    

  1. Navigate to the GET Health check menu item on the Collections page.
  2. Click the Authorization menu item below the request URL field.
  3. Choose the Basic Auth option from the Type dropdown list.
  4. To send the request, paste your "user-uid" into the username field and "api key" into the password. See the screenshot below.

    Basic Auth in Postman

Legacy

The legacy method for authentication with the Verifone APIs can be found here.

Prerequisite to using APIs

To authenticate with the Verifone APIs, you must obtain an access token. This access token is attached to API requests and inspected for a valid signature and expiration time when performing API calls.

How to obtain the API key and secret

You will be provided with the following details during onboarding:

  • API key
  • Secret for API key (associated to the key)
  • Scope

Use the following links for each environment:

US Production https://us.vam.verifone.cloud/oauth2/realms/root/realms/VerifoneServices/access_token
Global Sandbox https://cst1.test-vam.vfims.com/oauth2/realms/root/realms/VerifoneServi…

With this information combination, you can authenticate/authorize and receive the access token.

How to obtain the access token

The access token is formatted as a JWT (Json Web Token).

The OAuth2.0 Client Credential grant flow is used to get the access token. Your application will need to have the API key and secret stored securely.

Perform the following call to get your access token:

curl -k --request POST \
        --data "grant_type=client_credentials" \
        --data "client_id=${APIKEY}" \
        --data "client_secret=$API_SECRET}" \
        --data "scope=${SCOPE}" \
        https://cst1.test-vam.vfims.com/oauth2/realms/root/realms/VerifoneServices/access_token

Request parameters

  • client_credentials - indicating that Client Credentials grant is in use,
  • scope - must be at least one custom scope received from Verifone.

Response parameters

  • access_token: Contains the access token in JWT Format RFC 7519.
  • expires_in: Contains the expiration time in seconds for the access token. Once the access token expires, you should send a new request to the authorization endpoint in order to re-authenticate your application.
  • scope - Contains the list of all the scopes associated with the "access_token".

Example access token

If the credentials are valid, the application will receive back an access token in JSON Web Token (JWT).

Example access token:

eyJ0eXAiOiJKV1QiLCJ6aXAiOiJOT05FIiwia2lkIjoid1UzaWZJSWFMT1VBUmVSQi9GRzZlTTFQMVFNPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI1OWJlYjAzNy1kNjRhLTQyMjgtODM2NC0wZWQ1NDAyMDVmZDUiLCJjdHMiOiJPQVVUSDJfU1RBVEVMRVNTX0dSQU5UIiwiYXVkaXRUcmFja2luZ0lkIjoiN2NlYzIzZGItNjc1ZC00ZDJmLWFmMmYtZTkxZjQ4ZGY4NzJkLTQ3NDM2IiwiaXNzIjoiaHR0cHM6Ly9xYXQxLnRlc3QtdmFtLnZmaW1zLmNvbS9vYXV0aDIvcmVhbG1zL3Jvb3QvcmVhbG1zL1Zlcmlmb25lU2VydmljZXMiLCJ0b2tlbk5hbWUiOiJhY2Nlc3NfdG9rZW4iLCJ0b2tlbl90eXBlIjoiQmVhcmVyIiwiYXV0aEdyYW50SWQiOiJLOFF1SGFxYnpVTnhIVVVRak04d2FaRmF6bjgiLCJhdWQiOiJNYXJrZXRwbGFjZU9hdXRoIiwibmJmIjoxNTk2OTcwODc1LCJncmFudF90eXBlIjoiY2xpZW50X2NyZWRlbnRpYWxzIiwic2NvcGUiOlsibWFya2V0cGxhY2UiXSwiYXV0aF90aW1lIjoxNTk2OTcwODc1LCJyZWFsbSI6Ii9WZXJpZm9uZVNlcnZpY2VzIiwiZXhwIjoxNTk2OTcxMDU1LCJpYXQiOjE1OTY5NzA4NzUsImV4cGlyZXNfaW4iOjE4MCwianRpIjoidmtRZ01kZW03bm1VYTItT1FZeHRKM1dQMC1BIiwiZW50aXR5X2lkIjoiODEwNDlmZDEtNjEyNi00ZDQxLTg0MTYtYWEzNTZjNDk4Y2NhIiwicm9sZXMiOiJbVkVSSUZPTkVfQURNSU5dIn0.YW4MeQAMJgpLM3pOFtnx1KXJfSTTHYLklmxld8NozBuA_lQNrO9kN5Sai3MC4roOavcOYbs_TXNP2jXkOE9tNmgGUGHVtiITTIltBAJ2O7s_QCNu6v1k3tTK0-GfE5gC4I2TavwBN3nFoXmNQYbzcAh3Qetudh5A-KlsxeepeyxrLfj0BX2NbK5tVEisI1si7yS89aBJvEvCGcKTw5Ujte8naYZCGUJJUIaE2HXk-DGCNdNpmFD9_hnoDWKnN9n3ABuUW4Z6LoAW0J-BgKpuO6BroweL8fiCWYHV79f_0hCbm7sUqBmcal9j7pc4J2luy0k7TxOexHfry7w2JbpTBQ

To inspect the token, you can use Jwt.io or you can use the jwt command line tool.

$ cat Token.txt | xargs  jwt decode

Token header
------------
{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "wU3ifI23aqasB/FG6eM1P1QM="
}

Token claims
------------
{
  "aud": "VerifoneOauth",
  "auditTrackingId": "7cec23db-555-6666-7777-999999999-47436",
  "authGrantId": "K8QuHaqbzUJAQWSM8waZFazn8",
  "auth_time": 1596970875,
  "cts": "OAUTH2_STATELESS_GRANT",
  "entity_id": "81049fd1-6126-4d41-8416-aa356c498cca",
  "exp": 1596971055,
  "expires_in": 180,
  "grant_type": "client_credentials",
  "iat": 1596970875,
  "iss": "https://cst1.test-vam.vfims.com//oauth2/realms/root/realms/VerifoneServices/access_token",
  "jti": "vkQgMdem7nmUa2-OQYxtJ3WP0-A",
  "nbf": 1596970875,
  "realm": "/VerifoneServices",
  "roles": "[VERIFONE_TEST]",
  "scope": [
    "verifoneScope"
  ],
  "sub": "59beb037-d64a-4228-8364-0ed540205fd5",
  "tokenName": "access_token",
  "token_type": "Bearer"
}

Access Token Format

Obtained Access Token is in JWT format [RFC 7519]

Header

# Claim Content Claim Name Claim type
1 "alg" RS256 Hashing algorithm (RS256 - RSASSA-PKCS-v1_5 using SHA-256) Registered
2 "typ" JWT The type of the token Registered
3 "kid" Key Identifier ("1ee4d9e7dcfef215d133c7ed7ac87c95f8d8e712") Key ID (which key was used to secure the JWS) Registered[RFC7515]

Payload

# Claim Content user ID Claim type
# Claim Content Claim Name Claim type
1 "sub" "5f8a9877-965c-4d25-bc86-45d1cfc1c324" Subject (User UUID) Registered
2 "entity_id" "a4994358-a475-4ee2-aefe-acefd622991c" User associated Entity_id Private
3 "iss" "https://identity.vfims.com/oauth2/realms/root/realms/MerchantApp" Issuer Registered
4 "aud" "Verifone View" Audience - recipient for which the JWT is intended Registered
5 "iat" 1516239022 Issued At Time Registered
6 "exp" NumericDate value Expiration Time Registered
7 "nbf" 1568783970 (Not Before Time) - Time before which the JWT must not be accepted for processing Registered
8 "roles" ["MERCHANT_REVIEWER", "MERCHANT_DEVELOPER"] User associated role(s) Private
9 "jti" TO6JCVdqS4hJB3_DzVurB3HOe9s (JWT ID) - Unique identifier; can be used to prevent the JWT from being replayed Registered
10 "scope" Merchant Scope Scopes (limit the API category that can be accessed) Registered
11 "auditTrackingId" cbadf943-c28c-450b-bd53-ef11c2b7d80c-17881178 AM correlation to audit trail Private
12 "auth_level" 0 AM Authentication level Private
13 "tokenName" access_token Token description Private
14 "realm" "/MerchantApp" AM authentication realms Private

Signature

The result of the following computation:

JWT_Hash = SHA256(Header + Payload)
JWT_Signature = RS256(JWT_Hash, Private_key)

 

Rate this article:
Logo of Verifone