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”
}xample:

{

“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”

}

Parame

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)
• Suspended : flag to suspend the contact or not (Optional)
• Values : ref1, ref2, … in the array (Optional)
• 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 (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 : xero/Quickbooks contact id
• OrgPGID : organisation payment gateway ids, (may be an array)
• email : Token of the gateway API

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
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 ID and a valid email address for a user in the organisation.

Organisation Status

Format:

http://app.ucollect.biz/extension?method=organisation&ledger=xxxxx&user=zzzz@zzz.zz&format=json

Parameters:

Method: “organisation”
Ledger: The ShortID of the ledger – contact support to obtain this value
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:

http://app.ucollect.biz/extension?method=invoice&contact_id=7c913d33-39d5-4a1c-b8b1-e23f5fc999e0&invoice_id=a909dda4-555b-414b-a395-ba7a4077de72&ledger=xxxxx&user=zzzz@zzz.zz&format=json

Parameters:

Method: “invoice”
Contact_id: contact ID from accounting system (optional)
Invoice_id: invoice ID from accounting system
Ledger: The ShortID of the ledger – contact support to obtain this value
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 ENABLED: if this contact has not had 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:

http://app.ucollect.biz/extension?method=contact&contact_id=7c913d33-39d5-4a1c-b8b1-e23f5fc999e0&ledger=xxxxx&user=zzzz@zzz.zz&format=json

Parameters:

Method: “contact”
Contact_id: contact ID from accounting system
Ledger: The ShortID of the ledger – contact support to obtain this value
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 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)

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.