--- title: "Customers Module" slug: "customers-module" updated: 2025-07-29T08:23:06Z published: 2025-07-29T08:23:06Z canonical: "docs.monri.com/customers-module" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.monri.com/llms.txt > Use this file to discover all available pages before exploring further. # Customers Module ## Requirements To start integrating with our service you will need the following: - Test merchant account - Tokenization enabled (optional) If you don’t have a test merchant account, please contact us at [support@monri.com](mailto:support@monri.com) and we will open one for you. Then you can login into your account at [https://ipgtest.monri.com/en/login](https://ipgtest.monri.com/en/login) with login and password provided. ## Requests Documentation below describes: - api url values - required headers - authentication header ### Api URL | environment | value | | --- | --- | | `test` | `https://ipgtest.monri.com` | | `prod` | `https://ipg.monri.com` | *NOTE* Parametrize api url value. ### Headers | name | value | description | | --- | --- | --- | | Content-Type | `application/json` | All api endpoints require `application/json` Content-Type header | | Accept | `application/json` | All api endpoints require `application/json` Accept header | | Authorization | `<authorization_header>` | All api endpoints require `Authorization` header. See below how to generate one | ### Authentication Every request to the Monri’s backend requires authentication. Depending on `HTTP` method algorithm used to create `Authorization` header differs. To create authorization header you’ll need: - `merchant_key` (available on merchant’s dashboard) - `authenticity_token` (available on merchant’s dashboard) Authorization header for `GET|POST` request is created from: | name | value | description | | --- | --- | --- | | schema | `WP3-v2.1` | | | authenticity_token | `<authenticity_token>` | Available on merchant’s dashboard | | timestamp | `<timestamp>` | Unix timestamp, eg PHP’s time() | | digest | `<digest>` | See docs for digest generation | Example of authorization header: ``` WP3-v2.1 7db11ea5d4a1af32421b564c79b946d1ead3daf0 1593457122 bd120476c656a8ec3ce5d6a150f17061d03a8e280b0fbba278a73a15066830562f73ce5536882c9222e265f1ff6c2df629173375b549cba5a9275b08686f32ea where: schema is WP3-v2.1 authenticity-token is 7db11ea5d4a1af32421b564c79b946d1ead3daf0 timestamp is 1593457122 digest is bd120476c656a8ec3ce5d6a150f17061d03a8e280b0fbba278a73a15066830562f73ce5536882c9222e265f1ff6c2df629173375b549cba5a9275b08686f32ea ``` #### Digest generation | name | value | description | | --- | --- | --- | | merchant_key | `<merchant_key>` | Value available on merchant’s dashboard | | timestamp | `<timestamp>` | Same timestamp value used in authorization header | | authenticity_token | `<authenticity_token>` | Value available on merchant’s dashboard | | fullpath | `<fullpath>` | Full path of request, eg, `/v2/terminal-entries/create` | | body | `<body>` | Empty string if `GET` request, request body if `POST` request | **Digest example** If we have: - url: https://ipgtest.monri.com/v2/payment/new - method: `POST` - fullpath is then: `/v2/payment/new` - merchant_key: `qwert1234` - timestamp: `1593457122` - authenticity_token: `7db11ea5d4a1af32421b564c79b946d1ead3daf0` - body: ``` { "example": "1" } ``` Then we create digest as: ``` const crypto = require('crypto'); var fullpath = `/v2/payment/new` var body = JSON.stringify({ "example": "1" }) var merchantKey = `qwert1234` var authenticityToken = `7db11ea5d4a1af32421b564c79b946d1ead3daf0` var timestamp = 1593457122 // If you are using this as an example replace exact value with call to eg (new Date()).getTime() // we create digest for merchantKey + timestamp + authenticityToken + fullpath + body which is equal to // qwert123415934571227db11ea5d4a1af32421b564c79b946d1ead3daf0/v2/payment/new{"example":"1"} var digest = crypto.createHash('sha512') .update(merchantKey + timestamp + authenticityToken + fullpath + body) .digest('hex'); // we should get bd120476c656a8ec3ce5d6a150f17061d03a8e280b0fbba278a73a15066830562f73ce5536882c9222e265f1ff6c2df629173375b549cba5a9275b08686f32ea ``` ## Response Handling Monri’s API adheres to following principles: - `status` field is always in response and has values: | status | status code | description | | --- | --- | --- | | created | 200 | Resource is created | | updated | 200 | Resource is updated | | approved | 200 | Request successful | | invalid-request | 4** | There’s something wrong with request | | error | 500 | Something went wrong while processing the request | - If response code is `2**`: Request is accepted and processed, response is returned - If response code is `401`: Authorization failed, there’s probably an issue with `Authorization` header - If response code is `400`: Request processing failure, eg. attempted to create resource with invalid amount ### Valid (approved) response Example of valid response: ``` { "status": "approved", //...other fields } ``` ### Invalid-request response Example of `invalid-request` response: ``` { "status": "invalid-request", "message": "Order number can't be blank, Order number is too short (minimum is 3 characters)" } ``` ### Error response Example of `error` response: ``` { "status": "error", "message": "An error occurred while processing request. Please try later." } ``` ## Create a customer ### Request To create a Customer you’ll need to provide: - Valid `Authorization` header (see above how to create one) - Valid request #### Request endpoint details | name | value | description | | --- | --- | --- | | path | `v2/customers` | This path is used for create action | | method | `POST` | We are creating resource, hence `POST` method | #### Request body: | field | length | type | required | description | | --- | --- | --- | --- | --- | | merchant_customer_id | 1-100 | `String` | `NO` | Merchant’s customer id | | description | 1-200 | `String` | `NO` | The Customer description | | email | 1-200 | `String` | `NO` | Customer’s email address. | | name | 1-50 | `String` | `NO` | Customer’s full name or business name. | | phone | 1-30 | `String` | `NO` | Customer’s phone | | metadata | predefined | `Dictionary` | `NO` | Set of key-value pairs. Useful for storing additional data about the object | | zip_code | 1-9 | `String` | `NO` | Customer’s ZIP or postal code. | | city | 3-30 | `String` | `NO` | Customer’s city, district, suburb, town, or village. | | address | 3-100 | `String` | `NO` | Customer’s address | | country | 2 | `String` | `NO` | Two-letter country code, see [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) | ### Response | field | length | type | description | | --- | --- | --- | --- | | status | enum | `String` | approved, invalid-request or error | | uuid | predefined | `String` | Customer’s uuid - use this value for operations with customer | | merchant_customer_id | 100 | `String` | Merchant’s customer id | | description | 1-200 | `String` | The Customer description | | email | 1-200 | `String` | Customer’s email address. | | name | 1-50 | `String` | Customer’s full name | | phone | 1-30 | `String` | Customer’s phone | | metadata | predefined | `Dictionary` | Set of key-value pairs. Useful for storing additional data about the object | | zip_code | 1-9 | `String` | Customer’s ZIP or postal code. | | city | 3-30 | `String` | Customer’s city | | address | 3-100 | `String` | Customer’s address | | country | 2 | `String` | Two-letter country code, see [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) | | deleted | predefined | `Boolean` | True if customer is deleted | | created_at | predefined | `DateTime` | Created at | | updated_at | predefined | `DateTime` | Created at | | deleted_at | predefined | `DateTime` | Nullable, set if customer is deleted | Example of response: ``` { "uuid": "4b281da4-d145-4233-b957-2018cf9aa0fb", "merchant_customer_id": "customer-id-1234", "description": "Customer", "email": "email@email.com", "name": "Test", "phone": null, "status": "approved", "deleted": false, "city": null, "country": "BA", "zip_code": "71000", "address": null, "metadata": { "key": "value" }, "created_at": "2019-02-12T11:22:33Z", "updated_at": "2019-02-12T11:22:33Z", "deleted_at": null } ``` ## Retrieve a customer To retrieve previously created customer you’ll need to provide: - Valid `Authorization` header (see above how to create one) - Create resource beforehand - Provide valid resource `uuid` ### Request | name | value | description | | --- | --- | --- | | path | `/v2/customers/:uuid` | `uuid` of previously created resource | | method | `GET` | | ### Response Response is the same as the one for [create](https://ipg.monri.com/en/documentation/customer_api#response) --- ## Retrieve a customer via merchant_customer_id To retrieve previously created customer you’ll need to provide: - Valid `Authorization` header (see above how to create one) - Create resource beforehand - Provide valid `merchant_customer_id` ### Request | name | value | description | | --- | --- | --- | | path | `/v2/merchants/customers/:merchant_customer_id` | `merchant_customer_id` of previously created resource | | method | `GET` | | ### Response Response is the same as the one for [create](https://ipg.monri.com/en/documentation/customer_api#response) ## Update a customer To update previously created customer you’ll need to provide: - Valid `Authorization` header (see above how to create one) - Create resource beforehand - Provide valid resource `uuid` ### Request | name | value | description | | --- | --- | --- | | path | `/v2/customers/:uuid` | `uuid` of previously created resource | | method | `POST` | We are updating resource, hence `POST` method | #### Request body: - Updates the specified customer by setting the values of the parameters passed. - Any parameters not provided will be left unchanged. - Fields available for `create` are also available for update. - Setting key to null in metadata will unset value for that key. ### Response Response is the same as the one for [create](https://ipg.monri.com/en/documentation/customer_api#response) --- ## Delete a customer To delete previously created customer you’ll need to provide: - Valid `Authorization` header (see above how to create one) - Create resource beforehand - Provide valid resource `uuid` ### Request | name | value | description | | --- | --- | --- | | path | `/v2/customers/:uuid` | `uuid` of previously created resource | | method | `DELETE` | | ### Response | field | length | type | description | | --- | --- | --- | --- | | status | enum | `String` | approved, invalid-request or error | | id | 20 | `String` | Customer’s id | | deleted | predefined | `Boolean` | True if customer is deleted | Example of response: ``` { "status": "approved", "id": "4b281da4-d145-4233-b957-2018cf9aa0fb", "deleted": true } ``` --- ## List all customers To list previously created customers you’ll need to provide: - Valid `Authorization` header (see above how to create one) ### Request | name | value | description | | --- | --- | --- | | path | `/v2/customers` | `uuid` of previously created resource | | method | `GET` | We are retrieving resources, thus `GET` | | query | `limit` | Limit number of objects listed, default limit is `50`. Must be valid number. | | query | `offset` | If you need to skip values set offset to non 0 value, objects are sorted by `created_at DESC`. Must be valid number. | ### Response | field | length | type | description | | --- | --- | --- | --- | | status | enum | `String` | approved, invalid-request or error | | data | 20 | `Array<Dictionary>` | An array of customers | ``` { "status": "approved", "data": [ { "id": "4b281da4-d145-4233-b957-2018cf9aa0fb", "description": "Customer", "email": "email@email.com", "name": "Test", "phone": null, "status": "approved", "deleted": false, "city": null, "country": "BA", "zip_code": "71000", "address": null, "metadata": { "key": "value" }, "created_at": "2019-02-12T11:22:33Z", "updated_at": "2019-02-12T11:22:33Z", "deleted_at": null } ] } ``` --- ## List all payment methods To list previously created customers you’ll need to provide: - Valid `Authorization` header (see above how to create one) ### Request | name | value | description | | --- | --- | --- | | path | `/v2/customers/:uuid/payment-methods` | `uuid` of previously created resource | | method | `GET` | We are retrieving resources, thus `GET` | | query | `limit` | Limit number of objects listed, default limit is `50`. Must be valid number. | | query | `offset` | If you need to skip values set offset to non 0 value, objects are sorted by `created_at DESC`. Must be valid number. | ### Response | field | length | type | description | | --- | --- | --- | --- | | status | enum | `String` | approved, invalid-request or error | | data | 20 | `Array<Dictionary>` | An array of customers | ``` { "status": "approved", "data": [ { "status": "approved", "id": "00c1eb1a4a0b61d1c2921c8d3a3f4570801da3f3f087c280e832cb4876a5e633", "masked_pan": "405840******0005", "expiration_date": "2025-12-31", "keep_until": "2024-12-31T23:00:00Z", "created_at": "2019-02-12T11:22:33Z", "updated_at": "2019-02-12T11:22:33Z", "customer_uuid": "4b281da4-d145-4233-b957-2018cf9aa0fb", "token": "00c1eb1a4a0b61d1c2921c8d3a3f4570801da3f3f087c280e832cb4876a5e633", "expired": false } ] } ``` ---