Customer Management

Introduction

In Paysafe embedded wallet, there are three main types of wallet owners:

Merchant is the legal entity that provides services or goods to its customers and manages the Wallet as a Service solution. The merchant has one or more wallets in the Paysafe Embedded Wallets platform.
Customer is a physical person associated with a wallet and is the legal owner of the e-money stored in the accounts ledger.
Legal entity is a customer who is not a physical person. Legal entities have extended compliance requirements and onboarding processes.

The merchant wallets are created during the initial embedded wallet system setup. Onboarding new customers or legal entities requires a new wallet creation.

Customer Onboarding

Diagram: Onboarding a customer

Creating a new wallet for a customer requires the following data to be passed in the body of the request:

customer - all required fields must be fully populated - Paysafe needs this information for regulatory purposes.
customer.kyc - property tracks the customer KYC process status and data
- kyc.status - This flag must be passed when creating a customer wallet. The flag denotes, that Paysafe accepts only customers, that have passed the KYC verification process. If the value of this flag is different from COMPLETED, then the wallet creation will fail.
- customer.kyc.idVerification, customer.kyc.addressVerification, customer.kyc.faceMatch, customer.kyc.EDD - optional objects
- status - Mandatory property if the object is present. The accepted value on onboarding is "COMPLETED".
- date - Optional property. Date of KYC verification completion. Current date is used if the value is not passed.
- electronicallyVerified - Property that shows if the customer has been KYC verified by an external vendor. Mandatory if documentUrls is empty.
- vendor - Name of vendor that has done the KYC verification. Mandatory if documentUrls is empty.
- documentUrls - List of URLs of documents that the customer has provided during KYC verification. Merchant is obligated to provide them or provide electronicallyVerified and vendor to guarantee that the customer has gone through KYC verification.
- EDD.date - Mandatory property if EDD.status is "COMPLETED", otherwise optional.
accounts - at least one account object has to be populated and it must contain a currency code. Please refer to the Merchant's agreement with Paysafe for a list of supported wallet currencies per country. If an unsupported currency is passed, or if two Account objects with the same currency are provided, creating the wallet will fail.
- when creating a new wallet, totalBalance and availableBalance are disregarded
- If hasIban == true, a new Virtual IBAN (vIBAN) will be allocated for this customer for that account and currency. The vIBAN will be provided to the Merchant in the API response.
termsAndConditionsAccepted - this flag is needed as proof that the Merchant has presented the Paysafe T&Cs to the customer, and the customer has accepted these T&Cs. If this flag has a value different than true, then the wallet creation will fail.
identityDocuments - metadata about all documents, submitted by the Customer during the KYC & EDD process

The wallet account can only be created in EUR for the European Economic Area and in GBP for the United Kingdom.

Assigning a virtual IBAN may be asynchronous due to differences in the banks that are used. The Merchant will receive a webhook event with IBAN_ASSIGNED type when the vIBAN is assigned.

When the vIBAN is created and assigned, the merchant might obtain it by using the iban property from getAccounts API.

To set up the balance, the Merchant must call an API endpoint to debit the amounts specified from the Merchant wallet, and credit these amounts into the customer's wallet effectively creating a starting balance.

In case the provided email provided is not unique, and a wallet is already created with this email address, the creation of a new wallet will fail.

Note: Providing an email for the customer during onboarding is a configurable option per Merchant. If the email is not provided, Paysafe would set an autogenerated email address (e.g. autogen.xxx.08891111@something.com). The email can be updated only once with another value using the update API.

After creating the wallet, the customer might be restricted on Paysafe side based on regulatory and risk checks.

POST https://api.paysafe.com/digitalwallets/v1/wallets

{
    "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "title": "Mr",
        "email": "john.doe@example.com",
        "mobile": "+443452555151",
        "address1": "23 Four Str",
        "city": "London",
        "zip": "E17 033",
        "countryCode": "GB",
        "birthDate": "1999-08-24",
        "registrationIp": "115.148.82.143",
        "nationality": "GB",
        "externalId": "d6f475fe-57c9-4865-9316-0c3b8e8128d4",
        "kyc": {
            "status": "COMPLETED",
            "idVerification": {
              "status": "COMPLETED",
              "date": "2021-03-12T13:27:41Z",
              "electronicallyVerified": true,
              "vendor": "Vendor"
            },
            "addressVerification": {
              "status": "COMPLETED",
              "date": "2021-03-12T13:27:41Z",
              "documentUrls": [
                "https://documents.com/document1.png",
                "https://documents.com/document2.png"
              ]
            },
            "faceMatch": {
              "status": "COMPLETED",
              "date": "2021-07-21T13:27:41Z",
              "electronicallyVerified": true,
              "vendor": "Vendor"
            },
            "EDD": {
                "status": "COMPLETED",
                "date": "2021-03-12T13:27:41Z",
                "electronicallyVerified": true,
                "vendor": "Vendor",
                "documentUrls": [
                    "https://documents.com/document1.png",
                    "https://documents.com/document2.png"
                ]
            },
            "addressVerificationDocumentsReceived": [
                "BANK_STATEMENT",
                "CREDIT_CARD",
                "TAX_RETURN",
                "PENSION_DOCUMENT",
                "PHONE_BILL",
                "UNKNOWN_DOC"
            ]
        },
          "pep": {
            "status": "MATCH",
            "lastScreenDate": "2021-07-19T13:35:41Z",
            "reason": "Matched"
          },
          "sanctions": {
            "status": "NO_MATCH",
            "lastScreenDate": "2021-07-19T13:35:41Z",
            "reason": "Incorrect data"
          }
        }
    },
    "accounts": [
    {
        "currencyCode": "GBP",
        "hasIban": true
    }
    ],
    "risk": {
        "customerRiskRating": 1,
        "isScaPerformed": true,
        "isCustomerIPTrusted": true,
        "isBeneficiaryTrusted": true
    },  
    "termsAndConditionsAccepted": true,
    "deviceInfo": {
        "threatMetrixSessionId": "a71a475b-1956-4814-9c92-7faa8226b218",
        "threatMetrixData": "true_ip=87%2e120%2e141%2e75&true_ip_assert_history=NEGATIVE_HISTORY&true_ip_attributes=_CHALLENGED&true_ip_attributes=_CHALLENGE_PASSED&true_ip_attributes=_TRUSTED&true_ip_attributes=_TRUSTED_CONF&...",
        "appType": "WEB_APP"
    },
    "customerIp": "73.82.192.17"
}

Legal Entity Onboarding

Onboarding a legal entity requires providing extended information since extended due diligence is required.

List of required fields for onboarding

legalEntity - all required fields must be fully populated - Paysafe needs this information for regulatory purposes. List of required fields
- externalId - customer unique identifier at merchant site
- email - The field is required for legal entities
- registrationIp - registration ip address
- registrationDate - registration date
- accounts - at least one account object has to be populated and it must contain a currency code. Please refer to the Merchant's agreement with Paysafe for a list of supported wallet currencies per country. If an unsupported currency is passed, or if two Account objects with the same currency are provided, creating the wallet will fail.
- companyName - company name
- companyIdentifier - company registration identifier as per local law
- registrationAddress - registration address
- operatingAddress - operating address
- websiteUrl - web site URL
- representative - main company representative
- directors - at least one director needs to be specified
- ultimateBeneficialOwners - at least one owner must be specified
- sourceOfFunding - source of funding
- natureOfBusiness - nature of business
- reasonToApply - reasons to apply

Expected Transaction Volume

For legal entities it is required to pass the expected transaction volume information during onboarding.

expectedTransactionVolume - Expected transaction volume of the legal entity for a rolling period of 1 year. The field contains the following properties:
- amount - the amount in minor units
- currencyCode - the amount currency code for example EUR. Use the same currency as the main account currency used during onboarding.

KYC field in `representative`, `representatives`, `directors` and `ultimateBeneficialOwners`

For representative.kyc.status the value must be present and set to either COMPLETED or NOT_COMPLETED depending on the KYC model used for legal entities.

COMPLETED - must be used if KYC process is managed by the merchant
NOT_COMPLETED - must be used if KYC process is managed by Paysafe

The KYC model used depends on the contract between Paysafe and the merchant. The API will reject requests with invalid parameter value.

Fields in KYC object

For simplicity idVerification, addressVerification, and faceMatch in kyc field will be referred to as <verification> as they have the same structure and rules applied.

The structure of the legal entity KYC object is the same as the customer KYC object. The KYC object structure for representative, directors, ultimateBeneficialOwners, representatives is the same. The kybDocuments array represents Business documents while kyc.<verification>.documentUrls represent Personal documents.
kyc and kybDocuments are optional properties, but the merchant is obligated to provide KYC verification documents.

POST https://api.paysafe.com/digitalwallets/v1/wallets

{
    "legalEntity": {
        "externalId": "6622429017",
        "email": "companymail@company.com",
        "mobile": "088634001917",
        "registrationIp": "87.120.141.75",
        "companyName": "companyName",
        "companyIdentifier": "companyIdentifier",
        "registrationAddress": {
          "countryCode": "BG",
          "stateProvince": "Sofia",
          "city": "Sofia",
          "postalCode": "1000",
          "address1": "reg address 1",
          "address2": "reg address 2"
        },
        "operatingAddress": {
          "countryCode": "BG",
          "stateProvince": "Sofia",
          "city": "Sofia",
          "postalCode": "1000",
          "address1": "operating address 1",
          "address2": "operating address 2"
        },
        "websiteUrl": "somecompany.com",
        "expectedTransactionVolume": {
          "amount": 100200300400,
          "currencyCode": "EUR"
        },
        "representative": {
          "firstName": "John",
          "middleName": "Alexander",
          "lastName": "Doe",
          "dateOfBirth": "1961-11-11",
          "countryCode": "BG",
          "identificationNumber": "6111118787",
          "identificationNumberIssuingCountryCode": "BG",
          "kyc": {
            "status": "COMPLETED",
            "idVerification": {
              "status": "COMPLETED",
              "documentUrls": [
                "https://documents.com/document.png"
              ]
            }
          },
          "kybDocuments": [
            {
              "type": "OWNERSHIP_STRUCTURE",
              "documentUrls": [
                "https://documents.com/document.png"
              ]
            },
            {
              "type": "STATEMENT_OF_WORK",
              "documentUrls": [
                "https://documents.com/document.png"
              ]
            }
          ]          
        },
        "directors": [
            {
              "firstName": "John",
              "middleName": "A",
              "lastName": "Doe",
              "dateOfBirth": "1961-11-11",
              "countryCode": "BG",
              "identificationNumber": "6111118787",
              "identificationNumberIssuingCountryCode": "BG",
              "kyc": {
                "status": "COMPLETED",
                "idVerification": {
                  "status": "COMPLETED",
                  "documentUrls": [
                    "https://documents.com/document.png"
                  ]
                }
              }              
            }
        ],
        "ultimateBeneficialOwners": [
            {
              "firstName": "John",
              "middleName": "Alexander",
              "lastName": "Doe",
              "dateOfBirth": "1961-11-11",
              "countryCode": "BG",
              "identificationNumber": "6111118787",
              "identificationNumberIssuingCountryCode": "BG",
              "kyc": {
                "status": "COMPLETED",
                "idVerification": {
                  "status": "COMPLETED",
                  "documentUrls": [
                    "https://documents.com/document.png"
                  ]
                }
              }
            }
        ],
        "sourceOfFunding": "funding source",
        "natureOfBusiness": "nature of business",
        "reasonToApply": "application reason"
    },
    "deviceInfo": {
        "appType": "WEB_APP"
    },
    "customerIp": "87.120.141.75",
    "accounts": [
        {
            "currencyCode": "EUR",
            "hasIban": true
        }
    ],
    "risk": {
        "customerRiskRating": 1,
        "isScaPerformed": true,
        "isCustomerIPTrusted": true,
        "isBeneficiaryTrusted": true
    },
    "termsAndConditionsAccepted": true,
    "kybDocuments": [
      {
        "type": "ARTICLES_OF_ASSOCIATION",
        "documentUrls": [
          "https://documents.com/document.png"
        ]
      },
      {
        "type": "CERTIFICATE_OF_INCORPORATION",
        "documentUrls": [
          "https://documents.com/document.png"
        ]
      }
    ]    
}

Update Customer Details

Customer details updates must be reflected on the Paysafe side, for regulatory purposes.

Customer profile information can be updated using the following endpoint.

PATCH https://api.paysafe.com/digitalwallets/v1/customer-persons/{customerId}

The following fields cannot be updated, and any attempt to do so will result in an error:

birthDate - can not be changed
type - Must be PERSON. 404 Not Found error is returned if it does not match the requirements
email
restrictions

The following fields are disregarded during the update so do not pass it:

registrationIp
id
externalId

Updating the following customer details might result in customer restriction and require new KYC Verification.

firstName, lastName - re-trigger KYC verification
address1, address2 - re-trigger address verification of KYC process

Change Of Customer Country

Changing customer country requires moving the customer account from one country jurisdiction to another. It impacts both accounting and compliance handling.

Legal entities can not change countries.

The process of account migration has the following prerequisites.

Customer accounts must have zero balance
Customer must provide address located in the new country
Base account currency in the new country must be specified upon migration.
One account must be provided for the initial migration. Additional accounts might be added using the Accounts API.
The customer accounts in the old country would be deactivated
KYC address verification information must be passed for the new address. If not passed the account might be restricted, until the address verification is performed.

Customer transaction history and verified instruments remain after the account migration.

For changing the customer country, you should use customer-persons PATCH request and pass all the required parameters for complying with the requirements above.

PATCH https://api.paysafe.com/digitalwallets/v1/customer-persons/{customerId}

{
  "address1": "23 Four Str",
  "city": "London",
  "zip": "E17 033",
  "countryCode": "GB",
  "kyc": {
    "status": "COMPLETED",
    "addressVerification": {
      "status": "COMPLETED",
      "date": "2021-07-15T17:54:12Z",
      "documentUrls": [
        "https://documents-repository.com/images/doc3"
      ]
    }
  },
  "accounts": [{
    "currencyCode": "GBP",
    "hasIban": true
  }
  ]
}

Update KYC

Except EDD.date all properties are optional. EDD.date would be mandatory if EDD.status is "COMPLETED".

Providing kyc.status would change values of idVerification.status, addressVerification.status and faceMatch. status unless they are provided.

Example:

{
  "kyc": {
    "status": "NOT_COMPLETED",
    "idVerification": {
      "status": "COMPLETED"
    }
  }
}

In the above example addressVerification.status and faceMatch.status would change to "NOT_COMPLETED" and idVerification.status to "COMPLETED".

Update Legal Entity

The following specifics are valid for updating legal entities.

partial update of representatives, directors and ultimateBeneficialOwners is not possible. Full list must be provided upon update. The operation replaces the existing representatives, directors and ultimateBeneficialOwners. Pass empty list to delete all record of specific type.
registrationAddress - can be updated as long as country is not changed. Legal entities can not change country.

Main represetative can not have the same identification number as one of the additional representatives. To promote additional representative to main representative, you must remove it from the representative list and set it as main representative.

Two representatives, directors and ultimate beneficial owners can not have the same identification numbers.

The following fields can not be updated

email - email is a required field for onboarding legal entities
type - can not be changed from LEGAL_ENTITY to PERSON
id - customer id can not be changed
externalId - external customer id can not be changed
registrationIp
restrictions - are disregarded. Restrictions are placed using dedicated restrictions API.
accounts - accounts can not be updated through this API.
registrationDate - can not be updated

Deactivate Customer

When a customer closes their account with the Merchant, the embedded wallet on the Paysafe side must be deactivated. Deactivation on Paysafe side restricts all customer operations.

The API Deactivate Customer must be used to achieve that.

Customer Accounts

Account information can be retrieved with the following APIs:

Add new account for a customer - Add Account
Get a list of all accounts for a customer - Get Account List
Get details and current balance for an account - Get Account

Direct update and delete accounts are not supported via API.

Was this page helpful?

On this Page

Search Overlay