Skip to content

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

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

List credit notes

Request

Return a list of credit notes.

Security
basicAuth
Query
limitinteger[ 25 .. 100 ]

Limit the number of credit notes returned.

Default 25
pagestring

Specify the page of credit notes returned.

Default "1"
filterobject

Filter credit notes by the specified fields.

Filter semantics: filter[field][operator]=value.

Available filter operators:

  • eq - equal (=)
  • gt - greater than (>)
  • gte - greater than or equal (>=)
  • lt - less than (<)
  • lte - less than or equal (<=)

Filtering is allowed by the following fields:

  • number (eq)
  • customer_id (eq)
  • invoice_id (eq)
  • payment_id (eq)
  • amount (eq, gt, lt, gte, lte)
  • amount_balance (eq, gt, lt, gte, lte)
  • amount_paid (eq, gt, lt, gte, lte)

Example: filter[number][eq]=CN-001

Note: filter with the eq operator is equivalent to the following filter filter[field]=value

sortstring

Sort credit notes by the specified field. Use - prefix for descending order.

Available sort fields:

  • id
  • created_at
  • amount
  • amount_balance

Example: sort=-created_at (sort by created_at in descending order)

Default "-created_at"
Enum"id""-id""created_at""-created_at""amount""-amount""amount_balance""-amount_balance"
curl -i -X GET \
  -u <username>:<password> \
  'https://api-docs.resolvepay.com/_mock/swagger/credit-notes?limit=25&page=1&filter%5Bnumber%5D=%5Bobject+Object%5D&filter%5Bcustomer_id%5D=%5Bobject+Object%5D&filter%5Binvoice_id%5D=%5Bobject+Object%5D&filter%5Bpayment_id%5D=%5Bobject+Object%5D&filter%5Bamount%5D=%5Bobject+Object%5D&filter%5Bamount_balance%5D=%5Bobject+Object%5D&filter%5Bamount_paid%5D=%5Bobject+Object%5D&sort=id'

Responses

A paginated list of credit notes.

Bodyapplication/json
countinteger
Example: 1
limitinteger
Example: 25
pageinteger
Example: 1
resultsArray of objects(CreditNote)
Response
application/json
{
  "count": 1,
  "limit": 25,
  "page": 1,
  "results": [
    { … }
  ]
}

Create a credit note

Request

Create a new credit note.

Security
basicAuth
Bodyapplication/json

Issue a credit note for an invoice.

invoice_idstringrequired

ID of the invoice

Example: "PMMlaE5wbg0"
amountnumber(double)required

Amount of the credit note

Example: 2000
numberstring

Number of the credit note

Example: "CN-001"
reason_codestringrequired

Reason code for the credit note

Enum"chargeback""duplicate""fraudulent""requested_by_customer""missing_remittance""overpayment_on_invoice""invoice_was_refunded""double_payment_on_invoice""missing_invoice_in_resolve""credit_transfer"
Example: "reason_code"
reason_messagestring

Reason message for the credit note

Example: "reason_message"
credit_note_urlstring

URL for the publicly-accessible credit note PDF.

Example: "https://example.com/credit_note_url.pdf"
curl -i -X POST \
  -u <username>:<password> \
  https://api-docs.resolvepay.com/_mock/swagger/credit-notes \
  -H 'Content-Type: application/json' \
  -d '{
    "invoice_id": "PMMlaE5wbg0",
    "amount": 2000,
    "number": "CN-001",
    "reason_code": "reason_code",
    "reason_message": "reason_message",
    "credit_note_url": "https://example.com/credit_note_url.pdf"
  }'

Responses

An object containing the status of the credit note creation request.

Bodyapplication/json
statusstring

Status of the credit note action

Enum"pending""processing""failed""completed"
Example: "pending"
Response
application/json
{
  "status": "pending"
}

Request to void a credit note

Request

Request to void an existing credit note.

Security
basicAuth
curl -i -X POST \
  -u <username>:<password> \
  'https://api-docs.resolvepay.com/_mock/swagger/credit-notes/{credit_note_id}/void'

Responses

The credit note object.

Bodyapplication/json
idstring

Unique identifier for the credit note.

Example: "CNMlaE5wbg0"
sourcestring

Source of the credit note creation.

Enum"MERCHANT_USER""ADMIN_USER""API"
Example: "MERCHANT_USER"
customer_idstring

ID of the customer associated with the credit note.

Example: "X50sgfRd"
merchant_idstring

ID of the merchant.

Example: "MER456789"
invoice_idstring

ID of the invoice this credit note is associated with.

Example: "PMMlaE5wbg0"
created_by_user_idstring

ID of the user who created the credit note.

Example: "USR123456"
numberstring

Credit note number identifier.

Example: "CN-001"
amountnumber(double)

Total amount of the credit note.

Example: 1000
amount_balancenumber(double)

Remaining balance to be applied.

Example: 500
amount_paidnumber(double)

Amount that has been applied/paid out.

Example: 500
amount_voidednumber(double)

Amount that has been voided.

Example: 0
amount_payoutnumber(double)

Total payout amount for the credit note.

Example: 1000
amount_payout_balancenumber(double)

Remaining payout balance.

Example: 500
amount_payout_paidnumber(double)

Amount that has been paid out.

Example: 500
credit_note_urlstring

The credit note PDF that you've uploaded to Resolve.

Example: "https://www.example.com/credit-note.pdf"
resolve_credit_note_urlstring

Resolve-issued credit note PDF.

Example: "https://www.example.com/resolve-credit-note.pdf"
reason_codestring

The reason code for issuing this credit note.

Enum"chargeback""duplicate""fraudulent""requested_by_customer""missing_remittance""overpayment_on_invoice""invoice_was_refunded""double_payment_on_invoice""missing_invoice_in_resolve""credit_transfer"
Example: "requested_by_customer"
reason_messagestring

Additional details explaining the reason for the credit note.

Example: "Customer returned damaged goods"
voidedboolean

Indicates whether the credit note is voided.

Example: false
voided_atstring(date-time)

Date the credit note was voided.

Example: null
Response
application/json
{
  "id": "CNMlaE5wbg0",
  "source": "MERCHANT_USER",
  "customer_id": "X50sgfRd",
  "merchant_id": "MER456789",
  "invoice_id": "PMMlaE5wbg0",
  "created_by_user_id": "USR123456",
  "number": "CN-001",
  "amount": 1000,
  "amount_balance": 500,
  "amount_paid": 500,
  "amount_voided": 0,
  "amount_payout": 1000,
  "amount_payout_balance": 500,
  "amount_payout_paid": 500,
  "credit_note_url": "https://www.example.com/credit-note.pdf",
  "resolve_credit_note_url": "https://www.example.com/resolve-credit-note.pdf",
  "reason_code": "requested_by_customer",
  "reason_message": "Customer returned damaged goods",
  "voided": false,
  "voided_at": null
}

Fetch a credit note

Request

Retrieve an existing credit note by its ID.

Security
basicAuth
Path
credit_note_idstringrequired

ID of the credit note to retrieve

curl -i -X GET \
  -u <username>:<password> \
  'https://api-docs.resolvepay.com/_mock/swagger/credit-notes/{credit_note_id}'

Responses

The credit note object.

Bodyapplication/json
idstring

Unique identifier for the credit note.

Example: "CNMlaE5wbg0"
sourcestring

Source of the credit note creation.

Enum"MERCHANT_USER""ADMIN_USER""API"
Example: "MERCHANT_USER"
customer_idstring

ID of the customer associated with the credit note.

Example: "X50sgfRd"
merchant_idstring

ID of the merchant.

Example: "MER456789"
invoice_idstring

ID of the invoice this credit note is associated with.

Example: "PMMlaE5wbg0"
created_by_user_idstring

ID of the user who created the credit note.

Example: "USR123456"
numberstring

Credit note number identifier.

Example: "CN-001"
amountnumber(double)

Total amount of the credit note.

Example: 1000
amount_balancenumber(double)

Remaining balance to be applied.

Example: 500
amount_paidnumber(double)

Amount that has been applied/paid out.

Example: 500
amount_voidednumber(double)

Amount that has been voided.

Example: 0
amount_payoutnumber(double)

Total payout amount for the credit note.

Example: 1000
amount_payout_balancenumber(double)

Remaining payout balance.

Example: 500
amount_payout_paidnumber(double)

Amount that has been paid out.

Example: 500
credit_note_urlstring

The credit note PDF that you've uploaded to Resolve.

Example: "https://www.example.com/credit-note.pdf"
resolve_credit_note_urlstring

Resolve-issued credit note PDF.

Example: "https://www.example.com/resolve-credit-note.pdf"
reason_codestring

The reason code for issuing this credit note.

Enum"chargeback""duplicate""fraudulent""requested_by_customer""missing_remittance""overpayment_on_invoice""invoice_was_refunded""double_payment_on_invoice""missing_invoice_in_resolve""credit_transfer"
Example: "requested_by_customer"
reason_messagestring

Additional details explaining the reason for the credit note.

Example: "Customer returned damaged goods"
voidedboolean

Indicates whether the credit note is voided.

Example: false
voided_atstring(date-time)

Date the credit note was voided.

Example: null
Response
application/json
{
  "id": "CNMlaE5wbg0",
  "source": "MERCHANT_USER",
  "customer_id": "X50sgfRd",
  "merchant_id": "MER456789",
  "invoice_id": "PMMlaE5wbg0",
  "created_by_user_id": "USR123456",
  "number": "CN-001",
  "amount": 1000,
  "amount_balance": 500,
  "amount_paid": 500,
  "amount_voided": 0,
  "amount_payout": 1000,
  "amount_payout_balance": 500,
  "amount_payout_paid": 500,
  "credit_note_url": "https://www.example.com/credit-note.pdf",
  "resolve_credit_note_url": "https://www.example.com/resolve-credit-note.pdf",
  "reason_code": "requested_by_customer",
  "reason_message": "Customer returned damaged goods",
  "voided": false,
  "voided_at": null
}

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