Getting Started

Authentication

The /auth/authenticate endpoint allows you to obtain an authorization bearer token required for making authenticated requests to the API. This guide provides step-by-step instructions on how to use this endpoint.

Prerequisites

Before proceeding, ensure that you have:

Subscription Key

  • Can be used as a Query Parameter: subscription-key or Header: Ocp-Apim-Subscription-Key

  • The subscription key will be specific to the environment you are connecting to, for example sandbox, sandbox1, sandbox2, or production.

API Credentials

  • apiKey: Your API key.

  • apiSecret: Your API secret.

Steps to Obtain Authorization Token

1. Make a POST Request to /auth/authenticate

Send a POST request to the /auth/authenticate endpoint with the following details:

Endpoint: /auth/authenticate

Method: POST

Request Headers:

Ocp-Apim-Subscription-Key: your_subscription_key
Content-Type: application/json

Request Body:

{
  "apiKey": "your_api_key",
  "apiSecret": "your_api_secret"
}

2. Receive Authorization Token

If the request is successful, you will receive a response with a status code of 200. The response body will contain an authorization token and its expiration date.

{
  "token": "your_authorization_token",
  "expiration": "expiration_date_time"
}

Important Notes

  • Security: Keep your API key and secret secure. Do not expose them in public spaces.

  • Token Expiration: The authorization token has a limited lifespan. Be aware of its expiration and refresh it as needed.

3. Use the Authorization Token

Include the obtained authorization token in the Authorization header of your subsequent API requests. This will authenticate and authorize your requests to the protected endpoints.

Test by making a GET Request to /account/list

Send a GET request to the /account/list endpoint with the following details:

Endpoint: /account/list

Method: GET

Request Headers:

Authorization: Bearer your_authorization_token
Ocp-Apim-Subscription-Key: your_subscription_key

If the request is successful, you will receive a response with a status code of 200. The response body will contain a JSON object with information about the listed accounts.

{
  "success": true,
  "error": "string",
  "message": "string",
  "count": 0,
  "data": [
    {
      "accountId": "string",
      "accountNumber": "string",
      "productName": "string"
    }
  ]
}

Response Format

Every endpoint returns the same JSON envelope, so you can handle success and failure consistently across the API.

{
  "success": true,
  "error": "string",
  "message": "string",
  "data": { }
}

  • success - Indicates whether the request was processed successfully. Always check this value before reading data.

  • error - A description of the failure, including an error code. Omitted when the request succeeds.

  • message - Additional context about the request. Not always present.

  • data - The result of the request. Endpoints that return a collection also include a count property.

Error Codes

Errors include a code in the form (Error Code: VE00001). The prefix identifies the category of the failure, which is useful when deciding whether a request should be corrected, retried, or escalated.

  • VE - Validation. The request was malformed or a value was outside the allowed range. Correct the request before retrying.

  • PE - Payment. The request was well formed but could not be accepted, such as exceeding a limit.

  • KA - Authorization. Your subscription is not authorized for the requested account or endpoint.

  • CA - Core banking. An internal error occurred communicating with the core. Retry, and contact us if it persists.

  • LE - Third party. An internal error occurred communicating with an external service.

  • GE - General. An internal or configuration error occurred. Contact us if it persists.

A response with an HTTP status of 200 or 201 may still contain "success": false. Treat the success property as the authoritative result of your request.

Idempotency

Idempotency is a concept in API design that ensures the same request, when made multiple times, produces the same result as the initial request. It is particularly useful in scenarios where a client may need to retry a request that was not completed successfully without risking unintended side effects.

This guide explains the use of the Idempotency-Key header in API requests to achieve idempotency.

What is the Idempotency-Key?

The Idempotency-Key is a unique value generated by the client and included in the request headers. This key allows the server to recognize subsequent retries of the same request and ensures that repeated requests with the same key do not result in unintended side effects.

How to Use Idempotency-Key

  1. Generate a Unique Idempotency Key

    Before making an API request, generate a unique idempotency key. This key should be unique for each distinct operation or request.

  2. Include the Idempotency Key in the Request

    Include the generated idempotency key in the Idempotency-Key header of your API request. This header signals to the server that the request should be treated idempotently.

    POST /payment/ach
    Host: your_api_host
    Content-Type: application/json
    Idempotency-Key: unique_idempotency_key

  3. Server Processing

    When the server receives a request with the Idempotency-Key header, it checks if a previous request with the same key has been processed in the past 12 hours. If the server has already processed a request with the same key, it returns an error:

    You have provided a duplicate Idempotency key. (Error Code: VE00027)

ACH

Lots of resources are available in Needham Bank's ACH Originator Guide.

Reversals

Introduction to ACH Reversals

Definition: An ACH reversal is used to correct an erroneous or duplicate transaction that has been processed through the ACH network. It effectively cancels the original transaction, either fully or partially, depending on the specific situation.

Purpose: The primary purpose of an ACH reversal is to rectify processing errors, ensuring the financial integrity of both parties involved in the transaction.

When to Use an ACH Reversal

  • Duplicate Transactions: If a transaction is accidentally processed more than once, an ACH reversal can be used to remove the duplicate entries. While we utilize idempotency to prevent duplicate transactions, if a duplicate is submitted with unique idempotency keys a reversal can be used.

  • Incorrect Amounts: In cases where the transaction amount is wrong, a reversal can correct the financial records.

  • Wrong Account: If funds are sent to or debited from the wrong account, a reversal can rectify this error.

  • Unauthorized Transactions: For transactions processed without proper authorization, reversals are necessary to comply with legal and regulatory standards.

Legal and Compliance Considerations

  • Timeframe: The National Automated Clearing House Association (NACHA) rules generally require reversals to be initiated within five business days from the settlement date of the erroneous transaction.

  • Authorization: Certain reversals might require the consent of the party receiving the funds, depending on the nature of the error and regulatory requirements.

To Submit an ACH Reversal through the API

  1. Submit a new ACH Payment through the correct /payment endpoint.

  2. Ensure the values for counterparty and other details match the original transaction.

  3. Use REVERSAL__ as the companyEntryDescription property.

Failure of an Originator or Third-Party Sender to fund its outgoing credit file is not a valid reason for a file reversal.

  • The reversing entry must be transmitted to the bank within five banking days after the settlement date of the duplicate or erroneous file.

  • Transmit the reversing entry within 24 hours of discovering the error.

Our team may reach out to you to assist if a reversal is submitted.

Webhooks

Data for the chosen events will be sent as JSON via POST requests to the provided URLs.

Format

{
  "PaymentId": "a85ab18d-cb35-468f-bb0e-d5e07dbeb675",
  "OldStatus": "Pending",
  "NewStatus": "Approved",
  "EffectiveDate": "2024-01-11"
}

X-ProvX-Signature Value

49a354dac40cb896f4a49afe1201239d1e83952a

Verifying Webhooks from Our System

Understanding the Verification Process

To ensure the security and integrity of webhooks received by your system, it is crucial to verify the source of each webhook request. This is done using the "X-ProvX-Signature" header, which is included in each webhook request sent from our system.

X-ProvX-Signature Header

  • Purpose: The "X-ProvX-Signature" header is used to validate the authenticity of the webhook request.

  • Composition: This header contains a SHA1 hash. This hash is a unique representation, generated from the concatenation of the webhook ID and the JSON body of the request.

Steps for Verification

  1. Extract the Signature

    When your system receives a webhook request, extract the "X-ProvX-Signature" header value.

  2. Generate Your Hash

    Use the SHA1 hashing algorithm to create a hash. Concatenate the webhook ID and the raw JSON body of the request, in that order, to form the input string for the hash. The webhook ID must be lowercase with the hyphens removed, for example 3fa85f6457174562b3fc2c963f66afa6. Hash the input string as UTF-8 and format the result as lowercase hexadecimal.

  3. Compare Hashes

    Compare the SHA1 hash you generated with the hash provided in the "X-ProvX-Signature" header. If they match, it confirms the request is from a trusted source.

Your webhook ID is the webhookId value returned by GET /webhook/list and GET /webhook/{webhook_id}.

Webhook Events

Below are the events available for triggering a webhook.

Payment Received

Triggered when a payment is successfully received by your system.

Payment Status Update

Notifies changes in the status of a payment.

Sub-Events

ACH Statuses:

  • Completed: Indicates the payment has been processed and sent to the Federal Reserve.

  • Settled: Occurs when funds are deposited into the account.

  • Returned: Triggered when funds are returned by the other institution.

Wire Completed

Indicates the completion of a wire transfer.

ProvX Completed

Triggered upon the successful completion of a ProvX transaction.

Account Application Status Update

Notifies changes in the status of an account application.

Account Created

Triggered when a new account is successfully created.

Account Fee

Notifies when a fee is applied to an account.

Customer Person Verification Status Update

Updates on the verification status of an individual customer.

Customer Business Verification Status Update

Updates on the verification status of a business customer.

Check Deposit

The /account/{account_id}/check endpoint allows you to submit a remote deposit capture check deposit by providing the check details along with images of the front and back of the check.

How It Works

  1. You submit the check details and images. The deposit is accepted immediately and recorded with a status of Pending.

  2. Deposits are batched once each business day at the daily cutoff of 3:25 PM ET and submitted for clearing. Deposits submitted after the cutoff, or on a weekend or Federal holiday, are included in the next business day batch.

  3. Each business day, pending deposits are verified against the account. Once the deposit is located, the status changes to Complete.

  4. If a deposit cannot be verified within two business days of submission, the status changes to Failed.

Before You Begin

Before submitting a deposit, ensure that:

  • You have a valid authorization token, as described in Authentication above.

  • The account is in an Active status. Deposits to an account in any other status are rejected.

  • Your subscription is approved for check deposits and the amount is within your assigned limits.

Checking Your Limits

Check deposits are validated against both a per-transaction limit and a daily limit. Retrieve your current limits with a GET request to /limit.

Endpoint: /limit

Method: GET

Request Headers:

Authorization: Bearer your_authorization_token
Ocp-Apim-Subscription-Key: your_subscription_key

The checkDeposit object in the response contains your limits.

{
  "success": true,
  "data": {
    "checkDeposit": {
      "transactionExposureLimit": 25000.00,
      "dailyExposureLimit": 100000.00,
      "available": 100000.00
    }
  }
}

  • transactionExposureLimit - The maximum amount for a single deposit. A value of 0 indicates that no per-transaction limit is applied.

  • dailyExposureLimit - The maximum total amount that may be deposited in a single day.

  • available - The remaining amount that may be deposited today.

Image Requirements

Both the front and back images are required and must meet the following requirements:

  • Encoding: A Base64-encoded string. Do not include a data URI prefix such as data:image/png;base64,.

  • Format: TIFF, PNG, or JPEG. The format is detected from the image data itself, so the value must be a valid file of one of these types.

  • Size: A maximum of 250 kB per image, measured on the decoded image.

For best results, capture the check cropped to its edges, in grayscale or black and white, with the full MICR line legible.

Submitting a Check Deposit

Endpoint: /account/{account_id}/check

Method: POST

Request Headers:

Authorization: Bearer your_authorization_token
Ocp-Apim-Subscription-Key: your_subscription_key
Idempotency-Key: unique_idempotency_key
Content-Type: application/json

The Idempotency-Key header is required for this endpoint. See the Idempotency section above.

Request Body:

{
  "transactionAmount": 1250.75,
  "payorBankRoutingNumber": "011401533",
  "checkNumber": "1042",
  "front": "base64_encoded_front_image",
  "back": "base64_encoded_back_image",
  "internalDescription": "October rent - unit 12",
  "externalReference": "INV-000123"
}

Request Properties

  • transactionAmount - Required. The amount of the check in USD. Minimum 0.01, maximum 99999999.99, with no more than two decimal places.

  • payorBankRoutingNumber - Required. The full 9-digit routing number of the paying bank from the MICR line, including the check digit. Digits only.

  • checkNumber - Required. The check number. Maximum 15 characters.

  • front - Required. A Base64-encoded image of the front of the check.

  • back - Required. A Base64-encoded image of the back of the check.

  • internalDescription - Optional. Information about the deposit for your own future use. Maximum 250 characters.

  • externalReference - Optional. Information about the deposit. Maximum 100 characters.

Receiving the Deposit Response

A successful request returns a status code of 201. The response body contains the details of the newly created deposit.

{
  "success": true,
  "data": {
    "transactionId": "a85ab18d-cb35-468f-bb0e-d5e07dbeb675",
    "accountId": "3f21c9de-7b44-4a12-9d8e-1c2b3a4d5e6f",
    "createDate": "2026-09-08T10:30:00",
    "externalReference": "INV-000123",
    "internalDescription": "October rent - unit 12",
    "checkNumber": "1042",
    "amount": 1250.75,
    "status": "Pending"
  }
}

Retain the transactionId value. It is required to check the status of the deposit.

Checking Deposit Status

Check deposits do not trigger a webhook event. To monitor a deposit, poll the transaction details endpoint using the transactionId returned when the deposit was created.

Endpoint: /account/transaction/{transaction_id}

Method: GET

Request Headers:

Authorization: Bearer your_authorization_token
Ocp-Apim-Subscription-Key: your_subscription_key

Because deposits are batched and verified on a daily schedule, polling once per business day is sufficient. Deposits also appear in the results of /account/{account_id}/transactions.

Deposit Statuses

  • Pending - The deposit has been accepted and is awaiting or undergoing clearing.

  • Complete - The deposit has been verified and posted to the account.

  • Failed - The deposit could not be verified within two business days and was not posted.

Check Deposit Errors

In addition to the standard authentication and idempotency errors, the following errors are specific to check deposits.

  • VE00001 - A required parameter was not provided. One of transactionAmount, checkNumber, front, or back is missing.

  • VE00002 - payorBankRoutingNumber is missing, is not exactly 9 characters, or contains non-numeric characters.

  • VE00020 - checkNumber, internalDescription, or externalReference exceeds its maximum length.

  • VE00028 - transactionAmount is greater than 99999999.99.

  • VE00062 - An image is not valid Base64, or is not a TIFF, PNG, or JPEG.

  • VE00063 - One or both images exceed the maximum allowed size of 250 kB.

  • PE00001 - The deposit would exceed your daily check deposit limit.

  • PE00008 - The deposit exceeds your per-transaction check deposit limit.

  • KA00003 - The account is not in an Active status.

A transactionAmount with more than two decimal places returns the message "Value provided is not a valid currency value."

Important Notes

  • Retain your images. Keep your own copy of the check images and the original paper item, in accordance with your retention policy, until the deposit reaches a Complete status.

  • Avoid duplicate deposits. Use a unique idempotency key for each deposit, and do not submit the same physical check more than once. Duplicate presentment may result in a returned item.

  • Endorsement. The back image should reflect a proper endorsement of the item.

  • Retrieving paid check images. The /account/{account_id}/checks/images endpoint returns images of checks paid against your account. It does not return images of checks you have deposited.