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.
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:
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 [email protected], then you'd have a URL like https://sample-provider.cohortgo.app?r=X1234&a=500&[email protected].
See it in action:
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:
Settings.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.
| Field | Explanation |
|---|---|
| required_fields | Fields are required(*). The information need to be in the response. |
| optional_fields | Fields are optional, it can be ignored. |
| account_reference | The 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']
}
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:
complete and cancel parameters should not be included in these;expires parameter. The expires will be checked and must be greater than the current time. See https://en.wikipedia.org/wiki/ISO_8601#Timessecret parameter set to the secret you have registered with Cohort Gofingerprint param with your requestFor example, with the following parameters:
| Field | Example |
|---|---|
a[tuition] | 5000 |
a[services] | 200 |
r | INV123451 |
Add the expires & secret:
| Field | Example |
|---|---|
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:
| Field | Example |
|---|---|
fingerprint | 919353961a02408b3ce2e9bfd6435947408fa5b4 |
expires | 2019-01-01T01:00:00Z |
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:
| Field | Key | Description | Example |
|---|---|---|---|
| Completion URL | complete | A URL to return to when the payment flow has been completed. | ?complete=http://app.example.com |
| Cancel URL | cancel | A URL to return to if the flow encounters an issue or the user attempts to cancel. | ?cancel=http://app.example.com |
| Reference | r | A reference number/text for the payment that will be provided in later reconciliation. | ?r=INV123451 |
| Amount | a | Specify a total amount. Only used if breakdown fields aren't specified. | ?a=5000 |
| Breakdown Amount | a[<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 |
e | The student's email address. | [email protected] | |
| Home Country | hc | The 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:
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:
| Field | Key | Description | Example |
|---|---|---|---|
| Completion URL | complete | A URL to return to when the payment flow has been completed. A cps URL param will be included. | ?complete=http://app.example.com |
| Cancel URL | cancel | A 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 |
| Reference | r | A reference number/text for the payment that will be provided in later reconciliation. | ?r=INV123451 |
| Amount | a | Specify a total amount. Only used if breakdown fields aren't specified. | ?a=5000 |
| Currency | ccy | The 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 Amount | da | Specify 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 Amount | a[<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 Name | in | The name of the institution. | ?in=Learning Centre |
| Invoice Type | it | The type of invoice. Must be one of [tuition, living_expenses, accommodation_fees, guardian_fees, other]. | ?it=living_expenses |
| Invoice Document URL | doc | A 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 Number | sn | The student's id number, assigned by the institution. | ?sn=12345678 |
| Completion Date | cd | The 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 |
e | The student's email address. | [email protected] | |
| Home Country | hc | The 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 Name | gn | The student's given name. | ?gn=Albert |
| Family Name | fn | The student's family name. | ?fn=Smith |
| Date of Birth | dob | The student's date of birth in ISO 8601 format. See https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates | ?dob=1999-11-26 |
| Phone Number | p | The student's phone number. | ?p=861083410308 |
| Passport Country | pc | The 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 Number | pn | The student's passport number. | ?pn=M1234567 |
In cases where the payer is not the same as the student, you are also able to populate their details:
| Field | Key | Description | Example |
|---|---|---|---|
pe | The payers's email. | [email protected] | |
| Given Name | pgn | The payers's given name. | ?pgn=George |
| Family Name | pfn | The payers's family name. | ?pfn=Smith |
| Date of Birth | pdob | The payers's date of birth in ISO 8601 format. See https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates | ?pdob=1999-11-26 |
| Phone Number | pp | The payers's phone number. | ?pp=861083410308 |
| Passport Country | ppc | The 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 Number | ppn | The payers's passport number. | ?ppn=M1234567 |
See it in action:
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:
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,
"cleared_funds": true
}
Points of note in this notification:
amount field may be lower than the original requested amount;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.For a completion notification, a payload would look like:
{
"invoice": "INV0001",
"state": "settled",
"transaction": "CPS12341234",
"timestamp": "20171120023800",
"amount": 500.0,
"refundable": false,
"fingerprint": "7e240de74fb1ed08fa08d38063f6a6a91462a815"
}
For the fields in each of these notifications:
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.
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.POST made to your notification endpoint.POST made to your notification endpoint.