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
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 (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 |
Phone | String (max. 15 characters not counting white spaces, so technically any length) | Customers mobile phone number. Validation according to country of origin. | |
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. |
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
Merchant: calls /authorization/{id}
to check status and if Completed then fulfill the order.
Callback Failed
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. |