> ## Documentation Index
> Fetch the complete documentation index at: https://developer.me-cash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Transaction

> Initiate a crypto-to-fiat (offramp) or crypto-to-crypto transaction using a quote

<Warning>
  🚧 **The Ramp API is currently under construction.** Endpoints and features described here are subject to change. Do not use in production until this notice is removed.
</Warning>

## Create Transaction

This endpoint executes a transaction (either off-ramp to fiat or crypto-to-crypto transfer) using a previously generated `quoteId`.

***

## Endpoint

`POST` `{{baseURL}}/v1/ramp/order`

***

## Headers

| **Header**     | **Value**          | **Required** | **Description**                          |
| -------------- | ------------------ | ------------ | ---------------------------------------- |
| `Content-Type` | `application/json` | Yes          | Specifies that the request body is JSON. |
| `x-api-key`    | `YOUR_API_KEY`     | Yes          | API key for authentication.              |

***

## Request Examples

### 1. Off-Ramp (Crypto-to-Fiat) Payout

This request sends cryptocurrency out of the wallet and initiates a bank payout to a fiat recipient.

<CodeGroup>
  ```bash cURL theme={null}
  curl --location '{{baseURL}}/v1/ramp/order' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
      "recipient": {
          "name": "Pastor Bright",
          "type": "BUSINESS",
          "account": {
              "accountNumber": "0867543789",
              "sortCode": "044"
          }
      },
      "quoteId": "3f41daaa-029c-44a2-b7c6-ed922a68177b",
      "reason": "Gift",
      "remark": "thanks"
  }'
  ```

  ```js JavaScript (fetch) theme={null}
  const payload = {
    recipient: {
      name: "Pastor Bright",
      type: "BUSINESS",
      account: {
        accountNumber: "0867543789",
        sortCode: "044"
      }
    },
    quoteId: "3f41daaa-029c-44a2-b7c6-ed922a68177b",
    reason: "Gift",
    remark: "thanks"
  };

  fetch('{{baseURL}}/v1/ramp/order', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify(payload)
  })
  .then(res => res.json())
  .then(console.log)
  .catch(console.error);
  ```
</CodeGroup>

### 2. Crypto-to-Crypto Transfer

This request converts or transfers assets directly to an external blockchain wallet address.

<CodeGroup>
  ```bash cURL theme={null}
  curl --location '{{baseURL}}/v1/ramp/order' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
      "recipient": {
          "symbol": "USDC",
          "blockchain": "MATIC-AMOY",
          "address": "0xd62acd62fdb155afaa5d12c6caf01119d413dfd9"
      },
      "quoteId": "59628a6c-3d05-406a-ad39-77f92b09137c",
      "reason": "Test",
      "remark": "Check"
  }'
  ```

  ```js JavaScript (fetch) theme={null}
  const payload = {
    recipient: {
      symbol: "USDC",
      blockchain: "MATIC-AMOY",
      address: "0xd62acd62fdb155afaa5d12c6caf01119d413dfd9"
    },
    quoteId: "59628a6c-3d05-406a-ad39-77f92b09137c",
    reason: "Test",
    remark: "Check"
  };

  fetch('{{baseURL}}/v1/ramp/order', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify(payload)
  })
  .then(res => res.json())
  .then(console.log)
  .catch(console.error);
  ```
</CodeGroup>

***

## Request Body Breakdown

| **Field**                         | **Type** |  **Required** | **Description**                                            |
| --------------------------------- | -------- | :-----------: | ---------------------------------------------------------- |
| `quoteId`                         | string   |      Yes      | The UUID of the quote returned from the `/quote` endpoint. |
| `reason`                          | string   |      Yes      | Purpose of the transaction (e.g. `"Salary"`, `"Gift"`).    |
| `remark`                          | string   |       No      | Additional comments/memo.                                  |
| `recipient`                       | object   |      Yes      | Recipient details depending on type.                       |
| `recipient.name`                  | string   | Yes (offramp) | Full name of the beneficiary.                              |
| `recipient.type`                  | string   | Yes (offramp) | Recipient type (`"INDIVIDUAL"`, `"BUSINESS"`).             |
| `recipient.account.accountNumber` | string   | Yes (offramp) | Bank account number.                                       |
| `recipient.account.sortCode`      | string   | Yes (offramp) | Bank sort code.                                            |
| `recipient.address`               | string   |  Yes (crypto) | Wallet address.                                            |
| `recipient.blockchain`            | string   |  Yes (crypto) | Target blockchain network.                                 |
| `recipient.symbol`                | string   |  Yes (crypto) | Target cryptocurrency symbol.                              |

***

## Success Response (Off-Ramp) 201 Created

```json theme={null}
{
    "message": "order successfully created",
    "status": "success",
    "data": {
        "id": "80709a38-1e22-40f2-ad05-ac181f611531",
        "type": "SEND",
        "category": "OFF_RAMP",
        "state": "PENDING",
        "referenceNumber": "XXEYBAHUJORQB",
        "quote": {
            "id": "54728dcf-650d-4eb5-994f-95a060677487",
            "source": {
                "currency": "USDC",
                "symbol": "USDC",
                "type": "CRYPTOCURRENCY",
                "amount": 5,
                "network": {
                    "id": "f8fc48ff-81e6-4b5f-9a70-44fb744e3572",
                    "name": "Polygon Amoy",
                    "blockchain": "MATIC-AMOY"
                }
            },
            "target": {
                "currency": "NGN",
                "country": "NG",
                "type": "FIAT",
                "paymentChannel": "BANK_TRANSFER",
                "amount": 5537.1
            },
            "rate": 0.000903,
            "fees": [
                {
                    "amount": 0.025,
                    "gas": {
                        "type": "MEDIUM",
                        "total": 0.29237925
                    }
                }
            ],
            "summary": {
                "total": 5.31737925
            }
        },
        "recipient": {
            "id": "95475698-61d2-46ee-b148-b882956a0eff",
            "name": "Pastor Bright",
            "type": "BUSINESS",
            "account": {
                "sortCode": "044",
                "accountNumber": "0867543789"
            }
        },
        "created": "2025-06-03T22:56:20.748484620"
    }
}
```

***

## Success Response (Crypto-to-Crypto) 201 Created

```json theme={null}
{
    "message": "order successfully created",
    "status": "success",
    "data": {
        "id": "da0ab3cd-a608-4b0a-8de5-710112e2cb06",
        "type": "SEND",
        "category": "CRYPTOCURRENCY",
        "state": "PENDING",
        "referenceNumber": "PENUHSL7PRXEF",
        "quote": {
            "id": "6d70f89d-bc23-45c1-8504-d805ccd22235",
            "source": {
                "currency": "USDC",
                "symbol": "USDC",
                "blockchain": "MATIC-AMOY",
                "type": "CRYPTOCURRENCY",
                "amount": 2
            },
            "target": {
                "currency": "USDC",
                "symbol": "USDC",
                "blockchain": "MATIC-AMOY",
                "type": "CRYPTOCURRENCY",
                "amount": 2
            },
            "rate": 1,
            "fees": {
                "amount": 0.01,
                "gas": {
                    "type": "LOW",
                    "amount": 0.01875321
                }
            },
            "summary": {
                "total": 2.02875321
            }
        },
        "recipient": {
            "id": "962aabb8-f74e-4e1f-aab1-99467b9cf3b5",
            "address": "0xd62acd62fdb155afaa5d12c6caf01119d413dfd9",
            "network": {
                "id": "f8fc48ff-81e6-4b5f-9a70-44fb744e3572",
                "name": "USDC",
                "blockchain": "MATIC-AMOY"
            }
        },
        "created": "2025-06-04T12:04:00.817316767"
    }
}
```

***

## Error Responses

| **HTTP Status** | **Error Code**  | **Message**                | **Description**                                           |
| --------------- | --------------- | -------------------------- | --------------------------------------------------------- |
| 400             | `INVALID_INPUT` | Invalid request payload    | Required parameters are missing or formatted incorrectly. |
| 401             | `UNAUTHORIZED`  | Missing or invalid API key | The `x-api-key` header is missing or incorrect.           |
| 422             | `QUOTE_EXPIRED` | Stale quote                | The quote associated with the `quoteId` has expired.      |
| 500             | `SERVER_ERROR`  | Internal server error      | An unexpected error occurred on the server.               |


## OpenAPI

````yaml post /v1/ramp/order
openapi: 3.0.3
info:
  title: meCash API
  version: 3.0.3
  description: >-
    API for meCash services, including FIAT and Ramp operations. This is the
    OpenAPI specification for the meCash API, covering all available endpoints
    for wallet management, currency quotes, and payouts.


    It follows a design-first approach based on OpenAPI 3.0.


    Authentication is handled via an API key passed in the `x-api-key` header.
    Replace `YOUR_API_KEY` with your actual key when making requests.


    Some useful links:

    - [meCash Documentation](https://docs.me-cash.com/)

    - [Authentication Guide](https://docs.me-cash.com/authentication)
servers:
  - url: https://sandboxapi.me-cash.com
    description: Sandbox Server for Testing
security:
  - ApiKeyAuth: []
tags:
  - name: Wallet
    description: Wallet management operations
  - name: Quote
    description: Currency quote operations
  - name: Payout
    description: Payout operations
  - name: Transaction
    description: Transaction management
  - name: Virtual Account
    description: Virtual account operations for static and dynamic accounts
  - name: Bank
    description: Bank account and list operations
  - name: Ramp
    description: Ramp operations for crypto
  - name: Miscellaneous
    description: Utility and miscellaneous operations
  - name: Collection
    description: Mobile money and wallet funding operations
  - name: Bulk Payout
    description: >-
      Bulk transfer operations for sending to multiple beneficiaries in a single
      request
paths:
  /v1/ramp/order:
    post:
      tags:
        - Ramp
      summary: Create Transaction
      description: >-
        Executes a transaction (either off-ramp to fiat or crypto-to-crypto
        transfer) using a previously generated quoteId. Takes parameters in
        multipart/form-data: transaction (JSON object string) and optional
        invoice (file).
      operationId: createRampOrder
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - transaction
              properties:
                transaction:
                  type: string
                  description: JSON string representing the transaction payload.
                  example: >-
                    {"recipient":{"name":"Pastor
                    Bright","type":"BUSINESS","account":{"accountNumber":"0867543789","sortCode":"044"}},"quoteId":"3f41daaa-029c-44a2-b7c6-ed922a68177b","reason":"Gift","remark":"thanks"}
                invoice:
                  type: string
                  format: binary
                  description: Optional invoice file (PDF).
      responses:
        '201':
          description: Order successfully created.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/RampOfframpOrderResponse'
                  - $ref: '#/components/schemas/RampCryptoOrderResponse'
        '401':
          $ref: '#/components/responses/PayoutUnauthorized'
        '422':
          description: Unprocessable entity. For example, if the quote has expired.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: error
                  message:
                    type: string
                    example: quote expired
        '500':
          $ref: '#/components/responses/PayoutInternalServerError'
components:
  schemas:
    RampOfframpOrderResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: order successfully created
        data:
          type: object
          properties:
            id:
              type: string
              format: uuid
              example: 80709a38-1e22-40f2-ad05-ac181f611531
            type:
              type: string
              example: SEND
            category:
              type: string
              example: OFF_RAMP
            state:
              type: string
              example: PENDING
            referenceNumber:
              type: string
              example: XXEYBAHUJORQB
            quote:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  example: 54728dcf-650d-4eb5-994f-95a060677487
                source:
                  type: object
                  properties:
                    currency:
                      type: string
                      example: USDC
                    symbol:
                      type: string
                      example: USDC
                    type:
                      type: string
                      example: CRYPTOCURRENCY
                    amount:
                      type: number
                      example: 5
                    network:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                          example: f8fc48ff-81e6-4b5f-9a70-44fb744e3572
                        name:
                          type: string
                          example: Polygon Amoy
                        blockchain:
                          type: string
                          example: MATIC-AMOY
                target:
                  type: object
                  properties:
                    currency:
                      type: string
                      example: NGN
                    country:
                      type: string
                      example: NG
                    type:
                      type: string
                      example: FIAT
                    paymentChannel:
                      type: string
                      example: BANK_TRANSFER
                    amount:
                      type: number
                      example: 5537.1
                rate:
                  type: number
                  example: 0.000903
                fees:
                  type: array
                  items:
                    type: object
                    properties:
                      amount:
                        type: number
                        example: 0.025
                      gas:
                        type: object
                        properties:
                          type:
                            type: string
                            example: MEDIUM
                          total:
                            type: number
                            example: 0.29237925
                summary:
                  type: object
                  properties:
                    total:
                      type: number
                      example: 5.31737925
            recipient:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  example: 95475698-61d2-46ee-b148-b882956a0eff
                name:
                  type: string
                  example: Pastor Bright
                type:
                  type: string
                  example: BUSINESS
                account:
                  type: object
                  properties:
                    sortCode:
                      type: string
                      example: '044'
                    accountNumber:
                      type: string
                      example: '0867543789'
            created:
              type: string
              example: '2025-06-03T22:56:20.748484620'
    RampCryptoOrderResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: order successfully created
        data:
          type: object
          properties:
            id:
              type: string
              format: uuid
              example: da0ab3cd-a608-4b0a-8de5-710112e2cb06
            type:
              type: string
              example: SEND
            category:
              type: string
              example: CRYPTOCURRENCY
            state:
              type: string
              example: PENDING
            referenceNumber:
              type: string
              example: PENUHSL7PRXEF
            quote:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  example: 6d70f89d-bc23-45c1-8504-d805ccd22235
                source:
                  type: object
                  properties:
                    currency:
                      type: string
                      example: USDC
                    symbol:
                      type: string
                      example: USDC
                    blockchain:
                      type: string
                      example: MATIC-AMOY
                    type:
                      type: string
                      example: CRYPTOCURRENCY
                    amount:
                      type: number
                      example: 2
                target:
                  type: object
                  properties:
                    currency:
                      type: string
                      example: USDC
                    symbol:
                      type: string
                      example: USDC
                    blockchain:
                      type: string
                      example: MATIC-AMOY
                    type:
                      type: string
                      example: CRYPTOCURRENCY
                    amount:
                      type: number
                      example: 2
                rate:
                  type: number
                  example: 1
                fees:
                  type: object
                  properties:
                    amount:
                      type: number
                      example: 0.01
                    gas:
                      type: object
                      properties:
                        type:
                          type: string
                          example: LOW
                        amount:
                          type: number
                          example: 0.01875321
                summary:
                  type: object
                  properties:
                    total:
                      type: number
                      example: 2.02875321
            recipient:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  example: 962aabb8-f74e-4e1f-aab1-99467b9cf3b5
                address:
                  type: string
                  example: '0xd62acd62fdb155afaa5d12c6caf01119d413dfd9'
                network:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      example: f8fc48ff-81e6-4b5f-9a70-44fb744e3572
                    name:
                      type: string
                      example: USDC
                    blockchain:
                      type: string
                      example: MATIC-AMOY
            created:
              type: string
              example: '2025-06-04T12:04:00.817316767'
    PayoutFailedResponse:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message.
        status:
          type: string
          example: failed
      required:
        - message
        - status
  responses:
    PayoutUnauthorized:
      description: Unauthorized. The provided API key is invalid or missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PayoutFailedResponse'
          example:
            message: Invalid API key
            status: failed
    PayoutInternalServerError:
      description: Internal Server Error. The server failed to process the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PayoutFailedResponse'
          example:
            message: Server failed to process request.
            status: failed
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````