NOTE: this guide is only relevant for Providers using the API - for information about booking transactions as an Agent see Booking Transactions via our API (for Agents).
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 Provider Invoices Endpoint. You can include the details of the student or just use student_number is fine.
An example of this may look like:
curl \
-u '<[email protected]>:<service-token>' \
-d '{
"invoice":{
"student_number":"12341234",
"reference":"ABC1234",
"amount":500.05,
"description":"Initial Deposit",
"document_upload_url":"http://some.host/invoice.pdf"
}' \
-H "Content-Type: application/json" \
-XPOST \
https://demo.s.portal.cohortgo.com/api/v1/services/payments/provider_invoices.json
This will respond with a payload like:
{
"id": "SI1234",
"state": "uploaded",
"payment_remitted": "2021-08-19",
"document_link": "https://example.com/document/doc.pdf",
"payment_url": "https://payments.cohortgo.com/r/aBasc2as"
}
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 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
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 would be:
curl \
-u '<[email protected]>:<service-token>' \
-H "Content-Type: application/json" \
https://demo.s.portal.cohortgo.com/api/v1/addresses/IN.json
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",
"suppress_emails": true,
"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": [],
"address_details": {
"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_details": {
"street_address": "12 Smith St",
"locality": "Medellin",
"region": "ME",
"postcode": "12345",
"country": "CO"
}
}
}' \
-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.
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.
As the transactions progresses, the Cohort Go platform will notify your system of transaction updates. These will be delivered by a JSON POST request to the the endpoint configured when you setup your Inbound Domain.
Included in this request payload will be a payment_instructions_url to retrieve the payment instructions for the customer.
Transaction updates will be sent in the following order:
awaiting_funds - Waiting to receive funds from student via the selected payment methodfunds_received - Funds have been received from the student in a foreign currencysettled - Funds have been sent domestically to the partner's bank accountFor 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,
"payment_instructions_url": "https://example.com/payment_instructions.pdf"
}
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",
"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;payment_instructions_url - url to the payment instructions document for the student to make paymentfingerprint - an authenticity fingerprint for the message. Calculated as hex(sha1(timestamp '|' secret '|' invoice '|' transaction '|' amount))Note the above fingerprint is generated using a secret configured on your Inbound Domain.
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"
}
}