Handling Client Authentication ​

The Payment Gateway is expected to handle and expire authentication credentials issued for clients. Clients will attempt to reauthenticate if the Payment Gateway returns the 401 Unauthorized status code and there are locally stored credentials. With this, it is possible for us to expire credentials every hour or so by returning 401, or invalidate credentials from a separate site if necessary.

Signing In ​

When signing in, the client will make the following request.
POST /v2/authenticate

{
	"callback": "myclient://authenticationCallback",
	"udid": "4e1243bd22c66e76c2ba9eddc1f91394e57f9f83",
	"model": "iPhone7,2"
}

Headers that are sent by a client are outlined on the Prerequesites page. The Payment Gateway should respond with a URL that the client will open in a browser window to initate the login process. On completion, the URL must redirect to the supplied callback and supply an authorization, payment, and refresh token.

Expected Response:

{
	"auth_url": "https://mygateway.com/login?goto=myclient%3A%2F%2FauthenticationCallback"
}

Callback Example:
myclient://authenticationCallback?auth_token=a5f72a60-e0ad-42c9-a93c-ba1aa642d319&payment_secret=0f7995e3-14ae-46fc-95f9-1f92f1c33f62&refresh_token=5ad42376-2be1-405b-a1ee-4aa46330903d

Signing Out ​

When signing out, the client will make the following request.
POST /v2/revoke

{
	"auth_token": "a5f72a60-e0ad-42c9-a93c-ba1aa642d319",
	"payment_secret": "0f7995e3-14ae-46fc-95f9-1f92f1c33f62",
	"refresh_token": "5ad42376-2be1-405b-a1ee-4aa46330903d"
}

As long as the Payment Gateway responds with the 200 OK status code, the client will treat the operation as successful and reflect that change. If a different code is returned, the client will treat it as an operation failure and assume that the client is still authenticated.

Refreshing Expired Credentials ​

A client treats credentials as expired if an authenticated request that it makes results in a 401 Unauthorized response. To refresh credentials, the client will make the following request.
POST /v2/refresh

{
	"auth_token": "a5f72a60-e0ad-42c9-a93c-ba1aa642d319",
	"payment_secret": "0f7995e3-14ae-46fc-95f9-1f92f1c33f62",
	"refresh_token": "5ad42376-2be1-405b-a1ee-4aa46330903d"
}

If the refresh token is correct and the credentials are indeed expired, the Payment Gateway must respond with an updated set of credentials. Please keep in mind that refresh tokens are one-time use only. If the Payment Gateway does not give a proper response, the client will automatically sign out.

{
	"auth_token": "7d86c830-9109-4243-ab56-9dc99b2690af",
	"payment_secret": "7bafed94-b15e-456d-b882-f985da16bfa2",
	"refresh_token": "7cd60302-3a82-4942-8123-060da184d0b1"
}