Create

Overview

The Create RPC creates a customer record at the payment processor. This stores customer information (name, email, phone, address) at the connector level, enabling streamlined future transactions without resending personal details.

Business Use Case: When a new customer signs up or makes their first purchase, you create their profile at the payment processor. This customer ID can then be used across multiple payment operations, improving authorization rates through customer history and enabling features like saved payment methods and recurring billing.

Purpose

Why create customer profiles at the payment processor?

Scenario	Benefit
Returning customers	Faster checkout without re-entering personal information
Recurring billing	Link subscriptions to a consistent customer identity
Multiple payment methods	Organize stored cards/wallets under one customer
Unified reporting	Track all customer transactions in one view

Key outcomes:

• Unique connector_customer_id for referencing this customer

• Consistent identity across all payment operations

• Foundation for payment method tokenization

• Improved authorization rates for repeat customers

Request Fields

Field	Type	Required	Description
merchant_customer_id	string	Yes	Your unique customer reference
customer_name	string	No	Full name of the customer
email	SecretString	No	Email address of the customer
phone_number	string	No	Phone number of the customer
address	PaymentAddress	No	Billing and shipping address information
metadata	SecretString	No	Additional metadata for the connector (max 20 keys)
connector_feature_data	SecretString	No	Connector-specific metadata for the transaction
test_mode	bool	No	Process as test transaction

Response Fields

Field	Type	Description
merchant_customer_id	string	Your customer reference (echoed back)
connector_customer_id	string	Connector's customer ID (e.g., Stripe cus_xxx)
error	ErrorInfo	Error details if creation failed
status_code	uint32	HTTP-style status code (200, 400, etc.)
response_headers	map<string,string>	Connector-specific response headers

Example

Request (grpcurl)

grpcurl -H "x-connector: stripe" \
  -H "x-connector-auth: {\"Stripe\":{\"api_key\":\"$STRIPE_API_KEY\"}}" \
  -d '{
    "merchant_customer_id": "cust_user_12345",
    "customer_name": "John Doe",
    "email": "[email protected]",
    "phone_number": "[phone]",
    "address": {
      "billing_address": {
        "first_name": "John",
        "last_name": "Doe",
        "line_1": "123 Main Street",
        "city": "San Francisco",
        "state": "CA",
        "zip_code": "94105",
        "country": "US"
      }
    },
    "metadata": "{\"tier\": \"premium\"}",
    "test_mode": true
  }' \
  localhost:8080 \
  types.CustomerService/Create

Response

{
  "merchant_customer_id": "cust_user_12345",
  "connector_customer_id": "cus_9OhXXXXXXXXXXXX",
  "status_code": 200
}

Next Steps

• Authorize - Create a payment linked to this customer

• PaymentMethodService.Tokenize - Store payment methods for this customer

• SetupRecurring - Set up recurring billing with customer reference