Guides
Start typing to search…

Step 1. Customers

Customers represent your users in the Walapay ecosystem. By registering your users with Walapay, you can enable seamless transfers of stablecoins or fiat currencies from or to your users' wallets and bank accounts. All KYC and KYB checks are handled by Walapay so you can safely move funds, knowing that Walapay has properly vetted your users in compliance with legal requirements.

If of type BUSINESS, you'll also need to pass along the information related to the Associated Persons (e.g., Ultimate Beneficial Owners, Control Persons) of these businesses. Please check our compliance requirements for details regarding the KYC/KYB process.

There are two ways to create a Customer:

  1. Use the Get KYC link for a customer endpoint to create a form that can be shared with your end user. This will create a customer within the Walapay system and automatically get updated with the data submitted by the user within the form. Once the user has been approved, you will can get all the data they have submitted (including files) through a webhook event or by calling the GET /customers/:id endpoint
  2. Use the Create a new customer endpoint to directly create the customer with all the data required for compliance. This option is best if you already have the end user's data or want full control of the UI to collect the required fields

📘

Email address

In both Sandbox and Production, you will encounter issues if you try to upload customers with the same email address. If one of your users has submitted a KYC form, you should not submit another customer with the same email address.

Individual Customer Creation

Request (KYC Link)

curl --request POST \
  --url 'https://sandbox-api.walapay.io/v1/customers' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --data '{
    "type": "INDIVIDUAL",
    "firstName": "James", // Optional, but recommended
    "lastName": "Smith", // Optional, but recommend
    "email": "[email protected]"
}'

Request (Direct through API)

For the fields required when creating an individual customer, please see the Requirements for Individuals page.

curl --request POST \
  --url 'https://sandbox-api.walapay.io/v1/customers' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --data '{
  "type": "INDIVIDUAL",
  "firstName": "James",
  "middleName": "Robert",
  "lastName": "Smith",
  "dateOfBirth": "1990-01-15",
  "email": "[email protected]",
  "phone": "+14155552671",
  "phoneCountryCode": "US",
  "address": {
    "streetLine1": "123 Main Street",
    "city": "San Francisco",
    "stateRegionOrProvince": "CA",
    "postalCode": "94105",
    "countryCode": "US"
  },
  "taxIdentificationNumber": "123456789",
  "governmentIssuedIdentification": {
    "type": "DRIVERS_LICENSE",
    "countryCode": "US",
    "number": "123456789",
    "issuanceDate": "2020-01-01",
    "expirationDate": "2030-01-01",
    "frontImage": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
    "backImage": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }
}'
curl --request POST \
  --url 'https://sandbox-api.walapay.io/v1/customers' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'X-Api-Key: fa15de08-f1af-4c41-a74b-2302b6785c13' \
  --data '{
  "type": "INDIVIDUAL",
  "firstName": "Jean",
  "lastName": "Dupont",
  "dateOfBirth": "1980-03-25",
  "email": "[email protected]",
  "phone": "+33612345678",
  "phoneCountryCode": "FR",
  "address": {
    "streetLine1": "10 Rue de Paris",
    "city": "Paris",
    "stateRegionOrProvince": "31",
    "postalCode": "75001",
    "countryCode": "FR"
  },
  "taxIdentificationNumber": "1234567890123",
  "governmentIssuedIdentification": {
    "type": "NATIONAL_ID",
    "countryCode": "FR",
    "number": "FR12345678",
    "issuanceDate": "2019-06-01",
    "expirationDate": "2029-06-01",
    "frontImage": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
    "backImage": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }
}'
curl --request POST \
  --url 'https://sandbox-api.walapay.io/v1/customers' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --data '{
  "type": "INDIVIDUAL",
  "firstName": "タロウ",
  "middleName": "ロバート",
  "lastName": "ヤマダ",
  "transliteratedFirstName": "Taro",
  "transliteratedMiddleName": "Robert",
  "transliteratedLastName": "Yamada",
  "dateOfBirth": "1990-01-15",
  "email": "[email protected]",
  "phone": "+81345678901",
  "phoneCountryCode": "JP",
  "address": {
    "streetLine1": "東京都港区六本木",
    "streetLine2": "1-6-1 泉ガーデンタワー",
    "city": "港区",
    "stateRegionOrProvince": "01",
    "postalCode": "106-6024",
    "countryCode": "JP"
  },
  "transliteratedAddress": {
    "streetLine1": "Roppongi",
    "streetLine2": "1-6-1 Izumi Garden Tower",
    "city": "Minato-ku",
    "stateRegionOrProvince": "01",
    "postalCode": "106-6024",
    "countryCode": "JP"
  },
  "taxIdentificationNumber": "123456789012",
  "governmentIssuedIdentification": {
    "type": "PASSPORT",
    "countryCode": "JP",
    "number": "TZ1234567",
    "issuanceDate": "2020-01-01",
    "expirationDate": "2030-01-01",
    "frontImage": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }
}'
curl --request POST \
  --url 'https://sandbox-api.walapay.io/v1/customers' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --data '{
  "type": "INDIVIDUAL",
  "firstName": "Chinedu",
  "lastName": "Okeke",
  "dateOfBirth": "1990-07-15",
  "email": "[email protected]",
  "phone": "+2348012345678",
  "phoneCountryCode": "NG",
  "address": {
    "streetLine1": "12 Adeola Odeku Street",
    "streetLine2": "Suite 205",
    "city": "Lagos",
    "stateRegionOrProvince": "LA",
    "postalCode": "101241",
    "countryCode": "NG"
  },
  "taxIdentificationNumber": "12345678-0001",
  "employmentStatus": "EMPLOYED",
  "mostRecentOccupation": "291291",
  "sourceOfFunds": "SALARY",
  "accountPurpose": "INVESTMENT_PURPOSES",
  "accountPurposeExplanation": "Receiving freelance payments and managing business expenses",
  "expectedMonthlyPaymentsUSD": "UNDER_FIVE_THOUSAND",
  "actingAsIntermediary": false,
  "governmentIssuedIdentification": {
    "type": "NATIONAL_ID",
    "countryCode": "NG",
    "number": "A1234567891",
    "issuanceDate": "2021-04-20",
    "expirationDate": "2031-04-20",
    "frontImage": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
    "backImage": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  },
  "supportingDocuments": [
    {
      "type": "PROOF_OF_ADDRESS",
      "file": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
      "description": "Utility bill",
      "subType": "UTILITY_BILL"
    }
  ]
}'

For example responses, please visit the API Reference's Create Customer endpoint and click on one of the available examples.

Business Customer Creation

Request (KYC Link)

curl --request POST \
  --url 'https://sandbox-api.walapay.io/v1/customers' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --data '{
    "type": "BUSINESS",
    "businessName": "Acme",
    "email": "[email protected]"
}'

Request (Direct through API)

For the fields required when creating an individual customer, please see the Requirements for Businesses page.

curl --request POST \
  --url 'https://sandbox-api.walapay.io/v1/customers' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'X-Api-Key: fa15de08-f1af-4c41-a74b-2302b6785c13' \
  --data '{
  "type": "BUSINESS",
  "businessType": "C_CORPORATION",
  "legalName": "Global Enterprises Inc",
  "tradeName": "Global Enterprises",
  "description": "Financial services corporation",
  "industry": "111120",
  "website": "www.example.com",
  "email": "[email protected]",
  "phone": "+1987654321",
  "address": {
    "streetLine1": "789 Corporate Blvd",
    "streetLine2": "Floor 20",
    "city": "Dallas",
    "stateRegionOrProvince": "TX",
    "postalCode": "75301",
    "countryCode": "US"
  },
  "accountPurpose": "PAYROLL",
  "sourceOfFunds": "SALES_OF_GOODS_AND_SERVICES",
  "isDao": false,
  "conductsMoneyServices": false,
  "estimatedAnnualRevenueUSD": "HUNDRED_THOUSAND_TO_MILLION",
  "expectedMonthlyPaymentsUSD": 10000,
  "operatesInProhibitedCountries": false,
  "taxIdentificationNumber": "12-3456789",
  "registrationNumber": "REG123456",
  "registrationDate": "2015-01-01",
  "supportingDocuments": [
    {
      "type": "BUSINESS_FORMATION",
      "file": "data:image/jpeg;base64,BASE64_ENCODED_IMAGE_DATA",
      "description": "Certificate of Incorporation"
    },
    {
      "type": "OWNERSHIP_INFORMATION",
      "file": "data:image/jpeg;base64,BASE64_ENCODED_IMAGE_DATA"
    },
    {
      "type": "PROOF_OF_ADDRESS",
      "file": "data:image/jpeg;base64,BASE64_ENCODED_IMAGE_DATA",
      "description": "Checking account Oct 2024",
      "subType": "BANK_STATEMENT"
    }
  ],
  "associatedPersons": [
    {
      "firstName": "James",
      "lastName": "Smith",
      "email": "[email protected]",
      "phone": "+1987654321",
      "address": {
        "streetLine1": "789 Corporate Blvd",
        "streetLine2": "Floor 20",
        "city": "Dallas",
    		"stateRegionOrProvince": "TX",
    		"postalCode": "75301",
    		"countryCode": "US"
      },
      "dateOfBirth": "1990-01-01",
      "percentageOwnership": 60,
      "hasControl": true,
      "title": "CEO",
      "isSigner": true,
      "isDirector": true,
      "relationshipEstablishmentDate": "2015-01-01",
      "taxIdentificationNumber": "123456789",
      "governmentIssuedIdentification": {
        "type": "PASSPORT",
        "countryCode": "US",
        "number": "UBO123456",
        "issuanceDate": "2020-01-01",
        "expirationDate": "2030-01-01",
        "frontImage": "data:image/jpeg;base64,BASE64_ENCODED_IMAGE_DATA"
      },
      "supportingDocuments": [
        {
          "type": "PROOF_OF_ADDRESS",
          "file": "data:image/jpeg;base64,BASE64_ENCODED_IMAGE_DATA",
          "description": "Utility bill",
          "subType": "UTILITY_BILL"
        }
      ]
    },
    {
      "firstName": "Kim",
      "lastName": "Possible",
      "email": "[email protected]",
      "phone": "+1987654322",
      "address": {
        "streetLine1": "790 Corporate Blvd",
        "city": "Dallas",
    		"stateRegionOrProvince": "TX",
    		"postalCode": "75301",
   		  "countryCode": "US"
      },
      "dateOfBirth": "1990-01-01",
      "percentageOwnership": 40,
      "hasControl": false,
      "title": "CFO",
      "isSigner": false,
      "isDirector": true,
      "relationshipEstablishmentDate": "2015-01-01",
      "taxIdentificationNumber": "123456789",
      "governmentIssuedIdentification": {
        "type": "DRIVERS_LICENSE",
        "countryCode": "US",
        "number": "UBO123457",
        "issuanceDate": "2020-01-01",
        "expirationDate": "2030-01-01",
        "frontImage": "data:image/jpeg;base64,BASE64_ENCODED_IMAGE_DATA",
        "backImage": "data:image/jpeg;base64,BASE64_ENCODED_IMAGE_DATA"
      },
      "supportingDocuments": [
        {
          "type": "PROOF_OF_ADDRESS",
          "file": "data:image/jpeg;base64,BASE64_ENCODED_IMAGE_DATA",
          "description": "Bank statement",
          "subType": "BANK_STATEMENT"
        }
      ]
    }
  ]
}'
curl --request POST \
  --url 'https://sandbox-api.walapay.io/v1/customers' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'X-Api-Key: fa15de08-f1af-4c41-a74b-2302b6785c13' \
  --data '{
  "type": "BUSINESS",
  "legalName": "Pilipinas Enterprises Inc",
  "tradeName": "Pilipinas Enterprises Inc",
  "businessType": "C_CORPORATION",
  "description": "Financial services corporation",
  "industry": "111120",
  "website": "www.example.com",
  "email": "[email protected]",
  "phone": "+639171234567",
  "phoneCountryCode": "PH",
  "address": {
    "streetLine1": "123 Ayala Avenue",
    "streetLine2": "Makati Central Business District",
    "city": "Makati",
    "stateRegionOrProvince": "01",
    "postalCode": "1226",
    "countryCode": "PH"
  },
  "accountPurpose": "CHARITABLE_DONATIONS",
  "sourceOfFunds": "BUSINESS_LOANS",
  "estimatedAnnualRevenueUSD": "UNDER_HUNDRED_THOUSAND",
  "expectedMonthlyPaymentsUSD": 10000,
  "isDao": false,
  "conductsMoneyServices": false,
  "operatesInProhibitedCountries": false,
  "taxIdentificationNumber": "123-456-789-000",
  "registrationNumber": "REG123456",
  "registrationDate": "2015-01-01",
  "supportingDocuments": [
    {
      "type": "BUSINESS_FORMATION",
      "file": "data:image/jpeg;base64,BASE64_ENCODED_IMAGE_DATA",
      "description": "Certificate of Incorporation"
    },
    {
      "type": "OWNERSHIP_INFORMATION",
      "file": "data:image/jpeg;base64,BASE64_ENCODED_IMAGE_DATA"
    },
    {
      "type": "PROOF_OF_ADDRESS",
      "file": "data:image/jpeg;base64,BASE64_ENCODED_IMAGE_DATA",
      "description": "Checking account Oct 2024",
      "subType": "BANK_STATEMENT"
    }
  ],
  "associatedPersons": [
    {
      "firstName": "Maria",
      "lastName": "Santos",
      "email": "[email protected]",
      "phone": "+639171234568",
      "phoneCountryCode": "PH",
      "address": {
        "streetLine1": "456 Ortigas Avenue",
        "streetLine2": "Ortigas Center",
        "city": "Pasig",
        "stateRegionOrProvince": "AGS",
        "postalCode": "1605",
        "countryCode": "PH"
      },
      "dateOfBirth": "1990-01-01",
      "percentageOwnership": 60,
      "hasControl": true,
      "title": "CEO",
      "isSigner": true,
      "isDirector": true,
      "relationshipEstablishmentDate": "2015-01-01",
      "taxIdentificationNumber": "123-45-6789",
      "governmentIssuedIdentification": {
        "type": "PASSPORT",
        "countryCode": "PH",
        "number": "UBO123456",
        "issuanceDate": "2020-01-01",
        "expirationDate": "2030-01-01",
        "frontImage": "data:image/jpeg;base64,BASE64_ENCODED_IMAGE_DATA"
      }
    },
    {
      "firstName": "Jose",
      "lastName": "Reyes",
      "email": "[email protected]",
      "phone": "+639171234569",
      "phoneCountryCode": "PH",
      "address": {
        "streetLine1": "789 Bonifacio High Street",
        "streetLine2": "Bonifacio Global City",
        "city": "Taguig",
        "stateRegionOrProvince": "AGS",
        "postalCode": "1634",
        "countryCode": "PH"
      },
      "dateOfBirth": "1990-01-01",
      "percentageOwnership": 40,
      "hasControl": false,
      "title": "CFO",
      "isSigner": false,
      "isDirector": true,
      "relationshipEstablishmentDate": "2015-01-01",
      "taxIdentificationNumber": "123-45-6789",
      "governmentIssuedIdentification": {
        "type": "PASSPORT",
        "countryCode": "PH",
        "number": "UBO123457",
        "issuanceDate": "2020-01-01",
        "expirationDate": "2030-01-01",
        "frontImage": "data:image/jpeg;base64,BASE64_ENCODED_IMAGE_DATA"
      }
    }
  ]
}'

For example responses, please visit the API Reference's Create Customer endpoint and click on one of the available examples.

Updated 11 days ago