DisburseCloud logo
API docs by Redocly

DisburseCloud (2.0.0)

Download OpenAPI specification:Download

API Support: apiteam@disbursecloud.com URL: https://disbursecloud.com Terms of Service

Introduction

The DisburseCloud API offers a powerful and flexible solution for managing financial disbursements and related processes. Designed for seamless integration with various business platforms, it provides a robust set of tools for handling transactions, authenticating users, and ensuring secure financial operations. Our API is tailored to cater to a wide range of financial services, including automated payments, real-time transaction tracking, and efficient management of user credentials. With its dual environments for sandbox testing and production use, DisburseCloud ensures a reliable and scalable infrastructure, making it an ideal choice for businesses looking to optimize their financial workflows. Whether you're a small enterprise or a large organization, the DisburseCloud API is engineered to provide an intuitive, secure, and efficient way to manage your financial transactions.

Authentication

Disbursecloud uses Access Tokens for Authentication:

  • Description: This endpoint is central to our API's security framework, serving as the primary method for user authentication. By submitting your credentials to this endpoint, you initiate a secure authentication process. Upon successful authentication, the system grants an access token (Bearer token), which is essential for authorizing subsequent API calls. It's important to note that this access token has a validity period of 3600 seconds. For continued access to our API services, include this token in the Authorization header of your API requests, ensuring uninterrupted and secure interaction with our endpoints.

BearerAuth

Security Scheme Type: HTTP
HTTP Authorization Scheme: bearer

authentication

How to authenticate into DisburseCloud

Authentication

This API endpoint allows for user authentication using provided credentials. Upon successful authentication, a Bearer token (access token) will be returned. This token is required for authorization in subsequent API calls and has a lifespan of 3600 seconds . The access token should be passed in the "Authorization" header of all subsequent API requests.

Request Body schema: application/json
required

Create a new token

username
required
string

TIN number of the Company

password
required
string

Company API Key

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiLQndCw0YLQsCDQndCw0YLQsCIsImVtYWlsIjoi0J3QsNGC0LAg0J3QsNGC0LAiLCJqdGkiOiIyZjgzNGNmNi1jZDQ1LTRkOWUtODFiNy1hMDVkZDYzYmMwOTIiLCJpYXQiOiIxMi8yMy8yMDIyIDY6NTk6NTMgUE0iLCJVc2VySWQiOiIxNDkwMTBhZi1mZDI3LTQ2ZTgtYmIzYi03YmNlYTRiYWFjZDkiLCJSb2xlIjoiQWRtaW4iLCJMYW5nIjoiNTc3ODkzZmItOTRkMy00ZjZhLWE1YzMtM2Y3ZDUzNjA4YjU0IiwiVmlkZW9TZXJ2ZXIiOiJWaW1lbyIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvcm9sZSI6IkFkbWluIiwibmJmIjoxNjcxODIxOTkzLCJleHAiOjE2NzE5MDgzOTMsImlzcyI6IkRlbW9Jc3N1ZXIiLCJhdWQiOiJEZW1vQXVkaWVuY2UifQ.lOzWfrSPObws4Q3S_ap59axD_VkEaRfoGWDVv8SH0V0",
  • "token_type": "Bearer",
  • "expires_in": 36000
}

add funds

Add funds to company balance

This endpoint is used to add funds to your company’s account on DisburseCloud. Specify the amount in the query params you want to add to your account and it will deduct that amount from the bank that you provided the details for at the time of signing up for DisburseCloud.

Authorizations:
BearerAuth
query Parameters
amount
required
number

The amount you want to add to the company balance

Responses

Response samples

Content type
application/json
{
  • "prev_balance": 0,
  • "new_balance": 0,
  • "transaction_id": "string",
  • "created_at": "2023-01-20T01:08:33"
}

disbursement

Full-process one-timers

This endpoint is used to release disbursements to payees. You can also specify authorization parties that will authorize a particular payee’s disbursement before the payee receives it. If the information provided is correct, Disbursecloud will release the disbursement to all the payees. DisburseCloud provides its users some payment options such as ACH, Virtual card, Instant deposit, Digital check, Postal Check, Venmo, and PayPal. You can also specify which payment options you want your users to see/choose in this API call.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Create disbursement

payor_email
required
string

Enter the payor’s email that has an account on DisburseCloud associated with your company.

disbursement_uuid
required
string

Enter a unique string which identifies your disbursement.

Array of objects (authorization-partie)

This array contains the AUTH_PARTY objects described below.

required
Array of objects (payee)

This array contains the PAYEE objects described below. You can add the payees to this array you want to send the disbursements to.

Responses

Request samples

Content type
application/json
{
  • "payor_email": "payor@example.com",
  • "disbursement_uuid": "disbursement-1",
  • "authorization_parties": [
    ],
  • "payees": [
    ]
}

Response samples

Content type
application/json
{
  • "disbursement_uuid": "disbursement-test-132",
  • "payor_email": "payor@example.com",
  • "authorization_parties": [
    ],
  • "payees": [
    ],
  • "created_at": "2023-01-20T01:08:33"
}

Cancel disbursement

The "Cancel Disbursement" endpoint enables developers to cancel a disbursement for a specific payee by providing the disbursement uuid and the payee uuid of the disbursement to be cancelled in the request body.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Create a new token

disbursement_uuid
required
string

The disbursement uuid of the disbursement you want to cancel

payee_uuid
required
string

The payee uuid of the payee you want to cancel the disbursement for.

Responses

Request samples

Content type
application/json
{
  • "disbursement_uuid": "disbursement-1",
  • "payee_uuid": "payee-1"
}

Response samples

Content type
application/json
{
  • "name": "The name of the error. Can be one of the following VALIDATION_ERROR INTERNAL_SERVER_ERROR LOW_FUNDS_ERROR",
  • "message": "Provides an explanation for the error's cause.",
  • "details": [
    ]
}

Get disbursement.

This endpoint is used to get the details of a disbursement’s payee.

Authorizations:
BearerAuth
path Parameters
disbursement_uuid
required
string

The disbursement uuid of the disbursement you want the details for.

payee_uuid
required
string

The specific payee’s payee_uuid of whom you want the details for.

Responses

Response samples

Content type
application/json
{
  • "payee_type_id": 1,
  • "amount": 20,
  • "payee_uuid": "payee-1",
  • "email": "payee_1@gmail.com",
  • "first_name": "John",
  • "last_name": "Doe",
  • "address_one": "123 Main Street",
  • "address_two": "",
  • "city": "Payee city",
  • "state": "FL",
  • "zip_code": 33052,
  • "phone": "0000000000",
  • "delivery_options": {
    },
  • "allowed_payment_method_ids": [
    ],
  • "permission_required_from": [
    ],
  • "field_values": [
    ]
}

Resend disbursement email.

This endpoint is used to resend the disbursement email in case the payee does not receive it.

Authorizations:
BearerAuth
path Parameters
disbursement_uuid
required
string

The disbursement uuid of the disbursement you want the details for.

payee_uuid
required
string

The specific payee’s payee_uuid of whom you want the details for.

Responses

Response samples

Content type
application/json
{
  • "name": "The name of the error. Can be one of the following VALIDATION_ERROR INTERNAL_SERVER_ERROR LOW_FUNDS_ERROR",
  • "message": "Provides an explanation for the error's cause.",
  • "details": [
    ]
}

Resend disbursement email.

This endpoint is used to get the transaction details of a payee’s disbursement. The transaction details contain how much was the disbursecloud fee on this payee transaction, what was the billed amount and which payment method was used to complete this payment. You will not get a transaction of a payment unless the payee chooses a payment method.

Authorizations:
BearerAuth
path Parameters
disbursement_uuid
required
string

The disbursement uuid of the disbursement you want the details for.

payee_uuid
required
string

The specific payee’s payee_uuid of whom you want the details for.

Responses

Response samples

Content type
application/json
{
  • "name": "The name of the error. Can be one of the following VALIDATION_ERROR INTERNAL_SERVER_ERROR LOW_FUNDS_ERROR",
  • "message": "Provides an explanation for the error's cause.",
  • "details": [
    ]
}

Get Payee Disbursement Signed Documents.

This endpoint is designed to retrieve all the signed documents related to a payee's disbursement. By utilizing this endpoint, you can access a comprehensive collection of all documents that have been signed and associated with the payee's disbursement. This includes documents such as Auth party, ACH, Payee, and other legal paperwork that may be necessary for the disbursement process. The endpoint provides a convenient and efficient way to access all the necessary signed documents in one place, helping to streamline the disbursement process and ensure that all necessary documentation is easily accessible.

Authorizations:
BearerAuth
Request Body schema: application/json
required

Create disbursement

disbursement_uuid
required
string

The disbursement uuid of the disbursement you want the details for.

payee_uuid
required
string

The specific payee’s payee_uuid of whom you want the details for.

Responses

Request samples

Content type
application/json
{
  • "disbursement_uuid": "string",
  • "payee_uuid": "string"
}

Response samples

Content type
application/json
{
  • "DocumentName": "string",
  • "SignedBy": "string",
  • "SignedOn": "string",
  • "DocumentLink": "string"
}

The Auth Model

username
required
string

TIN number of the Company

password
required
string

Company API Key

{
  • "username": "string",
  • "password": "string"
}

The Onetimer Create Model

payor_email
required
string

Enter the payor’s email that has an account on DisburseCloud associated with your company.

disbursement_uuid
required
string

Enter a unique string which identifies your disbursement.

Array of objects (authorization-partie)

This array contains the AUTH_PARTY objects described below.

required
Array of objects (payee)

This array contains the PAYEE objects described below. You can add the payees to this array you want to send the disbursements to.

{
  • "payor_email": "payor@example.com",
  • "disbursement_uuid": "disbursement-1",
  • "authorization_parties": [
    ],
  • "payees": [
    ]
}

The Auth Party Model

party_uuid
required
string

To ensure proper identification and differentiation between authorization parties, the "party_uuid" field must be unique.

title
string

The "title" field allows developers to specify a title for the authorization party. This title will be displayed in the email sent to the authorization party for the purpose of approving the disbursement. Any relevant or descriptive text can be entered in this field.

email
required
string

The "email" field requires developers to input the email of the authorization party, where they will receive the request for authorization of the disbursement.

first_name
required
string

Auth party’s first name.

last_name
required
string

Auth party’s last name.

phone
required
string

The "phone" field requires developers to input the phone number of the authorization party. This is necessary for authentication via OTP when the authorization party receives the email requesting approval of the disbursement.

{
  • "party_uuid": "auth-party-1",
  • "title": "Policy holder",
  • "email": "auth_party@example.com",
  • "first_name": "James",
  • "last_name": "McGill",
  • "phone": "0000000000"
}

The Delivery Option Model

email
boolean

The "email" field allows developers to specify whether the disbursement should be sent to the payee via email. By setting this field to "true", the disbursement will be delivered to the payee through their registered email.

sms
boolean

The "sms" field allows developers to specify whether the disbursement should be sent to the payee via sms to their registered phone number. By setting this field to "true", the disbursement will be delivered to the payee via SMS.

{
  • "email": true,
  • "sms": false
}

The Payee Model

payee_type_id
required
integer

This parameter defines the type of payee you are sending the disbursement to. The value ranges from 1 to 4. Following is the explanation of all the payee type ids ONE_TIMER = 1, VENDOR = 2, AGENCY = 3, NAMED_INSURED = 4

amount
required
number

The amount needed to be paid to the payee.

payee_uuid
required
string

A unique identifier for the disbursement payee.

email
required
string

When specifying the payee type as "VENDOR", "AGENCY" or "NAMED_INSURED", the "email" field requires developers to input the registered email of the respective vendor on the DisburseCloud platform. In the event that the entered email is not registered, the payee will receive an email inviting them to register on DisburseCloud in order to receive their payment. Alternatively, when specifying the payee type as "ONE_TIMER", the "Enter Payee Email" field requires developers to input the email of the one-time payee to whom the disbursement will be sent.

first_name
required
string

First name of the payee

last_name
required
string

Last name of the payee

address_one
required
string

Address one of the payee

address_two
required
string

Address two of the payee

city
required
string

City name of the payee

state
required
string

The "state" field requires developers to input the state abbreviation in short form. For example, instead of "Florida" it should be entered as "FL".

zip_code
required
string

Payee’s zip code. Should be five characters long.

phone
required
string

Payee’s phone number. Should be 10 characters long. This number is required to verify the payee using an OTP.

required
object (delivery-option)
allowed_payment_method_ids
required
Array of integers

The "allowed_payment_method_ids" field requires developers to input the desired payment method IDs for the payee. The available options range from 1 to 7, corresponding to the following payment methods. 1. ACH 2. POSTAL CHECK 3. VIRTUAL CARD 4. INSTANT DEPOSIT 5. DIGITAL CHECK 6. VENMO 7. PAYPAL For example, to allow the payee to receive payment through ACH and Virtual Card, the developer would input the value of this field in the request body as allowed_payment_method_ids

permission_required_from
Array of strings

To include authorization parties for the payee, developers must add the "party_uuid" field of the AUTH_PARTY object for each desired authorization party to the request array. This will ensure that each designated party approves the payment before it is released to the payee.

Array of objects (field_values)
{
  • "payee_type_id": 1,
  • "amount": 20,
  • "payee_uuid": "payee-1",
  • "email": "payee_1@gmail.com",
  • "first_name": "John",
  • "last_name": "Doe",
  • "address_one": "123 Main Street",
  • "address_two": "",
  • "city": "Payee city",
  • "state": "FL",
  • "zip_code": 33052,
  • "phone": "0000000000",
  • "delivery_options": {
    },
  • "allowed_payment_method_ids": [
    ],
  • "permission_required_from": [
    ],
  • "field_values": [
    ]
}

The Field Value Model

name
required
string

API name of the custom field.

value
required
string

Value of the custom field.

{
  • "name": "insurer_first_name",
  • "value": "Gustavo"
}

The Cancel Disbursement Model

disbursement_uuid
required
string

The disbursement uuid of the disbursement you want to cancel

payee_uuid
required
string

The payee uuid of the payee you want to cancel the disbursement for.

{
  • "disbursement_uuid": "disbursement-1",
  • "payee_uuid": "payee-1"
}

The Signed Documents Model

disbursement_uuid
required
string

The disbursement uuid of the disbursement you want the details for.

payee_uuid
required
string

The specific payee’s payee_uuid of whom you want the details for.

{
  • "disbursement_uuid": "string",
  • "payee_uuid": "string"
}

The Signed Document Response Model

DocumentName
string

This represents the name of the signed document related to the payee's disbursement. It provides a unique identifier for the document, allowing you to easily differentiate between different documents associated with the disbursement.

SignedBy
string

This indicates who signed the document related to the payee's disbursement. It could be the payee themselves, or it could be another party involved in the disbursement process, such as a company representative or legal entity.

SignedOn
string

This element specifies the date on which the document related to the payee's disbursement was signed. It provides important context regarding the timeline of the disbursement process.

DocumentLink
string

This element contains a link to the signed document related to the payee's disbursement. However, please note that the link will only be available for a limited time of 5 minutes. After this time period has elapsed, the link will expire and you will no longer be able to access the document using the link.

{
  • "DocumentName": "string",
  • "SignedBy": "string",
  • "SignedOn": "string",
  • "DocumentLink": "string"
}

The Auth Response Model

access_token
string

This API call includes an access token that must be used for authorization in all subsequent API calls

token_type
string

Indicates the type of authorization token. 'Bearer'.

expires_in
integer

Specifies the expiration time of the token in seconds.

{
  • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiLQndCw0YLQsCDQndCw0YLQsCIsImVtYWlsIjoi0J3QsNGC0LAg0J3QsNGC0LAiLCJqdGkiOiIyZjgzNGNmNi1jZDQ1LTRkOWUtODFiNy1hMDVkZDYzYmMwOTIiLCJpYXQiOiIxMi8yMy8yMDIyIDY6NTk6NTMgUE0iLCJVc2VySWQiOiIxNDkwMTBhZi1mZDI3LTQ2ZTgtYmIzYi03YmNlYTRiYWFjZDkiLCJSb2xlIjoiQWRtaW4iLCJMYW5nIjoiNTc3ODkzZmItOTRkMy00ZjZhLWE1YzMtM2Y3ZDUzNjA4YjU0IiwiVmlkZW9TZXJ2ZXIiOiJWaW1lbyIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvcm9sZSI6IkFkbWluIiwibmJmIjoxNjcxODIxOTkzLCJleHAiOjE2NzE5MDgzOTMsImlzcyI6IkRlbW9Jc3N1ZXIiLCJhdWQiOiJEZW1vQXVkaWVuY2UifQ.lOzWfrSPObws4Q3S_ap59axD_VkEaRfoGWDVv8SH0V0",
  • "token_type": "Bearer",
  • "expires_in": 36000
}

The Disbursement Response Model

disbursement_uuid
string
payor_email
string
Array of objects (authorization-partie)
Array of objects (payeeResponse)
created_at
string
{
  • "disbursement_uuid": "disbursement-test-132",
  • "payor_email": "payor@example.com",
  • "authorization_parties": [
    ],
  • "payees": [
    ],
  • "created_at": "2023-01-20T01:08:33"
}

The Payee Response Model

payee_uuid
string
amount
number
email
string
first_name
string
last_name
string
address_one
string
address_two
string
city
string
state
string
zip_code
string
phone
string
object (delivery-option)
allowed_payment_method_ids
Array of integers
permission_required_from
Array of strings
status
string
payee_type_id
integer
Array of objects (field_values)
{
  • "payee_uuid": "payee-test-1",
  • "amount": 20,
  • "email": "payee_1@gmail.com",
  • "first_name": "John",
  • "last_name": "Doe",
  • "address_one": "123 Main Street",
  • "address_two": "",
  • "city": "Payee city",
  • "state": "FL",
  • "zip_code": 33052,
  • "phone": "0000000000",
  • "delivery_options": {
    },
  • "allowed_payment_method_ids": [
    ],
  • "permission_required_from": [
    ],
  • "status": "PendingAuthorizationPartiesPermission",
  • "payee_type_id": 1,
  • "field_values": [
    ]
}

The Bad Request Model

name
string
message
string
Array of objects (ERROR_DETAIL)

Provides specific details on which fields contain errors.

{
  • "name": "The name of the error. Can be one of the following VALIDATION_ERROR INTERNAL_SERVER_ERROR LOW_FUNDS_ERROR",
  • "message": "Provides an explanation for the error's cause.",
  • "details": [
    ]
}

The Not Found Model

name
string
message
string
Array of objects (ERROR_DETAIL)

Contains the details about the specific fields that have an error.

{
  • "name": "The name of the error. Will be one of the following. NOT_FOUND_ERROR",
  • "message": "Contains the reason why this error occurred.",
  • "details": [
    ]
}

The ERROR DETAIL Model

Issue
string
Field
string
Location
string

The location of the field where it is located. This field’s value can be one of the following body,header

{
  • "Issue": "The description of the error",
  • "Field": "The name of the field that has the error.",
  • "Location": "string"
}

The Internal Server Error Model

name
string
message
string
details
string
{
  • "name": "INTERNAL_SERVER_ERROR",
  • "message": "An error occurred while processing your request. Please try again!",
  • "details": null
}