Skip to main content

Pre-requisite to use e-commerce API

To use the Verifone e-commerice API authentication, a merchant must obtain an access token. This access token is attached to API request and inspected for a valid signature and expiration time by the Verifone API Gateway.

How to obtain the API key and secret

A Verifone employee will onboard a merchant and provide the following:

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

With this information combination, you can authenticate/authorize and recieve 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 recevied 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)

 

About us

Verifone logo

Contact

Support

 

Facebook  Twitter  Linkedin