> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fincode.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

Songhai Exchange(SHE) is Fincode's payment switching platform that facilitates cross-border transactions, enabling services such as bank transfers, mobile money payments, and wallet management across multiple currencies and countries.

## Base URL

All API requests for the staging environment should be sent to:

```bash theme={null}
https://api.stag.songhaiexchange.io
```

## Authentication

The API uses **OAuth2** for security.

1. **Generate Token**: Call the `POST /oauth/token` endpoint using Basic Authentication (Client ID and Secret) along with your username and password.
2. **Make Requests**: Use the returned `access_token` as a Bearer token in the `Authorization` header for all protected endpoints.

```http theme={null}
Authorization: Bearer <your_access_token>
```

## Transaction Reference (PCN)

Every transaction is identified by a unique **Reference Code** (often referred to as PCN). This code is generated by you (the partner) and must be unique for every request. It is used to:

* Track the status of a transaction.
* Reconcile payments.

## Reference Data

### Transaction Types

Use these values for the `transaction_type` field.

| Value                        | Description      |
| :--------------------------- | :--------------- |
| `AIRTIME_TOPUP`              | Airtime Top-up   |
| `ACCOUNTPAYMENT`             | Bank Transfer    |
| `ACCOUNTPAYMENT_DEBIT_CARD`  | Debit Card       |
| `ACCOUNTPAYMENT_CREDIT_CARD` | Credit Card      |
| `CASHPICKUP`                 | Cash Pickup      |
| `CURRENCY_CONVERTER`         | Bureau de Change |
| `CRYPTO_CURRENCY`            | Cryptocurrency   |
| `BILL_PAYMENT`               | Bill Payment     |
| `WALLET`                     | Wallet           |
| `MERCHANT_PRODUCT`           | Merchant Product |
| `MOBILE_MONEY`               | Mobile Money     |
| `MERCHANT_PAYMENT`           | Merchant Payment |

### Transaction Purposes

Use these values for the `transaction_purpose` field.

| Value                    | Description                   |
| :----------------------- | :---------------------------- |
| `FAMILY_SUPPORT`         | Family support                |
| `EDUCATION`              | Education                     |
| `GIFT_AND_DONATION`      | Gift and other donations      |
| `MEDICAL_TREATMENT`      | Medical treatment             |
| `MAINTENANCE_EXPENSES`   | Maintenance or other expenses |
| `TRAVEL`                 | Travel                        |
| `SMALL_VALUE_REMITTANCE` | Small value remittance        |
| `LIBERALIZED_REMITTANCE` | Liberalized remittance        |
| `OTHER`                  | Other purposes                |

### Beneficiary Relationships

Common values for `beneficiaryRelationship`: `FRIENDS`, `PARENTS`, `RELATIVES`, `SPOUSE`, `SIBLING`, `SELF`, `BUSINESS_PARTNER`, etc.

### Document Types

Documents required for KYC/Compliance.

| Value                        |
| :--------------------------- |
| Passport                     |
| National Id                  |
| Driving License              |
| Voter’s card                 |
| Proof of Address             |
| Customer declaration form    |
| Certificate of Incorporation |
| ... (and others)             |

### Response Statuses

The lifecycle status of a transaction.

| Status          | Description                                      | Lifecycle  |
| :-------------- | :----------------------------------------------- | :--------- |
| `SUCCESS`       | Instruction successfully received.               | Incomplete |
| `PAID`          | Successfully paid out to beneficiary.            | Completed  |
| `FAILED`        | Processed but unsuccessful.                      | Completed  |
| `PENDING`       | Sent to beneficiary bank, awaiting confirmation. | Incomplete |
| `READY_TO_CALL` | Queued to be sent to beneficiary bank.           | Incomplete |
| `PROCESSING`    | Queued for processing.                           | Incomplete |
| `CANCEL`        | Instruction canceled.                            | Completed  |
| `ERROR`         | Technical issue occurred.                        | Completed  |

### Response Codes

Specific error or success codes returned in `msg_code`.

| Code    | Status  | Description                        |
| :------ | :------ | :--------------------------------- |
| `00`    | PAID    | Paid successfully                  |
| `0000`  | PENDING | Awaiting processing                |
| `0001`  | FAILED  | Invalid Bank Account Number        |
| `0002`  | FAILED  | Recipient Contact Details Invalid  |
| `0005`  | FAILED  | Invalid Bank Code                  |
| `0030`  | FAILED  | Insufficient Funds                 |
| `0042`  | PENDING | Ready to Call (Queued)             |
| `50004` | FAILED  | Unknown Error / Transaction Failed |

### HTTP Status Codes

**Client Errors**

| Code  | Description                 |
| :---- | :-------------------------- |
| `400` | Bad Request                 |
| `401` | Unauthorized                |
| `403` | Forbidden                   |
| `404` | Not Found                   |
| `429` | Too Many Requests (implied) |

**Server Errors**

| Code  | Description           |
| :---- | :-------------------- |
| `500` | Internal Server Error |
| `502` | Bad Gateway           |
| `503` | Service Unavailable   |
| `504` | Gateway Timeout       |