Verification Requirements for Payouts
Learn what recipient information is required to process payouts.
When you onboard a recipient, Finix conducts an OFAC check to verify they are not on government or US watchlists. You can use Webhooks to listen and respond to rejections, all within the Finix API and Dashboard.
Onboarding Webhooks
We recommend integrating into our webhooks to get alerted when a rejection occurs. Several webhook events get sent during the onboarding process. See Webhooks for details on how to set up webhooks.
Onboarding States
Once you've verified and onboarded the recipient, a Merchant
gets created in a PROVISIONING
state until approved or rejected.
When a decision gets made, a webhook event with entity
merchant and type
updated gets sent. It can take anywhere from seconds to several minutes to review and underwrite a Merchant
. Use the onboarding_state
to understand the result and the next steps to take with the recipient:
State | Description |
---|---|
PROVISIONING |
The request is pending and being processed by Finix's system. |
APPROVED |
The Merchant was successfully onboarded. The recipient is ready to receive a payout. |
REJECTED |
The Merchant was rejected and you need to handle the rejection. |
Approved Merchants
When a Merchant
is APPROVED
, you receive a webhook event with entity
merchant and type
underwritten.
An approved Merchant
means your seller is ready to receive a bank payout or card payout.
The following details the different onboarding states and how to handle rejections.
Merchant Underwritten Webhook Event
{
"type": "underwritten",
"entity": "merchant",
"occured_at": "2021-11-14T19:20:29.48Z",
"_embedded": {
"merchants": [
{
"id": "MUoBGzwPdFxb397BKM3bHUvf",
"application": "APcVnXxyWotD6TGRWV2bRWuD",
"identity": "IDgXNAaoy5d4TLkp5ze6gScA",
"verification": "VIeZ3gBoRemaDimjp6qS58An",
"merchant_profile": "MP9e916zYUTTqHUDe4F9ZQvp",
"processor": "DUMMY_V1",
"processing_enabled": true,
"settlement_enabled": true,
"gross_settlement_enabled": false,
"creating_transfer_from_report_enabled": false,
"card_expiration_date_required": true,
"card_cvv_required": false,
"tags": {
"key_2": "value_2"
},
"mcc": "4900",
"mid": "FNXqtgiZAvNPz44hT67Ai632W",
"merchant_name": "Finix Flowers",
"settlement_funding_identifier": "UNSET",
"ready_to_settle_upon": null,
"fee_ready_to_settle_upon": "RECONCILIATION",
"level_two_level_three_data_enabled": false,
"created_at": "2021-11-14T19:20:29.15Z",
"updated_at": "2021-11-14T19:20:29.48Z",
"onboarding_state": "APPROVED"
}
]
}
}
Rejected Merchants
Sometimes a recipient does not pass verification and the onboarding_state
of the Merchant
gets set as REJECTED
. Usually, a REJECTED
state means Finix requires more information to verify the user's identity and enable processing.
Here is an example of a rejected Merchant
:
{
"id": "MUoBGzwPdFxb397BKM3bHUvf",
"created_at": "2021-11-14T19:20:29.15Z",
"updated_at": "2021-11-14T19:20:29.48Z",
"application": "APcVnXxyWotD6TGRWV2bRWuD",
"card_cvv_required": false,
"card_expiration_date_required": true,
"creating_transfer_from_report_enabled": false,
"fee_ready_to_settle_upon": "RECONCILIATION",
"gross_settlement_enabled": false,
"identity": "IDgXNAaoy5d4TLkp5ze6gScA",
"level_two_level_three_data_enabled": false,
"mcc": "4900",
"merchant_name": "Finix Flowers",
"merchant_profile": "MP9e916zYUTTqHUDe4F9ZQvp",
"mid": "FNXqtgiZAvNPz44hT67Ai632W",
"onboarding_state": "REJECTED",
"processing_enabled": true,
"processor": "DUMMY_V1",
"ready_to_settle_upon": null,
"settlement_enabled": true,
"settlement_funding_identifier": "UNSET",
"surcharges_enabled": false,
"tags": {
"key_2": "value_2"
},
"verification": "VIeZ3gBoRemaDimjp6qS58An"
}
To understand what the rejection is, look up the Verification
that got created for the Merchant
.
curl https://finix.sandbox-payments-api.com/verifications/VIpdSnQwTNeWgMHXvFDCPVsx \
-H "Content-Type: application/json" \
-H 'Finix-Version: 2022-02-01' \
-u "USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041"
Example response:
{
"id": "VIvyMuSk9EdyVUrCw2JcXq4r",
"created_at": "2023-09-12T16:08:17.03Z",
"updated_at": "2023-09-12T16:08:17.10Z",
"application": "AP7sqs8G9eTwcLPpjEHLgfUq",
"identity": null,
"merchant": "MUno35MtzSMr61mUvY7qCayR",
"merchant_identity": "IDbM99DS8MaYXyqynqB7z1mR",
"messages": ["ID_VERIFICATION_NEEDED", "ID_VERIFICATION_FAILED"],
"payment_instrument": null,
"payment_instrument_verification_details": {
"push_to_card_domestic": null,
"push_to_card_cross_border": null,
"card_type": null,
"billing_currency": null,
"issuer_country": null
},
"processor": "DUMMYY_V1",
"raw": [
{
"outcome_code": "ID_VERIFICATION_NEEDED",
"description": "ID Verification needed on owner(s).",
"remediation_item": "Submit a valid Driver's License, State ID, or Passport. To submit these file(s), use our File Upload feature. "
},
{
"outcome_code": "ID_VERIFICATION_FAILED",
"description": "ID Verification was unsuccessful.",
"remediation_item": "Ensure ID Verification matches the owner's full name, is readable, and is not expired. Resubmit ID Verification to the link provided by Customer Service for the Merchant Resource (MUxx)."
}
],
"state": "FAILED",
"tags": {},
"trace_id": "FNXboZb9r4P8TRKXluF2udGEv",
"type": "MERCHANT",
"_links": {
"self": {
"href": "https://finix.live-payments-api.com/verifications/VIvyMuSk9EdyVUrCw2JcXq4r"
},
"application": {
"href": "https://finix.live-payments-api.com/applications/AP7sqs8G9eTwcLPpjEHLgfUq"
},
"merchant": {
"href": "https://finix.live-payments-api.com/merchants/MUno35MtzSMr61mUvY7qCayR"
}
}
}
The raw
field will contain an array of the rejections and suggestions to get the Merchant
approved. Though we recommend building your integration to handle every reject code.
attention
We may add new reject codes over time to help improve the onboarding process.
Most steps to resolve rejections involve updating the information of the recipient's Identity
. Once you've updated the Identity
, try verifying the Merchant
again.
Please note, some reject codes are hard rejections which means the Identity
can not be onboarded to Finix. Hard-rejected sellers won't be able to process payments on Finix. If you have any questions, please reach out to your Finix point of contact or the Finix Support team.
Reverifying a Merchant
Reverify a Merchant
when:
-
The
Merchant
initially rejected and failed onboarding. Update theIdentity
and attempt onboarding again (also called reattemptingMerchant
provisioning ). -
Your recipient needs to update their information, which also requires updating the
Identity
and attempting onboarding again once the changes have been made by the recipient.
If more information is requested, update the Identity
and then resubmit the information to Finix. To resubmit the information to Finix, attempt onboarding again by creating a new Verification
on the Merchant
:
curl https://finix.sandbox-payments-api.com/merchants/MUucec6fHeaWo3VHYoSkUySM/verifications \
-H "Content-Type: application/json" \
-H 'Finix-Version: 2022-02-01' \
-u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
-d '{}'
A successful response returns a 200 and a PENDING
Verification
resource.
{
"id": "VI4zELwvT6beu2bJpwG24zLF",
"created_at": "2022-10-10T05:06:04.88Z",
"updated_at": "2022-10-10T05:06:04.93Z",
"application": "APgPDQrLD52TYvqazjHJJchM",
"identity": null,
"merchant": "MUucec6fHeaWo3VHYoSkUySM",
"merchant_identity": "IDpYDM7J9n57q849o9E9yNrG",
"messages": [],
"payment_instrument": null,
"processor": "DUMMY_V1",
"raw": null,
"state": "PENDING",
"tags": {},
"trace_id": "002ef04f-9227-4179-8232-3dc2df8fa8a0",
"_links": {
"self": {
"href": "https://finix.sandbox-payments-api.com/verifications/VI4zELwvT6beu2bJpwG24zLF"
},
"application": {
"href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
},
"merchant": {
"href": "https://finix.sandbox-payments-api.com/merchants/MUucec6fHeaWo3VHYoSkUySM"
}
}
}
The Merchant
resource will update back to a PROVISIONING
stage and you will be notified via webhook when a decision is made.