Testing in sandbox

In production, RFIs are raised by Hubpay's review team when additional information or documentation is needed on an account or transaction. You can't open, close, or cancel an RFI yourself in production — but in sandbox, dedicated endpoints let you drive every step of the lifecycle so you can verify your integration end-to-end without waiting on a real review.

Sandbox only

All endpoints on this page are gated to non-production environments. They return 404 in production.

Prerequisites

Before you begin, make sure you have:

A sandbox API key and the ability to authenticate (see Authentication)
A webhook endpoint registered to receive events (see Webhooks overview)
An onboarded account (ACTIVE status) on your sandbox partner — RFIs typically appear post-onboarding, so you'll want an account past the initial KYB stage before opening one

What you can simulate

Endpoint	What it does	Webhook fired
`POST /v1/rfi/open`	Opens a new RFI on the calling account	`v1.rfi.case.opened`
`POST /v1/rfi/{rfiId}/close`	Transitions the RFI to `CLOSED`	`v1.rfi.case.closed`
`POST /v1/rfi/{rfiId}/cancel`	Transitions the RFI to `CANCELLED`	`v1.rfi.case.cancelled`

For approving or declining individual documents attached to an RFI, use the RFI-scoped sandbox endpoints:

Endpoint	Webhook fired
`POST /v1/rfi/documents/{documentId}/approve`	`v1.rfi.document.approved`
`POST /v1/rfi/documents/{documentId}/decline`	`v1.rfi.document.declined`

For KYB documents uploaded during initial onboarding, see Simulating onboarding decisions.

End-to-end RFI flow

Below is a typical sandbox round-trip — open an RFI, respond to it from your integration, mark the documents as reviewed, then close the case.

1. Open an RFI

POST /v1/rfi/open opens a new RFI against the calling account. Provide at least one question or one document request. Document requests take a free-text customLabel describing what the customer should upload.

curl -L -X POST 'https://sandbox-api.hubpay.io/v1/rfi/open' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'AccountId: 058a2d45-139c-436b-8d1f-eec265e0f418' \
-H 'Authorization: Bearer <token>' \
-d '{
  "subjectType": "ONBOARDING_APPLICATION",
  "subjectId": "058a2d45-139c-436b-8d1f-eec265e0f418",
  "customerDisplayMessage": "We need a few more documents before we can complete your application.",
  "questions": [
    {
      "prompt": "What is the source of the initial deposit?"
    }
  ],
  "documentRequests": [
    {
      "customLabel": "Bank statement covering the last 3 months"
    }
  ]
}'

The response is the full Rfi — capture the id. Your webhook endpoint will receive v1.rfi.case.opened immediately after.

2. Respond to the RFI

Switch to your customer-facing integration and respond using the normal RFI APIs — answer the questions and attach the requested documents. This part is identical between sandbox and production.

3. Approve or decline each attached document

For each document the customer attaches to a slot, use the RFI-scoped sandbox endpoints to mark it APPROVED or DECLINED:

curl -L -X POST 'https://sandbox-api.hubpay.io/v1/rfi/documents/{documentId}/approve' \
-H 'AccountId: 058a2d45-139c-436b-8d1f-eec265e0f418' \
-H 'Authorization: Bearer <token>'

Each call dispatches the matching v1.rfi.document.approved (or .declined) webhook so your integration can update the per-slot UI.

4. Close (or cancel) the RFI

Once you've simulated reviewing every item, close the case to transition it to the terminal state and fire v1.rfi.case.closed:

curl -L -X POST 'https://sandbox-api.hubpay.io/v1/rfi/{rfiId}/close' \
-H 'AccountId: 058a2d45-139c-436b-8d1f-eec265e0f418' \
-H 'Authorization: Bearer <token>'

Or cancel the case (with a reason recorded for audit) to fire v1.rfi.case.cancelled:

curl -L -X POST 'https://sandbox-api.hubpay.io/v1/rfi/{rfiId}/cancel' \
-H 'Content-Type: application/json' \
-H 'AccountId: 058a2d45-139c-436b-8d1f-eec265e0f418' \
-H 'Authorization: Bearer <token>' \
-d '{
  "cancellationReason": "Superseded by a follow-up request."
}'

Both endpoints return 204 No Content.

Notes

The owning account always resolves from the AccountId header — you cannot open or transition an RFI on another partner's account.
customLabel on each document request is required.
For subjectType=TRANSACTION, you must also supply subjectReference (the transaction reference the customer will see in the customer-display message).

Prerequisites​

What you can simulate​

End-to-end RFI flow​

1. Open an RFI​

2. Respond to the RFI​

3. Approve or decline each attached document​

4. Close (or cancel) the RFI​

Notes​