Customers

When posting a one-time or recurring charge to ReceivePay, you have the option of linking the payment to a customer record. If you do not supply either an existing customer_id or a customer node with customer information for a recurring charge, a new customer record will automatically create a customer record and return the new customer_id in the successful transaction response.

Customer records can be created, update, and deleted via the API. Furthermore, you can request data about certain customers or search all customers using search filters.

Object Data

Variable	Type	Required	Format/Example
id	automatic		123456789
internal_id	string		A username or user ID in your own records, e.g. "Simulatedusername", "98765432".
first_name	string	yes	Joe
last_name	string	yes	Smith
address_1	string		12345 Simulated St.
address_2	string		For apartment/unit/suite #'s, eg. "Unit 2".
city	string		Toronto
state	string		The state/province/region of the customer. For the US and Canada, this must be supplied as the two letter abbreviation, eg. "ON"
country	country		The ISO 3166-1 alpha-2 code of the customer's country, e.g. "CA", "US".
postal_code	string		The zip or postal code of the user, e.g. "A1B2C3", "90210".
email	email		A valid email address for the customer.
phone	string		1-555-555-0000
date_created	date (automatic)		The date the record was created, e.g. 2009-05-29 04:44:04

Embedding customer data in Charge/Recur requests

To minimize the number of requests necessary, API users who want to link charges to customers do not have to call both NewCustomer and a Charge or Recur request to link the charge to a new customer. You can embed a customer node within either of these requests and a new customer will be created automatically. If you do embed new customer data in a request, a customer_id will be returned in the response, along with other variables such as response_code and charge_id.

Example request:

<?xml version="1.0" encoding="UTF-8"?>
<request>
	<authentication>
		<api_id>Simulated000API000ID</api_id>
		<secret_key>Simulated000API000SECRET000KEY</secret_key>
	</authentication>
	<type>Charge</type>
	<gateway_id>594082</gateway_id>
	<customer>
		<first_name>Joe</first_name>
		<last_name>Customer</last_name>
		<address_1>1345 Ontario Street</address_1>
		<address_2>Apt 1</address_2>
		<city>San Diego</city>
		<state>CA</state>
		<postal_code>92101</postal_code>
		<country>USA</country>
	</customer>
	<credit_card>
		<card_num>0000123412341234</card_num>
		<exp_month>12</exp_month>
		<exp_year>2015</exp_year>
		<cvv>123</cvv>
	</credit_card>
	<amount>95.00</amount>
</request>

Linking Charge/Recur requests to existing customers

If a customer already exists in the system, you can link a new Charge or Recur request to this customer by embedding a customer_id node in your request.

Example request:

<?xml version="1.0" encoding="UTF-8"?>
<request>
	<authentication>
		<api_id>Simulated000API000ID</api_id>
		<secret_key>Simulated000API000SECRET000KEY</secret_key>
	</authentication>
	<type>Charge</type>
	<gateway_id>594082</gateway_id>
	<customer_id>123456789</customer_id>
	<credit_card>
		<card_num>0000123412341234</card_num>
		<exp_month>12</exp_month>
		<exp_year>2015</exp_year>
		<cvv>123</cvv>
	</credit_card>
	<amount>95.00</amount>
</request>

Method: NewCustomer

Customer records can be created through this method.

Required data:

• first_name
• last_name

Optional data:

• Any/all of the object data above, except id.

Response data:

• response_code of "200", upon success.
• customer_id - The ID of the new customer

Method: UpdateCustomer

Update an existing customer record.

Required data:

• customer_id

Optional data:

• Any/all of the object data above, except id.

Response data:

• response_code of "201", upon success.

Method: DeleteCustomer

Delete an existing customer record.

Required data:

• customer_id

Response data:

• response_code of "202", upon success.

Method: GetCustomer

Gets a record for an individual customer.

Required data:

• customer_id - The ID of the customer record. This is not the internal_id.

All available customer data is returned in the response, including a node of any active recurring plans linked to the user.

Response data:

• customer
  • All available customer data.
  • status - Either "active" or "deleted".
  • If the user has active plans, a plans node filled with each plan's data.

Example response:

<?xml version="1.0" encoding="utf-8"?>
<response>
  <customer>
    <id>140</id>
    <internal_id/>
    <first_name>Joe</first_name>
    <last_name>Customer</last_name>
    <company/>
    <address_1>123 Broadway</address_1>
    <address_2/>
    <city>San Diego</city>
    <state>CA</state>
    <postal_code>92101</postal_code>
    <country>USA</country>
    <email>joe@example.com</email>
    <phone/>
    <date_created>2009-05-29 04:44:44</date_created>
    <plans>
      <plan>
        <id>123456789</id>
        <type>paid</type>
        <name>Simulated Plan</name>
        <amount>14.95</amount>
        <interval>30</interval>
        <notification_url>http://www.example.com/post.php</notification_url>
        <status>active</status>
      </plan>
    </plans>
  </customer>
</response>

Method: GetCustomers

Searches all customers. If a request is made without any filters, the first 100 customer records, ordered by "last_name", are returned.

Optional filters:

• Any of the variables listed under Object Data, except id.
• plan_id - Only retrieve customers with an active recurring plan of this ID.
• active_recurring - Only retrieve customers with an active recurring charge of any kind.
• deleted - Set to "1" to retrieve only deleted customers. Default: 0.
• offset - Retrieval will begin after offset # of records. Useful for pagination. Default: 0.
• limit - The total number of records to retrieve, beginning at the offset. Maximum: 100. Default: 100.
• sort - The field on which to sort retrieved records. Default: "last_name". Available values:
  • first_name
  • last_name
  • date
• sort_dir - The direction in which to sort retrieved records. Default: "asc". Can also be "desc".

Response data:

• results - Number of records in this response
• total_results - Total # of records to retrieve. Use offset to gather all records over multiple iterated requests.
• customers
  • A customer node for each returned customer
    • All data available for the customer, in the format of GetCustomer.

Example response:

<?xml version="1.0" encoding="utf-8"?>
<response>
  <results>3</results>
  <total_results>3</total_results>
  <customers>
    <customer>
      <id>5</id>
      <internal_id/>
      <first_name>Joe</first_name>
      <last_name>Customer</last_name>
      <company/>
      <address_1>12345 Toronto St.</address_1>
      <address_2/>
      <city>San Diego</city>
      <state>CA</state>
      <postal_code>A1BC2D</postal_code>
      <country>USA</country>
      <email/>
      <phone/>
      <date_created>2009-05-19 11:11:08</date_created>
    </customer>
    <customer>
      <id>4</id>
      <internal_id/>
      <first_name>Paul</first_name>
      <last_name>Other</last_name>
      <company/>
      <address_1>54321 Manitoba St.</address_1>
      <address_2>Unit 6</address_2>
      <city>Winnipeg</city>
      <state>MB</state>
      <postal_code>92101</postal_code>
      <country>USA</country>
      <email/>
      <phone/>
      <date_created>2009-04-17 04:44:44</date_created>
    </customer>
    <customer>
      <id>3</id>
      <internal_id/>
      <first_name>Carl</first_name>
      <last_name>Simpson</last_name>
      <company/>
      <address_1/>
      <address_2/>
      <city/>
      <state/>
      <postal_code/>
      <country/>
      <email/>
      <phone/>
      <date_created>2009-03-06 14:23:44</date_created>
      <plans>
        <plan>
          <id>50593</id>
          <type>paid</type>
          <name>Simulated Plan</name>
          <amount>90.00</amount>
          <interval>365</interval>
          <notification_url/>
          <status>active</status>
        </plan>
      </plans>
    </customer>
</response>