Skip to main content

​
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.
​
id
string
Unique identifier for the payment.
​
depositAddress
string
On-chain address the customer sends funds to.
​
amount
number
Payment amount in NGN (the currency the merchant specified).
​
amountInUSDC
number
Equivalent amount in USDC at the time of creation.
​
redirectUrl
string
URL the customer is redirected to after payment.
​
checkoutUrl
string
Orafi-hosted checkout page URL. Redirect your customer here to complete payment.
​
status
string
default:"INITIALIZED"
Current payment status. One of INITIALIZED, CONFIRMED, or FAILED.
​
token
string
default:"USDC"
Token used for the payment. Currently always USDC.
​
refunded
boolean
default:"false"
Whether this payment has been refunded.
​
paymentMethod
string
How the payment was initiated. One of PAYMENT_LINK or HOSTED_CHECKOUT.
​
txRef
string
Merchant-supplied transaction reference. Acts as an idempotency key.
​
transactionId
string
ID of the parent transaction record.
​
paylinkId
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:
​
id
string
Unique identifier for the payment.
​
token
string
default:"USDC"
Token used for the payment.
​
refunded
boolean
default:"false"
Whether this payment has been refunded.
​
depositAddress
string
On-chain address the customer sent funds to.
​
txRef
string
Merchant-supplied transaction reference (idempotency key).
​
paymentMethod
string
How the payment was created. One of PAYMENT_LINK or HOSTED_CHECKOUT.
​
redirectUrl
string
URL the customer is redirected to after checkout.
​
paylinkId
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

​
amount
number
required
Amount to charge in NGN. Minimum 1.
​
customer
object
required
Customer information for this payment.
​
txRef
string
required
Unique transaction reference from your system. Acts as an idempotency key — duplicate txRef values return the original payment.
​
redirectUrl
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"
  }'

​
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

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

​
Retrieve a payment

GET /transactions/payment/retrieve
Fetches full details of a payment including deposit address, business name, and amounts.

​
Query parameters

​
paymentId
string
required
The payment ID to retrieve.
curl -X GET "https://api.orafi.app/transactions/payment/retrieve?paymentId=cmjw65j510001v81cilq0u13v" \
  -H "x-api-key: ora_test_your_api_key"