Used in Gateway Integration

Overview

The Refresh Token API is used to extend the lifetime of the Access Token so that it can be continuously be used in future API requests.

API Description

Headers

Header	Description/Value
Content-Type	`application/vnd.carry1st.payments.partnerauthentication+json`
Accept	`application/vnd.carry1st.payments.partnerauthentication+json`

URL Format

POST /api/pay1st/auth/refresh

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

refreshToken

String

Y

This is a preceding refresh token that is obtained from either

The refreshToken contained in the original Authentication - Generate Access Token request
The previous refreshToken that has been returned from this same API request

Response

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

Example Response

{
    "role": "API_USER",
    "accessToken": "MTRudXRiRDYvUGY1T2FiVDcrYi9aYzFVdkJBRG1YWHgxcnY1MkVwTm1taWJWdDNOSGRocXpLOHB5UlR3d083RmZ4Q0pLSGlLdE1Kc2JEOWszWUE4a3crc2NiR210Q1VUNGt0THlCWW5TM1psNGVwWmJOQ1cvTThxRWN2dVNDMXhrWmhpVTdWZkZGb1l5cCtybGtlUVBWejVaQVV6Tmo2a2RZYWRncnNkQWtnSXZMM3k2OUZLZTcrUWRwL1djUjlsYkNBcElnVzFMdjhSK2ROem1aUkVsLzBQeVJWaW55b29IVWhMMm9FT0kxQnFFa2VFNkJUR3V6VHY2V0s2UlNrQUFZVS9pUEU0dUkvaUhiQXgwY1JrelcvdzNDU0ZJTXRQSTR0L1hucnE4alNoUlU3bU53NWg0MUp4UnlQeDFIZXFEOGdPMkdhbUpOMXFaWXR0OTFIV0pWanJ2S3I0WmNGMkorWmI2ZTlUYWJORDVaeUl2VURiT1NNMUJQZi95WFkweENnQmdsbWdySjVWTk02a3FleURoTnIzSWduZXBaOHZBVSs3aHU5dzlYMVNPclVIRy95U3pWQWtVL2VjVTgzRUQvcU9qTVN3K0RMd0FNYUZsVS85am1VU21JZDRwMEVGZkxoTm1lRzJ5My8xeDdyRjBST01WY1RETWh4emx0UVM=",
    "refreshToken": "MTRudXRiRDYvUGY1T2FiVDcrYi9aYzFVdkJBRG1YWHgxcnY1MkVwTm1taWJWdDNOSGRocXpLOHB5UlR3d083RmZ4Q0pLSGlLdE1Kc2JEOWszWUE4azIyQ3JnbUpPdnRmaEcwTlE0K3RZUjhlME81TWd2TkJxYnVGOVNVYWVvMTFPUzVFT1BqVGZlUGZYL1pxZU56Q3d1Zmx4K0xZem1XSEVjV292a1FaSEhBSXZMM3k2OUZLZTcrUWRwL1djUjlsYkNBcElnVzFMdjhSK2ROem1aUkVsLzBQeVJWaW55b29IVWhMMm9FT0kxQVU4VnNXRHNTQy9qaUtPblN1aU05Q2xyWmV0aWg4alhGYkxKVzQxR2xWSlJkNzU0M0hsaHFXa25ISjBtV0xZbVJ1elpvWU5TVzFPenc1eVBhS0tSbFBOV040RVNZV3Y1VlN0MmdjbUpQYUluYWZuZVIvaDRIUGxuWlE1MTZXYy91MENjQi9wdE5aQ2Zrb21LbVVMVnhJQ3haa2p3V2NYZWl0dG5xbEVTYk1KL05ZVC94a2doaWN4OEIrRjdzVmVMUVN4anF4UE5PRTBZSGM0Z0NxRVFWU0VUVW5NaE9hZndZK09TREZtSlFYdTFXeC9kU29wUGREQ1VudUt5MGRvbzVwTEVudFRsRFRIMzlkZld3Yk5xaEw="
}

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.