Customer Management Module

The PayRetailers Customer Management Module allows you to create customers in our database that you can then use for modules like our SPEI CLABE per Customer and Sports Betting & Gambling Regulated Merchants solutions.

In it, you will be able to create, modify, activate and deactivate Customers and Virtual Accounts.

The handling of Customers in the Customer Management Module is an asynchronous process, and therefore you will need to provide a Default Customer Events Notification Url that we will configure in order for you to receive notifications of these changes. The structure for these notifications is the following:

{
    "eventId": "string (GUID)",
    "eventType": "string",
    "entityId": "string",
    "entityType": "string",
    "timestamp": "datetime"
}

Here's a breakdown of each element:

eventId: (GUID) Unique identifier of the event.
eventType: The type of event. It can be one of the following:
- "CUSTOMER_CREATED"
- "CUSTOMER_DEACTIVATED"
- "VIRTUAL_ACCOUNT_CREATED"
entityId: The Customer's uniqueCustomerIdentifier
entityType: Customer entity. It can be the following:
- "CUSTOMER"
timeStamp: Date and time of the event.

Example of Customer Created notification:

{
    "eventId": "550e8400-e29b-41d4-a716-446655440000",
    "eventType": "CUSTOMER_CREATED",
    "entityId": "CUST123456",
    "entityType": "CUSTOMER",
    "timestamp": "2025-04-02T15:30:00Z"
}

Below is a breakdown of the endpoints and examples of the requests and responses for each available operation:

Create Customer

POST https://api.payretailers.com/api/v1/customers

Request body

{
    "uniqueCustomerIdentifier": "string (max 100 chars)",
    "notificationUrl": "string (required, max 200 chars, valid URL)",
    "country": "string (required, 2 chars, ISO 3166-1 alpha-2)",
    "personalId": "string (max 50 chars)",
    "firstName": "string (max 50 chars)",
    "lastName": "string (max 50 chars)",
    "address": "string (max 255 chars)",
    "city": "string (max 255 chars)",
    "zip": "string (max 50 chars)",
    "state": "string (max 50 chars)",
    "phone": "string (max 50 chars)",
    "email": "string (max 128 chars, valid email)",
    "language": "string (required, 2 chars, ISO 639-1)",
    "registeredAccounts": [
        {
            "bankName": "string",
            "accountNumber": "string",
            "accountAgencyNumber": "string",
            "accountTypeCode": "string"
        }
    ]
}

Response (202 Accepted):
No response body.

When that happens you will receive a notification that looks like this:

{
  "eventId": "550e8400-e29b-41d4-a716-446655440000",
  "eventType": "CUSTOMER_CREATED",
  "entityId": "CUST123456",
  "entityType": "CUSTOMER",
  "timestamp": "2025-04-02T15:30:00Z"
}

Whenever a Customer is created, you will also receive a notification of the activation of their Virtual Account as well:

{
  "eventId": "550e8400-e29b-41d4-a716-446655440001",
  "eventType": "VIRTUAL_ACCOUNT_CREATED",
  "entityId":"CUST123456",
  "entityType": "CUSTOMER",
  "timestamp": "2025-04-02T15:31:00Z"
}

Get Customer

Retrieves customer details by their unique identifier.

GET https://api.payretailers.com/api/v1/customers/{uniqueCustomerIdentifier}

Response (200OK)

{
    "uniqueCustomerIdentifier": "string",
    "isActive": "boolean",
    "deactivationReason": "string",
    "createdDate": "datetime",
    "editedDate": "datetime",
    "notificationUrl": "string",
    "countryCode": "string",
    "personalId": "string",
    "firstName": "string",
    "lastName": "string",
    "address": "string",
    "city": "string",
    "postalCode": "string",
    "state": "string",
    "phone": "string",
    "email": "string",
    "language": "string",
    "registeredAccounts": [
        {
            "bankName": "string",
            "accountNumber": "string",
            "accountAgencyNumber": "string",
            "accountTypeCode": "string"
        }
    ],
    "virtualAccounts": [
        {
            "id": "string",
            "paymentMethod": "string",
            "isDefault": "boolean",
            "isActive": "boolean",
            "deactivationReason": "string",
            "createdDate": "datetime",
            "editedDate": "datetime",
            "data": [
                {
                    "id": "integer",
                    "type": "string",
                    "value": "object"
                }
            ]
        }
    ]
}

Update Customer

Updates an existing customer's information.

PUT https://api.payretailers.com/api/v1/customers/{uniqueCustomerIdentifier}

Request Body: Same as Create Customer

Response (204 No Content):
No response body.

Activate Customer

Activates a customer account.

PATCH https://api.payretailers.com/api/v1/customers/{uniqueCustomerIdentifier}/activate

Response (204 No Content)
No response body.

Deactivate Customer

Deactivates a customer account.

PATCH https://api.payretailers.com/api/v1/customers/{uniqueCustomerIdentifier}/deactivate

Request body:

{
    "deactivationReason": "string"
}

In cases where a Customer needs to be deactivated from the PayRetailers' side asynchronously, you will receive a notification that looks like this:

{
  "eventId": "550e8400-e29b-41d4-a716-446655440002",
  "eventType": "CUSTOMER_DEACTIVATED",
  "entityId": "CUST123456",
  "entityType": "CUSTOMER",
  "timestamp": "2025-04-02T15:32:00Z"
}

Get Customer's Virtual Accounts

Retrieves all virtual accounts associated with a customer.

GET https://api.payretailers.com/api/v1/customers/{uniqueCustomerIdentifier}/virtual-accounts

Query Parameters:

paymentMethod (optional): Filter by payment method (max 50 chars)

isDefault (optional): Filter by default status (boolean)

Response (200OK)

{
    "uniqueCustomerIdentifier": "string",
    "virtualAccounts": [
        {
            "id": "string",
            "paymentMethod": "string",
            "isDefault": "boolean",
            "isActive": "boolean",
            "deactivationReason": "string",
            "createdDate": "datetime",
            "editedDate": "datetime",
            "data": [
                {
                    "id": "integer",
                    "type": "string",
                    "value": "object"
                }
            ]
        }
    ]
}

Activate Virtual Account

Activates a virtual account for a customer.

PATCH https://api.payretailers.com/api/v1/customers/{uniqueCustomerIdentifier}/virtual-accounts/{virtualAccountId}/activate

Response (204 No Content):
No response body.

Deactivate Virtual Account

Deactivates a virtual account for a customer.

PATCH https://api.payretailers.com/api/v1/customers/{uniqueCustomerIdentifier}/virtual-accounts/{virtualAccountId}/deactivate

Request Body:

{
    "deactivationReason": "string"
}

Response (204 No Content):
No response body.