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

# Payments

> Create hosted checkout payments, verify payment status, and retrieve payment details.

## The payment object

A payment represents a single charge initiated by a customer. Payments are created via the API and completed through Orafi's hosted checkout flow.

<ResponseField name="id" type="string">
  Unique identifier for the payment.
</ResponseField>

<ResponseField name="depositAddress" type="string">
  On-chain address the customer sends funds to.
</ResponseField>

<ResponseField name="amount" type="number">
  Payment amount in NGN (the currency the merchant specified).
</ResponseField>

<ResponseField name="amountInUSDC" type="number">
  Equivalent amount in USDC at the time of creation.
</ResponseField>

<ResponseField name="redirectUrl" type="string">
  URL the customer is redirected to after payment.
</ResponseField>

<ResponseField name="checkoutUrl" type="string">
  Orafi-hosted checkout page URL. Redirect your customer here to complete payment.
</ResponseField>

<ResponseField name="status" type="string" default="INITIALIZED">
  Current payment status. One of `INITIALIZED`, `CONFIRMED`, or `FAILED`.
</ResponseField>

<ResponseField name="token" type="string" default="USDC">
  Token used for the payment. Currently always `USDC`.
</ResponseField>

<ResponseField name="refunded" type="boolean" default="false">
  Whether this payment has been refunded.
</ResponseField>

<ResponseField name="paymentMethod" type="string">
  How the payment was initiated. One of `PAYMENT_LINK` or `HOSTED_CHECKOUT`.
</ResponseField>

<ResponseField name="txRef" type="string">
  Merchant-supplied transaction reference. Acts as an idempotency key.
</ResponseField>

<ResponseField name="transactionId" type="string">
  ID of the parent transaction record.
</ResponseField>

<ResponseField name="paylinkId" type="string">
  Paylink that initiated this payment, if applicable.
</ResponseField>

<ResponseExample>
  ```json The payment object theme={null}
  {
    "id": "cmjfu1cjv0003v8vsmmxgjk05",
    "depositAddress": "0x871cf48ff1847e7a...55c2d3",
    "amount": 4000,
    "amountInUSDC": 2.53,
    "redirectUrl": "https://yourapp.com/payment/complete",
    "checkoutUrl": "https://checkout.orafi.app/pay/cmjfu1cjv0003v8vsmmxgjk05",
    "status": "INITIALIZED",
    "token": "USDC",
    "refunded": false,
    "paymentMethod": "HOSTED_CHECKOUT",
    "txRef": "order_12345",
    "transactionId": "cmjfu1cjv0002v8vsabc12345",
    "paylinkId": null
  }
  ```
</ResponseExample>

### Transaction sub-object

When retrieving a [Transaction](/api-reference/endpoint/transactions) with `type: "PAYMENT"`, the payment appears as a nested `payment` sub-object with these fields:

<ResponseField name="id" type="string">
  Unique identifier for the payment.
</ResponseField>

<ResponseField name="token" type="string" default="USDC">
  Token used for the payment.
</ResponseField>

<ResponseField name="refunded" type="boolean" default="false">
  Whether this payment has been refunded.
</ResponseField>

<ResponseField name="depositAddress" type="string">
  On-chain address the customer sent funds to.
</ResponseField>

<ResponseField name="txRef" type="string">
  Merchant-supplied transaction reference (idempotency key).
</ResponseField>

<ResponseField name="paymentMethod" type="string">
  How the payment was created. One of `PAYMENT_LINK` or `HOSTED_CHECKOUT`.
</ResponseField>

<ResponseField name="redirectUrl" type="string">
  URL the customer is redirected to after checkout.
</ResponseField>

<ResponseField name="paylinkId" type="string">
  Paylink that initiated this payment, if applicable.
</ResponseField>

<ResponseExample>
  ```json Payment as transaction sub-object theme={null}
  {
    "id": "cmjfu1cjv0003v8vsmmxgjk05",
    "token": "USDC",
    "refunded": false,
    "depositAddress": "0x871cf48ff1847e7a...55c2d3",
    "txRef": "order_12345",
    "paymentMethod": "HOSTED_CHECKOUT",
    "redirectUrl": "https://yourapp.com/success",
    "paylinkId": null
  }
  ```
</ResponseExample>

***

## Create a payment

<div className="api-method-box">
  <span className="api-method post">POST</span> `/transactions/payment/create`
</div>

Creates a hosted checkout payment. Returns a `checkoutUrl` to redirect the customer to.

### Request body

<ParamField body="amount" type="number" required>
  Amount to charge in NGN. Minimum `1`.
</ParamField>

<ParamField body="customerId" type="string" required>
  Amount to charge in NGN. Minimum `1`.
</ParamField>

<ParamField body="customer" type="object" required>
  Customer information for this payment.

  <Expandable title="child attributes">
    <ParamField body="fullname" type="string" required>
      Full name of the customer.
    </ParamField>

    <ParamField body="email" type="string" required>
      Email address of the customer.
    </ParamField>
  </Expandable>
</ParamField>

\| Either the customerId or the object is required!

<ParamField body="txRef" type="string" required>
  Unique transaction reference from your system. Acts as an idempotency key — duplicate `txRef` values return the original payment.
</ParamField>

<ParamField body="redirectUrl" type="string">
  URL to redirect the customer to after checkout. If omitted, the customer stays on the Orafi checkout page.
</ParamField>

<ResponseExample>
  ```bash cURL theme={null}
  curl -X POST https://api.orafi.app/transactions/payment/create \
    -H "Content-Type: application/json" \
    -H "x-api-key: ora_test_your_api_key" \
    -d '{
      "amount": 10000,
      "customer": {
        "fullname": "John Doe",
        "email": "john@example.com"
      },
      "txRef": "order_12345",
      "redirectUrl": "https://yourapp.com/success"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.orafi.app/transactions/payment/create", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "ora_test_your_api_key"
    },
    body: JSON.stringify({
      amount: 10000,
      customer: {
        fullname: "John Doe",
        email: "john@example.com"
      },
      txRef: "order_12345",
      redirectUrl: "https://yourapp.com/success"
    })
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.orafi.app/transactions/payment/create",
      headers={
          "Content-Type": "application/json",
          "x-api-key": "ora_test_your_api_key"
      },
      json={
          "amount": 10000,
          "customer": {
              "fullname": "John Doe",
              "email": "john@example.com"
          },
          "txRef": "order_12345",
          "redirectUrl": "https://yourapp.com/success"
      }
  )
  ```

  ```json 201 — Created theme={null}
  {
    "success": true,
    "message": "Payment created successfully",
    "data": {
      "payment": {
        "id": "cmjw65j510001v81cilq0u13v",
        "depositAddress": "0x02c362...82f66",
        "amount": 10000,
        "amountInUSDC": 6.92,
        "redirectUrl": "https://yourapp.com/success"
      },
      "checkoutUrl": "https://checkout.orafi.app/cmjw65j4z0000v81c16vtqj14"
    }
  }
  ```

  ```json 400 — Bad Request theme={null}
  {
    "success": false,
    "message": "Invalid request parameters"
  }
  ```
</ResponseExample>

***

## Verify a payment

<div className="api-method-box">
  <span className="api-method post">POST</span> `/transactions/payment/verify`
</div>

Verifies the current status of a payment. Call this after the customer is redirected back to your application.

### Request body

<ParamField body="paymentId" type="string" required>
  The payment ID returned when the payment was created.
</ParamField>

<ResponseExample>
  ```bash cURL theme={null}
  curl -X POST https://api.orafi.app/transactions/payment/verify \
    -H "Content-Type: application/json" \
    -d '{
      "paymentId": "cmjw65j510001v81cilq0u13v"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.orafi.app/transactions/payment/verify", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ paymentId: "cmjw65j510001v81cilq0u13v" })
  });
  ```

  ```json 200 — Success theme={null}
  {
    "success": true,
    "message": "Payment verification completed",
    "data": {
      "status": "completed",
      "paymentId": "cmjw65j510001v81cilq0u13v"
    }
  }
  ```
</ResponseExample>

***

## Retrieve a payment

\| Retriving a transactionis only valid within the period of expected completion(10 minutes).

<div className="api-method-box">
  <span className="api-method get">GET</span> `/transactions/payment`
</div>

Fetches full details of a payment including deposit address, business name, and amounts.

### Query parameters

<ParamField query="paymentId" type="string" required>
  The payment ID to retrieve.
</ParamField>

<ResponseExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.orafi.app/transactions/payment?paymentId=cmjw65j510001v81cilq0u13v" \
    -H "x-api-key: ora_test_your_api_key"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.orafi.app/transactions/payment?paymentId=cmjw65j510001v81cilq0u13v",
    { headers: { "x-api-key": "ora_test_your_api_key" } }
  );
  ```

  ```json 200 — Success theme={null}
  {
    "success": true,
    "message": "Payment information retrieved successfully!",
    "data": {
      "id": "cmjw65j510001v81cilq0u13v",
      "depositAddress": "0x02c362...82f66",
      "transferAddress": "0x02c362...82f66",
      "businessName": "Acme Corp",
      "amount": 10000,
      "amountInUSDC": 6.92,
      "redirectUrl": "https://yourapp.com/success?oratx=cmjw65j4z0000v81c16vtqj14"
    }
  }
  ```
</ResponseExample>