Payments Cart Integration API

Introduction

The Cohort Go payments platform enables third-party providers to directly a link to Cohort Go Payments on their payment page. This link enables seamless transfer of customer details to Cohort Go where they will be able to finalise their payment.

Initial Configuration

To establish an external integration, Cohort requires the following information:

  • Receiving Bank Account Details
    • any invoice created via the integration will have fixed banking details applied.
  • Update Notification Endpoint
    • an endpoint that can will receive notification when funds are received by Cohort, and when they are remitted to the partner's bank account.
  • Agree a pre-shared secret
    • communication between endpoints is secured using fingerprints based upon a pre-shared secret. This will in the form of a randomly generated 20 character string.

Payment Form

A payment is initiated by having the user perform a POST request to https://payments.cohortgo.com/invoice. Generally, we would expect this this to be driven by a "Pay with Cohort Go" button on the partner's payment page.

A sample form to drive this button might look like:

  <form action="https://payments.cohortgo.com/invoice" method="POST">
    <input name="partner" type="hidden" value="example-partner" />
    <input name="locale" type="hidden" value="en" />
    <input
      name="cancel_url"
      type="hidden"
      value="http://example.com/app/INV0001/cancel"
    />
    <input
      name="completion_url"
      type="hidden"
      value="http://example.com/app/INV0001/completed"
    />
    <input name="timestamp" type="hidden" value="20171120031112" />
    <input
      name="fingerprint"
      type="hidden"
      value="8cb2237d0679ca88db6464eac60da96345513964"
    />
    <input name="email" type="hidden" value="[email protected]" />
    <input name="given_name" type="hidden" value="First" />
    <input name="family_name" type="hidden" value="Last" />
    <input name="dob" type="hidden" value="2000-01-01" />
    <input name="phone1" type="hidden" value="0412123123" />
    <input name="home_country" type="hidden" value="CN" />
    <input name="passport_country" type="hidden" value="CN" />
    <input name="passport_number" type="hidden" value="M1231234" />
    <input name="invoice" type="hidden" value="INV00001" />
    <input name="description" type="hidden" value="Tuition Deposit" />
    <input name="due" type="hidden" value="2017-11-30" />
    <input name="amount" type="hidden" value="500.0" />
    <input
      name="document_url"
      type="hidden"
      value="http://example.com/invoices/doc.pdf"
    />
    <button type="submit">Pay with Cohort Go</button>
  </form>

The hidden fields included in this can be broken down into a 3 distinct sections. Setting up the integration, providing details of the customer and providing details of the invoice.

For setting up the integration:

  • partner - a unique identifier allocated to you by Cohort when we enable the partner's integration;
  • locale - the language that the Cohort Go interface should be presented in. If an appropriate value for this is not known, specify ‘en’;
  • cancel_url - a URL that the Cohort Go system should redirect the user back to if they cancel the payment;
  • completion_url - a URL that the Cohort Go system should redirect the user to when the payment is completed/initiated (noting that payment may not be completed at this point, only that the user initiated and received payment instructions);
  • timestamp - a UTC timestamp in the form YYYYmmddHHMMss representing the current time;
  • fingerprint - a fingerprint calculated as hex(sha1(timestamp '|' secret '|' invoice '|' amount)) (where amount is formatted as XXX.XX);

For the student details:

  • email - the student's email address. Used to send the student payment instructions and updates on the status of their payment;
  • given_name - the student's first/given name;
  • family_name - the student's family/last name;
  • dob - the student's date of birth, in ISO8601 format;
  • phone1 - the student's phone number, ideally with IDD prefix;
  • home_country - the student's "home country". This is used to determine the payment options provided to the student;
  • passport_country - the country of the student's passport;
  • passport_number - the student's current passport number;

For the invoice details:

  • invoice - a unique identifier allocated to the invoice that will be used in communication between the Cohort Go system and partner's system;
  • description - a description of the invoice. Shown throughout the Cohort Go UI as well as on any payment instructions that we issue;
  • due - the date that the invoice is due, in ISO8601 formatting;
  • amount - the amount payable on the invoice, in the currency of the partner (eg, AUD);
  • document_url - a URL for retrieving a PDF document for the invoice. Cohort Go requires an official invoice to present to relevant authorities in markets with controlled currencies;

API Endpoints

Successful integration with the Cohort Go payments system requires the implementation of a number of API endpoints.

Notifications

The Cohort Go system can notify a partner system when funds are received in a foreign currency, as well as when funds have been sent domestically to the partner's bank account. This notification is delivered as a JSON POST to a pre-agreed endpoint (the Update Notification Endpoint established during the setup).

Funds Received Notification

For a funds received notification, a payload would look like:

    {
      "invoice": "INV0001",
      "state": "funds_received",
      "transaction": "CPS12341234",
      "timestamp": "20171120023800",
      "fingerprint": "7e240de74fb1ed08fa08d38063f6a6a91462a815",
      "amount": 500.0,
      "cleared_funds": true
    }

Points of note in this notification:

  • If you have agreed with Cohort Go to accept short payments, then the amount field may be lower than the original requested amount;
  • The cleared_funds field will be false in cases where Cohort Go still needs to complete a process of clearing funds with local regulators. It may be possible in these cases that additional information might be needed from the customer to finalise the payment, or further that the payment may need to be cancelled. It is recommended that if you are performing immediate processes based upon a funds_received notification that these processes wait until a "cleared_funds": true value is received. If an initial notification is sent with "cleared_funds": false, then an updated notification will be sent with "cleared_funds": true once this process completes. In some circumstances such as delivery failures, it may be possible that a settled notification will be sent first - in this case, it can be safely assumed that funds did clear.

Settled Notification

For a completion notification, a payload would look like:

    {
      "invoice": "INV0001",
      "state": "settled",
      "transaction": "CPS12341234",
      "timestamp": "20171120023800",
      "fingerprint": "7e240de74fb1ed08fa08d38063f6a6a91462a815",
      "amount": 500.0
    }

For the fields in each of these notifications:

  • invoice - the invoice reference, as provided initially when requesting the payment;
  • state - the state of the invoice - will be one of funds_received or settled;
  • transaction - the Cohort Go internal reference for the payment being made. This can be treated as a unique reference for a given payment;
  • timestamp - a timestamp for this message (used as part of the fingerprint);
  • amount - the amount paid;
  • fingerprint - an authenticity fingerprint for the message. Calculated as hex(sha1(timestamp '|' secret '|' invoice '|' transaction '|' amount))