Charges

Charges are individual payments made with a credit card. Charges can be linked to recurring charges and/or customers. However, charges can also exist without a link to either a customer or a recurring charge.

Charges are processed immediately via the gateway specified by the gateway_id in the request or by the default gateway associated with the API client. If there is only one gateway associated with the API account, this gateway will be for the charge.

Charges can be created and records of charges can be retrieved. However, charges cannot be updated and/or deleted because the records serve as receipts for payments made via external payment gateways. To refund or void charges, one should access their specific payment gateway's control panel.

Method: Charge

This method is the heart of the billing engine. A Charge request represents a payment made via a payment gateway. One makes a request of this type to charge a credit card.

To create subscription charges, you will not use this method. You will use the Recur method. However, all individual charges for a recurring subscription are stored in the charges database and returned in GetCharge and GetCharges requests.

Charge requests can be linked to customers via either a customer_id or an embedded customer node embedded within this request to the API. For more information on embedding customer data in a Charge request, see the customers page.

How to add a free charge to a customer (e.g., for records purposes):
Pass amount as "0". Complete dummy credit card information with "0000000000000000" as the credit card number and any future expire date. Your gateway will not be passed this charge.

Request data:

Variable	Type	Required	Format/Example
amount	money	yes	e.g. "45.67"
coupon	string		A coupon code that relates to a coupon in the database (e.g., "TEST123"). If the coupon code is invalid, it will be ignored.
credit_card	node	yes	All credit card sub-nodes must be included with accurate credit card information regarding the purchaser.
card_num	int	yes	The purchaser's credit card number, e.g. "1234567809876543".
name	string	yes	The purchaser's name. This must match the name on the credit card.
exp_month	int	yes	The purchaser's credit card expiry month with 2-digit representation, e.g. "10".
exp_year	int	yes	The purchaser's credit card expiry year with 2-digit representation, e.g. "14".
cvv	int	yes	The purchaser's credit card CVV2/security number. It's required for any card where it is available. If not available on the card, send this parameter as empty.
gateway_id	int		The system ID for the payment gateway used for the charge. If left empty, the default/only gateway will be used.
customer_id	int		The ID of the customer to link the charge to, e.g. "4". Only include this parameter if you are not embedding customer information below. Charges do not need to be linked to a customer.
customer	node		Include sub-nodes with any/all available customer data. For more information, see the "Embedding customer data in Charge/Recur requests" on the customers page. Only include this parameter if you are not including a customer_id. Charges do not need to be linked to a customer.
customer_ip_address	string		You can optionally send the purchaser's IP address.

Response data:

• response_code - "1" upon success, "2" upon failure.
• response_text - A verbose description of the response_code.
• charge_id - The ID of the charge record.
• customer_id - The ID of the new customer, if a customer node was embedded in the request.
• amount - The amount of the charge, useful for coupon-adjusted requests.

Method: Refund

Refunds a successful charge.

Note: Not all gateways allow refunds via their API. This method will return an error (code = 5020) if this is the case. It will also return an error if the charging gateway was disabled/deleted, or if the charge cannot be found in the database.

Required data:

• charge_id- The ID of the charge to refund.

Response data:

• response_code - "50" upon success, "51" upon failure.
• response_text - A verbose description of the response_code.

Method: GetCharge

Retrieves available information about a previous charge.

Required data:

• charge_id - The ID of the charge record.

Response data:

Variable	Type	Required	Format/Example
id	automatic		123456789
gateway_id	int		The system ID for the payment gateway used for the charge.
date	date		The date of the charge.
amount	money	yes	e.g. "45.67"
card_last_four	int		The last four digits of the charged credit card.
recurring_id	int		The ID of the recurring charge related to this individual charge. Only returned if a recurring charge is available.
status	string (automatic)		"ok" if the charge was successful, "failed" if the charge was unsuccessful.
If a customer_id is passed in a Charge request, a customer node is returned with all available data in the format of a GetCustomer request.

Example simple response:

<?xml version="1.0" encoding="utf-8"?>
<response>
  <charge>
    <id>140</id>
    <gateway_id>12345</gateway_id>
    <amount>24.95</amount>
    <date>2009-05-29 22:11:44</date>
    <card_last_four>9876</card_last_four>
    <status>ok</status>
  </charge>
</response>

Example response with customer information and linked to a recurring charge:

<?xml version="1.0" encoding="utf-8"?>
<response>
  <charge>
    <id>140</id>
    <gateway_id>12346</gateway_id>
    <amount>15.35</amount>
    <date>2009-05-14 11:25:14</date>
    <card_last_four>5467</card_last_four>
    <recurring_id>192824</recurring_id>
    <status>ok</status>
    <refunded>0</refunded>
    <customer>
	    <id>140</id>
	    <internal_id/>
	    <first_name>Joe</first_name>
	    <last_name>Customer</last_name>
	    <company/>
	    123 Broadway
	    <address_2/>
	    San Diego
	    <state>CA</state>
	    92101
	    USA
	    <email>joe@example.com</email>
	    <phone/>
  	</customer>
  </charge>
</response>

Method: GetCharges

Returns records of charges, with optional filters. If a request is made without any filters, the latest 100 active customer records are returned.

Optional filters:

• id
• recurring_id - Get all charges linked to a recurring charge.
• gateway_id
• customer_id
• customer_last_name
• customer_internal_id
• recurring_only - Set to "1" to only retrieve charges linked to recurring charges.
• status - Values: "ok", "refunded", or "failed". If not present in the request, all transactions are returned regardless of status.
• 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: "date". Available values:
  • customer_first_name
  • customer_last_name
  • date
  • amount
• sort_dir - The direction in which to sort retrieved records. Default: "desc". Can also be "asc".

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.
• charges
  • A charge node for each returned charge
    • All data available for the charge, in the format of GetCharge.

Example response:

<?xml version="1.0" encoding="utf-8"?>
<response>
  <results>2</results>
  <total_results>2</total_results>
  <charges>
     <charge>
       <id>140</id>
       <gateway_id>12345</gateway_id>
       <amount>24.95</amount>
       <date>2009-05-29 22:11:44</date>
       <card_last_four>9876</card_last_four>
       <status>ok</status>
       <refunded>1</refunded>
       <refund_date>2009-06-14 12:11:09</refund_date>
     </charge>
     <charge>
       <id>140</id>
       <gateway_id>12346</gateway_id>
       <amount>15.35</amount>
       <date>2009-05-14 11:25:14</date>
       <card_last_four>5467</card_last_four>
       <recurring_id>192824</recurring_id>
       <status>ok</status>
       <customer>
	      <id>140</id>
	      <internal_id/>
	      <first_name>Joe</first_name>
	      <last_name>Customer</last_name>
	      <company/>
	      123 Broadway
	      <address_2/>
	      San Diego
	      <state>CA</state>
	      92101
	      USA
	      <email>joe@example.com</email>
	      <phone/>
       </customer>
     </charge>
  </charges>
</response>

Method: GetLatestCharge

Retrieves available information about a previous charge for a customer.

Required data:

• customer_id - The ID of the customer.

Optional data:

• gateway_id - Only retrieve data for this gateway ID.

Response data:

• All charge data (in the format of GetCharge).