Code Flow

The OAuth2 Code Flow provides a secure way to request an access token on behalf of a Pushpay user. That is, the application requesting the token is never exposed to the user's login or password, and the Pushpay user is given the opportunity to consent to granting the client access to their information.

The Code Flow uses HTTP redirects to complete the request for an access token. The process starts by redirecting to an authorization endpoint, appended with details of the client the token will be issued for, the scopes required, and the URL to redirect back to once authorization is complete.

Step 1 — Getting Consent

To initiate this flow, direct the user's browser to the authorization server endpoint:

https://auth.pushpay.com/pushpay/oauth/authorize

This URL must have the following query parameters appended:

Notes:

• The redirect URL must be on the whitelist of allowable redirect URLs — the Pushpay platform does not allow open redirects.
• To whitelist your redirect URL, email [email protected].
• Redirect URLs must use HTTPS.

Upon receiving the request, the authorization server will:

1. Redirect to the Pushpay website, where the Pushpay user can log in.
2. Once authenticated, redirect the user to the authorization server's consent page. This page shows the user your application's name, along with the scopes (permissions) being requested. The user is also asked how long to grant permission for — anywhere from one day to one year, or indefinitely (via the "forever" option).
3. Let the user either allow or deny access. Note that the user can uncheck any (or all) of the requested scopes while still clicking "Allow" — your application must be able to handle these scenarios.
4. Redirect back to the redirect_uri from the initial request, with a code appended. For example:

   http://my-payment-app.com/callback?code=b12d5abc34567bbca8cc9012f634b56f

Step 2 — Retrieving an Access Token

Once your application receives the request at redirect_uri, make a request to the authorization server to generate an access token:

1. Set a "Basic Auth" header, using the client_id and client_secret as the username/password. (Basic Auth combines the ID and secret separated by a colon, then base64-encodes the result.)
2. Set the content type of the request to application/x-www-form-urlencoded.
3. Supply a form-encoded body with the parameters:

   Parameter	Value
   grant_type	authorization_code
   code	The code query parameter appended to the redirect URL
   redirect_uri	The redirect URL used in the original authorization endpoint request

4. Make a POST request to:

   https://auth.pushpay.com/pushpay/oauth/token

Success Response

On success, you'll receive a 200 OK response with a JSON body like:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1N....",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "652a15ee623b4f4cada11d4c4b3c2a6f"
}

The access_token property contains the token you must use for all subsequent API requests.