Booking Transactions via our API (for Agents)


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).

Introduction

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.

Process Flow

StudentYour WebsiteCohort GoInternational BankCreates an orderCreates an invoice describing the orderProvides an order identifierRequests payment methods for the invoiceAs part of your initial data collection,you'll need to collect a countrythey'll make payment from.Offers available payment methodsSelects Payment MethodRequests identity informationAs part of the payment method data,required identity details will beindicated by Cohort GoProvides Identity InformationBooks TransactionProvides transaction reference(Webhook) Provides link to payment instructionsEmails payment instructionsNotifies that funds are awaitingSends payment to Cohort GoStudentYour WebsiteCohort GoInternational Bank


Before You Begin

  1. Ensure you have set up API Authentication.
  2. Contact your Cohort Go account representative to ensure your account has been given access to the 'White Label API' feature.

Creating an Invoice

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 '<service-email@email.com>:<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"
}

Retrieving Payment Methods

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 '<service-email@email.com>:<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"
        }
      ]
    }
  ]
}

Collecting KYC Information

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.

Structuring Addresses

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 '<service-email@email.com>:<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.

Booking a Transaction

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 '<service-email@email.com>:<service-token>' \
  -d '{
    {
      "invoices": ["1234"],
      "payment_method": "method:1234",
      "rate_sig": "asdasd123asdasd",
      "student": {
        "email": "student@test.com",
        "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": "payer@test.com",
        "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"
    }
  }
}

Retrieving Transaction Details

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 '<service-email@email.com>:<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.

Receiving Transaction Updates

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 update
  • external_reference - Invoice reference number from agent's side

An example of this may look like:

curl \
  -u '<service-email@email.com>:<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:

  1. funds_received - Funds have been received from the student in a foreign currency
  2. settled - Funds have been paid to the institution or the education service provider as per invoice
  3. expired - Funds have not been received before expiry date
  4. cancelled - Transaction request has been cancelled

Funds Received Notification

For 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:

  • 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:

{
  "reference": "AUS123",
  "state": "settled",
  "transaction": "CPS1234",
  "amount": 5500.99,
  "cleared_funds": true
}

Expried Notification

For a expried notification, a payload would look like:

{
  "reference": "AUS123",
  "state": "expired",
  "transaction": "CPS1234",
  "amount": 5500.99,
}

Cancelled Notification

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;

Renewing a Transaction

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 '<service-email@email.com>:<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"
  }
}