Customers

Customers represent the end users who send or receive payments through your integration. They represent the individuals or businesses involved in payment transactions with a Straddle account.

This guide will walk you through the process of creating, managing, and verifying customers using Straddle’s API. This guide explains how to create and manage customers while maintaining compliance and security.

​

The Customer Object

A customer in Straddle is an entity (individual or business) that you interact with for payment purposes.

​

Identity Built-in

When you create a customer, Straddle automatically initiates the identity verification process. This process includes:

The result of this verification process determines the customer’s status, which can be one of the following:

• pending: Initial status when the customer is created

• review: Additional review is needed

• verified: Customer has passed all verification checks

• rejected: Customer failed verification checks

• inactive: Customer is no longer active

​

Customer Attributes

​

Customer Status Details

​

Creating a Customer

To create a customer, you’ll use the POST /v1/customers endpoint. Here’s an example of how to create a customer using the Straddle API:

curl -X POST https://api.straddle.io/v1/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "type": "individual",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "address": {
      "address1": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "zip": "12345",
      "type": "residential"
    },
    "compliance_profile": {
      "dob": "1990-01-01",
      "ssn": "123-45-6789"
    },
    "external_id": "cust_123",
    "metadata": {
      "user_id": "user_123"
    }
  }'

This request creates a new customer with the provided information. The response will include a unique id for the customer, which you’ll use for future operations.

​

Retrieving Customer Information

To retrieve information about a customer, use the GET /v1/customers/{id} endpoint:

curl https://api.straddle.io/v1/customers/{id} \
  -H "Authorization: Bearer YOUR_API_KEY"

​

Updating Customer Information

You can update a customer’s information using the PUT /v1/customers/{id} endpoint:

curl -X PUT https://api.straddle.io/v1/customers/{id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "email": "john.smith@example.com"
  }'

​

Listing Customers

To retrieve a list of customers, use the GET /v1/customers endpoint. This endpoint supports pagination and various filter options:

curl "https://api.straddle.io/v1/customers?page_number=1&page_size=10&sort_by=created_at&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

You can filter customers by various parameters such as status, type, created_from, created_to, and more. Refer to the API reference for a complete list of available filters.

​

Handling Customer Reviews

When a customer’s status is set to review, it means additional verification is needed. You can use the GET /v1/customers/{id}/review endpoint to retrieve detailed information about the review:

curl https://api.straddle.io/v1/customers/{id}/review \
  -H "Authorization: Bearer YOUR_API_KEY"

The response will include detailed information about the verification process, including any specific issues that need to be addressed.

To update the status of a customer under review, use the PATCH /v1/customers/{id}/review endpoint:

curl -X PATCH https://api.straddle.io/v1/customers/{id}/review \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "verified"
  }'

​

Working with Unmasked Customer Data

In certain situations, you may need to access unmasked customer data. This is sensitive information and should be handled with care. To retrieve unmasked customer data, use the GET /v1/customers/{id}/unmasked endpoint:

curl https://api.straddle.io/v1/customers/{id}/unmasked \
  -H "Authorization: Bearer YOUR_API_KEY"

​

Best Practices for Working with Customers

1. Provide as much information as possible: The more information you provide when creating a customer, the more accurate the verification process will be.

2. Handle verification failures gracefully: If a customer’s verification fails, provide clear instructions on what they need to do next.

3. Keep customer information up to date: Regularly update customer information to ensure accuracy and maintain compliance.

4. Use webhooks: Set up webhooks to receive real-time notifications about changes in customer status or verification results.

5. Respect privacy: Only collect and store the minimum amount of personal information necessary for your business operations.

6. Implement proper error handling: Be prepared to handle various API errors and provide appropriate feedback to your users.

7. Use pagination for listing customers: When retrieving large lists of customers, always use pagination to improve performance and responsiveness.

8. Leverage metadata: Use the metadata field to store additional information about customers that’s specific to your business needs.

9. Implement proper access controls: Ensure that only authorized personnel have access to sensitive customer information, especially unmasked data.

10. Regular audits: Periodically review your customer data and processes to ensure ongoing compliance with regulations and best practices.

​

Understanding Reason Codes

Straddle uses reason codes to provide detailed information about verification results. These codes can help you understand why a customer might have failed verification or been flagged for review. Here are some common reason codes:

• I1001: Identity not found within Consortium Institutions

• R201: The input SSN is invalid

• R551: Email address is invalid

• R603: Phone number is invalid

• R703: Address is invalid or does not exist

For a complete list of reason codes and their meanings, refer to the Reason Codes Reference.

​

Handling Specific Use Cases

​

High-Risk Customers

For customers flagged as high-risk, you may want to implement additional verification steps:

1. Request additional documentation

2. Conduct manual review

3. Implement transaction limits

​

Business Customers

When working with business customers, you’ll need to collect additional information:

1. Business name

2. Business type (LLC, Corporation, etc.)

3. Tax ID (EIN for US businesses)

4. Information about business owners or authorized representatives

For more information on Business Identity verification, refer to the Business Identity guide.

​

Conclusion

Understanding and effectively managing customers is crucial for successful integration with Straddle. By leveraging Straddle Identity, you can ensure that you’re interacting with verified individuals and businesses, reducing the risk of fraud and enhancing the security of your payment operations.

Remember that customer management is an ongoing process. Regularly review and update your practices to ensure they align with the latest regulations and industry best practices.

For more detailed information about the customer-related API endpoints, refer to the Customers API Reference.