Online Payment Methods

Announcements
1

Hi all,

We’re currently beta testing a new API feature which allows online payment methods to be specified and managed for invoices.

Companies with this feature enabled will be able to pass and read a payment_methods hash on their invoices.

e.g.

{
    "invoice": {
        "url": "https://api.freeagent.com/v2/invoices/1234",
        "payment_url": "https://payments.freeagent.com/p/aaaabbbbccccdddd",
        ...
        "payment_methods": {
            "gocardless_preauth": false,
            "gocardless": true,
            "paypal": false,
            "paypal_here": false
        }
    }
}

All payment methods supported by the FreeAgent app are available, but their status will be reported by the API only if the integration is enabled for the company. In the example above, stripe is not being included in the response as the company doesn’t use it.

The payment methods available are:

  • paypal
  • paypal_here
  • gocardless
  • gocardless_preauth (“direct debit” style mandate)
  • stripe
  • dwolla

If anyone is interested in joining the beta users group, please DM me with the details of the company you wish the feature to be enabled for (not your integration I’m afraid - it is only possible to enable this on a per-company basis), and I will begin the process for adding them to the trial.

As with any beta the implementation may be subject to change, so if you are running mission-critical production integrations then this may not be a good thing to trial, however we are keen to see this tested to ensure it meets our users’ needs before we finalise the API requests and publish the documentation.

If anyone has any questions, feel free to respond to this post and we’ll do what we can to help.

Cheers,
Paul.

2

Quick update to this. Following a question from one of the beta users asking how to determine which payment methods are valid for each invoice, I’ve made a small tweak to the API responses.

Now the list of payment methods against each invoice will only list those methods which can be applied to the invoice.

A summary of the rules around this is:

  • Dwolla - the company must have enabled the Dwolla integration and the invoice currency must be USD
  • GoCardless - the company must have enabled the GoCardless integration and the invoice currency must be GBP
  • GoCardless Preauth - as GoCardless, but the contact must have a current active preauth agreement
  • PayPal - the company must have a PayPal bank account
  • PayPal Here - PayPal here must be enabled on the first PayPal bank account
  • Stripe - the company must have the Stripe integration enabled and the invoice currency must be supported by Stripe

Example API responses:

bool in each case may be true/false to signify whether that payment option is enabled for the specific invoice.

For a company with PayPal enabled but not PayPal Here:

{
  "payment_methods": {
    "paypal": bool
  }
}

For a company with GoCardless enabled, on a GBP invoice to a contact without a preauth agreement:

{
  "payment_methods": {
    "gocardless": bool
  }
}

For a company with GoCardless enabled, on a GBP invoice to a contact with a preauth agreement:

{
  "payment_methods": {
    "gocardless": bool,
    "gocardless_preauth": bool
  }
}

For a company with GoCardless enabled, on a USD invoice to a contact with a preauth agreement:

{
  "payment_methods": {}
}

Hopefully that all makes sense, and will make the API responses more usable as you’ll be able to infer which payment methods are valid for any given invoice.

As always, any feedback on this will be gratefully received.

Cheers,
Paul.

3

And another change, again only available to users on the invoice payments beta for now: We are now exposing details of GoCardless direct debit mandates as part of the contacts API:

Calls to /v2/contacts will now contain an additional field for contacts which have a current direct debit mandate only (see https://www.freeagent.com/support/kb/integrations/gocardless-taking-payments-with-a-direct-debit-mandate/)

{
  contacts: [
    {
      ...
      "direct_debit_mandate_state": state
    }
    ...
  ]
}

The state value can be one of the following:

  • “setup”: the agreement has been created in the FreeAgent UI and the email is to be sent to the customer
  • “pending”: the customer has been sent the mandate email
  • “inactive”: the customer has completed the mandate agreement and we are waiting on confirmation from GoCardless
  • “active”: GoCardless have confirmed the mandate and it is now usable

Of those four, you are pretty unlikely to see “setup” and “inactive” as these are transitional states and the agreement should not be in that condition for more than a second or two at a time but they are included here for completeness.

This is further expanded on when calling /v2/contacts/:id

{
  "contact": {
    ...
    "direct_debit_mandate_state": "active",
    "direct_debit_mandate": {
      "currency": "GBP",
      "max_amount": "5000.0",
      "remaining_amount": "5000.0",
      "next_interval_starts_on": "2017-06-30"
    }
  }
}

Hopefully that change will allow the invoice payment method fields to be used to their full potential. If anyone has any comments on this, or wants to be included in the beta group please do let me know.

Cheers,
Paul.