# Pay Third-parties using JikoNet

JikoNet allows you to transact at high volumes with third-parties directly between Jiko pockets, with 24/7 secure real-time settlement, underpinned by T-bills, ensuring safety and generating yield until the time of payment for the payor and from the time of collection for the payee.

**Important: in API calls, JikoNet is named `on-us`.**

## Create a Recipient

### Business Goal

To initiate a JikoNet payment, you must first create the counterparty, referred to as the "Recipient" in Jiko's UI. You are responsible for gathering the necessary payment information (the Recipient's legal business name and Jiko Network Address) directly from the counterparty outside of the Jiko system.

### Business Workflow Example

Customer systems:

1. Gather from the counterparty the Legal business name and the Jiko Network Address (example: "123456789012") of the destination Jiko pocket. The counterparty will find it under "`Transfers` > `Receive money` > `Jiko network details`" in the Jiko UI.
2. Send to Jiko a counterparty creation API request, providing this counterparty pocket's name and network address.
3. Receive from Jiko the unique Jiko ID assigned to this counterparty.
4. Associate this Jiko Id with the counterparty in customer's payment origination systems.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | Post the creation of a JikoNet counterparty, using the endpoint fields corresponding to case #2 CreateOnUsCounterpartyRequest. Where field `account_number` represents the Jiko Network Address. The response returns a `UUID`. | POST [`/api/v2/counterparties/`](/products/customer-api/reference/counterparties-v2/create-counterparty-v2) |


## Submit a JikoNet Transfer request

### Business Goal

Send funds instantly (upon the approval of the transfer request) from a JikoNet-enabled pocket to a third-party's pocket. Note: not all pockets are connected to JikoNet.

### Business Workflow Example

Customer systems:

1. Get from Jiko the list of pockets with their enabled payment rails, to identify which of your pockets are connected to JikoNet.
2. Get from Jiko the balance of JikoNet-enabled pockets.
3. Choose which pocket to debit.
4. Get from Jiko the list of the counterparties connected to JikoNet.
5. Initiate a payment request, specifying the recipient, payment amount, and remittance details, as well as an internal transaction id.
6. Send the transfer request to Jiko.
7. Confirm successful posting of the payment transaction to the payment origination system.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | If not already known, get the list of your pockets for which the `ON_US` (JikoNet) payment rail is enabled: pockets where `payment_rails` includes `ON_US`. | GET [`/api/v1/portals/`](/products/customer-api/reference/portals/list_customer_portals_api_v1_portals__get) |
| 2 | Get the balance of JikoNet-enabled pockets. See also [Get the Current Balance for a Pocket or Group of a pockets](/products/customer-api/use-cases/manage-pockets-and-balances#get-the-current-balance-for-a-pocket-or-group-of-a-pockets). | GET [`/api/v2/pockets/{pocket_id}/`](/products/customer-api/reference/pockets-v2/get_customer_pocket_api_v2_pockets__pocket_id___get) |
| 3 | Get the list of the counterparties connected to JikoNet. They are identified through `type` = `on_us`. | GET [`/api/v2/counterparties/`](/products/customer-api/reference/counterparties-v2/list-counterparties-v2) |
| 4 | Create a new transfer request, for: • #1 CreateOnUsTransfer • #0 CreatePeerToPeerTransfer | POST [`/api/v1/transfer-requests/`](/products/customer-api/reference/transfer-requests/create_transfer_request_api_v1_transfer_requests__post) |


## Cancel a JikoNet Transfer request

### Business Goal

Allow to cancel a previously submitted transfer request before it is completed. To stop transfers that were submitted in error, require correction, or are no longer needed.

### Business Workflow Example

Customer systems:

1. Identify the submitted transfer request that needs to be canceled.
2. Verify that the transfer is still eligible for cancellation (still pending).
3. Call Jiko's transfer cancellation endpoint with the transfer identifier.
4. Confirm that the Jiko transfer status has been updated to "Cancelled".
5. Update internal systems or user interfaces to reflect the canceled transfer.
6. Log the cancellation action for audit and reconciliation purposes.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | Retrieve a filtered list of transfer requests, to obtain the Jiko ID of the transfer request to cancel, if the "transfer.id" is not already known. | GET [`/api/v1/transfer-requests/`](/products/customer-api/reference/transfer-requests/get_transfer_requests_api_v1_transfer_requests__get) |
| 2 | Cancel the transfer request, identified its "transfer.id". | DELETE [`/api/v1/transfer-requests/{transfer_id}/`](/products/customer-api/reference/transfer-requests/cancel_transfer_request_api_v1_transfer_requests__transfer_id___delete) |
| 3 | Get the status of this transfer request, to check that it was changed to "CANCELED". | GET [`/api/v1/transfer-requests/{transfer_id}/`](/products/customer-api/reference/transfer-requests/get_transfer_request_api_v1_transfer_requests__transfer_id___get) |


## Approve a JikoNet Transfer request

### Business Goal

Review and approve or deny transfer requests, through API or the UI. In the current version, approval is mandatory. A future version will offer the flexibility to customize the number of required approval levels.

### Business Workflow Example

Customer systems:

1. Submit a transfer request in Jiko.
2. Get from Jiko the list of the Jiko users with a "Checker" role.
3. Or get the list of the checker users specifically designated for a given transfer request.
4. Notify approvers.
5. Collect the approval decision.
6. Record the approval decision in Jiko.
7. Monitor the execution status of the transfer.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | Get a list of transfer requests to be approved: transactions with `status` = `UNDER_REVIEW`. | GET [`/api/v1/transfer-requests/`](/products/customer-api/reference/transfer-requests/get_transfer_requests_api_v1_transfer_requests__get) |
| 2a | Get the list of all the active Jiko users having a "Checker" role. | GET [`/api/v1/transfer-requests/reviewers/`](/products/customer-api/reference/transfer-requests/get_transfer_request_reviewers_api_v1_transfer_requests_reviewers__get) |
| 2b | Or get the list of the checker users specifically designated for a given transfer request, listed in field "reviewers" for this transfer request. | GET [`/api/v1/transfer-requests/{transfer_id}/`](/products/customer-api/reference/transfer-requests/get_transfer_request_api_v1_transfer_requests__transfer_id___get) |
| 3 | Approve or reject the request, using one of the following status values:• #1 `APPROVED` • #4 `REJECTED` In the case of a reject, optionally choose a Denial reason and transmit a Denial memo text. | PATCH [`/api/v1/transfer-requests/{transfer_id}/status/`](/products/customer-api/reference/transfer-requests/update_transfer_request_status_api_v1_transfer_requests__transfer_id__status__patch) |


### Illustration

PATCH [`/api/v1/transfer-requests/{transfer_id}/status/`](/products/customer-api/reference/transfer-requests/update_transfer_request_status_api_v1_transfer_requests__transfer_id__status__patch):


```json
{
 "status": "APPROVED"
}
```

## Retrieve the Status of a JikoNet Transfer

### Business Goal

Enable payment and treasury teams to maintain real-time visibility and control over payments, by continuously tracking execution status, detecting issues, and ensuring payments are completed successfully.

### Business Workflow Example

Customer systems:

1. Query the payment status at defined intervals using the transfer identifier.
2. Interpret the returned status to understand where the payment is in the execution lifecycle.
3. Handle exceptions by detecting `DENIED` or `REJECTED` statuses and reviewing associated error codes or messages.
4. Trigger internal downstream actions (ERP posting, invoice update, beneficiary notification) based on the final execution outcome.
5. Record the final payment state in the payment origination system and metadata for audit, reporting, and compliance purposes.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1a | Get the status of a specific transfer request identified by its Jiko `id`. | GET [`/api/v1/transfer-requests/{transfer_id}/`](/products/customer-api/reference/transfer-requests/get_transfer_request_api_v1_transfer_requests__transfer_id___get) |
| 1b | Or get a list of transfer requests filtered by status (and optionally by other filtering parameters). | GET [`/api/v1/transfer-requests/`](/products/customer-api/reference/transfer-requests/get_transfer_requests_api_v1_transfer_requests__get) |


## Receive notifications of changes in a JikoNet payment status (webhook)

### Business Goal

Enable real-time notifications of payment status changes via webhooks, allowing to track payment progress instantly, automate downstream processes, and respond quickly to exceptions. By eliminating repetitive polling and manual checks, it improves operational efficiency.

### Business Workflow Example

Customer systems:

1. Register a webhook endpoint URL with the platform, including a shared secret when creating the webhook subscription.
2. Configure the event types or payment statuses to receive.
3. Listen for incoming webhook notifications in real time.
4. Verify each notification's authenticity and integrity.
5. Retrieve in the event payload the Jiko id of the processed data.
6. Get from Jiko additional data related to this id if needed.
7. Process the event by updating internal systems or triggering workflows.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | Create a new webhook subscription to receive real-time notifications for specified events. Event types for outgoing JikoNet transfers are: • `transfers.on-us.out.processing` • `transfers.on-us.out.success` • `transfers.on-us.out.rejected` Event types for incoming JikoNet transfers are: • `transfers.on-us.received` Available events for a given subscription can also be retrieved using GET [`/api/v1/events/`](/products/customer-api/reference/events/get_events_api_v1_events__get). | POST [`/api/v1/subscriptions/`](/products/customer-api/reference/subscriptions/create_subscription_api_v1_subscriptions__post) |


## List historical JikoNet payments

### Business Goal

Retrieve a filtered list of payment transactions, enabling efficient approval, reconciliation, and reporting based on relevant criteria such as status and reviewer.

### Business Workflow Example

Customer systems:

1. Define filter criteria (status, reviewer).
2. Submit the query request to Jiko with the selected filters.
3. Handle pagination or cursors for large result sets.
4. Receive and parse the response payload.
5. Process or store the data for notification, reconciliation, or reporting.
6. Repeat queries as needed to retrieve updated or incremental results.


### Relevant API Endpoints

| Step | Purpose | Jiko API Endpoints |
|  --- | --- | --- |
| 1 | Get a filtered list of transfers. | GET [`/api/v1/transfer-requests/`](/products/customer-api/reference/transfer-requests/get_transfer_requests_api_v1_transfer_requests__get) |