Authorization API

Invoice

POST /authorization/invoice

The method authorizes an monthly invoices. All customers who purchase for this partner, this period are charged on one invoice. Credit decision is based on provided parameters and if approved returns authorizationID. If Electronic ID validation is required the function will respond only with purchaseid and a flag that electronicID validation is required.

Authenticate via oAuth2 to api oaut2/token using your ClientID/ClientSecret received from Avarda.
Token needs to be sent as Bearer Token in the following requests.
Post authorization request to Avarda Authorization API Invoice
Check HTTP response:
- 201 – Credit request approved by Avarda. Continue and fulfill order on partner side.
- 202- Credit request requires strong auth. Redirect to Electronic ID validation.
- 400 – Request has bad format or some of its data did not pass validation.
- 422 – Credit request was denied.
If HTTP Response 202 – Strong Auth is REQUIRED:
- Check response – if http response is 422 then electronic ID validation/strong auth is required. Response contains authoriationID and redirect url.
- redirect user to Avarda strong auth service defined in the redirect url.
- After electronicID validation/strong auth is successful then Avarda redirect user back to predefined partner URL with additional query parameter ?AuthorizationID=abcdefghijklmnopqrstuvz.
- Example: https://yourreturnurl.com/?authorizationId=d736dd5fea853b18a30fd2413efcab5
Partner needs to check status after redirect back from Avarda to verify credit request via api /authorization/{id}. If status approved then it is ok fulfill the order.
On delivery – post request to Order and charge customer.
If return – post request to Return and credit customer.
If cancel – post request to Cancel to remove credit reservation

Redirect after completed ID validation

The callback URL has a following format

https://{partner-provided-callback-url}?authorizationId={authorization-id}?orderId={orderId} – for successfully completed ID validation

https://{partner-provided-callback-url}?authorizationId={authorization-id}&orderId={orderId}&errorCode={error-code} – for failed ID validation

Error codes are following:

50: User did not complete ID validation in time – there is a 30 minutes timeout on waiting for user to complete the validation

51: User failed ID Validation with the identity provider – this is typically when the user cancel the validation on the identity provider UI or the identity provider returns another provider specific error

52: During ID validation the user authenticated with a SSN different than the one in the original credit request

53: Newer request with the same parameters arrived, processing newer one, cancelling this one – this happens if a new credit authorization request with same parameters is received while the current one is waiting for ID validation completion

As the callback can be faked the partner should treat it merely as a notification and verify the result by calling GET authorization/{authorization-id}. This will also provide the localized description of the error in addition to the error code.

Input Parameters

Name	Data Type	Default Value	Description
Customer
IdentificationNumber	String	An empty string	Social security number of the customer
UserLanguageCode	Int	826	Codes of supported languages (ISO codes, https://www.iban.com/country-codes, numeric values: http://fasteri.com/list/4/numeric-country-codes) 208 = Dk 246 = Fi 578 = No 752 = Se 826 = En
Phone	String (max. 15 characters not counting white spaces, so technically any length)		Customers mobile phone number. Validation according to country of origin.
Email	String max 60 Characters		Customers email
InvoicingAddress
FirstName	String (max. 40 characters)	An empty string	Customer’s first name. This is used also as a first name of the person on the invoicing address.
LastName	String (max. 40 characters)	An empty string	Customer’s last name. This is used also as a last name of the person on the invoicing address.
AddressLine1	String (max. 40 characters)	An empty string	The line of the invoicing address that appears below customer’s name. Usually contains a street name and an ordinal number of the building.
AddressLine2	String (max. 40 characters)	An empty string	The line of the invoicing address that appears below customer’s name. Usually contains a street name and an ordinal number of the building.
Zip	String (max. 6 characters)	An empty string	The ZIP on the invoicing address.
City	String (max. 30 characters)	An empty string	The city on the invoicing address.
DeliveryAddress
FirstName	String (max. 40 characters)	An empty string	First name of the person on the delivery address.
LastName	String (max. 40 characters)	An empty string	Last name of the person on the delivery address.
AddressLine1	String (max. 40 characters)	An empty string	The line of the delivery address that appears below customer’s name. Usually contains a street name and an ordinal number of the building.
AddressLine2	String (max. 40 characters)	An empty string	The line of the delivery address that appears below customer’s name. Usually contains a street name and an ordinal number of the building.
Zip	String (max. 6 characters)	An empty string	The ZIP on the delivery address.
City	String (max. 30 characters)	An empty string	The city on the delivery address.
UseDifferentDeliveryAddress	Boolean	FALSE	If use different Delivery address option is set and address not recognized before then strong auth could be triggered.
Items	List of items	None. Must be specified	A list of items representing the individual rows on an invoice. Individual items may have a negative value but the total sum of all items must be positive.
Description	String (max. 35 characters)	None. Must be specified.	A shorter description of the item (that would typically appear on an invoice line)
Notes	String (max. 35 characters)	An empty string	An optional longer description of the item that might or might not be displayed on the invoice.
Amount	Decimal	None. Must be specified.	The item amount. Can be negative, zero or positive. The tax amount should be included in the amount.
TaxCode	String	An empty string.	The tax code. The value should be in %. If tax code are 25% send in 25.
TaxAmount	Decimal	0.00	The item tax amount. Can be zero or positive.

LoyaltyNumber	String	An empty string	Can be a number of a customer’s membership card.
Description	String	An empty string	Description of delivery method
OrderReference	String	An empty string	Merchant custom ID reference.
PosID	String	An empty string	Point of sales id. If different sales locations /stores.
ForceCreditDecision	Boolean	FALSE	According to agreement if partner will take own risk for invoice.

Example request

{
  "customer": {
    "identificationNumber": "string",
    "userLanguageCode": 208,
    "phone": "string",
    "email": "string"
  },
  "invoicingAddress": {
    "firstName": "string",
    "lastName": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "zip": "string"
  },
  "deliveryAddress": {
    "firstName": "string",
    "lastName": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "zip": "string",
    "country": "string"
  },
  "useDifferentDeliveryAddress": true,
  "items": [
    {
      "description": "string",
      "notes": "string",
      "amount": 0,
      "taxCode": "string",
      "taxAmount": 0,
      "productGroup": "string"
    }
  ],
  "orderReference": "string",
  "posId": "string",
  "description": "string",
  "emailInvoice": true,
  "loyaltyNumber": "string"
}

Output parameters

Return Http 201 – No extra electronicID validation is required. Process is Done.

Name	Data Type	Description
AuthorizationID	String	ID to the authorization – should be used for following requests to Status check, Order, Return or Cancel.
CreditLimit	Decimal	Credit amount granted

Output parameters Example

{
    "authorizationId": "d736dd5fea853b18a30fd2413ebfcab5",
    "CreditLimit": 4000,
}

Return Http 202 – Extra electroniID validation is required.

Name	Data Type	Description
AuthorizationID	String	ID to the authorization – should be used for following requests to Status check, Order, Return or Cancel.
RedirectURL	String	Partner needs to redirect user to this url to fulfil strong authentication. User will be redirected back to partner site via predefined agreed URL with extra query parameters to identify the authorization.

Output parameters Example

{
  "authorizationId": "string",
  "redirectUrl": "string"
}

Redirect user to ID validation

Redirect user to redirectURL in the authorization response where ElectronicID validation is performed.

Callback Success

https://yourreturnurl.com/?externalId=d736dd5fea853b18a30fd2413ebfcab5&status=OK

Merchant: calls /authorization/{id} to check status and if Completed then fulfill the order.

Callback Failed

https://yourreturnurl.com/?externalId=d736dd5fea853b18a30fd2413ebfcab5&status=Cancel

Merchant: offer other payment method or try electronic id validation again.

Return HTTP 422 – Credit not approved Error messages

{
  "authorizationId": "string",
  "errorCode": 0,
  "errorMessage": "string"
}

Return HTTP 400 – Bad request format or data validation did not pass

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "extensions": {},
  "errors": {
    "additionalProp1": [
      "string"
    ],
    "additionalProp2": [
      "string"
    ],
    "additionalProp3": [
      "string"
    ]
  }
}

Address (in delivery address) must be between 0 and 40 characters.

Address (in invoicing address) must be between 0 and 40 characters.

Address (in invoicing address) should not be empty.

Amount can’t be empty!

Checkout site is not allowed to work with B2b.

City (in delivery address) must be between 0 and 30 characters.

City (in invoicing address) must be between 0 and 30 characters.

City (in invoicing address) should not be empty.

Customer Token is not valid.

Description must be between 0 and 4000 characters.

E-mail is not a valid email address.

E-mail must be between 0 and 60 characters.

E-mail should not be empty.

EmailInvoice must be equal 0, 1 or empty

Identification Number should not be empty.

Invalid or not supported UserLanguageCode.

Item Amount must be specified.

Item description must be specified and must not be longer than 35 characters or empty.

Item notes must not be longer than 35 characters.

Items List must contain at least one item.

Name (in delivery address) must be between 0 and 40 characters.

Name (in invoicing address) must be between 0 and 100 characters.

Name (in invoicing address) must be between 0 and 40 characters.

Name (in invoicing address) should not be empty.

Number of notes characters exceeded

Order Reference should not be empty.

Payment Terms should not be empty.

Phone Number must be between 0 and 15 characters.

Phone should not be empty.

Price must be either 0 (in case of no items), or greater than or equal to 0 and greater than or equal to sum of item prices.

Price should not be empty.

Site has no invoice account class associated.

SSN is invalid.

TermsAndConditionsUrl is not in valid format

The items amount can have a maximum of 2 decimal places.

The items tax amount can have a maximum of 2 decimal places.

The price can have a maximum of 2 decimal places.

Total price is not equal to sum of item prices

ZIP (in delivery address) must be between 0 and 10 characters.

ZIP (in invoicing address) must be between 0 and 10 characters.

ZIP (in invoicing address) should not be empty.