Transfer RFI

What to do when Harbor needs more information to process a transfer.

Sometimes Harbor needs more information about a transfer before it can process it. This is a Request for Information (RFI). The transfer stops until the Customer provides the information.

ActionEndpoint
Retrieve the transferGET /api/v2/transfers/{transfer_uuid}
Get the RFI questionsGET /api/v2/transfers/{transfer_uuid}/rfi
Send the RFI answersPOST /api/v2/transfers/{transfer_uuid}/rfi/answer

How It Works

  1. The transfer's status changes to request_for_information. Harbor sends the transfer.status.request_for_information webhook.
  2. The Customer answers the RFI, on a hosted page or through your app.
  3. Harbor reviews the answers.
  4. The transfer continues, or it's rejected.

Types of RFI

The transfer's sub_status shows the type:

  • Payment network RFI (cpn_rfi): the off-ramp payment network needs more information. Harbor also sends the transfer.sub_status.cpn_rfi webhook.
  • Compliance RFI (null): Harbor's compliance team needs more information, or the Customer must redo facial liveness verification.

Find the RFI

GET /api/v2/transfers/{transfer_uuid}

The transfer, and the webhook, include the RFI details:

{
    "data": {
        "uuid": "transfer_ti4wqXVJ5OG9iWtKvyrWQFycFGmFu22tOKm8Zd5z",
        "status": "request_for_information",
        "sub_status": "cpn_rfi",
        "type": "off-ramp",
        ...,
        "rfi_link": "https://harbor-sandbox.owlpay.com/gocpnrfi?expires=...&hash=...",
        "rfi_description": null,
        "rfi_questions": [],
        ...
    }
}
  • rfi_link: the page where the Customer answers.
  • rfi_description: what's needed. Compliance RFI only; otherwise null.
  • rfi_questions: the questions. Compliance RFI only; otherwise empty.

These fields only appear while the transfer is in request_for_information.

Answer on the Hosted Page

Send the Customer to the rfi_link. They answer the questions and upload any files there.

This is the simplest option, and it works for every RFI.

Answer With the API

Use this to show the questions in your own app.

Get the Questions

GET /api/v2/transfers/{transfer_uuid}/rfi

{
    "data": {
        "type": "cpn",
        "status": "pending",
        "expire_date": "2026-09-20T00:00:00+00:00",
        "description": "Please provide additional documentation to support this transaction.",
        "questions": [
            {
                "key": "SOURCE_OF_FUNDS",
                "label": "Source of Funds",
                "type": "short_answer",
                "required": true,
                "limit": {}
            },
            {
                "key": "PROOF_OF_FUNDS",
                "label": "Proof of Funds",
                "type": "file",
                "required": true,
                "limit": {}
            }
        ],
        ...
    }
}
{
    "data": {
        "type": "general",
        "status": "pending",
        "expire_date": null,
        "description": "Please provide additional documentation regarding the source of funds.",
        "questions": [
            {
                "key": "1",
                "label": "Proof of address",
                "type": "file",
                "required": true,
                "limit": {
                    "count": { "min": 1, "max": 6 },
                    "size": { "max": 8192 },
                    "acceptType": ["jpg", "png", "pdf"]
                }
            },
            {
                "key": "2",
                "label": "Purpose of transaction",
                "type": "select",
                "required": true,
                "options": [
                    { "label": "Payment for goods", "value": "GOODS" },
                    { "label": "Payment for services", "value": "SERVICES" }
                ],
                "limit": {}
            }
        ],
        ...
    }
}

Each question has a type, such as short_answer or file.

  • Payment network RFI: limit is empty. A file question takes one file.
  • Compliance RFI: a file question has a limit with count (how many files), size (the largest file, in KB) and acceptType (the allowed file types). A select question has options, and a multi_select question lets you choose several.

Payment network RFI keys are names, like SOURCE_OF_FUNDS. Compliance RFI keys are numbers, like "1". Always use the key from the response.

Send the Answers

POST /api/v2/transfers/{transfer_uuid}/rfi/answer

Use each question's key as the answer's name:

curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v2/transfers/{{TRANSFER_UUID}}/rfi/answer' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--data-raw '{
    "answers": {
        "SOURCE_OF_FUNDS": "Business revenue"
    }
}'

To answer a file question, send a multipart/form-data request instead. Use each question's key in the field names:

FieldUse for
answers[key]Text and select answers
answers[key][]Each value of a multi_select answer
files[key]The file for a payment network RFI question
files[key][]Each file for a compliance RFI question

A payment network RFI takes one file for each question. A compliance RFI takes several: repeat files[key][] for each file, up to the question's limit. A compliance RFI also accepts one file as files[key].

curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v2/transfers/{{TRANSFER_UUID}}/rfi/answer' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--form 'answers[SOURCE_OF_FUNDS]="Business revenue"' \
--form 'files[PROOF_OF_FUNDS]=@"proof-of-funds.pdf"'
curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v2/transfers/{{TRANSFER_UUID}}/rfi/answer' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--form 'answers[2]="GOODS"' \
--form 'files[1][]=@"proof-of-address-1.pdf"' \
--form 'files[1][]=@"proof-of-address-2.pdf"'

What Happens Next

While the answers are reviewed:

  • Payment network RFI: the sub_status changes to cpn_rfi_submitted. Harbor sends the transfer.sub_status.cpn_rfi_submitted webhook.
  • Compliance RFI: nothing changes until the review is done.

After the review:

  • Approved: the transfer continues. If the funds already arrived, it moves to pending_harbor, with a webhook. If not, it goes back to pending_customer_transfer_start, without a webhook.
  • Rejected: the transfer moves to reject. Harbor sends the transfer.status.rejected webhook.

See Transfer Lifecycle.

Errors

StatusMeaning
422 (code 2005)An answer didn't pass Harbor's checks, for example several files for a payment network question, a file that's too large, or the wrong file type. For a compliance RFI, details is keyed by question key. Basic request checks return errors keyed like files.SUPPORTING_DOCUMENT.
422A payment network RFI is missing a required file or field. errors is keyed by question key.
422 (code 9924)A compliance RFI only: the review service rejected the submission. details explains why.
409The RFI was already answered, or its status is requires_manual_review. For manual review, the Customer must answer on the rfi_link page.

Notes

Deadlines

  • A payment network RFI must be answered before its expire_date, or the transfer is rejected. A compliance RFI has no deadline.

Files

  • A payment network RFI takes one file for each question. A compliance RFI takes as many files as the question's limit.count.max allows.
  • In both cases, each file can be up to 20 MB and must be a .pdf, .jpg, .jpeg, .png, .doc or .docx. A compliance RFI sets a stricter limit for each file: its type must be in the question's acceptType, and its size can't be more than limit.size.max, in kB.

Retries

  • Send an X-Idempotency-Key header when you retry. For 24 hours, Harbor returns the same response to a repeat request with the same key.
  • If the first request is still running, Harbor returns 202 with code 2004 (general.idempotency_conflict).

Server Setup

  • Call this endpoint from your server, and keep your API key out of the browser.
  • Let your HTTP client set the Content-Type header, so it adds the multipart boundary.
  • Raise your server's upload limit to at least 20 MB per file.

Onboarding RFI

  • A transfer RFI is about one transfer. The transfer's status is request_for_information.
  • If Harbor needs more information about the Customer instead, it's an onboarding RFI. The Customer's state is update_required, and Harbor sends the customer.rfi.raised webhook. See Onboarding RFI.

Did this page help you?