Authentication

The PayTomorrow API uses OAuth 2.0 bearer tokens. You get a token by sending your API username and password, then send that token with every request.

Your credentials

Find these in Resources in the merchant dashboard:

• API username and API password: identify your integration.
• API Signature: your client ID and secret, already base64 encoded. Send it as Authorization: Basic <API Signature> when you request a token.

Request a token

curl -X POST https://api-staging.paytomorrow.com/api/uaa/oauth/token \
  -H "Authorization: Basic $PT_API_SIGNATURE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "scope=openid" \
  --data-urlencode "username=$PT_USERNAME" \
  --data-urlencode "password=$PT_PASSWORD"

grant_type is always password and scope is always openid.

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0...",
  "token_type": "Bearer",
  "expires_in": 18000,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIn0...",
  "refresh_expires_in": 432000,
  "scope": "openid profile email"
}

Use the token

Send it as Authorization: Bearer <access_token> on every API call. This example reads an application's status:

curl https://api-staging.paytomorrow.com/api/ecommerce/application/$TOKEN/status \
  -H "Authorization: Bearer $PT_ACCESS_TOKEN" \
  -H "Accept: application/json"

The only call that doesn't need a token is Validate postback.

Cache and refresh

Don't request a new token for every API call. Cache it and reuse it until it's close to expiring.

# Get a token once and reuse it for the rest of your session (it lasts expires_in seconds).
export PT_ACCESS_TOKEN=$(curl -s -X POST https://api-staging.paytomorrow.com/api/uaa/oauth/token \
  -H "Authorization: Basic $PT_API_SIGNATURE" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "scope=openid" \
  --data-urlencode "username=$PT_USERNAME" \
  --data-urlencode "password=$PT_PASSWORD" | jq -r .access_token)

If any call returns 401 Unauthorized, clear the cache, get a new token, and retry the call once.

Staging vs production

Credentials are issued per environment. Use your staging credentials against api-staging.paytomorrow.com and your production credentials against api.paytomorrow.com. Mixing them returns 401.