Payments

{
  "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
}

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.

string

Unique identifier for the payment.

string

On-chain address the customer sends funds to.

number

Payment amount in NGN (the currency the merchant specified).

number

Equivalent amount in USDC at the time of creation.

string

URL the customer is redirected to after payment.

string

Orafi-hosted checkout page URL. Redirect your customer here to complete payment.

string

default:"INITIALIZED"

Current payment status. One of INITIALIZED, CONFIRMED, or FAILED.

string

default:"USDC"

Token used for the payment. Currently always USDC.

boolean

default:"false"

Whether this payment has been refunded.

string

How the payment was initiated. One of PAYMENT_LINK or HOSTED_CHECKOUT.

string

Merchant-supplied transaction reference. Acts as an idempotency key.

string

ID of the parent transaction record.

string

Paylink that initiated this payment, if applicable.

{
  "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
}

Transaction sub-object

When retrieving a Transaction with type: "PAYMENT", the payment appears as a nested payment sub-object with these fields:

string

Unique identifier for the payment.

string

default:"USDC"

Token used for the payment.

boolean

default:"false"

Whether this payment has been refunded.

string

On-chain address the customer sent funds to.

string

Merchant-supplied transaction reference (idempotency key).

string

How the payment was created. One of PAYMENT_LINK or HOSTED_CHECKOUT.

string

URL the customer is redirected to after checkout.

string

Paylink that initiated this payment, if applicable.

{
  "id": "cmjfu1cjv0003v8vsmmxgjk05",
  "token": "USDC",
  "refunded": false,
  "depositAddress": "0x871cf48ff1847e7a...55c2d3",
  "txRef": "order_12345",
  "paymentMethod": "HOSTED_CHECKOUT",
  "redirectUrl": "https://yourapp.com/success",
  "paylinkId": null
}

Create a payment

POST /transactions/payment/create

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

Request body

number

required

Amount to charge in NGN. Minimum 1.

string

required

Amount to charge in NGN. Minimum 1.

object

required

Customer information for this payment.

Show child attributes

string

required

Full name of the customer.

string

required

Email address of the customer.

| Either the customerId or the object is required!

string

required

Unique transaction reference from your system. Acts as an idempotency key — duplicate txRef values return the original payment.

string

URL to redirect the customer to after checkout. If omitted, the customer stays on the Orafi checkout page.

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"
  }'

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"
  })
});

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"
    }
)

{
  "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"
  }
}

{
  "success": false,
  "message": "Invalid request parameters"
}

Verify a payment

POST /transactions/payment/verify

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

Request body

string

required

The payment ID returned when the payment was created.

curl -X POST https://api.orafi.app/transactions/payment/verify \
  -H "Content-Type: application/json" \
  -d '{
    "paymentId": "cmjw65j510001v81cilq0u13v"
  }'

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

{
  "success": true,
  "message": "Payment verification completed",
  "data": {
    "status": "completed",
    "paymentId": "cmjw65j510001v81cilq0u13v"
  }
}

Retrieve a payment

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

GET /transactions/payment

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

Query parameters

string

required

The payment ID to retrieve.

curl -X GET "https://api.orafi.app/transactions/payment?paymentId=cmjw65j510001v81cilq0u13v" \
  -H "x-api-key: ora_test_your_api_key"

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

{
  "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"
  }
}

Overview

Transactions

Refunds

Payouts

Paylinks

Customers

Subscriptions

Webhooks

Webhook Deliveries

Crypto Settlements

Fiat Settlements

Profile

Mode

Notifications

Extras

Payments

The payment object

Transaction sub-object

Create a payment

Request body

Verify a payment

Request body

Retrieve a payment

Query parameters

​The payment object

​Transaction sub-object

​Create a payment

​Request body

​Verify a payment

​Request body

​Retrieve a payment

​Query parameters

The payment object

Transaction sub-object

Create a payment

Request body

Verify a payment

Request body

Retrieve a payment

Query parameters