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.

Update Merchant Data

Learn how to keep merchant account data up to date

As an embedded payments partner, you can manage account data for your merchants to keep it accurate and up to date. When a merchant’s circumstances change — such as new contact or bank information — you can make these updates using our API. In this guide, we first retrieve a merchant’s data to verify existing information and then submit the necessary updates.

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
Have at least one boarded merchant under your partnership

Editable merchant data

The following table describes which merchant datasets are editable. For more examples of editable merchant data, see Merchants in the API Explorer.

Editable Merchant Data	Description
Add a Beneficial Owner	Allows a merchant to add a beneficial owner (an individual with 25% or more stake in the company).
Applicant Data	Personal data (including name, email, and phone number) associated with the primary person or applicant on a merchant account.
Business Address	Business street address of the merchant.
Gross Billing Bank Information*	If a merchant is configured for gross billing, this will be the bank account from which fees are pulled at the end of the billing cycle.
Payment Processing Statistics	Anticipated transactional and monthly processing volumes of a merchant.
Primary Payout Bank Information*	Primary bank account on file for the merchant. In most merchant configurations, this account is used for deposits.
Secondary Payout Bank Information*	Account to which merchant funds will be transferred if the account is configured for “split sweeps.”
Shipping Address	Shipping address of the merchant.
*Editing is available only in the United States.

Step 1: Retrieve merchant data

Before updating, we retrieve the merchant’s current details to verify existing information.

Sample request

curl --compressed -X GET "https://apis.sandbox.globalpay.com/ucp/merchants/MER_31087d9c-e68c-4389-9f13-39378e166ea5" \
-H "Authorization: Bearer DCKbRy6gtN6gWJI2ja0B7e3POtbb" \
-H "X-GP-Version: 2021-03-22" \

Sample response

{
    "id": "MER_31087d9c-e68c-4389-9f13-39378e166ea5",
    "type": "MERCHANT",
    "time_created": "2019-08-24T14:15:22Z",
    "time_last_updated": "2019-08-24T14:15:22Z",
    "status": "ACTIVE",
    "status_reason": "CLOSED_BY_MERCHANT",
    "name": "Unique Username",
    "reference": "Merchant1234",
    "currency": "USD",
    "dba": "MERCHANT XYZ",
    "website": "https://example.com/",
    "tax_id_reference": "123456789",
    "notification_email": "merchant@example.com",
    "pricing_profile": "test",
    "notifications": {
        "status_url": "https://www.example.com/notifications/status"
    },
    "persons": [
        {
            "functions": "APPLICANT",
            "first_name": "James",
            "middle_name": "A",
            "last_name": "Mason",
            "email": "example@email.com",
            "address": {
                "building_number": "1001",
                "building_name": "Rose Cottage",
                "line_1": "123 Merchant Street",
                "line_2": "Suite 2",
                "line_3": "foyer",
                "months_at_address": "48",
                "city": "Beverly Hills",
                "post_town": "London",
                "state": "CA",
                "postal_code": "90210",
                "country": "US"
            },
            "contact_phone": {
                "country_code": "US",
                "subscriber_number": "string"
            },
            "work_phone": {
                "country_code": "US",
                "subscriber_number": "string"
            }
        }
    ],
    "addresses": [
        {
            "functions": "BUSINESS",
            "building_name": "Rose Cottage",
            "line_1": "123 Merchant Street",
            "line_2": "Suite 2",
            "line_3": "foyer",
            "months_at_address": "48",
            "city": "Beverly Hills",
            "post_town": "London",
            "state": "CA",
            "postal_code": "90210",
            "country": "US",
            "phone": {
                "country_code": "US",
                "subscriber_number": "string"
            }
        }
    ],
    "payment_methods": [
        {
            "functions": "ACCOUNT_ACTIVATION_FEE",
            "name": "Johns Payment Method",
            "bank_transfer": {
                "account_holder_type": "PERSONAL",
                "masked_number_last4": "1234",
                "account_type": "CHECKING",
                "bank": {
                    "name": "High Street",
                    "cin": "819844",
                    "code": "124002971",
                    "international_code": "PNBPIE2D",
                    "address": {
                        "line_1": "123 Merchant Street",
                        "line_2": "Suite 2",
                        "line_3": "foyer",
                        "city": "Beverly Hills",
                        "state": "CA",
                        "postal_code": "90210",
                        "country": "US"
                    }
                }
            }
        }
    ],
    "start_date": "1980-01-01",
    "expiration_date": "1980-01-01",
    "action": {
        "id": "ACT_uzFr7t4VOqxdLDI44hHmXIjHtOOE8d",
        "type": "MERCHANT_CREATE",
        "time_created": "2021-05-03T21:23:39.718Z",
        "result_code": "SUCCESS",
        "app_id": "uzFr7t4VOqxdLDI44hHmXIjHtOOE8d",
        "app_name": "my_lovely_app"
    }
}

Step 2: Submit updates

After retrieving the merchant’s existing data and verifying it, we can now submit an update to their account information.

For complete details on API requests and responses, see [PATCH] Edit Merchant in the API Explorer.

Sample request

Sample response

{
    "id": "MER_d5f47f41120f4ebb8a97f8b4d92b8fde",
    "name": "John Doe Merchant 1",
    "status": "ACTIVE",
    "type": "MERCHANT",
    "time_created": "2022-11-10T05:36:13.949Z",
    "time_last_updated": "2022-11-10T05:36:13.949Z",
    "status_description": "Merchant Editing in progress",
    "action": {
        "id": "ACT_0KDZ8mhH96qwdo0wEn98lp8G0LXh93",
        "type": "MERCHANT_EDIT_INITIATED",
        "time_created": "2022-11-10T05:36:13.949Z",
        "result_code": "SUCCESS",
        "app_id": "U1lRHKomEn7DN907RCDPxVhyMfiMLcfy",
        "app_name": "demo_app"
    }
}

Step 3: Receive webhook confirmation

After submitting the update request, you’ll receive a webhook notification once the edit is complete.

Sample webhook notification

{
  "id": "MER_d5f47f41120f4ebb8a97f8b4d92b8fde",
  "name": "Doe Merchant 1",
  "status": "ACTIVE",
  "type": "MERCHANT",
  "time_created": "2022-11-09 19:17:30",
  "time_last_updated": "2022-11-10 05:45:55",
  "status_description": "Merchant Update Successful",
  "action": {
    "id": "ACT_Dcwtptaz57RZuYd3TcAxPCCewG7sBi",
    "type": "MERCHANT_EDIT",
    "time_created": "2022-11-10T05:45:58.816Z",
    "result_code": "SUCCESS",
    "app_id": "U1lRHKomEn7DN907RCDPxVhyMfiMLcfy",
    "app_name": "demo_app"
  }
}

Integration references

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

/merchants - API Explorer

See the full API specification for managing merchants.

SDKs & Libraries

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

Testing

This solution 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.

Retrieve Merchant & Account Reports

Use account data to support your merchants.

Request a Limit Increase

Increase processing limits for a merchant.

Policies

Connect

Additional Resources

Update Merchant Data

Prerequisites

Editable merchant data

Step 1: Retrieve merchant data

Sample request

Sample response

Step 2: Submit updates

Sample request

Sample response

Step 3: Receive webhook confirmation

Sample webhook notification

Integration references

/merchants - API Explorer

SDKs & Libraries

Testing

Test Cards

Postman Collection

Responses

Next steps

Retrieve Merchant & Account Reports

Request a Limit Increase