Authorization API
Flow Details

Main Flow

The primary scenario for interacting with the Authorization API is illustrated in the following sequence diagram.

Credit authorization main flow

Credit Approval

  1. Obtain Access Token Using the client credentials provided by Avarda, the Partner Backend retrieves an access token required to authenticate subsequent API calls. For details, see Authentication.

  2. Submit Credit Authorization Request When a Customer selects one of Avarda's credit payment methods, the Partner Backend sends a POST request to one of the following Authorization API endpoints:

  3. Credit Approval Response If the Customer's credit is pre-approved - pending the ID validation - the Authorization API responds with a 202 Accepted HTTP status code. The response body contains:

    • A unique authorizationId for the credit authorization, to be used in subsequent requests.
    • A URL for the Customer's ID validation service.

  4. Redirect to ID Validation Service The Partner Backend must redirect the Customer to the ID validation service URL provided in the API response. Depending on the market, this service could be BankID, FTN, or another external electronic identification provider.

  5. Handle ID Validation Completion Upon successful completion of the ID validation:

    • The Authorization API is notified via a redirect, which, in turn, triggers a redirect to the Partner Backend.
    • The redirect URL used by the Authorization API is derived from:
      • The idValidationCallbackUrl field of the original credit authorization request, if specified.
      • Otherwise, the default URL configured during Partner onboarding.

    The redirect URL includes the following query parameters:

    • authorizationId: The unique ID of the credit authorization.
    • orderId: The original orderReference from the credit authorization request.

    Example format:

    {partner-specified-base-url}?authorizationId={id}&orderId={orderReference}

  6. Verify ID Validation Result To confirm the ID validation result, the Partner Backend should perform a GET request to authorization/{id}. This verification step ensures the redirect notification is not forged.

    • A successful ID validation is indicated by an HTTP status code 200 and a status field value of 0 (Approved) in the response body.

Order Management

  • Check Purchase Status The Partner Backend can query the status of a purchase at any time by calling GET authorization/{id}.

  • Capture the Order When delivering the purchased items, the Partner Backend must call POST authorization/{id}/order to capture the order. This action finalizes the credit authorization and enables the Partner to invoice the Customer.

  • Cancel the Order To cancel the order and remove the credit reservation, the Partner Backend should call POST authorization/{id}/cancel.

  • Submit a Return or Price Adjustment To process a return or make price adjustments for purchased items, the Partner Backend should call POST authorization/{id}/return.

Important Notes

  • Background Processing Delay: It may take up to 80 seconds for the Authorization API to complete the background processing of a new credit authorization. During this period, order management methods will not be available, and calls made before completion will return a 404 Not Found status.

  • Availability Check: To determine if the order management methods are ready, the Partner Backend can call GET authorization/{id} and check the inBackOffice field in the response body. If the value is true, the order management methods are available.

Alternate Flows

This section describes possible deviations from the primary scenario. The numbers in the section headings correspond to the step numbers in the main flow where the alternate flow branches off.

2a. Invalid Request Data

All credit authorization request data is validated by the Authorization API. If validation fails, the Authorization API responds with:

3a. Customer ID Validation Not Required

In certain scenarios, Avarda does not require the Customer to complete ID validation. In this case:

  • HTTP status: 201 Created is returned with response body containing credit authorization ID
  • The Partner Backend can proceed with Order Management calls.

3b. Credit Authorization Rejected

If Avarda rejects the credit request based on its business rules, the Authorization API responds with:

  • HTTP status: 422 Unprocessable Entity
  • Response body:
    • A numerical error code.
    • A textual error description in the language specified by the customer.userLanguageCode field of the credit authorization request (list of errors).

3c. Technical Error

If the Authorization API responds with 500 Internal Server Error, it encountered a technical failure. Such failures are typically transient, and the Partner Backend should retry the call. The following is recommended:

  • Use a retry strategy with exponential backoff and a cap on the number of retries.
  • The response body will include a unique ID for the credit authorization attempt, which can be shared with Avarda support if retries fail.

5a. Customer ID Validation Error

This occurs if:

  1. The Customer validates with an SSN/National ID that differs from the one provided in the credit authorization request, or
  2. The external ID validation fails (e.g., the user cancels the validation explicitly).

In this case:

  • The redirect query string will include an errorCode.
  • Example redirect URL: 
    {partner-specified-base-url}?authorizationId={id}&orderId={orderReference}&errorCode={nn}

Error Codes:

  • 51: User canceled the validation or a provider error occurred.
  • 52: SSN/National ID mismatch.

The original link to the ID validation provider remains valid and credit authorization reserved - the Customer can use the link again to retry the ID validation.

5b. Customer ID Validation Timeout

If the Customer does not successfully complete the ID validation session within 30 minutes, the pre-approved credit authorization is canceled. In this scenario there is no redirect to the Partner Backend as the Customer might simply close their browser or navigated away.

The Partner Backend can verify the status of the ID validation by calling GET authorization/{id}:

  • If the response status is 202 Accepted, the ID validation is still in process.
  • If the response status is 200 OK and the status field in the response body is 2 (Canceled), the ID validation session has timed out.

This is a final state, and the credit reservation has been removed.

Getting StartedEnvironments