Authorize

Summary

Authorize is our implementation of the OAuth 2.0 framework. It enables secure authorization using standard methods that can easily be integrated in your app. If you're familiar with OAuth 2.0, everything should look familiar. If not, you may want to check out the OAuth 2.0 resources here.

Want to try this API out on our Playground?

Go play now

Endpoints on this page

post /clientCredentials/oauth2/token/hk/gcb	Client Credentials Grant: Retrieve Access Token
get /authCode/oauth2/authorize	Authorization Code Grant: Retrieve Authorization Code
post /authCode/oauth2/token/hk/gcb	Authorization Code Grant: Retrieve Access Token
post /authCode/oauth2/refresh	Authorization Code Grant: Refresh Access Token
post /authCode/oauth2/revoke	Authorization Code Grant: Revoke Access Token
post /cardAuth/oauth2/authorize/{countrycode}/{businesscode}	Enroll and Generate Card Access Token
post /cardAuth/oauth2/token/{countrycode}/{businesscode}	Activate Card Access Token
post /cardAuth/oauth2/refresh	Refresh Card Access Token
post /cardAuth/oauth2/revoke	Revoke Card Access Token
post /v1/issuedDeviceAdministration/accessToken/retrieve/{countryCode}/{businessCode}	JSON Web Encryption (JWE) Custom Grant: Rerrieve Access Token
post /v1/issuedDeviceAdministration/accessToken/refresh	JSON Web Encryption (JWE) Custom Grant : Refresh Card Access Token
post /v1/issuedDeviceAdministration/accessToken/revoke	JSON Web Encryption (JWE) Custom Grant: Revoke Card Access Token
put /partner/v1/mfa/statuses	Multi-Factor Authentication: Status Update
get /partner/v1/prelogin/security/e2eKey	Retrieve E2E Public Key Pre-login
post /partner/v1/prelogin/security/e2eKey	Client Credentials grant: Retrieve access token

Client Credentials Grant: Retrieve Access Token

post /clientCredentials/oauth2/token/hk/gcb

Description

This API is used to retrieve the access token for your application credentials. You can use this for APIs which do not require customer credential verification and consent (e.g. Onboarding).

Swagger

Header Parameters

Authorization

string required

HTTP Basic authentication by passing base64 encoded value of the client id and client secret separated by colon (:).Example: Base64(client_id:client_secret) will be passed as Basic KGNsaWVudF9pZDpjbGllbnRfc2VjcmV0KQ==

Content-Type

string required

Value should always be application/x-www-form-urlencoded

FormData Parameters

grant_type

string required

The grant type. Valid value is client_credentials.

scope

string required

The set of scopes requested to make API calls. You can pass multiple values delimted by space

cURL
Ruby
Python
PHP
Java
Node
Go
Swift

Example Request

Responses

The request has succeeded

Definitions

access_token
- The access token value received after exchanging the authorization token. This field should be passed as Authorization header in API request calls
- type : string
refresh_token
- You can use this token to refresh an expired access_token.
- type : string
scope
- Set of scopes allowed by customer and separated by space
- type : string
token_type
- Type of the access token issued. This is bearer token for authorization_code grant type
- type : string
expires_in
- Validity of access token in seconds
- type : number

Example Response for post /clientCredentials/oauth2/token/hk/gcb

error

invalid_request

invalid_grant

unsupported_grant_type

unauthorized_client

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /clientCredentials/oauth2/token/hk/gcb

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

error

invalid_client

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /clientCredentials/oauth2/token/hk/gcb

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

server_error

This operation returns no content.

Authorization Code Grant: Retrieve Authorization Code

get /authCode/oauth2/authorize

Description

This API is used to validate the customer credentials in Citi login Page and redirect back the authorisation code post successful validation.

Swagger

Query Parameters

response_type

string required

Value MUST be set to "code"

client_id

string required

Client ID generated during application registration.

scope

string required

The set of scopes required to make the API calls. Scope is case insensitive and multiple values can be passed using space delimiter.

countryCode

string required

Country code in 2 character ISO 3166 format (upper case)

businessCode

string required

The 3 character business code. Use GCB for consumer banking (upper case)

locale

string required

Locale identify a specific language and geographic region, it shoule follow [language[_territory]. eg - en_US, en_SG

state

string required

Opaque value to maintain the state between request and call back. This will be used to prevent cross-site request forgery.

redirect_uri

string required

Absolute uri for user-agent redirection.You should provide the uri used during client registration process.

cURL
Ruby
Python
PHP
Java
Node
Go
Swift

Example Request

Responses

Client Authentication

This operation returns no content.

The authorization response contains the authorization code needed to obtain an access token. Here are the parameters included in the response.

success response
field name	field type	mandatory	description
redirect_uri	location	yes	This is the absolute uri provided in the request
code	query	yes	The authorization code
state	query	yes	The same value as sent by the client in the state parameter, if any

If an error occurs during authorization, two situations can occur. The first is, that the client is not authenticated or recognized. For instance, a wrong redirect URI was sent in the request. In that case the authorization server must not redirect the resource owner to the redirect URI. Instead it should inform the resource owner of the error. The second situation is that client is authenticated correctly, but that something else failed. In that case the following error response is sent to the client, included in the redirect_uri

failure response
field name	field type	mandatory	description
redirect_uri	location	yes	This is the absolute uri provided in the request
state	query	yes	The same value as sent by the client in the state parameter, if any
error	query	yes
error_description	query	no
error_uri	query	no

Here is the list of errors:

error

invalid_request

unauthorized_client

unsupported_response_type

invalid_scope

access_denied

This operation returns no content.

server_error

This operation returns no content.

temporarily_unavailable

This operation returns no content.

Authorization Code Grant: Retrieve Access Token

post /authCode/oauth2/token/hk/gcb

Description

This API is used to validate the authorisation code and return back the access token.

Swagger

Header Parameters

Authorization

string required

Content-Type

string required

Value should always be application/x-www-form-urlencoded

FormData Parameters

grant_type

string required

Authentication grant type. Valid value is authorization_code

code

string required

The code from the response of GET /authCode/oauth2/authorize

redirect_uri

string required

Absolute uri for user-agent redirection. You should provide the uri passed in GET /authCode/oauth2/authorize request

cURL
Ruby
Python
PHP
Java
Node
Go
Swift

Example Request

Responses

The request has succeeded

Definitions

access_token
- The access token value received after exchanging the authorization token. This field should be passed as Authorization header in API request calls
- type : string
refresh_token
- You can use this token to refresh an expired access_token.
- type : string
scope
- Set of scopes allowed by customer and separated by space
- type : string
token_type
- Type of the access token issued. This is bearer token for authorization_code grant type
- type : string
expires_in
- Validity of access token in seconds
- type : number

Example Response for post /authCode/oauth2/token/hk/gcb

error

invalid_request

invalid_grant

unsupported_grant_type

unauthorized_client

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /authCode/oauth2/token/hk/gcb

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

error

invalid_client

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /authCode/oauth2/token/hk/gcb

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

server_error

This operation returns no content.

Authorization Code Grant: Refresh Access Token

post /authCode/oauth2/refresh

Description

This API is used to exchange for a new set of valid access and refresh tokens in case access token has expired and still have a valid refresh token.

Swagger

Header Parameters

Authorization

string required

Content-Type

string required

Content type. Value is application/x-www-form-urlencoded

FormData Parameters

grant_type

string required

The grant type. Valid value is refresh_token.

refresh_token

string required

The refresh token issued to the client

cURL
Ruby
Python
PHP
Java
Node
Go
Swift

Example Request

Responses

The request has succeeded

Definitions

access_token
- This field should be passed as Authorization header in API request calls
- type : string
refresh_token
- The refresh token value
- type : string
scope
- The list of scopes separated by space
- type : string
token_type
- The token type
- type : string
expires_in
- The access token expiry time (in seconds)
- type : number

Example Response for post /authCode/oauth2/refresh

error

invalid_request

invalid_grant

unsupported_grant_type

unauthorized_client

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /authCode/oauth2/refresh

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

error

invalid_client

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /authCode/oauth2/refresh

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

server_error

This operation returns no content.

Authorization Code Grant: Revoke Access Token

post /authCode/oauth2/revoke

Description

This API is used to revoke the access token. Along with the access token, the corresponding refresh token is also revoked and vice-versa.

Swagger

Header Parameters

Authorization

string required

Content-Type

string required

Content type. Value is application/x-www-form-urlencoded

FormData Parameters

token

string required

The token to be revoked

token_type_hint

string required

A hint about the type of the token submitted for revocation. Clients MAY pass this parameter in order to help the authorization server to optimize the token lookup. Valid values are access_token, refresh_token

cURL
Ruby
Python
PHP
Java
Node
Go
Swift

Example Request

Responses

The request has succeeded

Definitions

status
- The status of the token revocation request.
- type : string

Example Response for post /authCode/oauth2/revoke

error

invalid_request

invalid_grant

unauthorized_client

unsupported_grant_type

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /authCode/oauth2/revoke

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

error

invalid_client

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /authCode/oauth2/revoke

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

server_error

This operation returns no content.

Enroll and Generate Card Access Token

post /cardAuth/oauth2/authorize/{countrycode}/{businesscode}

Description

This API is used to enroll the customer to avail services like Rewards Redemption, EPP, LOP etc. from the partner's site through a common registration.

Swagger

Header Parameters

Authorization

string required

uuid

string required

128 bit random UUID generated uniquely for every request.

string required

Content-Type that are acceptable for the response.

client_id

string required

Client ID generated during application registration.

Content-Type

string required

application/json

clientDetails

string Optional

This field is used to capture device,browser and network information. Refer the developer portal for more information.These are the fields which will be passed as part of the header devicePrint,deviceTokenCookie,userIpAddress,userAgent,hardwareId,simId,deviceModel,deviceName,deviceOsName,deviceOsVersion,multitaskingSupportFlag,languageSupport,wifiMacAddress,cellTowerId,locationAreaCode,rsaApplicationKey,wapClientId,mobileCarrierCode,mobileCountryCode,osId,geoLongitude,geoLatitude,geoHorizontalAccuracy,geoAltitude,geoAltitudeAccuracy,geoSpeed,geoTimestamp,geoStatus,basicServiceSetId,signalStrength,wifiChannel,serviceSetId

channelId

string Optional

ChannelId

ConsumerOrg

string Optional

ConsumerOrg

Body Parameters

CardAuthorizationRequest

required

CardAuthorizationRequest

{
    "properties": {
        "grant_type": {
            "description": "The grant type. Valid value is refresh_token",
            "type": "string",
            "example": "card_authorization"
        },
        "lastFourDigitsCardNumber": {
            "description": "Last four digits fof the card number",
            "type": "string",
            "example": "5212"
        },
        "citiCardHolderPhoneNumber": {
            "description": "Phone Number of the citi primary card holder which is registered with Citi bank",
            "type": "string",
            "example": "11112222"
        },
        "merchantCustomerReferenceId": {
            "description": "Denotes the unique reference which merchant has for a particular customer.",
            "type": "string",
            "example": "CB072000128065"
        }
    },
    "required": [
        "lastFourDigitsCardNumber",
        "citiCardHolderPhoneNumber",
        "merchantCustomerReferenceId",
        "grant_type"
    ]
}

Path Parameters

countrycode

string required

Countrycode

businesscode

string required

Businesscode

cURL
Ruby
Python
PHP
Java
Node
Go
Swift

Example Request

Responses

Successful operation.

This operation returns no content.

Type	Code	Details
invalid	invalid_request	Missing or invalid Parameters

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/authorize/{countrycode}/{businesscode}

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
error	unAuthorized	Authorization credentials are missing or invalid

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/authorize/{countrycode}/{businesscode}

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
error	accessNotConfigured	The request operation is not configured to access this resource
error	mfaRequired	MFA is required

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/authorize/{countrycode}/{businesscode}

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
error	registrationFailed	Registration failed
invalid	invalid_grant	The provided access grant is invalid, expired, or revoked

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/authorize/{countrycode}/{businesscode}

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
fatal	serverUnavailable	The request failed due to an internal error

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/authorize/{countrycode}/{businesscode}

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Activate Card Access Token

post /cardAuth/oauth2/token/{countrycode}/{businesscode}

Description

This API activates customer's access token. Separate token activation is required for each credit card held by the customer.

Swagger

Header Parameters

Authorization

string required

uuid

string required

128 bit random UUID generated uniquely for every request.

string required

Content-Type that are acceptable for the response.

client_id

string required

Client ID generated during application registration.

Content-Type

string required

application/json

clientDetails

string Optional

channelId

string Optional

channelId

ConsumerOrg

string Optional

ConsumerOrg

Body Parameters

CardAuthorizationAccessTokenRequest

required

CardAuthorizationAccessTokenRequest

{
    "properties": {
        "grant_type": {
            "description": "The grant type. Valid value is refresh_token",
            "type": "string",
            "example": "card_authorization"
        },
        "controlFlowId": {
            "description": "Control Flow ID",
            "type": "string",
            "example": "44125873852316f2b4d4d796c344e38756339654972776f663745446e6d4c32486f455a4165374a476858343d"
        },
        "linkageConfirmationCode": {
            "description": "Confirmation for activation",
            "type": "string",
            "example": 123455
        }
    },
    "required": [
        "controlFlowId",
        "linkageConfirmationCode"
    ]
}

Path Parameters

countrycode

string required

Countrycode

businesscode

string required

Businesscode

cURL
Ruby
Python
PHP
Java
Node
Go
Swift

Example Request

Responses

Successful operation.

Definitions

token_type
- The token type
- type : string
expires_in
- The access token expiry time (in seconds)
- type : integer
- format : int32
scope
- The list of scopes separated by space
- type : string
refresh_token
- The refresh token value
- type : string
cardId
- The card id in encrypted format
- type : string
access_token
- This field should be passed as Authorization header in API request calls
- type : string
refresh_token_expires_in
- This refer to the time in refersh token expiry
- type : integer
consented_on
- This refer to the customer consent time for authorization
- type : string
customerId
- Customer number in the encrypted format
- type : string
cardReferenceNumber
- Partner will include Card reference number in the settlement file to sent it to Citi to aprove the purchase
- type : string

Example Response for post /cardAuth/oauth2/token/{countrycode}/{businesscode}

Type	Code	Details
invalid	invalidRequest	Missing or invalid Parameters

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/token/{countrycode}/{businesscode}

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
error	unAuthorized	Authorization credentials are missing or invalid

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/token/{countrycode}/{businesscode}

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
error	accessNotConfigured	The request operation is not configured to access this resource

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/token/{countrycode}/{businesscode}

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
error	activationFailed	Link code activation is failed
error	exceedsMaximumAttempts	Maximum attempts exceeded for activation. Link credit card to a merchant again.
error	linkageConfirmationCodeExpired	The linkage confirmation Code is expired . Link credit card to a merchant again.

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/token/{countrycode}/{businesscode}

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
fatal	serverUnavailable	The request failed due to an internal error

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/token/{countrycode}/{businesscode}

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Refresh Card Access Token

post /cardAuth/oauth2/refresh

Description

This API generates a fresh access token. If your access token has expired and you still have a valid refresh token, you can exchange it for a new set of valid access and refresh tokens.

Swagger

Header Parameters

Authorization

string required

uuid

string required

128 bit random UUID generated uniquely for every request.

string required

Content-Type that are acceptable for the response.

client_id

string required

Client ID generated during application registration.

Content-Type

string required

application/json

clientDetails

string Optional

Body Parameters

CardAuthorizationRefreshTokenRequest

required

CardAuthorizationRefreshTokenRequest

{
    "properties": {
        "grant_type": {
            "description": "The grant type. Valid value is refresh_token",
            "type": "string",
            "example": "card_authorization"
        },
        "refresh_token": {
            "description": "The refresh token issued to the client",
            "type": "string",
            "example": "AAGsyASCzlBplxGvA-5CFCkLhNinu6-0HQt-y7PuzsRLVAHok6yYs6KS2Np4t7bL0R8FMeT62wYXFxxY6F7LU_cc00QTXPfoQFFtay2tu3eGpBAGDg07ll_vNk_AEJo9l1GaEKYev7Q7drDOeRCDRqcD12zJzk36PsQEM6j1txFV2jR3snW5PLs3HVjxNRjUHWLR5IoI2qfb8zCZNahrFCRQ7T7ZVB_-E6Qk22tN3hZkZH7_kB3bZjtVoNxyjJ6qBDcrYdgtAvPvBV-xXDBmfUXD44JBYiZffHjEr2dFb_e3yA"
        }
    },
    "required": [
        "refresh_token"
    ]
}

cURL
Ruby
Python
PHP
Java
Node
Go
Swift

Example Request

Responses

Successful operation.

Definitions

token_type
- The token type
- type : string
access_token
- This field should be passed as Authorization header in API request calls
- type : string
expires_in
- The access token expiry time (in seconds)
- type : integer
- format : int32
scope
- The list of scopes separated by space
- type : string
refresh_token
- The refresh token value
- type : string
cardId
- The card id in encrypted format
- type : string

Example Response for post /cardAuth/oauth2/refresh

Type	Code	Details
invalid	invalidRequest	Missing or invalid Parameters

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/refresh

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
error	unAuthorized	Authorization credentials are missing or invalid

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/refresh

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
error	accessNotConfigured	The request operation is not configured to access this resource

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/refresh

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
invalid	invalid_grant	The provided access grant is invalid, expired, or revoked
error	unsupported_grant_type	grant type not supported

error	unauthorized_client	The client is not authorized to request an authorization code using this method
error	invalidCustomer	Customer not found or invalid

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/refresh

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
fatal	serverUnavailable	The request failed due to an internal error

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/refresh

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Revoke Card Access Token

post /cardAuth/oauth2/revoke

Description

This API is used to revoke the access token. The revoke call will terminate the access granted by Citi customer to avail services from your application.

Swagger

Header Parameters

Authorization

string required

uuid

string required

128 bit random UUID generated uniquely for every request.

string required

Content-Type that are acceptable for the response.

client_id

string required

Client ID generated during application registration.

Content-Type

string required

application/json

clientDetails

string Optional

Body Parameters

CardAuthorizationRevokeTokenRequest

required

CardAuthorizationRevokeTokenRequest

{
    "properties": {
        "token": {
            "description": "The token to be revoked",
            "type": "string",
            "example": "AAEkYzFjMDQ0Y2UtNTBmMy00NmY4LWI4YjEtYmQ5ODJkMWZiNGZh3xGP85xjqyxoHR7pXxzQJf223kWPL-HyWHD4zrRCvHZUkeBkTgxppbmpFtmWeVmjzDOxs1wFzI4s45YDS15eYmyuxzLbVog4d8H9pYSelrvL6naDYOLL9U16EaY0iyAMPBGX1H7RhCqtmd-7u_Eanw7QshbruLaZh2stOrdq2thC5CCSwW2r0e8PM1QbWubJOcMp8UGv-zNc0I3cTSihymSCF44HJ_yeuPAcXJ7kj-iPzQqxaO6FiWPmIsIh2YSxdGYo8alTyjJfG5AQDnM0HA"
        },
        "token_type_hint": {
            "description": "A hint about the type of the token submitted for revocation.  Clients MAY pass this parameter in order to help the authorization server to optimize the token lookup. Valid values are access_token,  refresh_token",
            "type": "string",
            "example": "refresh_token"
        }
    },
    "required": [
        "token",
        "token_type_hint"
    ]
}

cURL
Ruby
Python
PHP
Java
Node
Go
Swift

Example Request

Responses

Successful operation.

This operation returns no content.

Type	Code	Details
invalid	invalidRequest	Missing or invalid Parameters

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/revoke

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
error	unAuthorized	Authorization credentials are missing or invalid

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/revoke

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
error	accessNotConfigured	The request operation is not configured to access this resource

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/revoke

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
invalid	invalid_grant	The provided access grant is invalid, expired, or revoked
error	unsupported_grant_type	grant type not supported

error	unauthorized_client	The client is not authorized to request an authorization code using this method
error	invalidCustomer	Customer not found or invalid

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/revoke

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
fatal	serverUnavailable	The request failed due to an internal error

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /cardAuth/oauth2/revoke

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

JSON Web Encryption (JWE) Custom Grant: Rerrieve Access Token

post /v1/issuedDeviceAdministration/accessToken/retrieve/{countryCode}/{businessCode}

Description

This API is used to retrieve the customer access token based on JSON Web Encryption (JWE). This API supports multiple custom grants for different customer identification.

Swagger

Header Parameters

Authorization

string required

uuid

string required

128 bit random UUID generated uniquely for every request.

string required

Content-Type that are acceptable for the response.

client_id

string required

Client ID generated during application registration.

Content-Type

string required

The MIME type of the body of the request (used with POST and PUT requests). application/x-www-form-urlencoded.

clientDetails

string Optional

Path Parameters

countryCode

string required

Country code in ISO 3166 alpha-2 format. Examples: SG (Singapore), PH (Philippines), TH (Thailand).

businessCode

string required

Citi business codes. Examples: GCB, VMA, QCC.

Body Parameters

RetrieveIssuedDeviceAllocationAccessTokenRequest

required

RetrieveIssuedDeviceAllocationAccessTokenRequest

{
    "properties": {
        "jweSignature": {
            "description": "This refers to JWE Token. RFC for JWE encryption : https:\/\/tools.ietf.org\/html\/rfc7516 Example: BASE64URL(UTF8(JWE Protected Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' ||  BASE64URL(JWE Initialization Vector) || '.' ||  BASE64URL(JWE Ciphertext) || '.'||  BASE64URL(JWE Authentication Tag).\nJWE Protected Header: This will be shared by Citi to Partner. e.g. {\"type\":\"JWE\",\"alg\":\"\",\"enc\":\"\",\"kid\":\"\"} \nJWE Encrypted Key: o  Generate a random Content Encryption Key (CEK). Encrypt the CEK with the recipient's public key using the predefine Citi bank algorithm to produce the JWE Encrypted Key.  JWE Initialization Vector: o  Generate a random JWE Initialization Vector. JWE Ciphertext value\/JWE Authentication Tag: o  Perform authenticated encryption on the plaintext (refer to below for details) with the Pre defined Citi algorithm using:  1. Content Encryption Key (CEK) as the encryption key,  2. the JWE Initialization Vector,  requesting a 128-bit Authentication Tag output.\nplaintext: {  issuer : \"vma.creditcardapi.com\", subject : \"aspac.citi.com\", audience : \"1300819380\", expirationTime : \"1300819380\", issuedAt : \"1300819380\", jwtId : \"3535355535fsfsffsf\", grant_type : \"CARD_ADDITIONAL_AUTHORIZATION\", offerId: \"ABC12345\", lastFourDigitsCardNumber : \"1234\", citiCardHolderPhoneNumber : \"6585640987\", phoneCountryCode: \"61\", dateOfBirth : \"1999-12-03\", expiryCardNumber : \"1224\", partnerCustomerIdentifier : \"CUSTOMER_ID\", partnerCustomerIdentifierValue : \"123456\", fullCardNumber: \"1234567890123456\", scope : \"ACCOUNTS\" }  Note:- Above json fields will be conditional mandatory based on grant_type.  We support multiple grant_type using above fields. Grant_Type supported :   \"CARD_AUTHORIZATION\",\"CUSTOMER_AUTHORIZATION\", \"CARD_ADDITIONAL_AUTHORIZATION\", \"OFFER_AUTHORIZATION\" \"CARD_ONLY_AUTHORIZATION\" ",
            "type": "string",
            "example": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ.OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGeipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDbSv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaVmqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je81860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi6UklfCpIMfIjf7iGdXKHzg.48V1_ALb6US04U3b.5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6jiSdiwkIr3ajwQzaBtQD_A.XFBoMYUZodetZdvTiFvSkQ"
        }
    },
    "required": [
        "businessCode",
        "countryCode",
        "jweSignature"
    ]
}

cURL
Ruby
Python
PHP
Java
Node
Go
Swift

Example Request

Responses

Successful operation.

Definitions

tokenType
- Type of token, default is \"Bearer\".
- type : string
accessToken
- Session token which is created after auth service. The token is granted for an individual user to access his data.
- type : string
expiresIn
- The remaining lifetime of the access token.
- type : integer
- format : int32
refreshToken
- The refresh token issued to the client
- type : string
refreshTokenExpiresIn
- The remaining lifetime of the refresh access token.
- type : integer
- format : int32
cardId
- The customer card identifier in encrypted format
- type : string
scope
- The set of function scopes applicable for the token
- type : string

Example Response for post /v1/issuedDeviceAdministration/accessToken/retrieve/{countryCode}/{businessCode}

Type	Code	Details
invalid	invalidRequest	Missing or invalid Parameters
invalid	invalidGrant	Grant type is not valid

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /v1/issuedDeviceAdministration/accessToken/retrieve/{countryCode}/{businessCode}

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
error	unAuthorized	Authorization credentials are missing or invalid

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /v1/issuedDeviceAdministration/accessToken/retrieve/{countryCode}/{businessCode}

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
error	accessNotConfigured	Access is not configured for this resource

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /v1/issuedDeviceAdministration/accessToken/retrieve/{countryCode}/{businessCode}

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
error	resourceNotFound	Empty resource/resource not found

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /v1/issuedDeviceAdministration/accessToken/retrieve/{countryCode}/{businessCode}

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
error	businessValidationsFailed	Business validations failed
error	customerNotAllowed	Customer is not allowed based on accessibility check
error	validationFailed	Customer data is not valid

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /v1/issuedDeviceAdministration/accessToken/retrieve/{countryCode}/{businessCode}

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
fatal	serverUnavailable	The request failed due to an internal error/server unavailability

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /v1/issuedDeviceAdministration/accessToken/retrieve/{countryCode}/{businessCode}

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

JSON Web Encryption (JWE) Custom Grant : Refresh Card Access Token

post /v1/issuedDeviceAdministration/accessToken/refresh

Description

This API is used to exchange for a new set of valid access and refresh tokens in case access token has expired and still have a valid refresh token.

Swagger

Header Parameters

Authorization

string required

uuid

string required

128 bit random UUID generated uniquely for every request.

string required

Content-Type that are acceptable for the response.

client_id

string required

Client ID generated during application registration.

Content-Type

string required

The MIME type of the body of the request (used with POST and PUT requests). application/x-www-form-urlencoded.

clientDetails

string Optional

FormData Parameters

grantType

string required

This refers to the grant type.

refreshToken

string required

The refresh token issued to the client

cURL
Ruby
Python
PHP
Java
Node
Go
Swift

Example Request

Responses

Successful operation.

Definitions

tokenType
- Type of token, default is \"Bearer\".
- type : string
accessToken
- Session token which is created after auth service. The token is granted for an individual user to access his data.
- type : string
expiresIn
- The remaining lifetime of the access token.
- type : integer
- format : int32
refreshToken
- The refresh token issued to the client
- type : string
refreshTokenExpiresIn
- The remaining lifetime of the refresh access token.
- type : integer
- format : int32
cardId
- The customer card identifier in encrypted format
- type : string
scope
- The set of function scopes applicable for the token
- type : string

Example Response for post /v1/issuedDeviceAdministration/accessToken/refresh

Type	Code	Details
invalid	invalidRequest	Missing or invalid Parameters
invalid	invalidGrant	Grant type is not valid

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /v1/issuedDeviceAdministration/accessToken/refresh

{
    "properties": {
        "error_description": {
            "description": "Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred",
            "type": "string"
        },
        "error": {
            "description": "If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.",
            "type": "string",
            "enum": [
                "invalid_request",
                "unauthorized_client",
                "access_denied",
                "unsupported_response_type",
                "invalid_scope",
                "server_error",
                "temporarily_unavailable",
                "unsupported_token_type"
            ]
        },
        "error_uri": {
            "description": "A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.",
            "type": "string"
        }
    },
    "required": [
        "error"
    ]
}

Type	Code	Details
error	unAuthorized	Authorization credentials are missing or invalid

Definitions

error_description
- Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred
- type : string
error
- If the request fails due to a missing, invalid, or mismatching redirection URI, or if the client identifier is missing or invalid, the authorization server SHOULD inform the resource owner of the error and MUST NOT automatically redirect the user-agent to the invalid redirection URI.
- type : string
- enum : invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable, unsupported_token_type
error_uri
- A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
- type : string
required
- error

Response Schema for post /v1/issuedDeviceAdministration/accessToken/refresh