Creating Payment Requests via our API


Introduction

Your CRM already knows a lot of about your students, so instead of requiring all the student and destination information to be manually re-entered, the Cohort Go Payment Request API can be used to copy this information across and deliver a student or counsellor directly to a payment experience where they only need to finalise the payment.

Process Flow

Student/CounsellorYour CRMCohort GoCreates a student record containing basic student informationProvides a student identitiferCreate invoice for studentProvides invoice identitiferCreate payment request for studentProvide payment request payment linkProvides payment request link to complete paymentVisits Cohort Go website to select payment method and complete paymentStudent/CounsellorYour CRMCohort Go


Creating a Student

Basic details about the student completing the payment need to be provided to create a student record. This is done via the Create Student Endpoint.

An example of this may look like:

curl \
  -u '<api-user-email@cohortgo.com>:<api-user-token>' \
  -d '{
    "student":{
       "title": "Mr",
       "given_name": "John",
       "family_name": "Smith",
       "gender": "male",
       "email": "user@example.com",
       "home_country": "CN",
       "destination_country": "AU",
       "dob": "1990-05-20",
       "mobile": "61 412 123 123",
       "passport_number": "A1231234",
       "passport": {"url": "https://passport.example.com"}
    }' \
  -H "Content-Type: application/json" \
  -XPOST \
  https://demo.s.portal.cohortgo.com/api/v1/students.json

This will respond with a payload like:

{
  "id": 12345,
  "portal_url": "https://demo.s.portal.cohortgo.com/students/12345"
}

Managing Student Custom Data

If you have custom data configured for your students, you are able to pass in an additional object property when creating or updating a student record. This property additional_information can contain key value pairs for the custom data you wish to create for the student.

You can access your custom data configuration via the Settings -> Custom Data menu. Please speak with your Cohort Go Account Manager to understand how you can set up custom data configurations for your students.

An example of setting custom data may look like:

curl \
  -u '<api-user-email@cohortgo.com>:<api-user-token>' \
  -d '{
    "student":{
       "title": "Mr",
       "given_name": "John",
       "family_name": "Smith",
       "gender": "male",
       "email": "user@example.com",
       "home_country": "CN",
       "destination_country": "AU",
       "dob": "1990-05-20",
       "mobile": "61 412 123 123",
       "passport_number": "A1231234",
       "additional_information": {
         "referral-source": "Facebook"
       }
    }' \
  -H "Content-Type: application/json" \
  -XPOST \
  https://demo.s.portal.cohortgo.com/api/v1/students.json

This will respond with a payload like:

{
  "id": 12345,
  "portal_url": "https://demo.s.portal.cohortgo.com/students/12345",
  "additional_information": {
    "referral-source": "Facebook"
  }
}

Preparing your Invoice Document

We require a copy of the student's invoice or offer document to be uploaded alongside the invoice. If you have a publicly accessible copy of your document (perhaps with a secret URL) to provide in the next step, then this can be skipped.

If you do not have your document available, then the following can be used to store it temporarily in our S3 uploads bucket.

Retrieve an upload slot

Use the Retrieve File Upload Endpoint to retrieve a temporary URL to store the file at. For example:

curl \
  -u '<api-user-email@cohortgo.com>:<api-user-token>' \
  https://demo.s.portal.cohortgo.com/api/v1/files/request_upload_endpoint.json

This will respond with a payload like:

{
  "url": "https://cohortflow-assets.s3.amazonaws.com/uploads/2cb8e337-eb2a-48aa-a08a-3bced130ff05",
  "upload_params": {
    "AWSAccessKeyId": "123123",
    "Expires": "1234567890",
    "Signature": "098098098",
    "x-amz-acl": "public-read"
  }
}

Upload the file

Add all of the upload_params onto the end of the url, and perform a PUT:

curl \
  -XPUT \
  -T myfile.pdf \
  'https://cohortflow-assets.s3.amazonaws.com/uploads/2cb8e337-eb2a-48aa-a08a-3bced130ff05?AWSAccessKeyId=123123&Expires=1234567890&Signature=098098098&x-amz-acl=public-read'

Use the URL

The URL (without any parameters) from above can be used in the document_upload_url field in the Creating an Invoice step below.

Creating an Invoice

After the student record has been created, an invoice needs to be created for each destination that needs to be paid (eg, university, school, service provider). Either a single or multiple invoices can be created at this stage for a student to pay.

The Create Invoice Endpoint is used to create this invoice.

An example of this may look like:

curl \
  -u '<api-user-email@cohortgo.com>:<api-user-token>' \
  -d '{
      "invoice": {
        "institution_name": "University of Melbourne",
        "document_upload_url": "https://cohortflow-assets.s3.amazonaws.com/uploads/2cb8e337-eb2a-48aa-a08a-3bced130ff05?sig=abc123",
        "currency": "AUD",
        "amount": 12000.81
      }' \
  -H "Content-Type: application/json" \
  -XPOST \
  https://demo.s.portal.cohortgo.com/api/v1/students/{student_id}/services/payments/invoices.json

This will respond with a payload like:

{
  "institution_name": "University of Melbourne",
  "currency": "AUD",
  "amount": 12000.82,
  "payment_reference": "invoice:1234"
}

The important value here is the payment_reference which is the identifier that will be used when creating the payment request.

Creating the Payment Request

After all relevant invoices have been created, a payment request can be used to collect the invoices and send to a student or counsellor for payment.

The Create Payment Request endpoint is used to create this.

An example of this may look like:

curl \
  -u '<api-user-email@cohortgo.com>:<api-user-token>' \
  -d '{
    "payment_request": {
      "description": "Tuition Deposit and OSHC for enrolment at University of Melbourne",
      "invoice_payment_references": [
        "invoice:1234",
        "oshcaustralia:OSHC1234512345"
      ]
    }
  }' \
  -H "Content-Type: application/json" \
  -XPOST \
  https://demo.s.portal.cohortgo.com/api/v1/students/{student_id}/services/payments/payment_requests.json

This will respond with a payload like:

{
  "description": "Tuition Deposit and OSHC for enrolment at University of Melbourne",
  "link": "https://cohortpay.com/r/abc123",
  "reference": "WX22JKWML",
  "invoices": [
    {
      "institution_name": "University of Melbourne",
      "document_upload_url": "https://cohortflow-assets.s3.amazonaws.com/uploads/2cb8e337-eb2a-48aa-a08a-3bced130ff05?sig=abc123",
      "currency": "AUD",
      "amount": 12000.82,
      "payment_reference": "invoice:1234"
    }
  ]
}

The link field included here can be provided to the student or counsellor to finalise the booking of the payment. The reference can be retained for later to track status updates on this request.