Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.1.0
info:
version: 1.0.0
title: Accrue Merchant API
x-links:
- name: View Alternative Version
url: /api-fs/
description: >-
View API documentation with alternative enum-based WebhookIncluded
schema
servers:
- description: Production API
url: https://merchant-api.accruesavings.com
- description: Sandbox API
url: https://merchant-api-sandbox.accruesavings.com
tags:
- name: Introduction
description: >
## Sandbox
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.
## Environments
Accrue offers its API across two distinct environments:
| Environment | Description | API
URL
|
| ----------------------- | -------------------------------------
|---------------------------------------------------------------------------------------------------|
| **Sandbox Environment** | Designed for testing and development. |
[https://merchant-api-sandbox.accruesavings.com](https://merchant-api-sandbox.accruesavings.com/)
|
| **Live Environment** | For real-time production operations. |
[https://merchant-api.accruesavings.com/](https://merchant-api.accruesavings.com/)
|
## Authentication
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.
:::
```http title="Example"
GET /payments HTTP/1.1
Authorization: Bearer
633b336e4f57f095a405f6685e208cc7dd16de3e82494662f2acfeec3af1cdef
```
## Retrying API Requests
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.
## Rate Limits
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.
## Timeouts
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.
- name: API Design
description: >
## OpenAPI Specification
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](https://spec.openapis.org/oas/v3.1.0).
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.
## Full-Text Search
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'.
## Pagination
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-50, default is
10). A larger value is capped at 50 rather than rejected.
- `page[offset]`: Specifies the number of resources to skip (default is
0).
## Idempotency
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).
## About JSON API
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.
```js title="Singe resource example"
{
"data": {
"type": "User",
"id": "123e4567-e89b-12d3-a456-426614174000",
"attributes": {
// ... this users's attributes
},
"relationships": {
// ... this users's relationships
}
}
}
```
```js title="Array of Resources Example"
{
"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.
```js title="Resource example"
{
"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.
```js title="Relationships example"
{
"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
```bash title="Include query parameter example"
curl -X GET
'https://merchant-api.accruesavings.com/wallets/123e4567-e89b-12d3-a456-426614174000?include=User'
\-H "Authorization: Bearer ${TOKEN}"
```
```js title="Included resources example"
{
"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
},
]
}
```
## Errors
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
- name: Wallets
description: >-
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.
- name: PaymentIntents
description: >-
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.
- name: Payments
description: >-
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.
- name: Simulations
description: >-
Simulations are used to simulate payments authorizations and captures for
Card Rails (Virtual Debit Cards).
- name: Users
description: >-
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.
- name: Identity Verification
description: >-
Identity Verification provides knowledge-based authentication for
sensitive account changes. Use these endpoints to challenge a user with
profile and wallet questions, then apply verified phone or email updates
with a single-use verification token.
- name: Banking
description: >-
Banking APIs provide KYC (Know Your Customer) verification functionality
to enable users to comply with financial regulations when using banking
features. These endpoints manage identity verification through document
submission, status tracking, and automated compliance checks.
- name: Counterparties
description: >-
Counterparties define bank accounts where funds are settled for captured
payments. Settlement details live on `externalBankAccount`. There can be
multiple counterparties.
- name: CounterpartyTransfers
description: >-
Counterparty Transfers represent movements of funds between two
counterparties owned by the same partner. Use these endpoints to initiate,
list, and retrieve counterparty-to-counterparty transfers.
- name: LinkedAccounts
description: >-
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.
- name: Widgets
description: >-
<p>Widgets are components that are embedded into applications to enrich
the user experience. Some of those require additional data loaded through
API endpoints.</p><p>Learn more about the different widget types <a
href='/docs/payments/web/widgets'>here</a>.</p>
- name: Sweepstakes
description: >-
Sweepstakes campaigns give users the chance to win prizes by participating
in merchant-sponsored promotions. Each campaign is linked to a specific
merchant and tracks user entries. Users can earn entries through actions
like purchases, and winners are selected based on campaign rules.
Sweepstakes add an engaging layer of excitement and reward to the user
experience.
- name: Rewards
description: >-
Partner-issued rewards let trusted integrations credit customer wallets or
create pre-issued rewards for recipients identified by phone number. When
a recipient has an active wallet, rewards are deposited immediately. When
no active wallet exists, a pre-issued reward is created for the user to
claim when they sign up. All issue requests require an idempotency key.
- name: Gifts
description: >-
Gifts expose remaining spendable balance for a scanned lookUpId.
Point-of-sale remaining lookup is GET /api/v1/gifts/{lookUpId}. Spend
still uses payment intents with the same scanned string as lookUpId —
never send Gift.id as walletId. Amounts are integer cents.
- name: ExternalTransactions
description: >-
External transactions are records of transfers that happened outside the
Accrue system. E.g. purchases in an online shop using a non-Accrue payment
method.
- name: Webhooks
description: Webhook management APIs
- name: WebhookEvents
description: Webhook Event management APIs
- name: Webhook Topics
description: Webhook Topics
x-tagGroups:
- name: Overview
tags:
- Introduction
- API Design
- name: Users
tags:
- Users
- LinkedAccounts
- Identity Verification
- name: Wallets
tags:
- Wallets
- name: Gifts
tags:
- Gifts
- name: Payments
tags:
- PaymentIntents
- Payments
- ExternalTransactions
- Simulations
- name: Banking & KYC
tags:
- Banking
- Counterparties
- CounterpartyTransfers
- name: Sweepstakes
tags:
- Sweepstakes
- name: Rewards
tags:
- Rewards
- name: Widgets
tags:
- Widgets
- name: Webhooks
tags:
- Webhooks
- WebhookEvents
- Webhook Topics
components:
schemas:
PaymentIntentBalanceInformation:
type: object
properties:
available:
type: integer
description: Available wallet balance in cents
format: int32
example: 1500
eligibleReward:
type: integer
description: Eligible reward amount for this transaction in cents
format: int32
example: 500
upperLimit:
type: integer
description: Maximum checkout amount supported for this purchase, in cents
format: int32
example: 103600
required:
- available
- eligibleReward
- upperLimit
description: >-
Balance for this payment intent. `available` is the remaining spendable
amount in cents (gift remaining for a gift lookUpId, or wallet available
for a wallet).
x-tags:
- Model
CreatePaymentIntentResponse:
type: object
properties:
data:
type: object
properties:
id:
type: string
format: uuid
description: Unique identifier for the object.
readOnly: true
type:
type: string
enum:
- PaymentIntent
attributes:
type: object
properties:
balance:
$ref: '#/components/schemas/PaymentIntentBalanceInformation'
billingAddress:
type:
- object
- 'null'
properties:
street:
type:
- string
- 'null'
street2:
type:
- string
- 'null'
city:
type:
- string
- 'null'
state:
type:
- string
- 'null'
postalCode:
type:
- string
- 'null'
country:
type:
- string
- 'null'
required:
- street
- street2
- city
- state
- postalCode
- country
email:
type:
- string
- 'null'
format: email
error:
type:
- string
- 'null'
enum:
- LinkedAccountUnverified
- LinkedAccountDisconnected
- LinkedAccountMissing
- InsufficientBalance
- MissingFullName
- WrongEmail
- InvalidKycStatus
description: Specific error associated with the current invalid status.
expiresAt:
type:
- string
- 'null'
format: date-time
description: >-
The datetime at which the payment intent is set to expire.
After this time, the intent cannot be promoted to a payment
and is considered expired.
readOnly: true
fullName:
type:
- string
- 'null'
phoneNumber:
type:
- string
- 'null'
amount:
type: integer
description: Total purchase amount in cents.
format: int32
example: 3600
reference:
type:
- string
- 'null'
description: Reference to the data inside an external system.
example: MERCHANT-GENERATED-TOKEN
status:
type: string
enum:
- Promotable
- PromotedToPayment
- Invalid
- Expired
- Canceled
description: >-
The current status of the payment intent. Each status
represents a different stage in the payment intent
lifecycle, from creation to completion or cancellation.
example: Promotable
userId:
type:
- string
- 'null'
walletId:
type:
- string
- 'null'
description: >-
The ID of the wallet for which the payment intent is
created.
example: 123e4567-e89b-12d3-a456-426614174000
updatedAt:
type: string
format: date-time
readOnly: true
createdAt:
type: string
format: date-time
readOnly: true
required:
- balance
- updatedAt
- createdAt
required:
- id
- type
- attributes
required:
- data
CreatePaymentIntentInvalidResponse:
type: object
properties:
id:
type: string
format: uuid
description: A unique UUID for this particular occurrence of the problem.
example: 123e4567-e89b-12d3-a456-426614174000
status:
type: integer
description: The HTTP status code applicable to this error.
example: 400
code:
type: string
enum:
- InvalidAmountOrWalletIdentifier
description: A unique, camel-cased Accrue-specific code detailing the error.
example: InvalidAmountOrWalletIdentifier
title:
type: string
description: Generic title for the error.
example: ErrorResponseDto
detail:
type: string
description: >-
A human-readable explanation providing more insights about the
error.
examples:
- Invalid amount or wallet identifier validation failed
meta:
type: object
properties:
environment:
type: string
enum:
- production
- sandbox
example: sandbox
timestamp:
type: string
format: date-time
example: '2025-06-23T12:00:00.000Z'
path:
type: string
example: /api/v1/payment-intents
required:
- environment
- timestamp
- path
example:
environment: sandbox
timestamp: '2025-06-23T12:00:00.000Z'
path: /api/v1/payment-intents
required:
- id
- status
- code
- title
- detail
- meta
CreatePaymentIntentWalletAccessDeniedResponse:
type: object
properties:
id:
type: string
format: uuid
description: A unique UUID for this particular occurrence of the problem.
example: 123e4567-e89b-12d3-a456-426614174000
status:
type: integer
description: The HTTP status code applicable to this error.
example: 403
code:
type: string
enum:
- WalletAccessDenied
description: A unique, camel-cased Accrue-specific code detailing the error.
example: WalletAccessDenied
title:
type: string
description: Generic title for the error.
example: ErrorResponseDto
detail:
type: string
description: >-
A human-readable explanation providing more insights about the
error.
examples:
- Wallet identifier merchant mismatch
meta:
type: object
properties:
environment:
type: string
enum:
- production
- sandbox
example: sandbox
timestamp:
type: string
format: date-time
example: '2025-06-23T12:00:00.000Z'
path:
type: string
example: /api/v1/payment-intents
required:
- environment
- timestamp
- path
example:
environment: sandbox
timestamp: '2025-06-23T12:00:00.000Z'
path: /api/v1/payment-intents
required:
- id
- status
- code
- title
- detail
- meta
CreatePaymentIntentWalletNotFoundResponse:
type: object
properties:
id:
type: string
format: uuid
description: A unique UUID for this particular occurrence of the problem.
example: 123e4567-e89b-12d3-a456-426614174000
status:
type: integer
description: The HTTP status code applicable to this error.
example: 404
code:
type: string
enum:
- WalletIdentifierNotFound
description: A unique, camel-cased Accrue-specific code detailing the error.
example: WalletIdentifierNotFound
title:
type: string
description: Generic title for the error.
example: ErrorResponseDto
detail:
type: string
description: >-
A human-readable explanation providing more insights about the
error.
examples:
- Wallet identifier not found
meta:
type: object
properties:
environment:
type: string
enum:
- production
- sandbox
example: sandbox
timestamp:
type: string
format: date-time
example: '2025-06-23T12:00:00.000Z'
path:
type: string
example: /api/v1/payment-intents
required:
- environment
- timestamp
- path
example:
environment: sandbox
timestamp: '2025-06-23T12:00:00.000Z'
path: /api/v1/payment-intents
required:
- id
- status
- code
- title
- detail
- meta
CreatePaymentIntent:
type: object
properties:
id:
type: string
format: uuid
description: Unique identifier for the object.
readOnly: true
type:
type: string
enum:
- CreatePaymentIntent
attributes:
type: object
properties:
amount:
type: integer
description: Amount to be charged in cents
format: int32
example: 3600
walletId:
type: string
format: uuid
description: >-
Wallet identifier to validate. Optional alternative to
`lookUpId`. Provide exactly one of `walletId` or `lookUpId`.
example: 123e4567-e89b-12d3-a456-426614174000
lookUpId:
type: string
description: >-
Sca
# --- truncated at 32 KB (1290 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/accrue-savings/refs/heads/main/openapi/accrue-savings-merchant-api-openapi.yaml