Accrue Merchant API (1.0.0)

Welcome to the Accrue API! Our detailed documentation will guide you through essential topics, including authentication, request formatting, and the handling of financial transactions, with a current focus on payments.

Accrue treats every client as a unique entity. This approach allows for the management of critical components such as API tokens and user access, directly through our API, ensuring that each organization can tailor its use of our services to fit its specific needs.

The introductory section aims to familiarize you with the core concepts required to effectively utilize the services offered by our platform.

Accrue offers its API across two distinct environments:

Accrue's API leverages the Bearer Token for request authentication. Every API call requires the inclusion of a bearer token, which is a Client Secret associated with the Client for which you are making requests.

:::caution

Any issues with the token, such as being invalid, missing, or expired, will lead to HTTP 401 Unauthorized responses.

:::

GET /payments HTTP/1.1
Authorization: Bearer 633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef

When API requests fail due to network issues, rate limits, timeouts, or service incidents, it's a best practice to implement a retry mechanism. Guidelines for this mechanism include:

• Retryable HTTP Status Codes:
  • 5xx: Server errors.
  • 429: Rate Limits.
  • 408: Timeouts.
• Retry Strategy:
  • Use an exponential backoff and/or jitter for retries.
  • Implement idempotency keys where necessary.

The rate limit, based on your IP address, is set at 10,000 requests per minute, applicable to both the sandbox and live environments separately. Exceeding this limit triggers HTTP 429 status codes and relevant messages in responses.

To ensure prompt failure and allow for retries, our APIs are designed with timeouts. It's recommended to set similar request timeouts on the client side. Timeouts are categorized as follows:

• Short Timeout: A default timeout of 10 seconds for most APIs.
• Long Timeout: Some APIs require up to 90 seconds for longer processes.

Refer to the specific API documentation to ascertain the timeout applicable to your request.

OpenAPI, a widely-recognized standard for defining RESTful APIs, enhances API usability and integration. It facilitates client library (SDK) generation, testing, and integration with various development tools. The Accrue API conforms to OpenAPI 3.1, with its specification accessible here.

The Accrue OpenAPI specification can be used in conjunction with tools like Swagger or OpenAPI generators to create Accrue API client libraries in your preferred programming language.

Please note, while SDKs can be auto-generated, their full compatibility with our API and coverage of all endpoints isn't guaranteed. Contributions, including feedback, bug reports, and pull requests from the Accrue SDKs community, are welcome to help improve and address any issues.

Accrue's List operation for resources like Users, Linked Accounts, or Transactions includes full-text search functionality, enhancing your ability to locate specific resources easily.

This feature is especially useful for improving end-customer experiences, such as implementing a search box that allows customers to find transactions by descriptions (e.g., 'plane ticket') within their account transactions.

Full-Text Search Rules:

• Unquoted Text: Searches for words separated by 'And'. Example: 'john doe' finds resources containing both 'john' and 'doe'.
• OR Operator: Searches for words separated by 'Or'. Example: 'john or doe' finds resources containing either 'john' or 'doe'.
• Minus Sign (-): Excludes words following the minus. Example: 'john -doe' finds resources containing 'john' but not 'doe'.

List operations, like 'List Users', return a collection of resources. To navigate through a long list, use:

• page[limit]: Limits the number of resources returned (1-200, default is 50).
• page[offset]: Specifies the number of resources to skip (default is 0).

Accrue supports idempotency for certain API operations, allowing multiple requests while ensuring the operation is performed only once. Use any string up to 255 characters as an idempotency key (UUID version 4 is recommended).

Idempotency is vital for situations like network errors during sensitive operations (e.g., payment creation). It ensures that an operation, like a payment, is not duplicated despite multiple attempts.

Key Points:

• Idempotency keys remain effective for 48 hours.
• They are not shared across different API operations, but the same key can technically be used for different operations (not recommended).

Accrue's API is REST-based and adheres to the JSON:API specification.

JSON:API outlines how clients should request resources and how servers should respond. Accrue's resources encompass applications, customers, cards, accounts, transactions, among others.

Designed for efficiency, JSON:API reduces the number of requests and data transferred between clients and servers, achieving this without sacrificing readability, flexibility, or discoverability.

JSON:API mandates the use of the JSON:API media type (application/vnd.api+json) for data exchange.

Request and Response Structure

JSON:API structures all requests and responses as JSON documents. These documents must contain one of the following top-level members:

• Data: Represents the document's "primary data". For example, in creating an application resource, the primary data includes personal information.
• Errors: An array of error objects.

Primary data must be either:

• A single resource object for requests targeting individual resources.
• An array of resource objects for requests targeting resource collections.

    {
        "data": {
            "type": "User",
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "attributes": {
                // ... this users's attributes
                },
            "relationships": {
                // ... this users's relationships
            }
        }
    }

    {
        "data": [
            {
                "type": "User",
                "id": "123e4567-e89b-12d3-a456-426614174000",
                "attributes": {
                    // ... this users's attributes
                    },
                "relationships": {
                    // ... this users's relationships
                }
            },
            {
                "type": "User",
                "id": "123e4567-e89b-12d3-a456-426614174001",
                "attributes": {
                    // ... this users's attributes
                    },
                "relationships": {
                    // ... this users's relationships
                }
            }
        ]
    }

Resource Object

In JSON:API documents, resource objects are used to depict entities within the business domain, such as applications, customers, cards, accounts, transactions, etc., within Accrue's API.

Every resource object must include these two members:

• id: The unique identifier of the resource.
• type: The type of resource.

Note: The id member is not required for resource objects created on the client side that represent new resources to be created on the server.

Optional members of a resource object include:

• attributes: This object represents the resource's data, like name, address, email, etc.
• relationships: Describes connections between the current resource and other resources.

{
   "type": "User",
   "id": "123e4567-e89b-12d3-a456-426614174000",
   "attributes": {
      "disabled": false,
      "attachedProfile": {
          "referenceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "email": "user@email.com",
          "phoneNumber": "+12125559999"
        }
      "updatedAt":"2020-01-12T19:41:01.323Z",
      "createdAt":"2020-01-11T19:40:01.323Z"
   },
   "relationships": {
      //relationships listed here
   }
}

Relationships

The relationships object in JSON:API defines the connections between the current resource and other related resources. Each entry in this object signifies a unique reference.

For instance, the relationship between a User and UserProfile is depicted here.

Relationship Object

A "relationship object" is required to include a data member, which can be one of the following:

• Null: Indicating an empty 'to-one' relationship.
• Empty Array ([]): For empty 'to-many' relationships.
• Single Resource Identifier: With 'type' and 'id', for non-empty 'to-one' relationships.
• Array of Resource Identifiers: Each with 'type' and 'id', for non-empty 'to-many' relationships.

{
   "type": "Wallet",
   "id": "123e4567-e89b-12d3-a456-426614174000",
   "attributes": {
       //attributes here
    }
   },
   "relationships":{
      "User":{
         "data":{
            "type": "User",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
         }
      }
   }
}

Getting Related Resources

Accrue's API supports the include query parameter in GET operations on specific resources like Cards. This parameter allows fetching multiple related resources in a single response. You can specify one or several relationships, separated by commas, in the query (refer to the example below). The response will include an included key containing these related resources.

Utilizing this feature simplifies the API interaction by consolidating what would typically be multiple calls into a single request. This not only streamlines your code but also addresses common data integrity concerns associated with

curl -X GET 'https://merchant-api.accruesavings.com/wallets/123e4567-e89b-12d3-a456-426614174000?include=User' \-H "Authorization: Bearer ${TOKEN}"

{
    "type": "Wallet",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "attributes": {
            //attributes here
        },
        "relationships":{
            "User":{
                "data":{
                    "type": "User",
                    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
                }
            }
        }
    },
    "included": [
        {
            "type": "User",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "attributes":{
                //attributes here
        },
    ]
}

Accrue's API communicates the status of requests using standard HTTP Status Codes. Errors may occur at any point during processing, either as single or multiple instances. For example, schema validation issues often lead to multiple errors, while server processing problems typically result in a single error. Regardless, the response includes all identified errors.

An "error object" is required to have an HTTP status code. It may also include:

• code: (Optional) A unique, underscored Accrue-specific code detailing the error. A comprehensive list of error codes is available in the Accrue Errors documentation.
• detail: (Optional) A human-readable explanation providing more insights about the error.
• Meta: (Optional) This object contains name/value pairs relevant to the error

Users represent the end users and are the parent container of Wallets. A user is automatically created when the end-user signs into the Accrue product through various different methods using their phone number.

Linked Accounts represent payment methods that users have connected to their Accrue account. These accounts can be used for funding payments or topping up the wallet.

Wallets are where users save money and collect rewards for future payments to merchants. Each wallet is linked to a specific merchant and tracks the balance of deposits and rewards. Users can contribute to their wallet's balance as part of their payment planning, while also accruing rewards.

Payment Intents represent a commitment to pay a specified amount, allowing for a structured process to handle payments from initiation to completion. This resource serves as a provisional step in the payment process, where the amount, payment method, and other details are specified by the initiator (e.g., a user, support staff, or merchant). Payment Intents can go through several states, such as requiring action, being canceled, or being promoted to an actual payment upon successful authorization.

Payments are the realization of payment intents, representing the actual transfer or authorization of funds. This resource encapsulates the details of completed transactions, including the payment status, amount, and any adjustments or refunds that have occurred post-initial authorization. Payments can have various statuses reflecting their current state, from pending to refunded, providing a comprehensive view of the transaction lifecycle.