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 202 then electronic ID validation/strong auth is required. Response contains authorizationID 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 (opens in a new tab)
  • 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

NameData TypeDefault ValueDescription
Customer
------------
IdentificationNumberStringAn empty stringSocial security number of the customer
UserLanguageCodeInt826Codes of supported languages (ISO codes, https://www.iban.com/country-codes (opens in a new tab), numeric values: http://fasteri.com/list/4/numeric-country-codes (opens in a new tab))
208 = Dk
246 = Fi
578 = No
752 = Se
826 = En
PhoneString (max. 15 characters not counting white spaces, so technically any length)Customers mobile phone number. Validation according to country of origin.
EmailString max 60 CharactersCustomers email
InvoicingAddress
FirstNameString (max. 40 characters)An empty stringCustomer’s first name. This is used also as a first name of the person on the invoicing address.
LastNameString (max. 40 characters)An empty stringCustomer’s last name. This is used also as a last name of the person on the invoicing address.
AddressLine1String (max. 40 characters)An empty stringThe line of the invoicing address that appears below customer’s name. Usually contains a street name and an ordinal number of the building.
AddressLine2String (max. 40 characters)An empty stringThe line of the invoicing address that appears below customer’s name. Usually contains a street name and an ordinal number of the building.
ZipString (max. 6 characters)An empty stringThe ZIP on the invoicing address.
CityString (max. 30 characters)An empty stringThe city on the invoicing address.
DeliveryAddress
FirstNameString (max. 40 characters)An empty stringFirst name of the person on the delivery address.
LastNameString (max. 40 characters)An empty stringLast name of the person on the delivery address.
AddressLine1String (max. 40 characters)An empty stringThe line of the delivery address that appears below customer’s name. Usually contains a street name and an ordinal number of the building.
AddressLine2String (max. 40 characters)An empty stringThe line of the delivery address that appears below customer’s name. Usually contains a street name and an ordinal number of the building.
ZipString (max. 6 characters)An empty stringThe ZIP on the delivery address.
CityString (max. 30 characters)An empty stringThe city on the delivery address.
UseDifferentDeliveryAddressBooleanFALSEIf use different Delivery address option is set and address not recognized before then strong auth could be triggered.
ItemsList of itemsNone. Must be specifiedA 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.
DescriptionString (max. 35 characters)None. Must be specified.A shorter description of the item (that would typically appear on an invoice line)
NotesString (max. 35 characters)An empty stringAn optional longer description of the item that might or might not be displayed on the invoice.
AmountDecimalNone. Must be specified.The item amount. Can be negative, zero or positive. The tax amount should be included in the amount.
TaxCodeStringAn empty string.The tax code. The value should be in %. If tax code are 25% send in 25.
TaxAmountDecimal0.00The item tax amount. Can be zero or positive.
LoyaltyNumberStringAn empty stringCan be a number of a customer’s membership card.
DescriptionStringAn empty stringDescription of delivery method
OrderReferenceStringAn empty stringMerchant custom ID reference.
PosIDStringAn empty stringPoint of sales id. If different sales locations /stores.

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.

NameData TypeDescription
AuthorizationIDStringID to the authorization – should be used for following requests to Status check, Order, Return or Cancel.
CreditLimitDecimalCredit amount granted

Output parameters Example

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

Return Http 202 – Extra electroniID validation is required.

NameData TypeDescription
AuthorizationIDStringID to the authorization – should be used for following requests to Status check, Order, Return or Cancel.
RedirectURLStringPartner 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 (opens in a new tab)

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

Callback Failed

https://yourreturnurl.com/?externalId=d736dd5fea853b18a30fd2413ebfcab5&status=Cancel (opens in a new tab)

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"]
  }
}
Error message
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.