LogoLogo
  • Welcome
  • Merchant API
    • Authentication
    • Card linking Receipt API
    • Token Receipt API
    • Dynamic QR Code
  • Partner App API
    • Authentication
    • OAuth2 Flow
    • GET Receipt
    • Notifications
  • Issuers
    • Issuer flow
    • Bank Piloting
    • Notifications
  • Filetypes
    • ReceiptHero JSON
      • HeroJSON Specification
        • Payment Types
    • Finvoice XML eReceipt
  • Support
    • Slack channel
Powered by GitBook
On this page
  • Get an authorization code
  • Exchange the authorization code for an access token
  • Revoke Access Token
  • Update existing OAuth2 connection
  1. Partner App API

OAuth2 Flow

PreviousAuthenticationNextGET Receipt

Last updated 3 years ago

Overview of the flow OAuth2 Flow ReceiptHero

Get an authorization code

Initiate the flow by redirecting the user to the ReceiptHero consent page.

Redirect

https://dev.receipthero.io/auth?response_type=code&client_id={CLIENT_ID_HERE}&redirect_uri=https%3A%2F%2Freceipthero.io%2Fcallback&scope=receipt%3Awrite&state=cmVjZWlwdGhlcm9yb2Nrcw==

If the user approves the request then the authorization server will redirect the user to the redirect URI defined in the request.

Scopes

Scope
Description

receipt:write

Sending receipts to the ReceiptHero system

receipt:read

Reading receipts from the ReceiptHero system

State

Parameter
Type
Description

message

string

Custom message

partner_metadata

object

To use the state parameters, the state is to be defined in JSON and encoded into Base64.

Callback

https://client-server.com/callback?code=1745ee387c3545b2b77bf37baaf3b3f5&state=cmVjZWlwdGhlcm9yb2Nrcw==

The client must make sure that the state matches the provided state value provided to the authorization endpoint. This protects against CSRF type of attacks. The code expires one minute after it has been created.

Exchange the authorization code for an access token

The client sends the previously received authorization code to the token endpoint which then returns an access token.

Request

POST https://api.dev.receipthero.io/api/oauth/token

Content-Type: application/json

{
    "grant_type": "authorization_code",
    "code": "{CODE_HERE}",
    "client_id": "{CLIENT_ID_HERE}",
    "client_secret": "{CLIENT_SECRET_HERE}",
    "redirect_uri": "{REDIRECT_URI_HERE}"
}

The request can be made in either application/json or application/x-www-form-urlencoded.

Response

{
    "token_type": "Bearer",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWNlaXB0X2hlcm9faWQiOiI5Mjg5OTZmZC0yYTU3LTQ1NzctYjZlNy01ODNhZGM4ZGJlOGMiLCJpYXQiOjE2MjM3NDEwMDh9.gD17UFHxJoEmz_RrIHBQksjqgotyncoO8fDYurYPI2k"
}

The returned access token is a JSON Web Token.

In Token you get ID for this connection.

Claims

Claim

Description

receipthero_id

Unique identifier

Revoke Access Token

DELETE https://api.dev.receipthero.io/api/oauth/revoke
Host: api.dev.receipthero.io
Authorization: Bearer <USERS_OAUTH_TOKEN>

Response OK

HTTP 200 OK
Content-Type: application/json

Response Not Found

HTTP 404 Not Found
Content-Type: application/json

Update existing OAuth2 connection

It is possible to update an existing OAuth2 connection by using this dedicated view.

https://dev.receipthero.io/membership?receipthero_id={receipthero_id}&redirect_uri={redirect_uri}

Query Parameters

Scope
Description

receipthero_id

Unique connection identifier (contained in the JWT token)

redirect_uri

The URI where the user is redirected after taking actions on the connection update view

Redirect

The user is redirected back with the following query string parameters:

Parameter
Description

status

Describes the user action. Possible values are 'cancelled', 'modified' and 'removed'

receipthero_id

Unique connection identifier

Optional Partner defined key-value pairs for carrying relevant metadata (will be included in if provided)

webhook notification messages