Used in Gateway Integration

Overview

The Partner Token API is used to authenticate against all subsequent gateway integration API requests. This is a POST request that will return a JSON response to the Access Token and Refresh Token that should be used in subsequent requests.

API Description

Pre-Requisites

The API_KEY and API_SECRET as the authentication method for this API request. These can be found in Configuring API Credentials.

Headers

Header	Description/Value
Content-Type	`application/vnd.carry1st.payments.partnerauthentication+json`
Authorization	This will be a Base64 encoded String in the format of `Basic base64(\<API_KEY>:\<API_SECRET>)`

URL Format

To retrieve a list of available payment methods, make a POST request to the following endpoint:

POST api/pay1st/auth/token

POST Request Fields

The fields in the table below should be submitted as a JSON object.

Parameter	Format	Mandatory	Description
role	String	Y	This should be set to `API_USER`

Response

The API will respond with a JSON object containing the authentication and refresh tokens

Example Response

{
    "role": "API_USER",
    "accessToken": "MTRudXRiRDYvUGY1T2FiVDcrYi9aYzFVdkJBRG1YWHgxcnY1MkVwTm1taWJWdDNOSGRocXpLOHB5UlR3d083RmZ4Q0pLSGlLdE1Kc2JEOWszWUE4azhQR2NScGVwYktZSkQ5aTEzVkk2NEEvTVZ4RFJzK1hpNXVUeTV2WFNjL2hPUzVzbkhtdWpCM1JPQUR2WVVwdDllWUNzblM1cE9hU0ZZckZ4VEpXR2ZVSXZMM3k2OUZLZTcrUWRwL1djUjlsYkNBcElnVzFMdjhSK2ROem1aUkVsLzBQeVJWaW55b29IVWhMMm9FT0kxQnFFa2VFNkJUR3V6VHY2V0s2UlNrQUFZVS9pUEU0dUkvaUhiQXgwY1JrelcvdzNDU0ZJTXRQSTR0L1hucnE4alNoUlU3bU53NWg0MUp4UnlQeDFIZXFEOGdPMkdhbUpOMXFaWXR0OTFIV0pWanJ2S3I0WmNGMkorWmI2ZTlUYWJORDVaeUl2VURiT1NNMUJQZi95WFkweENnQmdsbWdySjVWTk02a3FleURoRWN6c2duNERSNlU3WGgxTTlFRXJoRDhZZ2pZcW1RTmw5UGV6NTRpOVJXbFNxUy9VU2RIRmRmVUhwRXJ4cjJRYWpQTm1LK0lrUHNQS0xYL2hrZit6d2NuWEhMN0FYbURDbXRhQWFES1NFRHo=",
    "refreshToken": "MTRudXRiRDYvUGY1T2FiVDcrYi9aYzFVdkJBRG1YWHgxcnY1MkVwTm1taWJWdDNOSGRocXpLOHB5UlR3d083RmZ4Q0pLSGlLdE1Kc2JEOWszWUE4azhQR2NScGVwYktZSkQ5aTEzVkk2NEEvTVZ4RFJzK1hpNXVUeTV2WFNjL2hPUzVzbkhtdWpCM1JPQUR2WVVwdDllWUNzblM1cE9hU0ZZckZ4VEpXR2ZVSXZMM3k2OUZLZTcrUWRwL1djUjlsYkNBcElnVzFMdjhSK2ROem1aUkVsLzBQeVJWaW55b29IVWhMMm9FT0kxQnFFa2VFNkJUR3V6VHY2V0s2UlNrQUFZVS9pUEU0dUkvaUhiQXgwY1JrelcvdzNDU0ZJTXRQSTR0L1hucnE4alNoUlU3bU53NWg0MUp4UnlQeDFIZXFEOGdPMkdhbUpOMXFaWXR0OTFIV0pWanJ2S3I0WmNGMkorWmI2ZTlUYWJORDVaeUl2VURiT1NNMUJQZi95WFkweENnQmdsbWdySjVWTk02a3FleURoRWN6c2duNERSNlU3WGgxTTlFRXJoRDhZZ2pZcW1RTmw5UGV6NTRpOVJXbFNxUy9VU2RIRmRmVUhwRXJ4cjJRYWpQTm1LK0lrUHNQS0xYL2hrZit6d2NuWEhMN0FYbURDbXRhQWFES1NFRHo="
}

Each payment method in the response contains the following fields:

Field	Format	Description
role	String	This will be the same role as specified in the request
accessToken	String	An encrypted token to use for subsequent API requests
refreshToken	String	The refresh token is used when there is a need to increase the expiry time of an accessToken

HTTP Response Codes

The payment method API may return the following HTTP Response Codes:

HTTP Status Code	Name	Description
200	Success	This indicates that the request has been successful.
400	Bad Request	This indicates that that an error occurred in the request. See Handling Error Codes
401	Unauthorized	The incorrect role value was used The incorrect `API Key` and `API Secret` combination was used (see Configuring API Credentials )
403	Forbidden	The incorrect `API Key` and `API Secret` do not have the appropriate permissions to make the request
429	Too Many Requests	The Partner is sending too many requests to this endpoint and will be rate limited

Error Handling

See Handling Error Codes for more details on handling error responses.