Transactions

Transactions are the core of ZuriPay. Use these endpoints to initialize payments, verify their status, and manage the full payment lifecycle.

The transaction model

The transaction model contains all the information about a payment processed through ZuriPay.

Properties

Name
transactionId
Type
string
Description
Unique transaction identifier (e.g., zp_a1b2c3d4e5).
Name
transactionReference
Type
string
Description
Unique reference for the transaction (e.g., ZURIPAYa1b2c3d4e5).
Name
amount
Type
integer
Description
Transaction amount in the smallest currency unit (e.g., cents). 1000 = $10.00.
Name
charges
Type
integer
Description
ZuriPay processing fee in the smallest currency unit.
Name
total
Type
integer
Description
Total amount including charges.
Name
currency
Type
string
Description
Three-letter ISO currency code (e.g., USD, ZWL).
Name
emailAddress
Type
string
Description
Customer's email address.
Name
status
Type
string
Description
Transaction status: pending, processing, success, or failed.
Name
checkoutId
Type
string
Description
Checkout session identifier for hosted checkout.
Name
successUrl
Type
string
Description
URL to redirect the customer after successful payment.
Name
failureUrl
Type
string
Description
URL to redirect the customer after failed payment.
Name
dateCreated
Type
timestamp
Description
Timestamp when the transaction was created.

POST/v1/transactions

Initialize transaction

Create a new payment transaction. The API key determines whether this is a test or live transaction.

Required attributes

Name
amount
Type
integer
Description
Amount in the smallest currency unit (e.g., 1000 for $10.00).
Name
email
Type
string
Description
Customer's email address.
Name
currency
Type
string
Description
Three-letter ISO currency code (e.g., USD, ZWL, ZAR).

Optional attributes

Name
payment_method_type
Type
string
Description
Payment method type: mobile_money or card.
Name
payment_method_code
Type
string
Description
Specific payment method code: ecocash, innbucks, zimswitch, dpo, ozow.
Name
mobile_money_number
Type
string
Description
Customer's mobile money number (required for mobile_money type). Must start with 0.
Name
transaction_reference
Type
string
Description
Custom reference (auto-generated if not provided).
Name
success_url
Type
string
Description
Redirect URL for successful payment.
Name
failure_url
Type
string
Description
Redirect URL for failed payment.
Name
requested_response
Type
string
Description
Test mode only: simulate success or failed for EcoCash.

Request

POST

/v1/transactions

curl -X POST https://api.zuripay.app/v1/transactions \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "email": "[email protected]",
    "currency": "USD",
    "success_url": "https://yoursite.com/success",
    "failure_url": "https://yoursite.com/failure"
  }'

Response

{
  "result": "success",
  "transaction_id": "zp_a1b2c3d4e5",
  "transaction_reference": "ZURIPAYa1b2c3d4e5",
  "message": "Transaction initiated successfully.",
  "total": 10.10
}

GET/v1/transactions/verify

Verify transaction

Verify the status of a transaction by its reference. Use this endpoint to confirm whether a payment was successful before fulfilling an order.

Required parameters

Name
reference
Type
string
Description
The transaction reference returned during initialization.

Request

GET

/v1/transactions/verify?reference=ZURIPAYa1b2c3d4e5

curl -G https://api.zuripay.app/v1/transactions/verify \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -d reference=ZURIPAYa1b2c3d4e5

Response

{
  "result": "success",
  "transaction_id": "zp_a1b2c3d4e5",
  "transaction_reference": "ZURIPAYa1b2c3d4e5",
  "amount": 1000,
  "charges": 10,
  "total": 1010,
  "currency": "USD",
  "status": "success",
  "emailAddress": "[email protected]",
  "dateCreated": "2025-01-15T10:30:00Z"
}

GET/v1/transactions/list

List transactions

Retrieve a list of all transactions for your business.

Optional parameters

Name
start_date
Type
string
Description
Filter by start date (format: YYYY-MM-DD).
Name
end_date
Type
string
Description
Filter by end date (format: YYYY-MM-DD).
Name
limit
Type
integer
Description
Maximum number of records to return (default: 100).

Request

GET

/v1/transactions/list

curl -G https://api.zuripay.app/v1/transactions/list \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -d limit=10

Response

{
  "result": "success",
  "transactions": [
    {
      "transaction_id": "zp_a1b2c3d4e5",
      "amount": "10.00",
      "currency": "USD",
      "status": "success",
      "message": "Transaction listed successfully.",
      "details": {}
    }
  ]
}

GET/v1/transactions/fetch

Fetch transaction

Retrieve a single transaction by its public ID.

Required parameters

Name
publicId
Type
string
Description
The public ID of the transaction.

Request

GET

/v1/transactions/fetch?publicId=abc123

curl -G https://api.zuripay.app/v1/transactions/fetch \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -d publicId=abc123

POST/v1/transactions/refund

Refund transaction

Initiate a refund for a completed transaction.

Required attributes

Name
transaction_reference
Type
string
Description
The reference of the transaction to refund.
Name
amount
Type
integer
Description
Amount to refund in the smallest currency unit. Must be less than or equal to the original transaction amount.

Request

POST

/v1/transactions/refund

curl -X POST https://api.zuripay.app/v1/transactions/refund \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_reference": "ZURIPAYa1b2c3d4e5",
    "amount": 1000
  }'

Response

{
  "result": "success",
  "message": "Refund initiated successfully.",
  "refund_id": "ref_xyz789",
  "status": "pending"
}