4.4. Authorization request

Authorization can be seen as a permission from the customer to let the caller of the API, e.g. a webshop, access their Paytrail account. More specifically, it is a means to ask the Paytrail account owner's consent for charge access to the stored payment method or for read access to delivery addresses.

If the resource is created and the caller receives HTTP 201, that newly created Authorization resource is ready to be confirmed with the PIN code that was sent to the Paytrail account owner.

Example 4.3. POST /connectapi/authorizations

Request body
{
    "authKey": string,
    "authType": string,
    "access": [ array of strings ],
    "validity": string,
    "locale": string
}

HTTP Status codes

201: On successful authorization request using requested authentication method

400: Bad Request


The following table gives more information on the content of the request. The m/o column indicates if the parameter is mandatory or optional.

Table 4.1. Parameters for the authorization request

NameTypem/oDescription
authKeystringmKey to identify a Paytrail account. e.g. email address.
authTypestringmAuthentication process for confirming the Paytrail account owner and their consent.
accessarray of stringsmPaytrail account owner is requested to authorize the API caller to do these actions.
validitystringmValidity period of the requested authorization. At the moment only "singleCharge" is supported. Reserved for recurring payment use case when the Paytrail account can be charged multiple times with one authorization from account owner.
localestringmThe locale of the Paytrail account owner, e.g. fi_FI.

Table 4.2. Valid parameter values

authTypeTriggered authentication process
email+smspinIf the provided authKey belongs to an active Paytrail account, its owner receives a PIN code via SMS.
accessm/oAccess to be requested from the Paytrail account owner during the authorization process
chargeoPaytrail account owner is asked to let the API caller charge the Paytrail account's default payment method.
deliveryAddressoPaytrail account owner is asked to reveal the delivery addresses they have verified to be valid.
validityThe duration of the requested authorization
singleChargeAccess for deliveryAddress is valid for 1 hour after confirming or until a charge is placed. After creating the charge, the authorization resource is invalidated.
Locale 
fi_FIFinnish in Finland
en_USUS English
se_SVSwedish in Sweden

Example 4.4. Example HTTP Request

POST /connectapi/authorizations HTTP/1.1
Timestamp: 2012-12-31T12:00:00+02:00
Content-MD5: ubewX5M7uzz64zskr7FThQ==
Authorization: PaytrailConnectAPI 13466:jmTwcsZlYKM9TuglR0nyNjWXNW8iLWGNvuSJfuvT+9k=

{
    "authType": "email+smspin",
    "authKey": "emma.example@paytrail.com",
    "access": ["deliveryAddress", "charge"],
    "validity": "singleCharge",
    "locale": "fi_FI"
}

Example 4.5. Example HTTP Response

HTTP/1.1 201 Created
Location: /connectapi/authorizations/AXJD28237XSDHJS18928