AuthenticationOAuth 2.0

Managing authorization

After redirecting merchants to the authorization URL, they will log in and accept or deny consent to the requested scopes.

Your application must be able to handle both scenarios.

Handling the authorization response

After the merchant grants or denies access, Yoco’s authorization server redirects them back to your application. Your application should handle both success and error responses.

Success response

When authorization succeeds, the redirect includes:

YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE
&scope=REQUESTED_SCOPES
&state=YOUR_STATE
Always validate the state parameter to prevent CSRF attacks.

Error response

When authorization fails, the redirect includes error details:

YOUR_REDIRECT_URI?error=invalid_client
&error_description=error_description

Common error codes include:

  • access_denied - Merchant declined authorization
  • invalid_client - Invalid client ID or configuration
  • invalid_request - Malformed authorization request

In the case of a failed authorization, your application should display a relevant message to the user.

Refreshing access tokens

Access tokens expire and need to be refreshed using the refresh token.

Refresh request

1POST /oauth2/token
2Content-Type: application/x-www-form-urlencoded
3
4grant_type=refresh_token
5&refresh_token=REFRESH_TOKEN
6&client_id=YOUR_CLIENT_ID
7&client_secret=YOUR_CLIENT_SECRET

Handling refresh failures

Your application must handle refresh token expiration:

  • Expired refresh token: Redirect user to authorization URL to re-grant consent
  • Revoked access: User has revoked your application’s access
  • Invalid client: Check your client credentials

Logout endpoint

Implement logout functionality with the RP-initiated logout endpoint:

1GET /oauth2/sessions/logout
2?post_logout_redirect_uri=YOUR_REDIRECT_URI
3&id_token_hint=ID_TOKEN
4&state=STATE

Requirements:

  1. Configure post_logout_redirect_uri in your OAuth application settings
  2. Include the user’s id_token_hint in the request
  3. Use a state parameter to maintain session state

Security best practices

  • Always verify the state parameter to prevent CSRF attacks
  • Store tokens securely (encrypted, server-side only)
  • Use HTTPS for all OAuth-related requests
  • Implement proper error handling for all scenarios
  • Never expose client secrets or tokens in frontend code