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

# Endpoints

> Interactive Merchant API endpoint playground.

Use the API playground below to test the authenticated profile endpoint. The generated endpoint pages in this section let you test every Merchant API endpoint from the OpenAPI reference.

## Authentication

Send your API key in the `x-api-key` header on every request.

Use `environment: sandbox` while testing. If the environment header is omitted, the request uses production.

## Endpoints covered

* `GET /v3/profile`
* `GET /v3/wallets`
* `GET /v3/wallet/{currency}`
* `POST /v3/collect`
* `POST /v3/transfer`
* `POST /v3/swap`
* `GET /v3/transactions`
* `GET /v3/transaction/{id}`
* `GET /v3/rates`

## Error codes

| Code  | Meaning                                                                                |
| ----- | -------------------------------------------------------------------------------------- |
| `400` | Invalid request data, unsupported currency, unsupported pair, or invalid phone number. |
| `401` | Missing or invalid API key.                                                            |
| `403` | Merchant profile or account context could not be resolved.                             |
| `404` | Requested wallet or resource was not found.                                            |
| `409` | `external_reference` already exists.                                                   |
| `500` | The request could not be processed.                                                    |


## OpenAPI

````yaml openapi.json GET /v3/profile
openapi: 3.1.0
info:
  title: Sarafa Merchant API
  summary: Enterprise API for Sarafa merchants.
  description: >-
    The Sarafa Merchant API is mounted under `/v3` and authenticated with a
    merchant API secret.
  version: 0.1.0
servers:
  - url: https://serviceapi.sarafa.ss
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Profile
  - name: Wallets
  - name: Money movement
  - name: Transactions
  - name: Rates
paths:
  /v3/profile:
    get:
      tags:
        - Profile
      summary: Get organization profile
      description: >-
        Returns the authenticated merchant organization profile and account
        number.
      operationId: getProfile
      parameters:
        - $ref: '#/components/parameters/EnvironmentHeader'
      responses:
        '200':
          description: Organization profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileResponse'
              example:
                status: success
                data:
                  organization:
                    name: Acme Ltd
                    description: Merchant account
                    slug: acme
                    logo_url: null
                    website_url: https://example.com
                  account_number: '9020260000001'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  parameters:
    EnvironmentHeader:
      name: environment
      in: header
      required: false
      description: Target environment. Defaults to `production` when omitted.
      schema:
        type: string
        enum:
          - production
          - sandbox
        default: production
  schemas:
    ProfileResponse:
      type: object
      required:
        - status
        - data
      properties:
        status:
          type: string
          enum:
            - success
        data:
          type: object
          required:
            - organization
            - account_number
          properties:
            organization:
              $ref: '#/components/schemas/Organization'
            account_number:
              type: string
    Organization:
      type: object
      required:
        - name
        - slug
      properties:
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        slug:
          type: string
        logo_url:
          type:
            - string
            - 'null'
          format: uri
        website_url:
          type:
            - string
            - 'null'
          format: uri
    ErrorResponse:
      type: object
      required:
        - status
        - message
      properties:
        status:
          type: string
          enum:
            - error
        message:
          type: string
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingApiKey:
              value:
                status: error
                message: API key is required
            invalidApiKey:
              value:
                status: error
                message: Invalid API key
    Forbidden:
      description: Organization or account context could not be resolved.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: error
            message: Organization account not found
    ServerError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: error
            message: Something went wrong. Request could not be processed
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Merchant API secret.

````