Authentication

The WhenThen API uses API keys to authenticate requests. You can view and manage your API keys in theWhenThen Web Application.

Sandbox mode public keys have the prefix pk_test_ and production public keys have the prefix pk_live_. Sandbox mode private keys have the prefix sk_test_ and production private keys have the prefix sk_live_. Sandbox mode client keys have the prefix ct_test_ and production client keys have the prefixct_live_.

Authentication to the API is performed via Bearer Authentication. Provide your API key as the bearer token value.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your private API keys in publicly accessible areas such as GitHub, client-side code etc.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

We recommend setting your client timeout to 30 seconds.

WhenThen authenticates your API requests using your account's API keys. If you don't include your key when making an API request, or use an incorrect or outdated one, WhenThen returns an error.

{
    "errors": [
        {
            "message": "Unauthorised API Key",
            "extensions": {
                "code": "api.key.unauthorized"
            }
        }
    ]
}

There are also two types of API keys: public and private.

Public API keys are meant solely to identify your account with WhenThen, they aren't secret. In other words, you can safely publish them in places like your frontend code, or in an Android or iPhone app. You will also us them with our frontend SDKs
Private API keys must be kept confidential and only store them on your own servers. You must not share your secret API key with any third parties. Your account's secret API key can perform any API request to Whenthen without restriction. If WhenThen believes that your secret API key has been compromised, we may cancel and reissue it, potentially resulting in an interruption to your WhenThen services.

Client Token

A client token is a temporary API key to authenticate API requests. It is used by the WhenThen SDKs. You can also use a client token directly on your frontend

Client tokens are only valid for certain APIs in API Reference labeled with Client Token and expire after 3 hours. Additionally to call authorisePayment the amount and currency must be supplied in the API call to generate the client token.

Your server is responsible for generating the client token. You should then pass it to your client so it can be used in a WhenThen SDK.

Sandbox mode client tokens have the prefix ct_test_ and production client tokens have the prefix ct_live_.

To generate a client token:

Get your private key from Settings -> Developers (For more information see Generate an API key section).
Use a private API key to call the generateClientToken API from your backend.

Generate client token

Mutation

Private Key

generateClientToken creates a new client token which expires after 3 hours.

Request

ValueType

amountLong
Amount in minor units e.g. 5099 = 50.99
currencyString
ISO 4217 Code e.g. EUR

CURL

curl
-X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxx"
-d '{
	"query": "mutation generateClientToken($amount: Long, $currency: String) {
    generateClientToken(amount: $amount, currency: $currency {
      token
      ttl
    }
  }",
  "variables":{}
}'
https://api.whenthen.com/api/graphql

Response

ValueType

tokenString
Token generated
ttlLong
Time-to-live of the token generated (unix time stamp)

JSON

"data": {
  "generateClientToken": {
    "token": "ct_live_XXX",
    "ttl": 1642077826508
  }
}

Rolling API Keys

You can generate a new API key and it can be used immediately. The old key will still work. Once you have updated your systems you should have the new key. You can safely delete you API Key from the Settings -> Developers.

Rolling Client Tokens

Client tokens automatically expire after 3 hours.

If you use an expired client token when making an API request, WhenThen returns an error.

You should generate a new client token if you receive this error.

{
    "errors": [
        {
            "message": "Unauthorised: Client Token is expired",
            "extensions": {
                "code": "api.login.error"
            }
        }
    ]
}

Initialize SDK

Query

Client TokenPrivate KeyPublic Key

Can be used to check if an API key is valid.

Request

CURL

curl
-X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxx"
-d '{
"query": "query initializeSDK {
    initializeSDK
  }"
}'
https://api.whenthen.com/api/graphql

Response

ValueType

initializeSDKBoolean

JSON

{
    "data": {
        "initializeSDK": true
    }
}