# Overview The Intermediaries Forex Settlement API allows Investec Intermediaries to: - Get, validate, and update their BOP (balance of payment) reports for foreign exchange transactions - Get and upload supporting documentation for a specified BOP report. - Get the forex allowance balance for a specified account number. # Authentication Decide which authentication route you will follow for your integration: - **OAuth 2**: Submit your API request in the context of your API key, client_id and client_secret - **3 Legged OAuth**: Submit your API requests in the context of an authorised user.

OAuth2.0

- Investec API authentication uses **OAuth 2.0 client credentials** (`client_id` and `client_secret`), with the addition of an `x-api-key`. - Log in to Investec Online to get your `client_id` and `client_secret` and to generate your `x-api key` with the scopes you require. **1. Get an access token** - To get an access token, you must exchange your `client_id`, `client_secret` and `x-api key` for the token. ```bash curl --location 'https://openapi.investec.com/identity/v2/oauth2/token' \ --header 'x-api-key: <>' \ --header 'Authorization: Basic <>' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' ``` **Headers explained:** - `x-api-key`: API key generated on Investec Online - `Authorization`: Base64-encoded `client_id:client_secret`. Take your `client_id` and `client_secret` and base64 encode them to provide a value for basic authorization. - `Content-Type`: Indicates the request body format **2. Use the token for all API requests** - Use the access token that you receive in all subsequent API requests - Access tokens are **valid for 30 minutes** and must be refreshed when expired ```bash curl --location 'https://openapi.investec.com/...' \ --header 'Authorization: Bearer <>' ``` **Notes** - Ensure your API key has the required scopes - you can set these when you create the key on Investec Online.

3 legged OAuth

You must be a registered third party to use 3 legged OAuth. You can apply on our Third Parties page

# Quickstart

View Quickstart (cURL)

This Quickstart walks you through making your first successful API call to the Investec Intermediaries API endpoints. We will use the sandbox to do this. To go live in production, you will need an approved intermediary relationship with Investec. By the end of this guide, you will: - Authenticate using OAuth 2.0 client credentials and an x-api key - Retrieve all BOP (Balance of Payment) reports that require documentation. **Before you start** Make sure you have the following: - You have enrolled for Investec Developer on Investec Online (not required if using Sandbox). - You have your client_id and client_secret from Investec Online and have created an API key (see Sandbox section for sandbox keys) - An API client such as Postman, cURL, or your own application code **Headers you will use on (almost) every call**: - **Authorization**: Bearer - **intermediaryId**: (required for most endpoints, you fetch it first) - **Content-Type**: application/json **Step 1: Get an access token (sandbox)** Sandbox: https://openapisandbox.investec.com. - To authenticate in the Sandbox environment, you are provided with a `client_id`, `client_secret`, and `x-api-key`. - The `client_id` and `client_secret` are combined and Base64 encoded to create the value used in the Authorization header as `Basic {base64_value}` — this encoded value is provided for you. - The `x-api-key` is sent as a separate header, and the request will return an `access_token`. - Sandbox credentials are available below in the Sandbox section. **Token request** ```bash curl --location 'https://openapisandbox.investec.com/identity/v2/oauth2/token' \ --header 'x-api-key: <>' \ --header 'Accept: application/json' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic <>' \ --data-urlencode 'grant_type=client_credentials' ``` **What this does** - Authenticates your application - Returns a short-lived access token called a bearer token (valid for 30 minutes) - Confirms your credentials and API key are valid **Successful response example** ```json { "access_token": "qwertyuiop123456789", "token_type": "Bearer", "expires_in": 1799, "scope": "accounts" } ``` **Step 2: Retrieve all BOP reports that require documentation** **Request** Specify the `DocsRequired` list type ```bash curl --location 'https://openapisandbox.investec.com/za/ifi/v1/forex/bop-reports?type=DocsRequired' \ --header 'Authorization: Bearer <>' \ --header 'Accept: application/json' ``` **Response** ```json { "data": [ { "reference": "lakkfi9mdkcc979h", "status": "DocsReceived", "valueDate": "2020-02-19", "currency": "GBP", "amount": "89357.09", "systemReference": "216d70e2-4c54-b5e6-d1ab-717214c40ee9", "tradeReference": "CORP2020012556688", "flow": "IN" }, { "reference": "twslzzlz3j97cnd1", "status": "DocsRequired", "valueDate": "2020-02-25", "currency": "ZAR", "amount": "93348.90", "systemReference": "84db466c-0cae-ef86-b2dc-1ff15dacd784", "tradeReference": "CORP2020072532484", "flow": "OUT" } ], "links": { "self": "https://openapisandbox.investec.com/za/ifi/v1/forex/bop-reports?type=DocsRequired" }, "meta": { "totalPages": 1 } } ``` # Sandbox

Sandbox access

**Base API URL**: https://openapisandbox.investec.com - To authenticate in the Sandbox environment, you are provided with a **client_id**, **client_secret**, and **x-api-key**. - The client_id and client_secret are combined and **Base64 encoded** to create the value used in the Authorization header as Basic {base64_value} — this encoded value is provided below for you. - The x-api-key is sent as a separate header, and the request will return an **access_token**. - Follow the [Quickstart](#Quickstart(cURL)) instructions to get going using the Sandbox **Sandbox credentials** | Field | Value | |-------|--------| | client_id | `gOUVQZoJ3AyTz22OHcIQAJJLzIG0Dy1Y` | | client_secret | `Rze5ccISF4mFrGek` | | x-api-key | `Z09VVlFab0ozQXlUejIyT0hjSVFBSkpMeklHMER5MVk6YVc1MlpYTjBaV010ZW1FdGFXWnBMV1p2Y21WNExXbHVkbVZ6ZEdWak0yeHZZUzF6WVc1a1ltOTQ=`| | Authorization | Basic `Z09VVlFab0ozQXlUejIyT0hjSVFBSkpMeklHMER5MVk6UnplNWNjSVNGNG1Gckdlaw==`| # Additional Guides

View known issues

Clarity on scenarios or field mapping confusion you might run into. **Report.locationCountry**: The location country field is to identify which country is involved in supplying/receiving a service or from which country goods were imported or to which country goods were exported. **Report. MonetaryAmount.locationCountry**: This indicates the country where the goods or services were procured or rendered. E.g. if importing from Germany it would be 'DE'. **Report.NonResident.Individual.Address.Country**: This cannot be 'ZA'. in cases where the actual value is ZA, using the country of the currency being paid is the correct approach. **Report.OriginatingCountry**: The country code of the originating bank (The bank from which the funds are being sent) **Report.ReceivingCountry**: The country code of the receiving bank (The bank to which the funds are being sent) **Report.Resident.Individual.TaxNumber**: We do run a SARS checksum validation on the TaxNumber provided. We will provide a warning (not an error) if the number provided does not validate successfully against the checksum. There are instances where a Tax number is valid but fails the checksum. **Report.counterpartyStatus**: This is the status of the Remitter or beneficiary (NonResident). The only valid values for this field are 'South African Resident' or 'Non Resident'.

Bulk Reporting

For bulk reporting you are required to have a SARB Authorisation Application Number. This enables you to report offshore payments without the need to onboard the underlying client (applicant) with Investec. Reporting: Submit a PUT request on the [Update a single BOP report](#tag/BOP-Reports/paths/~1za~1ifi~1v1~1forex~1bop-reports~1%7BtransactionReference%7D/put) endpoint: * Enhance the "resident" object of the payload with your applicant data * **report.monetaryAmount.sarbAuth.sarbAuthAppNumber** = {YOUR_SARB_AUTHORISATION_APPLICATION_NUMBER} * **report.monetaryAmount.sarbAuth.sarbAuthDate** = {SARB_AUTH_DATE} * **report.monetaryAmount.sarbAuth.sarbAuthRefNumber** = {YOUR_SARB_AUTHORISATION_REFERENCE_NUMBER} # Release Notes

Description of API changes

2025-04-11 * **Release**: Validate BOP and GET required documents without trnreference endpoints. 2024-02-14 * **Release**: Added Multiple Monetary Amounts allowing more than 1 sequence and SARB Authorization Code validation to allow for more Bulk reporting arrangements. Updated SDA forex allowances endpoint 2023-11-14 * **Release**: Added support for Bulk reporting with SARB Approval. This allows the resident (applicant) data to be submitted via the API when the required SARB approval is in place and recorded on Investec's systems 2023-07-07 * **Release**: Amended bop report request and response payloads to move the tax clearance certificate indicator to only the monetary amount section 2023-07-04 * **Release**: Updated bop report request payload 2022-07-28 * **Release**: First release deployed

Intermediaries Forex API