Paying an Invoice Via the API

To pay an invoice, you need to collect payment information from the customer and apply it to the invoice via the invoice token.

Do an HTTP PUT like so:

[ ~ ] $ curl -i -u 28068fe710ed67dd38de8bcd48b0544cbabcfb03:X \
-X PUT -H 'Content-Type: application/xml' \
-d '
<payment>
  <account-type>credit-card</account-type>
  <credit-card>
    <number>4222222222222</number>
    <card-type>visa</card-type>
    <verification-value>234</verification-value>
    <month>1</month>
    <year>2011</year>
    <first-name>Joe</first-name>
    <last-name>Bob</last-name>
  </credit-card>
</payment>' \
https://spreedly.com/api/v4/meresheep/invoices/6a54b2f6c6c6ce4d3128eef5929054badc646929/pay.xml

Valid possibilities for the card_type field are visa, master, discover, american_express.

There are three cards, all visa, that are useful for testing:

Here is the response:

<?xml version="1.0" encoding="UTF-8"?>
<invoice>
  <closed type="boolean">true</closed>
  <created-at type="datetime">2009-07-02T18:56:22Z</created-at>
  <token>6a54b2f6c6c6ce4d3128eef5929054badc646929</token>
  <updated-at type="datetime">2009-07-02T18:58:22Z</updated-at>
  <subscriber-store-credit>$0.00</subscriber-store-credit>
  <customer-id>44</customer-id>
  <price>$24.00</price>
  <amount type="decimal">24.0</amount>
  <currency-code>USD</currency-code>
  <line-items type="array">
    <line-item>
      <amount type="decimal">24.0</amount>
      <currency-code>USD</currency-code>
      <description>3 months</description>
      <price>$24.00</price>
      <subscription-plan-version-id type="integer">3</subscription-plan-version-id>
    </line-item>
  </line-items>
  <subscriber>
    <active-until type="datetime" nil="true">2009-10-02T18:58:22Z</active-until>
    <billing-first-name nil="true">Joe</billing-first-name>
    <billing-last-name nil="true">Bob</billing-last-name>
    <created-at type="datetime">2009-07-02T17:27:26Z</created-at>
    <customer-id>44</customer-id>
    <eligible-for-free-trial type="boolean">true</eligible-for-free-trial>
    <email nil="true"></email>
    <lifetime-subscription type="boolean">false</lifetime-subscription>
    <screen-name>joe</screen-name>
    <store-credit type="decimal">0.0</store-credit>
    <store-credit-currency-code>USD</store-credit-currency-code>
    <token>f3feb1b75abcc2b31ed509ebbc23f0a8c73caa09</token>
    <updated-at type="datetime">2009-07-02T18:58:22Z</updated-at>
    <recurring type="boolean">true</recurring>
    <card-expires-before-next-auto-renew type="boolean">false</card-expires-before-next-auto-renew>
    <subscription-plan-name>Basic</subscription-plan-name>
    <active type="boolean">true</active>
    <on-trial type="boolean">false</on-trial>
    <feature-level type="string">basic</feature-level>
  </subscriber>
</invoice>

If successful, a 200 (OK) status code is returned.

The xml of the invoice is returned in the response body.

Errors

A 404 (Not Found) status code is returned if an invoice with the specified token can't be found.

A 422 (Unprocessable Entity) is returned if any required information is missing or otherwise fails verification. Spreedly will additionally return an XML array of error information.

A 403 (Forbidden) is returned if you attempt to pay an already closed invoice, if the payment information fails to authorize, or if a gateway is not configured.

A 504 (Gateway Timeout) is returned if the payment gateway fails to respond in a timely manner and the payment is thus not applied.

Extra Credit

Payment Account On File

If a subscriber has a payment account on file (indicated in the subscriber XML), you can use that payment account rather than requiring them to enter a new one:

[ ~ ] $ curl -i -u 28068fe710ed67dd38de8bcd48b0544cbabcfb03:X \
-X PUT -H 'Content-Type: application/xml' \
-d '
<payment>
  <account-type>on-file</account-type>
</payment>' \
https://spreedly.com/api/v4/meresheep/invoices/6a54b2f6c6c6ce4d3128eef5929054badc646929/pay.xml

Pay with Store Credit

While a regular credit card payment will use store credit if it’s available, sometimes you may want to only use store credit so that no credit card is required. To do that, pass an ‘account-type’ of ‘store-credit`:

[ ~ ] $ curl -i -u 28068fe710ed67dd38de8bcd48b0544cbabcfb03:X \
-X PUT -H 'Content-Type: application/xml' \
-d '
<payment>
  <account-type>store-credit</account-type>
</payment>' \
https://spreedly.com/api/v4/meresheep/invoices/6a54b2f6c6c6ce4d3128eef5929054badc646929/pay.xml

If there is insufficient store credit to cover the whole invoice you will receive an error back.

Pay with General Credit

Sometimes you simply want to close out an invoice with a credit, regardless of what the customer has on file, and without requiring other payment information. A general credit allows this, simply applying a credit to the invoice in the amount of the invoice:

[ ~ ] $ curl -i -u 28068fe710ed67dd38de8bcd48b0544cbabcfb03:X \
-X PUT -H 'Content-Type: application/xml' \
-d '
<payment>
  <account-type>general-credit</account-type>
  <description>Paid via check</description>
</payment>' \
https://spreedly.com/api/v4/meresheep/invoices/6a54b2f6c6c6ce4d3128eef5929054badc646929/pay.xml

Return to the Payments API ↑

Olark Livehelp