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.
| Action | Endpoint |
|---|---|
| Retrieve the transfer | GET /api/v2/transfers/{transfer_uuid} |
| Get the RFI questions | GET /api/v2/transfers/{transfer_uuid}/rfi |
| Send the RFI answers | POST /api/v2/transfers/{transfer_uuid}/rfi/answer |
How It Works
- The transfer's status changes to
request_for_information. Harbor sends thetransfer.status.request_for_informationwebhook. - The Customer answers the RFI, on a hosted page or through your app.
- Harbor reviews the answers.
- 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 thetransfer.sub_status.cpn_rfiwebhook. - 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; otherwisenull.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:
limitis empty. Afilequestion takes one file. - Compliance RFI: a
filequestion has alimitwithcount(how many files),size(the largest file, in KB) andacceptType(the allowed file types). Aselectquestion hasoptions, and amulti_selectquestion 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:
| Field | Use 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_statuschanges tocpn_rfi_submitted. Harbor sends thetransfer.sub_status.cpn_rfi_submittedwebhook. - 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 topending_customer_transfer_start, without a webhook. - Rejected: the transfer moves to
reject. Harbor sends thetransfer.status.rejectedwebhook.
See Transfer Lifecycle.
Errors
| Status | Meaning |
|---|---|
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. |
422 | A 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. |
409 | The 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.maxallows. - In both cases, each file can be up to 20 MB and must be a
.pdf,.jpg,.jpeg,.png,.docor.docx. A compliance RFI sets a stricter limit for each file: its type must be in the question'sacceptType, and its size can't be more thanlimit.size.max, in kB.
Retries
- Send an
X-Idempotency-Keyheader 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
202with code2004(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-Typeheader, 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
statusisrequest_for_information. - If Harbor needs more information about the Customer instead, it's an onboarding RFI. The Customer's
stateisupdate_required, and Harbor sends thecustomer.rfi.raisedwebhook. See Onboarding RFI.
Updated about 14 hours ago