Using the Cohort Go "Bank Details" Javascript Component and our API, your end-to-end student refund process can be integrated directly into your own system.
Within your existing refund form, you'll embed our 'Bank Details' javascript component. This component handles all the work of collecting country appropriate bank details from your student, and returns you a simple key to be used when calling our API.
<script
type="text/javascript"
id="cohortgo-components"
data-partner="<your partner key>"
data-locale="en"
src="https://components.cohortgo.com/v1.js"
></script>
<form>
<!-- Your other form inputs go here -->
<div
data-cohortgo-component="bank-details"
data-name="refund_request[bank_details_key]"
data-value="<<Existing Key if editing>>"
></div>
<input type="submit">Request Refund</input>
</form>
Include the <script> tag once on your page to make the components available. In your form at the position you'd like the bank details capture to occur, insert the <div> tag. Use the data-name attribute to indicate the form field that you'd like the key stored in. If you're editing, or are restoring the page due to a validation error, please the previously provided key in the data-value attribute to allow editing of the pre-saved details.
Upon submission, the component will generate a key and add this to your form data. Store this key with your refund request, as it will be used later to make an API request.
After a user submits the form on your website and you've validated the rest of the form data on your side, you may wish to lock the bank details. This will prevent the user seeing or updating these details, even if they hold the key for the details.
For example, assuming that you'd previously received the key abc12345 as your bank_details_key using the javascript component, you would lock saved bank details by making a POST request to 'https://portal.cohortgo.com/api/v1/services/payments/outbound/payees/abc12345/lock.json'
Bank Details will then become only accessible via the authenticated API.
Bank details stored against a key can be retrieved at any time via the 'https://portal.cohortgo.com/api/v1/services/payments/outbound/payees/<key>.json' endpoint. Data returned via this endpoint will provide a user-presentable view of the details, ready to be rendered in a user facing interface.
For example, assuming that you'd previously received the key abc12345 as your bank_details_key using the javascript component, you would retrieve the saved bank details by making a GET request to 'https://portal.cohortgo.com/api/v1/services/payments/outbound/payees/abc12345.json'. This would return a response like:
{
"summary": [
["Account Name", "Foo Foo2"],
["Swift bic", "ICICIN2MXX"],
["IFSC", "ICIC000001"],
["Account number", "123123123"]
]
}
Create a payment using the Cohort Go platform API. The Book Remittance Request Endpoint enables this operation.
Assuming that you'd previously received the key abc12345 as your bank_details_key using the javascript component, you would generate a A$500 refund to a student by issuing a POST request with a payload like:
{
"remittance_request": {
"confirm": true,
"outward_payments": [{
"ccy": "AUD",
"amount": 500,
"reference": "my-local-reference",
"payee_key": "abc12345",
"account_reference": "Refund from provider A - S12345",
"outward_payment_type": "student_refund",
"fee_source": "ben",
"document": {"direct_upload_url": "http://example.org/document.pdf"},
"notification_url": "http://myapp.com/receive_status"
}]
}
}
If the original payment was paid with a payment method that is refundable; the customers bank details are not required so the payee_key can be omitted and the original_payment_reference used in it's place. The amount and currency of the payment will need to match the original transaction.
{
"remittance_request": {
"confirm": true,
"outward_payments": [{
"ccy": "AUD",
"amount": 500,
"reference": "my-local-reference",
"original_payment_reference": "CPS12345",
"account_reference": "Refund from provider A - S12345",
"outward_payment_type": "student_refund",
"fee_source": "ben",
"document": {"direct_upload_url": "http://example.org/document.pdf"},
"notification_url": "http://myapp.com/receive_status"
}]
}
}
Note that this request will need to be authenticated with API user credentials.
After submission of your remittance request, you'll receive a payment instructions document by email including the bank details to complete payment to, and a reference to include with your payment. Complete this payment with your bank, and Cohort Go will manage the payment of your international beneficiary.
Once the payment has been received (i.e. funds received) or completed (i.e. payment settled), you will be able to retrieve the proof of payment and payment confirmation documentation. The Book Remittance Request Endpoint enables this operation.
In the body of the response to creating the payment, you should have received a 'reference' (eg. "reference": "CPS00123456"). Use this reference to retrieve the details of the remittance request and it's associated outward payments 'https://portal.cohortgo.com/api/v1/services/payments/outbound/remittance_requests/CPS00123456'. The response should look something like the below.
{
"reference": "CPS00123456",
"status": "completed",
"outward_payments": [
{
"id": "SI00123456",
"state": "settled",
"funds_received_notification_url": "https://example.com/SI00123456/funds_received_notification.pdf",
"payment_confirmation_url": "https://example.com/SI00123456/payment_confirmation.pdf"
}
]
}
Note the outward_payments properties - funds_received_notification_url and payment_confirmation_url, you can use these URLs to retrieve the PDF documents for proof of payment and payment confirmation respectively. You can visit Retrieve Payment Instructions Endpoint or Retrieve Remittance Request Details Endpoint for more details.
For more details of these API endpoints, visit the API reference for Remittance Requests.
As above, these requests will need to be authenticated with API user credentials.