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>

Compare our service and prices to our competitors and
Give Us A Call

(800) 969-8047


All rights reserved. Built on the CodeIgniter framework.