In MoneyHash, a "Customer" is a part of a merchant's payment network. They have the ability to make payments and store payment methods. Each customer has their own information associated with them, which is used to process payments for different payment methods.

There are great benefits of using and taking advantage of the customer's module offered by MoneyHash:

  • Easily associate a transaction with their respective customer.
  • Save customer billing details in their own entity to send them automatically to the payment provider. Improving the customer's experience.
  • Faster checkouts with customer's saved tokenized cards.
  • Quickly access all transactions executed by each customer.

Customer registration

You can register a new customer entity in MoneyHash by making an API call to the Create Customer endpoint:

POST
/api/v1.1/customers/

You need to send the customer's information in the payload:

  • For a regular customer entity:
PropertyTypeDescription
typeStringThe type of customer entity.
first_nameStringThe customer's first name.
last_nameStringThe customer's last name.
emailStringThe customer's email address.
phone_numberStringThe customer's phone number.
descriptionStringA description of the respective customer (optional).
{
  "first_name": "test",
  "last_name": "customer",
  "email": "[email protected]",
  "phone_number": "+201234567891",
  "description": "test description"
}
  • For a company customer entity:
PropertyTypeDescription
typeStringThe type of customer entity. E.g.: "COMPANY".
company_nameStringThe company's name.
contact_person_nameStringThe name of a contact person from the company.
tax_idNumberThe tax identification number.
tax_rateNumberThe tax rate value.
emailStringThe company's email address.
phone_numberStringThe company's phone number.
descriptionStringA description of the respective customer (optional).
{
  "type": "COMPANY",
  "company_name": "test company name",
  "contact_person_name": "test contact person name",
  "tax_id": 0,
  "tax_rate": 0,
  "email": "[email protected]",
  "phone_number": "+201234567891",
  "description": "test description"
}

This process will create a new entity in the MoneyHash system. Each customer will have their own unique identifier (id). This id can be used for multiple things in MoneyHash, for example, tokenizing the customer's cards, creating a payment related to the respective customer, and using the customer's wallet to store their balance in different currencies.

Custom fields

When creating a new customer, you can store any metadata you wish to make part of the customer's entity in MoneyHash. To do this, you will need to add a custom_fields property to the payload. This property needs to be an object with key-value pairs defined by you. The values must be either string, int, float or boolean.

Filter customers by custom fields

As you define the custom fields, MoneyHash offers a way to find your customers by filtering based on your selected custom fields. To execute this filter, you need to make an API call to the following endpoint, adding the custom_fields as a query parameter:

POST
/api/v1.1/customers/?custom_fields__gender=male

The way to construct the query parameter is custom_fields__<custom_field_key>=<custom_field_value>. Where you need to replace <custom_field_key> with the desired key, and <custom_field_value> with the respective value to filter. The example above makes the query parameter like custom_fields__gender=male.

Customer relation with transactions

Using the customer's module and creating customers, you can relate each payment inside MoneyHash to an individual customer. The benefits of this are centralizing the data of each customer in their entity, being able to, while the customer goes through a payment, have the ability to save their payment method to their entity, as well as being able to use their Wallets inside MoneyHash's system.

To take advantage of this, you need to relate each new intent you create to the customer by adding the customer identification to the payload. Ways to perform this can be found on a few pages, such as Pay with a card token and Pay with a customer wallet.

Payment methods

Customers' entities can store payment methods, such as card information, by tokenizing and saving their cards for a frictionless payment experience and enabling recurring payments without additional information. Each customer can have multiple saved cards connected to them, and each card token represents one individual physical card.

The tokenized cards will be stored in different vaults based on each provider's integration. There are three possible situations here, those being:

  • Moneyhash’s vault: The card token will be saved only on MoneyHash's vault.
  • Provider’s vault: The card token will be saved only on the provider's vault.
  • Both vaults: The card token will be saved on both aforementioned vaults.

There are two different ways you can tokenize your customer's cards:

  • Tokenize cards with payments: When a customer makes a payment, you can choose whether to tokenize their card information. The payments section on the Tokenize Cards page presents how to do this.
  • Stand-alone Tokenization: You can create a process with the sole purpose of tokenizing and saving the customer's card in the system. You can learn how below.

Stand-alone tokenization

This is an option to tokenize and save a customer's card information without needing to start a payment process with the intent. To perform this, you need to start at the Create a Card Token endpoint:

POST
/api/v1.1/tokens/cards/

You need to add to the payload the respective customer's the following properties:

  • customer: The unique identifier of the customer.
  • webhook_url: A URL that the MoneyHash server will send a POST request to you when needed.
{
  "customer": "0fbc1fcd-0206-46d1-8e3c-28491c17b3ce",
  "webhook_url": "https://webhook.site/4d487d3a-2644-4e48-b985-46ccd7350a29"
}

This request will return with a JSON containing a embed_url that can be used with the Embedded integration. MoneyHash executes the card information collecting process with the URL provided for PCI Compliance reasons.

With the webhook_url furnished, you will receive the Webhooks events related to the progress of the tokenization to prepare your application to handle each situation.

Delete a card token

You might need to delete a customer's saved card from the vaults. To execute this, you need to request the following endpoint:

DELETE
/api/v1.1/customers/{customer}/cards/{to_delete_customer_card_token}/

Replacing the parameters above with the data relating to the respective customer and card:

  • customer: The unique identifier of the customer that owns the card.
  • to_delete_customer_card_token: The unique identifier of the saved_card that needs to be deleted.