Customer Lifecycle

This article details the requests and tools clients have available to manage customers.

Nium API

The following table details the requests available to manage customers:

Update a customerThe Customer Update API can update a customer's information at any time after the onboarding.
  • If complianceStatus = COMPLETED, you can update only the customer email and mobile fields.
  • If complianceStatus is any other value, any customer information can be updated.
  • Note: Per the Strong Customer Authentication (SCA) requirement, authenticationCode needs to be passed in the API within the EU and UK regions.
    Get a customer's detailsThe Customer Details API gets the detail information of the customer at any time.
  • The status field shows the status of the customer in the Nium platform.
  • The complianceStatus field shows the status of the compliance check for the customer.
  • Get a list of customersThe Customer List API gets a list of customers under you, which can be further filtered based on query parameters such as email address, mobile number, etc.
    Block/Unblock a customerThe Block/Unblock Customer API enables you to block or unblock a customer's account from processing any further activity.

    Customer Lifecycle

    When a customer passes KYC checks and gets approved by Nium, the customer#status updates to Clear.

    As your business needs change and customers come and go, you may need to suspend or block customers. Use the Block/Unblock Customer request to help manage customers.

    As you manage customers the status updates from Clear depending on the action you're performing.

    The following table details the different statuses a customer can change to after getting approved in Nium. The different states of customers, as documented in the status column, can be reviewed using the Customer List V2 request.

    ActionDescriptionBlock/Unblock Customer - actionstatus
    Suspend a customer’s accountCustomer accounts can be suspended by you or Nium’s Compliance team at any time.TEMPORARY_BLOCKSuspended
    Unsuspend a customer’s accountCustomer accounts can be unsuspended by you or Nium’s Compliance team at any time.UNBLOCKClear
    Close a customer’s account• Customer accounts can be closed by you or Nium’s Compliance team at any time.
    • This is a permanent change and status. Once closed, the customer’s information can be resubmitted to create a new customer.
    • A new customerHashId will be assigned to the customer.
    Terminate a customer's account• Customer accounts can be terminated by Nium’s Compliance team at any point of time due to fraudulent/ prohibited activities.
    • Account termination is a terminal state and can only be performed by Nium's compliance team.
    • Once terminated, the same customer’s information can't be used to create a customer and won't be accepted by Nium.
    Not applicableBlocked

    Suspend Customer Account

    Call the Block/Unblock Customer API with the TEMPORARY_BLOCK parameter, include one of the following in as the reason:


    Example of a failed message response where the provided reason is not included in the above list:

      "status": "BAD_REQUEST",
      "message": "Invalid Reason Provided",
      "errors": [
        "Reason is not valid to Temporarily Block Customer"

    Example of a successful message response:

      "status": "OK",
      "message": "Customer has been Blocked Temporarily",
      "errors": []

    Close Customer Account

    Customer accounts can be closed by you or Nium's compliance team at any time.

    Closing a customer's account is permanent, so if you suspect fraudulent or suspicious activity, suspend the account and contact your Nium account manager or Nium Support to review the customer's activity and block the account if necessary.

    If you want to proceed with permanently closing a customer's account, call the Block/Unblock Customer API with the PERMANENT_BLOCK parameter and include one of the following in the reason parameter:

    • OTHER

    Any existing balances will be refunded by Nium's operations team. If you have any questions about refunds, please contact your Nium account manager or Nium Support.

    To reopen a closed account, the customer must go through the onboarding process again and resubmit their information. Customers can resubmit their application and go through the eKYC process again using the:

    Unblock Customer Account

    A customer can be unblocked, but only in two scenarios:

    • You can unblock only if you request the temporary block.
    • Nium can unblock only if Nium requests the temporary block.

    When calling the Block/Unblock Customer API with the UNBLOCK parameter, include one of the following in the reason parameter:



    Nium offers the option to pass customized information via tags in the Unified Add Customer API and the Onboard Corporate Customer API. This feature is applicable for individual and corporate customers, and you can update or delete the tags. For details, see the Manage Customer Tags API.

    Notifications via Callback URL

    Any change in the compliance life cycle will be notified to you by a callback URL, configured at your system. For details, see Callback to receive customer compliance status.

    Rejected Customer

    When a customer is rejected, the process is as follows:

    1. Continue from any Add customer flow, where status=PENDING and complianceStatus=ACTION_REQUIRED.
    2. Nium compliance sends a callback request for the complianceStatus with customerHashId.
    3. Send a response with the HTTPS status code 200.
    4. Collect and send your customer's details in a GET request to the Customer Details V2 API with the customerHashId.
    5. Nium compliance is unable to process the customer onboarding and rejects the customer. Nium compliance updates the compliance status from ACTION_REQUIRED to REJECT .
    6. Nium sends a response with the following:
      • kycStatus=FAILED
      • complianceStatus=REJECT
      • remarks
      • complianceRemarks
    7. Tell the customer that the KYC failed and offer an option to reinstate KYC.
    8. Send a POST request to the Unified Add Customer API with corrected information and the existing customerHashId.
    9. Nium returns:
      • customerDetails
      • complianceStatus=COMPLETED
      • kycStatus=CLEAR

    Terms and Conditions