For AI agents: the complete documentation index is at /llms.txt, and the full text of every page is at /llms-full.txt. Most pages are also available as Markdown by adding .md to the URL.

Upload a Merchant Document for Validation

Learn how to submit documentation to support successful onboarding

This feature is available in the United States, Canada, and the United Kingdom.

When onboarding merchants, uploading supporting documentation is a critical step for partners when a merchant’s “know your customer” (KYC) validation fails due to missing or incorrect applicant information. For more information on KYC declines, see the KYC validation section of our boarding overview.

This guide outlines how to use our API to upload supporting documents to validate an applicant or a beneficial owner’s identity and submit a request for additional validation following a KYC decline. Once it’s approved, you receive a webhook notification with merchant status as ACTIVE, along with the Account IDs.

Documents to validate an applicant differ per region. To get a full list of acceptable supporting documentation, contact your account manager.

Prerequisites

Before starting the steps in this guide, make sure you:

Get set up in our Sandbox test environment:
- Get registered
- Get Partner-level Sandbox test credentials (contact our support team)
- Create an access token

Step 1: Identify a merchant using status

Following a Merchant Boarding request, you will receive a webhook notification informing you of the status and KYC response. This information can also be retrieved using GET merchants.

The WITH_MERCHANT status indicates that the automated KYC validation for the merchant failed. In this scenario, a merchant can then upload documentation and request an additional review.

To simulate KYC failure on merchant boarding, pass “1971-01-01” as the applicant’s date_of_birth. For an example, see [POST] Board Merchant in the API Explorer.

Sample webhook notification

{
  "id": "MER_d39cfb0dcb9342b9a69b2daa7cd6529e",
  "name": "John Doe Merchant 1",
  "status": "WITH_MERCHANT",
  "type": "MERCHANT",
  "time_created": "2023-02-01T19:30:31.338Z",
  "time_last_updated": "2023-02-01T19:30:31.338Z",
  "status_description": "Account Denied: Additional information is needed to activate this account.",
  "action": {
    "id": "ACT_CqhemobTmdJ9Tpr44z704PkFuZjmWl",
    "type": "MERCHANT_CREATE_STATUS_NOTIFICATION",
    "time_created": "2023-02-01T19:30:31.540Z",
    "result_code": "SUCCESS",
    "app_id": "U1lRHKomEn7DN907RCDPxVhyMfiMLcfy"
    "app_name": "demo_app"
  }
}

Step 2: Collect the required documents

Obtain the identity-validating documentation. Some common example include:

Government-issued photo ID (passport, driver’s license)
Proof of current address (recent utility bill or bank statement)

Documents to validate an applicant differ per region. To get a full list of acceptable supporting documentation, contact your account manager.

Step 3: Upload documentation via API

Use the Upload Merchant Docs POST request to submit the required documents.

For complete details on API requests and responses, see [POST] Upload Merchant Docs in the API Explorer.

Sample request

curl --location --request POST 'https://apis.sandbox.globalpay.com/ucp/merchants/MER_d5f47f41120f4ebb8a97f8b4d92b8fde/documents' \
--header 'X-GP-Version: 2021-03-22' \
--header 'Authorization: Bearer lye8PVG6nRa9oElUadmqjBKKROiI' \
--header 'Content-Type: application/json' \
--data-raw '{
  "function": "IDENTITY_VERIFICATION",
  "b64_content": "VGVzdGluZw==",
  "format": "TIF"
}'

Sample response

{
    "id": "MER_d5f47f41120f4ebb8a97f8b4d92b8fde",
    "status": "SUCCESS",
    "document_name": "IDENTITY_VERIFICATION_718558106_ucFTwT4812",
    "action": {
        "id": "ACT_A1VgW0Woo1sYnz1MEnz8ZhON4FUJxh",
        "type": "DOCUMENT_UPLOAD",
        "time_created": "2022-11-10T00:37:35.192Z",
        "result_code": "SUCCESS",
        "app_id": "U1lRHKomEn7DN907RCDPxVhyMfiMLcfy",
        "app_name": "demo_app"
    }
}

Step 4: Receive account activation webhook

Once the KYC is approved, you will receive a webhook notification with merchant status as ACTIVE, along with the Account IDs.

Sample webhook notification

{
  "id": "MER_4d9ac02fcdf64c57aae513fd1aaf18f0",
  "name": "John Doe Merchant 1 ",
  "status": "ACTIVE",
  "type": "MERCHANT",
  "time_created": "2023-03-15T15:00:49.000Z",
  "time_last_updated": "2023-03-15T15:01:31.000Z",
  "email": "james.mason@example.com",
  "address": {
    "line_1": "1 Business Address",
    "line_2": "Suite 2",
    "line_3": "foyer",
    "city": "Atlanta",
    "state": "GA",
    "postal_code": "30346",
    "country": "US"
  },
  "contact_phone": {
    "country_code": "01",
    "subscriber_number": "8008675309"
  },
  "products": [
    {
      "id": "PRO_TRA_CNP-US-CARD_PP",
      "name": "Card Not Present Transaction processing",
      "account": {
        "id": "TRA_f7ad82b526fb4091984a8478261f3bf9",
        "type": "TRANSACTION_PROCESSING",
        "name": "718576205_305901",
        "status": "ACTIVE",
        "channel": "CNP",
        "time_created": "2023-03-15T15:01:28.000Z",
        "permissions": [
          "BAT_GET_Single",
          "ACT_GET_Single_Logs",
          "ACC_GET_List",
          "ACC_GET_Single_Platform",
          "GET_Single",
          "TRN_POST_Authorize",
          "TRN_POST_Split",
          "VER_POST_Verify",
          "ACC_GET_Single",
          "TRN_POST_Adjust",
          "TRN_POST_Refund",
          "TRN_GET_Single",
          "AUT_POST_Results",
          "TRN_POST_Initiate",
          "ACT_POST_Auto_Action",
          "AUT_POST_Initiate",
          "AUT_POST_Check_Availability",
          "BAT_POST_Close",
          "TRN_POST_Confirm",
          "TRN_POST_Reverse",
          "TRN_POST_Capture",
          "ACT_GET_Single",
          "",
          "TRN_GET_List",
          "ACT_GET_List"
        ]
      }
    }
  ],
  "action": {
    "id": "ACT_vja2mabXbWE6F1cnP2jBIafdYlaidE",
    "type": "MERCHANT_CREATE_STATUS_NOTIFICATION",
    "time_created": "2023-03-15T15:01:50.053Z",
    "result_code": "SUCCESS",
    "app_id": "U1lRHKomEn7DN907RCDPxVhyMfiMLcfy",
    "app_name": "demo_app"
  }
}

Integration references

To get a deeper understanding of merchant boarding, we recommend that you use our provided integration references. For the full detailed API specification, see the API Explorer.

/access-token - API Explorer

See the full API specification for creating an access token.

/merchants - API Explorer

See the full API specification for boarding a merchant.

SDKs & Libraries

Add server-side or client-side code to your integration.

Testing

Merchant boarding is available for testing in our free Sandbox environment for registered users of this developer portal. Use our resources below to start testing different scenarios.

Test Cards

Test different transaction outcomes with simulated cards or banks.

Postman Collection

View, import, or fork our API collection in Postman.

Responses

View successful responses, HTTP status codes, action response data, and errors.

Next steps

Below are recommended next steps for your partner integration.

Request a Limit Increase

Increase processing limits for a merchant.

Merchant Management & Reporting

Use account data to better support your merchants.

Policies

Connect

Additional Resources

Upload a Merchant Document for Validation

Prerequisites

Step 1: Identify a merchant using status

Sample webhook notification

Step 2: Collect the required documents

Step 3: Upload documentation via API

Sample request

Sample response

Step 4: Receive account activation webhook

Sample webhook notification

Integration references

/access-token - API Explorer

/merchants - API Explorer

SDKs & Libraries

Testing

Test Cards

Postman Collection

Responses

Next steps

Request a Limit Increase

Merchant Management & Reporting