Contact Mapping API
While uCollect doesn’t have a full API. there are still a few things that you do. We have three APIs that can help you automate things. For more information please contact support. Please note that these are advanced topics and not suitable for end users. Our API is provided as is. We do not provide development assistance, support, testing or certification for you to work with our API.
Using the API
- To use the API you need to generate an API key. You can do this from the Edit, Organisation Settings, Organisation Profile section, Generate API Key). You will need this key in the next step.
- You will create a JSON POST that contains the APIKey in the Header.
- In the JSON POST Body include the payload as documented below.
Contact Mapping & Installments
Our Contact Mapping API is designed to allow you to quickly connect a contact with a gateway and/or to create an installment plan from your system. It’s perfect for onboarding systems.
Endpoint : AssignContact
URL : https://app.ucollect.biz/api/AssignContact
Example:
{
“ContactID” : “a4d48ba0-fd53-422d-95a1-6ea2dae05fe5”,
“OrgPGID” : “2105”,
“PGToken” : “cus_EWQJcUrpqp3Sb8”,
“Suspended” : “1”,“Values” : [“123″,”234″,”345”],“Installments” : {“f1328393-0d6e-44df-a11f-064d3c4d4bfd” : [“2019-02-21”, “150.50”], “d8272b94-e39d-4445-8ddb-9de09e5a28af” : [[“2019-02-22”, “50”],[“2019-02-24”, “50”]]},“blind” : “true”,“name” : “Cont1”}
Parameters:
- Contact ID : contact id from accounting system
- OrgPGID : organisation payment gateway id – you can find this in the URL when you edit the gateway. If you can’t find it please contact support.
- PGToken : Contact identifier with the gateway (e.g., Stripe customer token). Not all gateways use this value (especially upload gateways). Leave an empty string in this case.
- Suspended : flag to suspend the contact or not (Optional)
- Values : ref1, ref2, … in an array (Optional - used mainly for NZ or AU DD)
- Installments : { “inv_id” : [ [“date”, “amt”], [“date”, “amt”] ], “2nd_inv_id” : [“date”, “amt”] } installments for an invoice(s) – dates must be in yyyy-mm-dd format and amounts must add up the amount due; for a single-date installment don't forget the double brackets (e.g., [["2021-01-05","100.99"]]) (Optional)
- blind : flag to speed up the process by not performing all the usual validity tests (Optional)
- name : Contact name for reducing API to call accounting system to fetching the name if blind is true (Optional)
APIKey should be sent in the header.
If optional parameters are not supplied any existing data will be retained. To remove existing data you should send blank parameters.
Response:
- FAIL (response): if a fail code has been raised
- REPLACED: if OrgContact already existed
- OK: if OrgContact did not already exist
Send Invitation
Our Send Invite API allows you to request an invite to be sent to a customer.
Endpoint : SendInvite
URL : https://app.ucollect.biz/api/SendInvite
Example:
{
“ContactID” : “a4d48ba0-fd53-422d-95a1-6ea2dae05fe5”,
“OrgPGID” : [“2105″,”2051”],“email” : “test123@yopmail.com”}
Parameters:
- Contact ID : contact id from your accounting system
- OrgPGID : organisation payment gateway ids, (may be an array)
- email : Token of the gateway API
APIKey should be sent in the header. This is obtained from the Organisation Profile.
If optional parameters are not supplied any existing data will be retained. To remove existing data you should send blank parameters.
Response:
FAIL (response): if a fail code has been raised
OK: otherwise
Extension
The Extension API is used to obtain status data from uCollect about an Organisation, Contact or Invoice. No API key is required, but you must supply the Ledger name and a valid email address for a user in the organisation.
Organisation Status
Format:
Parameters:
Method: “organisation”
Ledger: The display name of the ledger – as seen in the Xero user interface. Replace spaces with %20
User: A valid email address for a user of the organisation
Format: “json” or “string”
Response:
- DUPLICATE ORGANISATION: a unique match between the ledger and user could not be made (i.e., two organisations were found for this LedgerName/User combo)
- NOT CONNECTED: no uCollect organisation exists for this ledgername (must have at least one PG to be deemed connected)
- CONNECTED: an organisation has been created in uCollect with at least one PG, but no PGs have PayNow enabled
- PAYNOW: an organisation has been created in uCollect with at least one PG, and at least one of the PGs has PayNow enabled
Invoice Status
Format:
Parameters:
Method: “invoice”
Contact_id: contact ID from accounting system (optional)
Invoice_id: invoice ID from accounting system
Ledger: The display name of the ledger – as seen in the Xero user interface. Replace spaces with %20
User: A valid email address for a user of the organisation
Format: “json” or “string”
Response:
- NOT CONNECTED: no uCollect organisation exists for this ledgername (must have at least one PG to be deemed connected)
- DUPLICATE ORGANISATION: a unique match between the ledger and user could not be made (i.e., two organisations were found for this LedgerName/User combo
- NOT ENABLED: if this contact does not have a PG attached
- CONTACT SUSPENDED: if this contact has a PG attached but the contact is suspended
- INVOICE SUSPENDED: if this contact has a PG attached but the invoice is suspended
- INSTALLMENTS (via PGName): if this contact has a PG attached (include the PG name in the response) but an installment plan has been created
- ENABLED (via PGName): if this contact has had a PG attached (include the PG name in the response) and none of the other scenarios apply
Contact Status
Format:
Parameters:
Method: “contact”
Contact_id: contact ID from accounting system
Ledger: The display name of the ledger – as seen in the Xero user interface. Replace spaces with %20
User: A valid email address for a user of the organisation
Format: “json” or “string”
Response:
- NOT CONNECTED: no uCollect organisation exists for this ledgername (must have at least one PG to be deemed connected)
- DUPLICATE ORGANISATION: a unique match between the ledger and user could not be made (i.e., two organisations were found for this LedgerName/User combo
- NOT ENABLED: if this contact has not had a PG attached
- CONTACT SUSPENDED: if this contact has a PG attached but the contact is suspended
- ENABLED (via PGName): if this contact has had a PG attached (include the PG name in the response) and none of the other scenarios apply
Pay Now URL
You don’t need an API call to generate the Pay Now URL. As long as you know the ContactID you can generate this.
Format: https://app.ucollect.biz/paynow/index/?org=[Ledger]&contactID=[Contact_ID]
Example: https://app.ucollect.biz/paynow/index/?org=!aYJhW&contactID=38ecc740-1d25-4135-b5c9-10140fe595f2 (link won’t work – just a sample)
You can get your generic PayNow URLs from your Edit, Organisation Settings page, Pay Now section.
Please note:
You must have Pay Enabled for at least one gateway in your uCollect organisation for this to work. You can’t yet restrict this to automatic or specific gateways (like an invite).
Parameters:
Contact_id: contact ID from accounting system
Ledger: The ShortID of the ledger – contact support to obtain this value