NOTE: this guide is only relevant for Agents using the API - for information about booking transactions as a Provider see Booking Transactions via our API (for Providers).
For a truly white-label payments experience, your application can implement the Cohort Go payments API to collect all information from the customer and book a transaction from within your own application. Note that this is considered an advanced payment method as it requires significant implementation build and likely maintenance within your application. We highly recommend the Payment Buttons approach as a first approach for integration.
After you've identified what you're looking to bill the customer for, this information should be created as an invoice in the Cohort Go platform. An invoice should be added via the Agent Invoices Endpoint, omitting the details of the student.
An example of this may look like:
curl \
-u '<[email protected]>:<service-token>' \
-d '{
"invoice":{
"institution_name": "University of Melbourne",
"currency": "AUD",
"country":"AU",
"amount": 5500.99,
"document_upload_url":"http://some.host/invoice.pdf",
"retained_commission":55.00
}' \
-H "Content-Type: application/json" \
-XPOST \
https://demo.s.portal.cohortgo.com/api/v1/services/payments/agent_invoices.json
NOTE: If you like to use the 'retained_commission' field to set the commission amount to be retained - please contact your Cohort Go account representative to ensure your account is set up to do so.
This will respond with a payload like:
{
"institution_name": "University of Melbourne",
"currency": "AUD",
"amount": 5500.99,
"payment_reference": "invoice:1234",
"id": "S123456789"
}
After uploading your invoice, you'll need to query for available payment methods for the student's home country. This is achieved via the Payment Methods Endpoint. Along with the payment method data that is returned, the response will include details of the KYC information that you'll need to collect for the customer. To make this call, you'll need to have identified the student's home country (with ISO Alpha-2 country code) and the id of the previous invoice created. This information is used to determine both the amount payable and the currency paths that the payment will make.
Note that the payment methods include presentational information that will need to be displayed in your UI. Specifically, it will describe a short-form title, description and visual logos that should be included.
Assuming that you had previously uploaded an invoice with an id of 1234, then retrieving payment methods would look like:
curl \
-u '<[email protected]>:<service-token>' \
-H "Content-Type: application/json" \
https://demo.s.portal.cohortgo.com/api/v1/services/payments/payment_methods?origin_country=CO&invoices[]=1234
Note: addon_commission_rate - Optional parameter available in some markets. The commission rate being added to the payment amount, represented as basis points. Basis points are calculated by multiplying the percentage by 100, eg. 1% => 100 basis points, 2.5% => 250 etc. Please speak with your Cohort Go Account Manager to understand if this field can be enabled in your market.
This will respond with a payload like (abbreviated for clarity):
{
"expires": "string",
"methods": [
{
...
"identity_field_requirements": [
{
"field": "given_name",
"label": "string",
"required_for_student": "always",
"required_for_payer": "always",
"student_description": "string",
"payer_description": "string"
}
],
...
"documentation_requirements": [
{
"field": "passport",
"required_for_student": "always",
"required_for_payer": "always",
"student_description": "string",
"payer_description": "string"
}
]
}
]
}
The Payment Methods Endpoint response will include the identity_field_requirements and documentation_requirements properties for each payment method. These are different per payment method and based upon required KYC information. You will need to render the specified fields in your UI using the labels provided by the Cohort Go system (as the appropriate labelling of these are country and payment method dependent).
Note that a Cohort Go transaction requires both a student and payer to be specified. Only if the payer is the same as the student then the payer information can be ommitted.
Given the variation in address formatting globally, Cohort Go accepts different fields depending upon the student/payer's address country.
To retrieve the structuring and labelling for an address, using the Address Config Endpoint. This takes an ISO Alpha-2 country code, and returns the fields that are required from the standard Address set, along with the country sensitive labels to use.
Note that the address country passed for a student or payer does not need to be the same as the home country.
An example of retrieving an address config for India would be:
curl \
-u '<[email protected]>:<service-token>' \
-H "Content-Type: application/json" \
https://demo.s.portal.cohortgo.com/api/v1/addresses/IN
This would return a payload like:
"street_address": {
"label": "Street Address",
"visible": true,
"collection": null,
"required": true,
"hint": false
},
"locality": {
"label": "City/District",
"visible": true,
"collection": null,
"required": true,
"hint": false
},
"sub_locality": {
"label": "Locality/Village Name",
"visible": true,
"collection": null,
"required": true,
"hint": false
},
"sub_region": {
"label": "Sub region",
"visible": false,
"collection": null,
"required": false,
"hint": false
},
"postcode": {
"label": "PIN",
"visible": true,
"collection": null,
"required": true,
"hint": false
},
"region": {
"label": "State",
"visible": true,
"collection": [
[
"Andaman and Nicobar Islands",
"AN"
],
...
],
"required": true,
"hint": null
}
}
Note that not all fields are visible, some should utilise collections (dropdowns) for display, and the labels use local terminology.
After you've completed the collection of KYC, the transaction is ready to be booked via the Book Transaction Endpoint.
Note: to disable email notifications to student ensure the suppress_emails field is set to true.
An example of booking this transaction would look like:
curl \
-u '<[email protected]>:<service-token>' \
-d '{
{
"invoices": ["1234"],
"payment_method": "method:1234",
"rate_sig": "asdasd123asdasd",
"student": {
"email": "[email protected]",
"home_country": "CO",
"given_name": "Stu",
"family_name": "Dent",
"dob": "2000-02-17",
"passport_number": "M123123",
"passport_country": "CO",
"phone_number": "01123123213",
"national_identity_number": "123412",
"passport_url": "http://example.com/passport.pdf",
"supporting_documents": [],
"suppress_emails": true,
"address": {
"street_address": "12 Smith St",
"locality": "Medellin",
"region": "ME",
"postcode": "12345",
"country": "CO"
}
},
"payer": {
"email": "[email protected]",
"given_name": "Payer",
"family_name": "Dent",
"dob": "1970-02-17",
"phone_number": "1235123123",
"passport_country": "CO",
"supporting_documents": [],
"address": {
"street_address": "12 Smith St",
"locality": "Medellin",
"region": "ME",
"postcode": "12345",
"country": "CO"
}
},
"addon_commission_rate": 100
}' \
-H "Content-Type: application/json" \
-XPOST \
https://demo.s.portal.cohortgo.com/api/v1/services/payments/transactions.json
The response to this will include the payment reference (generally in the form CPSxxxx), and may include a payment instructions document, depending upon the output of the automated Cohort Go KYC procedures.
Note: addon_commission_rate - Optional parameter available in some markets. The commission rate being added to the payment amount, represented as basis points. Basis points are calculated by multiplying the percentage by 100, eg. 1% => 100 basis points, 2.5% => 250 etc. Please speak with your Cohort Go Account Manager to understand if this field can be enabled in your market.
If the payment method supports immediate payment (for example, Alipay or Unionpay in China), then the response payload will include an immediate_payment field that provides details for presenting a link to the student to complete their payment.
Links for making immediate payment will need to redirect to the provided url via GET or POST using a hidden form. If the params field is included as part of immediate_payment you will also need to include these paramaters as hidden form fields.
When a transfer form is required to complete payment a transfer_form field will be included in the transaction booking response. This is most common for payments in India that require completing an A2 Form.
You will need to provide the student with a link to download the form using the download_url and a way to upload the form to the upload_url once it has been completed. The field will also include a label and description to display in your UI.
An example of a transaction booking response with immediate payment might look like:
{
"reference": "CPS12345",
"payment_instructions_url": "https://example.com/payment_instructions.pdf",
"transfer_form": {
"label": "A2 Form",
"description": "Transfer form required when making payments in India",
"download_url": "https://example.com/a2_form.pdf",
"upload_url": "https://example.com/upload_transfer_form"
},
"immediate_payment": {
"url": "https://merchant.com/payment/request",
"method": "POST",
"params" {
"proc_code": "1234",
"process_code": "1234567",
"trans_date": "20200601",
"merchant_no": "1234567"
}
}
}
After a transaction has been booked, the details of a transaction can be queried by using the Get Transaction endpoint. The payment's due date will also be returned in the response. Assuming that you had previously booked a transaction with a resulting reference of CPS12345, then retrieving the transaction status would look like:
curl \
-u '<[email protected]>:<service-token>' \
-H "Content-Type: application/json" \
https://demo.s.portal.cohortgo.com/api/v1/services/payments/transactions/CPS12345
This will respond with something similar to:
{
"reference": "CPS12345",
"status": "awaiting_funds",
"due_date": "2022-01-20",
"payment_instructions_url": "https://example.com/payment_instructions.pdf",
"payment_proof_upload_url": "https://example.com/payment_proof_upload_url"
}
NOTE: If the transaction is not in the state awaiting_funds, then the additional URL attributes will not appear in the response.
The Cohort Go platform can notify your system of transaction updates if you want to keep track the progress. This can be set up by adding two new fields: notification_url and external_reference when creating an invoice via the Agent Invoices Endpoint. The updates will be delivered by a JSON POST request to the provided URL.
notification_url - Endpoint where you want to receive the updateexternal_reference - Invoice reference number from agent's sideAn example of this may look like:
curl \
-u '<[email protected]>:<service-token>' \
-d '{
"invoice":{
"institution_name": "University of Melbourne",
"currency": "AUD",
"country":"AU",
"amount": 5500.99,
"document_upload_url":"http://some.host/invoice.pdf",
"notification_url": "http://notify.test",
"external_reference": "AUS123"
}' \
-H "Content-Type: application/json" \
-XPOST \
https://demo.s.portal.cohortgo.com/api/v1/services/payments/agent_invoices.json
This will respond with a playload like:
{
"institution_name": "University of Melbourne",
"currency": "AUD",
"amount": 5500.99,
"notification_url": "http://notify.test",
"external_reference": "AUS123",
"payment_reference": "invoice:1234",
"id": "S123456789"
}
Transaction updates will be sent if the status has changed to:
funds_received - Funds have been received from the student in a foreign currencysettled - Funds have been paid to the institution or the education service provider as per invoiceexpired - Funds have not been received before expiry datecancelled - Transaction request has been cancelledFor a funds received notification, a payload would look like:
{
"reference": "AUS123",
"state": "funds_received",
"transaction": "CPS1234",
"amount": 5500.99,
"cleared_funds": true
}
Points of note in this notification:
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:
{
"reference": "AUS123",
"state": "settled",
"transaction": "CPS1234",
"amount": 5500.99,
"cleared_funds": true
}
For a expried notification, a payload would look like:
{
"reference": "AUS123",
"state": "expired",
"transaction": "CPS1234",
"amount": 5500.99,
}
For a expried notification, a payload would look like:
{
"reference": "AUS123",
"state": "cancelled",
"transaction": "CPS1234",
"amount": 5500.99,
}
For the fields in each of these notifications:
reference - reference number from agent's side for the payment being made;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;amount - the amount paid;If the transaction expires before payment is received then you can renew the transaction through the Renew Transaction Endpoint with a new rate signature retrieved from the Payment Methods Endpoint.
Assuming that you had previously booked a transaction with an id of CPS1234, then renewing a transaction would look like:
curl \
-u '<[email protected]>:<service-token>' \
-d '{
"rate_sig":"asdasd123asdasd"
}' \
-H "Content-Type: application/json" \
-X POST \
https://demo.s.portal.cohortgo.com/api/v1/services/payments/transactions/CPS1234/renew
A successful response will return the same content as when you booked the transaction. An example of this might look like:
{
"reference": "CPS1234",
"payment_instructions_url": "https://example.com/payment_instructions.pdf",
"transfer_form": {
"label": "A2 Form",
"description": "Transfer form required when making payments in India",
"download_url": "https://example.com/a2_form.pdf",
"upload_url": "https://example.com/upload_transfer_form"
}
}