Skip to content
/
Payout Events

Resolve API Reference (V5)

API Support: accounts@resolvepay.com

Legacy (v2) API documentation: https://app.resolvepay.com/docs/api/v2

Download OpenAPI description
swagger.json
swagger.yaml
Languages
Servers
Mock server
https://api-docs.resolvepay.com/_mock/swagger
Sandbox server
https://app-sandbox.resolvepay.com/api

Introduction

The Resolve API is organized around REST principles. It uses predictable resource-oriented URLs, standard HTTP verbs and response codes, and accepts and returns JSON-encoded request and response bodies.

Getting started

Resolve offers both server-side and client-side integrations. This documentation refers to the server-side API. Refer to our e-commerce plugin guides for details on client-side checkout solutions.

There is a sandbox API available for testing, which leverages the same data store as your sandbox dashboard. Testing on sandbox won't affect your live data or create money movements.

Environment Base URL
Production https://app.resolvepay.com/api/
Sandbox https://app-sandbox.resolvepay.com/api/

Authentication

Before using the API, reach out and get your Resolve account created. This account enables access to the credentials that are necessary for API access.

Resolve uses HTTP basic authentication where the username refers to your merchant ID, and the password refers to your secret API key.

Versioning and Upgrading

When backwards-incompatible changes are released, a new, dated version is released. The current version is V5. You can upgrade the version of the api that your account uses within your merchant settings.

Legacy (v2) API documentation may be found here.

Rate Limits

To ensure platform reliability and fair use, Resolve implements rate limits for the REST API.

Resolve APIs use the Sliding Window algorithm to monitor and control request rates with a 100 requests/minute limit. The API will return a 429 Too Many Requests status if the amount of requests exceeds rate limits.

All responses from Resolve APIs will include the following headers:

  • X-Ratelimit-Limit: The maximum amount of requests permitted within a 60-second period.
  • X-Ratelimit-Remaining: The remaining requests within the current period.
  • X-Ratelimit-Reset: A UNIX timestamp indicating when the rate limit period will reset.

Best Practices

  • Use caching when necessary for data that is routinely requested by your application.
  • Utilize the X-Ratelimit-Limit and X-Ratelimit-Remaining response headers in your application to avoid surpassing rate limits.
  • Your application should avoid making additional API requests if your requests return with a 429 status code.

Webhooks

Webhooks allow you to receive real-time notifications about events in your Resolve account. When an event occurs, Resolve sends an HTTP POST request to your configured webhook endpoint with details about the event.

Operations

Webhook Event Structure

All webhook events follow a consistent structure:

{
  "id": "4ecbe7f9e8c1c9092c000027",
  "object": "invoice",
  "type": "invoice.created",
  "occurred_at": "2021-05-20T09:23:53+00:00",
  "data": {
    "id": "RH5fF9aeQ"
  }
}

The data.id field contains the ID of the object related to the event. You can use this ID to fetch the full object via the corresponding API endpoint.

Supported Event Types

Invoice Events

  • invoice.created - Triggered when a new invoice record is created.
  • invoice.balance_updated - Triggered when the outstanding balance of an invoice changes (for example, when a payment or credit note is applied).

Customer Events

  • customer.created - Triggered when a new customer record is created.
  • customer.status_updated - Triggered when a customer's status changes (for example, when a customer is submitted for a credit check or enrolled).
  • customer.line_amount_updated - Triggered when a customer's credit limit amount is updated.
  • customer.advance_rate_updated - Triggered when a customer's advance rate percentage is updated.
  • customer.credit_decision_created - Triggered when a new credit decision is created for a customer.

Payout Events

  • payout.created - Triggered when a new payout record is created.
  • payout.status_changed - Triggered when the status of a payout changes (for example, pending, in transit, paid).

Verifying Webhook Signatures

To ensure webhook requests are genuine and coming from Resolve, you should verify the webhook signature. Resolve includes a signature in the x-webhook-signature header of each webhook request.

JavaScript Example

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computedSignature)
  );
}

// Usage in Express.js
app.post('/webhooks', express.json(), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const isValid = verifyWebhookSignature(req.body, signature, process.env.WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook event
  const event = req.body;
  console.log('Received event:', event.type);

  res.status(200).send('Webhook received');
});

Retry Policy

If your webhook endpoint doesn't respond successfully (non-2xx status code or connection error), Resolve will automatically retry sending the webhook notification. The retry schedule follows an exponential backoff pattern:

  • 1st retry: 30 seconds after the initial attempt
  • 2nd retry: 90 seconds after the 1st retry
  • 3rd retry: 270 seconds (4.5 minutes) after the 2nd retry
  • 4th retry: 810 seconds (13.5 minutes) after the 3rd retry
  • 5th retry: 2430 seconds (40.5 minutes) after the 4th retry

After the 5th unsuccessful attempt, Resolve will stop retrying and the webhook delivery will be marked as failed.

Best Practices

  • Always verify webhook signatures to ensure the request is from Resolve
  • Respond with a 200 status code as quickly as possible to acknowledge receipt
  • Process webhook events asynchronously if they require time-intensive operations
  • Implement idempotency on your endpoint to handle duplicate events from retries
  • Use the event id to track which events you've already processed

List webhook endpoints

Request

Returns a list of all configured webhook endpoints for the merchant account.

Security
basicAuth
Query
limitinteger[ 25 .. 100 ]

Limit the number of webhook endpoints returned.

Default 25
pagestring

Specify the page of webhook endpoints returned.

Default "1"
curl -i -X GET \
  -u <username>:<password> \
  'https://api-docs.resolvepay.com/_mock/swagger/webhooks?limit=25&page=1'

Responses

An object with an array of results containing up to the limit. If no subscriptions are found, the results array will be empty.

Bodyapplication/json
countinteger

Total number of webhook endpoint subscriptions

Example: 3
pageinteger

Current page number

Example: 1
limitinteger

Number of results per page

Example: 25
resultsArray of objects(WebhookEndpoint)

Array of webhook endpoint objects. Each object represents one endpoint-topic subscription. If an endpoint is subscribed to multiple topics, it will appear multiple times in the array.

Response
application/json
{
  "count": 3,
  "page": 1,
  "limit": 25,
  "results": [
    { … },
    { … },
    { … }
  ]
}

Create or update webhook endpoints

Request

Create a new webhook endpoint or update an existing one. If an endpoint with the same URL already exists, it will be updated with the new event subscriptions.

Security
basicAuth
Bodyapplication/jsonrequired
endpoint_urlstring(uri)^https://required

The HTTPS URL where webhook events will be sent. Must use HTTPS protocol.

Example: "https://example.com/webhooks/resolve"
eventsobject(WebhookEventSubscriptions)required

Object containing boolean flags for each available webhook event topic. Set to true to subscribe to that event, or false to unsubscribe.

events.​invoice.createdboolean

Subscribe to invoice creation events

Example: true
events.​invoice.balance_updatedboolean

Subscribe to invoice balance update events

Example: false
events.​customer.createdboolean

Subscribe to customer creation events

Example: true
events.​customer.status_updatedboolean

Subscribe to customer status update events

Example: false
events.​customer.line_amount_updatedboolean

Subscribe to customer credit line amount update events

Example: false
events.​customer.advance_rate_updatedboolean

Subscribe to customer advance rate update events

Example: false
events.​customer.credit_decision_createdboolean

Subscribe to customer credit decision creation events

Example: true
events.​payment.createdboolean

Subscribe to payment creation events

Example: true
events.​payment.status_changedboolean

Subscribe to payment status change events

Example: true
events.​payout.createdboolean

Subscribe to payout creation events

Example: false
events.​payout.status_changedboolean

Subscribe to payout status change events

Example: false
curl -i -X POST \
  -u <username>:<password> \
  https://api-docs.resolvepay.com/_mock/swagger/webhooks \
  -H 'Content-Type: application/json' \
  -d '{
    "endpoint_url": "https://example.com/webhooks/resolve",
    "events": {
      "invoice.created": true,
      "invoice.balance_updated": true,
      "customer.created": true,
      "customer.credit_decision_created": true
    }
  }'

Responses

Successful response with webhook endpoint subscriptions

Bodyapplication/jsonArray [
idstring

Unique identifier for the webhook endpoint

Example: "whe_abc123def456"
merchant_idstring

The merchant ID associated with this webhook endpoint

Example: "mer_xyz789"
endpoint_urlstring(uri)

The HTTPS URL where webhook events will be sent

Example: "https://example.com/webhooks/resolve"
topicobject

The event topic this endpoint is subscribed to

created_atstring(date-time)

When this webhook endpoint subscription was created

Example: "2021-05-20T09:23:53+00:00"
updated_atstring(date-time)

When this webhook endpoint subscription was last updated

Example: "2021-05-20T09:23:53+00:00"
]
Response
application/json
[
  {
    "id": "whe_abc123def456",
    "merchant_id": "mer_xyz789",
    "endpoint_url": "https://example.com/webhooks/resolve",
    "topic": { … },
    "created_at": "2021-05-20T09:23:53+00:00",
    "updated_at": "2021-05-20T09:23:53+00:00"
  },
  {
    "id": "whe_def456ghi789",
    "merchant_id": "mer_xyz789",
    "endpoint_url": "https://example.com/webhooks/resolve",
    "topic": { … },
    "created_at": "2021-05-20T09:23:53+00:00",
    "updated_at": "2021-05-20T09:23:53+00:00"
  },
  {
    "id": "whe_ghi789jkl012",
    "merchant_id": "mer_xyz789",
    "endpoint_url": "https://example.com/webhooks/resolve",
    "topic": { … },
    "created_at": "2021-05-20T09:23:53+00:00",
    "updated_at": "2021-05-20T09:23:53+00:00"
  }
]

Delete webhook endpoints

Request

Delete a webhook endpoint and all its event subscriptions.

Security
basicAuth
Bodyapplication/jsonrequired
endpoint_urlstring(uri)^https://required

The HTTPS URL of the webhook endpoint to delete

Example: "https://example.com/webhooks/resolve"
curl -i -X DELETE \
  -u <username>:<password> \
  https://api-docs.resolvepay.com/_mock/swagger/webhooks \
  -H 'Content-Type: application/json' \
  -d '{
    "endpoint_url": "https://example.com/webhooks/resolve"
  }'

Responses

Webhook endpoint successfully deleted.

Response
No content

Invoices

The invoice represents the business transaction between you and your customer. In Resolve, an invoice must be tied to a customer and an advance can be taken on the invoice.

For an advance to be taken on the invoice, a PDF of the invoice must be uploaded and the associated customer must be approved and have available credit for the amount of the invoice.

Operations

Customers

A customer represents a company that you do business with. For larger companies, there may be several users with access to the customer account that can make purchases with their credit line. For smaller companies, a customer may represent a single individual. Retrieve a customer to get a summary of their total credit line and available credit balance.

Operations

Payouts

A Payout is a transfer of money between the Merchant and Resolve.

Operations

Payout Transactions

Payout Transactions are the individual transactions like customer payments, Resolve advances, forwarded payments, etc. that are rolled into a Payout. Each Payout is the sum of one or more transactions. Note that certain fields are only relevant to certain transaction types - e.g.: a Payout Transaction of type monthly_fee will have both customer_id and invoice_id set to null.

Operations

Payments

A payment represents a transaction where a customer pays towards their invoices. When a payment is made to Resolve, the customer's available credit balance is increased by the amount of the payment. Payments can be made via various methods including ACH, credit card, check, or wire transfer. Each payment can be applied to one or more invoices.

Operations

Credit Notes

Credit Notes are issued to customers to reduce the amount they owe.

Operations

Shipments

A shipment represents the fulfillment of goods or services for an invoice. Track shipments to monitor delivery status and fulfillment progress. Shipments can be fulfilled through various methods including shipping providers, self-delivery, customer pickup, or for services-only transactions.

Operations