Manage individual payees

Onboard and manage payee individuals.

Payee API introduction

What is a payee

A payee is the record of a beneficiary individual or legal entity on emerchantpay, storing the data needed for you to make safe, reliable, and compliant outbound payments.

Payee records include:

Identity and address details
Bank account information
Verification and compliance status

Purpose and benefits

The Payee API centralises beneficiary management and automates onboarding with built-in verification and compliance checks, allowing you to:

Standardise integration for payment initiation systems
Reuse payee records across flows to reduce operational friction
Ensure consistent compliance screening across beneficiaries
Avoid payouts to invalid or high-risk individuals
Improve payment success rates and keep payments fast and lightweight
Strengthen auditability

Note: This article explains how to create and manage records of individual people, not legal entities.

Prerequisites

Complete the following prerequisites before you start integrating the Payee API.

Authentication

To use the Genesis gateway, include your API credentials with HTTP Basic Authentication. You can find these credentials in the merchant account creation email from emerchantpay support, or in Genesis.

To find your credentials in Genesis:

Log in to Genesis.
Go to Configuration > Merchants.
Click Actions > View Details to the left of your merchant name.
Click Terminals in the Workflow section to the right.
Select the Terminal you want to use.
In the Api access section, copy your Api login, Api password, and the Terminal token.

Note: You start in the Genesis staging environment with staging credentials for setup and testing. To go live, log in to the production environment, use production credentials, and set your endpoint to PRODUCTION.

Choose a workflow and prepare the required data

You need the following information to call the Create payee endpoint:

Full name
Country
Date of birth
Address: country, state, city, street, and zip code

Following that, there are two payee onboarding workflows. The one you choose depends on who provides the Proof of Identity (PoI) document – national ID card, passport, or driving licence.

Onsite: Provide the payee with access to a hosted verification page run by a third-party verification provider, where they upload their PoI.
Offsite: Upload the payee’s PoI yourself. Use this when you have already verified the payee and have the document.

Note: Confirm the workflow with your Account Manager during onboarding before you start integration.

In both workflows, be ready to provide:

Proof of Address (PoA), if required: evidence of the payee’s residential address, such as a utility bill, bank statement, or any of the other supported document types.
- UK payees can pass address verification without a PoA if their PoI is a driving licence with a valid address; otherwise, emerchantpay uses Electronic Identity Verification (eIDV) to verify the address you submit with the Create payee endpoint. Upload a PoA if the PoI is not a driving licence, and the eIDV fails.
Bank account details:
- UK bank accounts: Bank account name, bank account number, and sort code.
- Other bank accounts: Bank account name, IBAN, and BIC.

To submit PoI and PoA documents, provide the contents as a base64-encoded string:

Supported formats: PDF, PNG, JPG
Maximum size: 10 MB
Required prefix: Include the MIME type using a data URI, for example: data:application/pdf;base64, JVBERi0xLjQKJcfs...
Important: Keep the space after the comma in the prefix.

Payee onboarding workflows

The following sections provide step-by-step overviews of both onboarding workflows.

Onsite onboarding overview

The onsite onboarding works as follows:

Call the Create payee endpoint and store the payee_unique_id – you need it for all future operations.
Call the Create payee document endpoint to upload the payee’s PoA document.
- For UK payees, PoA isn’t necessary if the PoI is a driving licence with a valid address. If the PoI is not a driving licence, emerchantpay uses Electronic Identity Verification (eIDV) to verify the address submitted in step 1. Upload a PoA if the PoI is not a driving licence, and the eIDV fails.
- For non-UK payees, emerchantpay verifies the PoA and matches the name to the one submitted in step 1.
Call the Create payee verification endpoint to start the verification and compliance checks and store the verification_unique_id.
emerchantpay returns a redirect_url – send the payee there for ID verification.
emerchantpay verifies the PoI document, then verifies the PoA document (if submitted), and runs compliance screening (sanctions, PEP, risk scoring). After that:
- emerchantpay approves or rejects the payee – if the payee state is failed, the decision is final.
- emerchantpay manually reviews the payee if there are potential PEP or sanctions issues. You can get an update on the PEP and sanctions screening status in a webhook notification or call the Retrieve payee verification endpoint.
Call the Create payee account endpoint to submit the payee’s bank account for verification and store the account_unique_id. After that:
- emerchantpay checks and approves or rejects UK bank accounts.
- emerchantpay requires a bank letter to manually review and approve or reject non-UK accounts. You must call the Create payee document endpoint to submit a bank letter receipt.
Once the payee goes through all verification and compliance checks successfully, you can make payments.

Offsite onboarding overview

The offsite onboarding works as follows:

Call the Create payee endpoint and store the payee_unique_id – you need it for all future operations.
Call the Create payee document endpoint to upload the payee’s PoI document.
Call Create payee document again to upload the payee’s PoA document.
- For UK payees, PoA isn’t necessary if the PoI is a driving licence with a valid address. If the PoI is not a driving license, emerchantpay uses Electronic Identity Verification (eIDV) to verify the address submitted in step 1. Upload a PoA if the PoI is not a driving license, and the eIDV fails.
- For non-UK payees, emerchantpay verifies the PoA and matches the name to the one submitted in step 1.
Call the Create payee verification endpoint to start the verification and compliance checks and store the verification_unique_id.
emerchantpay verifies the PoI document, then verifies the PoA document (if submitted) and runs compliance screening (sanctions, PEP, risk scoring). After that:
- emerchantpay approves or rejects the payee – if the payee state is failed, the decision is final.
- emerchantpay manually reviews the payee if there are potential PEP or sanctions issues. You can get an update on the PEP and sanctions screening status in a webhook notification or call the Retrieve payee verification endpoint.
Call the Create payee account endpoint to submit the payee’s bank account for verification and store the account_unique_id. After that:
- emerchantpay checks and approves or rejects UK bank accounts.
- emerchantpay requires a bank letter to manually review and approve or reject non-UK accounts. You must call the Create payee document endpoint to submit a bank letter receipt.
Once the payee goes through all verification and compliance checks successfully, you can make payments.

States

When the Payee API responses contain the payee and account objects, those objects can go through certain states, indicated by the status property.

Payee states

You get webhook notifications or call the Retrieve payee or Retrieve payee verification endpoints for updates on a payee’s state.

A payee’s record in emerchantpay can have these following status during the different stages of the onboarding process:

State	Meaning	Payments ready
new	You have called the `Create payee` endpoint, and haven’t started the verification and compliance checks yet.	No
pending	You have called the `Create payee verification` endpoint, but the checks haven’t started yet.	No
in_progress	emerchantpay is running automated ongoing security checks.	No
approved	emerchantpay has approved the payee and their bank account, and you can make payments.	Yes
error	A technical error has occurred.	No
retry_required	An `Update payee` request is complete, but emerchantpay hasn’t verified the updated data yet. An error has occurred at the start of a verification or compliance check.	No
failed	A verification or compliance check has failed. This is an end state indicating a final decision.	No

Bank account states

You can get webhook notifications or call the Retrieve payee account endpoint for updates on the payee’s bank account state.

A payee’s bank account can have the following status as it goes through different stages during the onboarding process:

Bank account state	Meaning	Payments ready
new	You have called the `Create payee account` endpoint, but the bank account hasn’t passed through verification yet.	No
pending	You have called the `Create payee account` endpoint, but the security checks haven’t started yet.	No
in_progress	emerchantpay is running the bank account verification check.	No
approved	emerchantpay has approved the payee’s bank account, and you can make payments.	Yes
error	A technical error has occurred.	No
manual_review_required	emerchantpay must perform a manual review based on a bank letter. You must call the `Create payee document` endpoint to submit the file and set the type to `bank_letter_receipt`.	No
failed	The bank account verification check has failed.	No

Verification and compliance checks

During onboarding, payees must pass through mandatory identity, address, and bank account verification checks, as well as compliance screening. A payee is eligible for payouts only after passing these stages. Once all checks are complete, emerchantpay sends a webhook notification to the notification_url.

The following table describes each security check:

Check	Purpose	Data used	Coverage	Automation	Notes
ID verification	Confirm that the payee’s identity is genuine by running Proof of Identity (PoI) document checks against trusted third-party data sources.	ID document Full name Date of birth	Global	Automatic	Includes document authenticity checks and identity matching. The PoI document can be a national ID card, passport, or driving license.
Address verification via Electronic Identity Verification (eIDV)	Verify that the address provided as text input is valid by checking it against third-party data sources.	Full name Residential address (text input)	UK only	Automatic	This is the primary address verification method for UK payees. You submit the address with the `Create payee` endpoint.
Address verification via Proof of Address (PoA) document	Verify that the address provided in the payee’s PoA document (e.g. utility bill, bank statement, tax document) is valid by checking it against third-party data sources.	PoA document Full name Residential address	Global	Automatic	This is the only address verification method for non-UK payees. Emerchantpay uses this address verification method when eIDV is unavailable or inconclusive for UK payees. The PoA document must be recent and issued by a trusted source, such as a utility bill or bank statement – see all supported document types.
Bank account verification	Validate the payee’s bank account ownership and correctness.	UK: Bank account name, sort code, and bank account number Other: Bank account name, IBAN, and BIC	Global	UK: Automatic Other: Manual	emerchantpay automatically verifies UK accounts if the account holder name matches the specified bank account using trusted UK third-party data sources. For other accounts, emerchantpay will verify ownership of the bank account manually after you call the `Create payee document` endpoint to submit the file with the type set to `bank_letter_receipt`.
Politically Exposed Person (PEP) screening	Determine if the payee is a politically exposed person and assess associated risk.	Full name (from the ID document) Date of birth (from the ID document) Country of nationality and/or residence	Global	Automatic Manual review when issues are detected	Screening uses fuzzy matching, alias detection, and date-based disambiguation to reduce false positives. Treat rejections where the payee state is `failed` as final.
Sanctions screening	Check the payee against official sanctions lists.	Full name (from the ID document) Date of birth (from the ID document) Country of nationality and/or residence	Global	Automatic Manual review when issues are detected	Screening uses fuzzy matching, alias detection, and date-based disambiguation to reduce false positives. Treat rejections where the payee state is `failed` as final.

Note: The API refers to both address verification methods as address.

Webhook notifications

emerchantpay sends webhooks when verification or compliance checks finish, or when someone must take manual action. Webhooks are optional, but they give you the most reliable way to track onboarding results that don’t come straight away by alerting you when anything changes.

The following notifications are available:

Verification redirect required: sent when a redirect_url is generated, so you can provide the URL to the payee and they can complete identity verification.
Verification completed: sent when all verification and compliance checks are complete, showing the overall status, timestamps, and detailed results.
Entity changed: sent when a payee is updated after verification finishes, showing their new state.

Note: The Verification redirect required notification works only in the Onsite workflow and requires additional configuration. Contact emerchantpay support for assistance.

Webhook setup overview:

Create a public HTTPS webhook endpoint to receive JSON notifications.
Provide the webhook endpoint URL as your notification_url so emerchantpay can send notifications.
Validate the notification signature before processing the notification payload.
Process the event and update your records.

Note: Treat webhooks as notifications, not a source of truth: always call Retrieve payee or Retrieve payee verification before acting.

Respond with HTTP 200 and { "unique_id": "<entity-unique-id>" } to acknowledge receipt and stop retries.

See Payee API notifications for more details.

Endpoints

The following sections define some of the core endpoints you need to get started. For all endpoints, see the complete Payee API reference.

Payee onboarding endpoints

Use the API endpoints in the following table during payee onboarding:

Endpoint	Method	Path	Description
Create payee	POST	`/payee`	Register a new payee.
Retrieve payee	GET	`/payee/:payee_unique_id`	Retrieve payee details.
Update payee	PATCH	`/payee/:payee_unique_id`	Modify payee details.
Create payee document	POST	`/payee/:payee_unique_id/documents`	Upload a document to a payee’s record.
List payee documents	GET	`/payee/:payee_unique_id/documents`	Retrieve the details of all payee documents.
Create payee verification	POST	`/payee/:payee_unique_id/verifications`	Start the verification and compliance checks: `kyc`, `address`, `pep`, and `sanction`.
Retrieve payee verification	GET	`/payee/:payee_unique_id/verifications/:verification_unique_id`	Retrieve a payee’s verification and compliance status details: `kyc`, `address`, `pep`, and `sanction`.
List payee verifications	GET	`/payee/:payee_unique_id/verifications`	Retrieve the details of all payee verifications: `kyc`, `address`, `pep`, and `sanction`.

Payee bank account endpoints

Use the following API endpoints to manage the payee’s bank account details:

Endpoint	Method	Path	Description
Create payee account	POST	`/payee/:payee_unique_id/account`	Add bank account details to a payee.
Retrieve payee account	GET	`/payee/:payee_unique_id/account/:account_unique_id`	Retrieve a payee’s bank account details and verification status.
Update payee account	PATCH	`/payee/:payee_unique_id/account/:account_unique_id`	Update a payee’s bank account details.
Reverify payee account	POST	`/payee/:payee_unique_id/account/:account_unique_id/reverify`	Reverify a bank account after a verification failure.
List payee accounts	GET	`/payee/:payee_unique_id/account`	Retrieve all bank account details belonging to a payee.

Troubleshooting

Use the error code returned in the API response or webhook payload to determine the next action.

Technical errors

If a payee enters the error state, a technical issue occurred. In most cases you can retry the same request after a short delay. If the issue persists, contact emerchantpay support with the payee_unique_id, verification_unique_id (if applicable), and the error code.

Payee service and merchant configuration

PRC100 – General Payee service error, please contact support.
PRC101 – Merchant not found, please contact support.
PRC102 – Merchant is not active, please contact support.

KYC and address service technical errors

PRC200 – Unexpected KYC error.
PRC201 – KYC Address service error.
PRC210 – KYC service response error.
PRC211 – KYC service response parsing error.

Verification process technical errors

PRC300 – Unexpected error during verification, please contact support.

Verification process timeouts

PRC410 – Verification could not be finalised in the given timeframe.
PRC411 – Verification could not be completed within the given timeframe. Please try to verify again.

Non-technical errors

These codes reflect verification failures, missing information, or screening outcomes. Most can be corrected and resubmitted, but sanctions and PEP matches are final.

Identity and verification issues

PRC412 – Identity Verification failed. The verification process cannot proceed.

Address data and checks

PRC321 – Address missing, please add required address.
PRC322 – Address check failed.

Document submission

PRC330 – Document missing, please upload required document.

Screening and compliance matches

SPDR34, SPDR160 – AML screening failed. User found in sanction lists.
SPDR34, SPDR163 – AML screening failed. User found in PEP (Politically Exposed Persons) lists.

Informational and manual overrides

PRC301 – Check is not applicable for this entity and will not impact the final status.
PRC340 – Entity check’s status manually set to failed.

Next Steps

Once the onboarding is complete and the payee is approved, you can use the Global payout API to make payments.

Was this page helpful?