Transactions

The transaction object

string

UUID.

string

On-chain transaction hash (66 characters). Unique.

string

SEND, RECEIVE, REQUEST or DEPOSIT.

string

Sender’s user UUID.

string

Receiver’s user UUID.

number

Decimal USDC.

string

PENDING, COMPLETED or FAILED.

string

ISO 8601 timestamp.

object

Public fields of the sender: id, name, phoneNumber, email, walletAddress.

object

Public fields of the receiver, same shape.

Record a transaction

POST /transaction · Requires auth Called by the app after a payment is sent. Both addresses must belong to Numpay users.

string

required

66-character transaction hash.

string

required

Sender’s smart-account address (42 characters).

string

required

Receiver’s smart-account address (42 characters).

number

required

Positive decimal USDC.

string

required

SEND, REQUEST, RECEIVE or DEPOSIT. The app sends SEND.

string

required

PENDING, COMPLETED or FAILED.

curl -X POST https://api.numpay.app/api/transaction \
  -H "Authorization: Bearer $ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "txhash": "0x9c1f…a4e2",
    "senderAddress": "0x8bA1…BA72",
    "receiverAddress": "0x3f5C…9e2A",
    "amount": 20,
    "transactionType": "SEND",
    "transactionStatus": "COMPLETED"
  }'

Responses: 201 transaction · 400 invalid input · 404 sender or receiver isn’t a Numpay user.

Get a transaction

GET /transaction/{id}

string

required

Transaction UUID.

Get a transaction by hash

GET /transaction/tx/{txhash}

string

required

66-character on-chain hash.

List a user’s transactions

GET /transaction/user/{userId}

string

required

User UUID.

string

send (SEND rows the user sent), receive (non-deposit rows the user received) or deposit (the user’s deposits). Omit for all, newest first.

Response

[
  {
    "id": "7e2b…",
    "txhash": "0x9c1f…a4e2",
    "transactionType": "SEND",
    "senderId": "4f0c…9e11",
    "receiverId": "b2d1…",
    "amount": 20,
    "transactionStatus": "COMPLETED",
    "createdAt": "2026-11-05T09:12:00.000Z",
    "sender": { "id": "4f0c…9e11", "name": "Ada", "phoneNumber": "+14155550123", "email": null, "walletAddress": "0x8bA1…BA72" },
    "receiver": { "id": "b2d1…", "name": null, "phoneNumber": "+2348012345678", "email": null, "walletAddress": "0x3f5C…9e2A" }
  }
]

Basics

Endpoints

The transaction object

Record a transaction

Get a transaction

Get a transaction by hash

List a user’s transactions

​The transaction object

​Record a transaction

​Get a transaction

​Get a transaction by hash

​List a user’s transactions

The transaction object

Record a transaction

Get a transaction

Get a transaction by hash

List a user’s transactions