Pay with Cohort Go directly from your website


Introduction

Add a 'Pay with Cohort Go' button to the end of your shopping cart journey will enable a seamless handover from your cart directly through a Cohort Go payment. Through this flow, you can pass a variable amount of information depending upon how much you'd like to customise the student experience.

Process Flow

StudentYour WebsiteCohort GoInternational BankYour BankClicks on the "Pay with Cohort Go Button"Button directs student to Cohort Go sitewith pre-configured payment details.Navigates to Cohort Go Payments site and books payment.Cohort Go requests relevant information from student andprovides local payment details.Notifies that funds are awaitingSends payment to Cohort GoNotifies payment receiptMatches paymentNotifies that funds have been receivedConverts funds to domestic currencySends batch fundsNotifies that funds have been remitted to your bankStudentYour WebsiteCohort GoInternational BankYour Bank

Redirect to the Cohort Go Payment Page

To initiate a payment, you'll need an Inbound Domain configured in your Cohort Go portal that manages your banking details and notification preferences. This inbound domain will have a URL like https://sample-provider.cohortgo.app.

Assuming that you've generated a reference and amount as part of your flow, then you'll want to pass that through to the button. This is done by adding ?r=<reference>&a=<amount> parameters to your url. For example, if you had a reference of X1234 and amount of $500, then you'd have a URL like https://sample-provider.cohortgo.app?r=X1234&a=500.

See it in action:

Pay with Cohort Go

Fields that are passed through are locked in to avoid your students from being able to edit the details. Should you want a pre-filled field to be editable, this can be done by prefixing an underscore _ to the front of the parameter; ?r=<reference>&a=<amount>&_e=<student.email>. In this case, students can choose to change the email into their preferred email address. For example, if you had a reference of X1234, amount of $500 and student email john.smith@teststudent.com, then you'd have a URL like https://sample-provider.cohortgo.app?r=X1234&a=500&_e=john.smith@teststudent.com.

See it in action:

Pay with Cohort Go

Auto-fill student identity information

The customer (inbound provider) can now customize their verify_identity page by auto-prefiling/disabling the fields in the identity page when users making transactions through their payment portal.

To set them up:

  1. In the Cohort Go Portal, select Settings.
  2. Search for Inbound Domains and navigate to it.
  3. Click the 'Edit' button on the inbound domain that you'd like to pre-fill identity information for.
  4. Provide the URL of a publicly accessible endpoint that the Cohort Go platform can send a POST request to to retrieve identity details.

The Cohort Go platform will make a POST request to the provided URL. The payload will contain a list of required fields, optional fields, and the account reference entered by the customer.

FieldExplanation
required_fieldsFields are required(*). The information need to be in the response.
optional_fieldsFields are optional, it can be ignored.
account_referenceThe reference of the person, eg: student number

The payload we are sending:

  {
    required_fields: ['given_name', 'family_name'],
    optional_fields: ['tax_identity_number'],
    account_reference: 'stu123'
  } 

Example Response:

This will auto-prefill the given_name and family_name of the person in the identity page.

  {
    'given_name': 'Lorem',
    'family_name': 'Ipsum'
  }

To disable/lock fields:

You will need to select/include the fields into params, _locked. If you want to disable/lock given_name or family_name field.

Example Response:

The identity page will auto-prefill the given_name and family_name fields. Both of them will be disabled since they are included in params, _locked.

  {
    'given_name': 'Lorem',
    'family_name: 'Ipsum',
    '_locked': ['given_name', 'family_name']
  }

Passing more information

Fingerprint verification

To ensure the integrity of the information passed, you can register a secret with Cohort Go and use that to generate a fingerprint that you send with your requests. This fingerprint will be validated by Cohort Go when your request is received.

To generate the fingerprint:

  1. Collect all the parameters you intend to send to Cohort Go
  2. Optionally add an ISO 8601 formatted expires parameter. The expires will be checked and must be greater than the current time. See https://en.wikipedia.org/wiki/ISO_8601#Times
  3. Add the secret parameter set to the secret you have registered with Cohort Go
  4. Sort all the parameters you are sending, alphabetically by key
  5. Format these parameters into a query string
  6. Create a hash of the complete query string using SHA-256. See https://en.wikipedia.org/wiki/SHA-2
  7. This is the fingerprint, include it in a fingerprint param with your request

For example, with the following parameters:

FieldExample
a[tuition]5000
a[services]200
rINV123451

Add the expires & secret:

FieldExample
expires (optional)2019-01-01T01:00:00Z
secret (do not send with request)secret-value

Sort the parameters alphabetically by key, and format them as a query string: a%5Bservices%5D=200&a%5Btuition%5D=5000&r=INV123451&secret=secret-value&expires=2019-01-01T01%3A00%3A00Z

Use the SHA-1 algorithm to hash the query string: 8768b72ac0dbff5af9f5c6c58d34129c0fc642ecc9b98323c68a16faba720fb1

And pass the result as a fingerprint parameter with your request to Cohort Go, along with the expires parameter if you used one:

FieldExample
fingerprint919353961a02408b3ce2e9bfd6435947408fa5b4
expires2019-01-01T01:00:00Z
URL GET

If your cart has additional information available, this can also be passed through to the payment page via the link.

Specifically, the following fields are the full options that can be sent in a GET query string:

FieldKeyDescriptionExample
Completion URLcompleteA URL to return to when the payment flow has been completed.?complete=http://app.example.com
Cancel URLcancelA URL to return to if the flow encounters an issue or the user attempts to cancel.?cancel=http://app.example.com
ReferencerA reference number/text for the payment that will be provided in later reconciliation.?r=INV123451
AmountaSpecify a total amount. Only used if breakdown fields aren't specified.?a=5000
Breakdown Amounta[<code>]Specify an amount in broken down components. Use the key configured on the inbound domain to reference a field.?a[tuition]=5000&a[services]=200
EmaileThe student's email address.?e=user@example.org
Home CountryhcThe student's home country, used to drive the payment options available to the student. Specified as an ISO Alpha-2 country code. See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 for a catalogue of codes.?hc=CN

See it in action:

Pay with Cohort Go

FORM POST

If your system has already captured most of the details of a student, you can jump directly to the payment method selection page by submitting these details as a Form POST.

Specifically, the following fields are the full options that can be sent as a POST:

FieldKeyDescriptionExample
Completion URLcompleteA URL to return to when the payment flow has been completed. A cps URL param will be included.?complete=http://app.example.com
Cancel URLcancelA URL to return to if the flow encounters an issue or the user attempts to cancel. A reason and msg URL param will be included. Reasons include user_initiated, invalid_fingerprint and missing_param?cancel=http://app.example.com
ReferencerA reference number/text for the payment that will be provided in later reconciliation.?r=INV123451
AmountaSpecify a total amount. Only used if breakdown fields aren't specified.?a=5000
CurrencyccyThe currency of the invoice, i.e. the currency of the Amount field, in ISO 4217 format. See https://en.wikipedia.org/wiki/ISO_4217?ccy=BRL
Display AmountdaSpecify the amount in the institution’s invoice. This amount will be shown in the payment confirmation sent to student which informs them we’ve paid to the relevant institutions.?da=1000
Breakdown Amounta[<code>]Specify an amount in broken down components. Use the key configured on the inbound domain to reference a field.?a[tuition]=5000&a[services]=200
Institution NameinThe name of the institution.?in=Learning Centre
Invoice TypeitThe type of invoice. Must be one of [`tuition`, `living_expenses`, `accommodation_fees`, `guardian_fees`, `other`].?it=living_expenses
Invoice Document URLdocA PDF or image version of the invoice, e.g. a scan of the original invoice. This document will be attached to the payment.?doc=http://example.org/invoice001.png
Student NumbersnThe student's id number, assigned by the institution.?sn=12345678
Completion DatecdThe date the student will complete their study, in ISO 8601 format. See https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates?cd=2030-11-25
EmaileThe student's email address.?e=user@example.org
Home CountryhcThe student's home country, used to drive the payment options available to the student. Specified as an ISO Alpha-2 country code. See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 for a catalogue of codes.?hc=CN
Given NamegnThe student's given name.?gn=Albert
Family NamefnThe student's family name.?fn=Smith
Date of BirthdobThe student's date of birth in ISO 8601 format. See https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates?dob=1999-11-26
Phone NumberpThe student's phone number.?p=861083410308
Passport CountrypcThe student's passport country. Specified as an ISO Alpha-2 country code. See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 for a catalogue of codes.?pc=CN
Passport NumberpnThe student's passport number.?pn=M1234567
Payer Details

In cases where the payer is not the same as the student, you are also able to populate their details:

FieldKeyDescriptionExample
EmailpeThe payers's email.?pe=payer@example.com
Given NamepgnThe payers's given name.?pgn=George
Family NamepfnThe payers's family name.?pfn=Smith
Date of BirthpdobThe payers's date of birth in ISO 8601 format. See https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates?pdob=1999-11-26
Phone NumberppThe payers's phone number.?pp=861083410308
Passport CountryppcThe payers's passport country. Specified as an ISO Alpha-2 country code. See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 for a catalogue of codes.?ppc=CN
Passport NumberppnThe payers's passport number.?ppn=M1234567

See it in action:

Invoice Details

Student Details

Payer Details

Redirect URLs

Opening the Payment Cart in an iframe

To prevent the user being directed away from your domain, the Cohort Go UI can be displayed in an <iframe> tag. There are many jQuery based libraries that can assist with this. For example, the Featherlight jQuery plugin can enable this based purely upon data attributes:

<script src="//code.jquery.com/jquery-latest.js"></script>
<script src="//cdn.rawgit.com/noelboss/featherlight/1.7.13/release/featherlight.min.js" type="text/javascript" charset="utf-8"></script>
<link href="//cdn.rawgit.com/noelboss/featherlight/1.7.13/release/featherlight.min.css" type="text/css" rel="stylesheet" />

<a href="https://devsite-demo.demo.s.chrtpy.com?r=X1234&a=4000" style="display: inline-block; padding: 5px 10px 2px 10px; background-color: #324A87; color: white; border-radius: 5px" data-featherlight="iframe" data-featherlight-iframe-height="800" data-featherlight-iframe-width="1000">Pay with Cohort Go</a>

See it in action:

Pay with Cohort Go

Notifications

The Cohort Go system can notify your 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 an endpoint configured when you set up your Inbound Domain. For an awaiting funds notification, a payload would look like the following:

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

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

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

For a completion notification, a payload would look like:

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

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 awaiting_funds, 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;
  • refundable - if the transaction can be refunded directly via Cohort Go without requiring return bank details for the customer;
  • fingerprint - an authenticity fingerprint for the message. Calculated as hex(sha1(timestamp '|' secret '|' invoice '|' transaction '|' amount))

Note in the above fingerprint property that we use a secret to generate this. This secret is similarly configured on your Inbound Domain.

Testing Notifications

  1. Before you begin: Request a 'Demo' account from your Cohort Go account representative, and use that to login here so that the links we provide take you to the right place.
  2. Visit your Inbound Domains and edit the domain in your account. Add a Notification URL that points to an endpoint available publicly that can receive POST request, and a Signing Secret to use to authenticate calls from Cohort Go.
  3. Create a test payment via your test subdomain - you'll see the link in the 'Subdomain' column of your Inbound Domains list.
  4. Visit your Inbound Payments page to see your new payment. Click on the payment to visit the detail page.
  5. Click 'Apply Funds' to simulate funds being received by Cohort Go. You should see a POST made to your notification endpoint.
  6. Click 'Settle Funds' to simulate funds being paid from Cohort Go to your account. You should see a POST made to your notification endpoint.