PayoutID OAuth2

PayoutID is Payout's OAuth2 and OpenID Connect provider. It supports three grants:

• Authorization code grant: act on behalf of a user who approves access.
• Refresh token grant: get a new access token without asking the user again.
• Client credentials grant: call an API as your own client, without a user.

Endpoints

Payout registers your application as a PayoutID client and gives you a client_id and a client_secret. The client also holds your registered redirect URIs and the scopes you may request. Each API lists the scopes its endpoints require.

Authorization code grant

Use this grant when you need data from a user or want to act on their behalf.

1. Redirect the user. Send the user's browser to Authorize user with your client_id, response_type=code, a registered redirect_uri, the scope you need and a state value.
2. The user approves. The user logs in or registers in PayoutID and approves the requested scopes.
3. Receive the code. PayoutID redirects the browser back to your redirect_uri with code and state in the query string. Check that state matches the value you sent. The code is valid for at most 60 seconds and works only once.
4. Exchange the code for tokens. Call Retrieve token with grant_type=authorization_code, the code and the same redirect_uri.
5. Call the API. Send the access token in the Authorization: Bearer <access_token> header.

Refresh token grant

Access tokens are short-lived: the lifetime is set per client, at most 24 hours, and expires_in in the token response tells you how long the token is valid. To keep access without sending the user through the flow again, use the refresh token issued with the access token from the authorization code grant. A refresh token is valid for at most 30 days.

A refresh token cannot be used to call an API. It can only be exchanged for a new access token: call Retrieve token with grant_type=refresh_token and the token in refresh_token.

Client credentials grant

Use this grant to access resources of your own client, without a user's consent in Payout. Call Retrieve token with grant_type=client_credentials, your client_id and client_secret, and the scope you need. No authorization code is involved.

When a resource belongs to another provider, such as the user's bank, the user may still have to authenticate with that provider.