Piggyvest Business

Introduction

API Doc

Webhooks

Pay With Pocket

DocsStatus Query
Ctrl K

Status Query

GET/api/v1/pocket/transfer/status/:reference

You might want to get the status of a payment request upon receiving webhooks. Use this endpoint to fetch the current status of a transfer. The same path is callable with either a secret key or a public key; the response shape differs slightly between the two — see Responses below.

Path Parameters

NameTypeRequiredDescription
referencestringYesYour reference or the PVB reference (pvb_reference or pvb_third_party_reference from the webhook payload).
Note: You can pass your own reference used when initiating the transfer, or the Piggyvest reference. Use pvb_reference or pvb_third_party_reference from the webhook payload.
1
cURL Example
(cURL)
curl -X GET "https://api.piggyvest.business/api/v1/pocket/transfer/status/your-reference" \
-H "Authorization: Bearer YOUR_SECRET_KEY"
2
Node.js Example
(JavaScript)
import axios from 'axios'
const secretKey = process.env.PVB_SECRET_KEY
const url = `${process.env.PVB_BASE_URL}/api/v1/pocket/transfer/status/:reference`
await axios.get(url, {
  headers: {
    'Authorization': `Bearer ${secretKey}`,
  },
})

Responses

The response shape depends on which key you authenticate with. The two variants below describe the same endpoint called as either an API (secret key) request or a checkout (public key) request.

API (secret key) — standard envelope

Server-to-server calls authorized with your secret key return the standard status / message / data envelope used elsewhere in the API.

Success Response (200)
(JSON)
{
  "status": true,
  "message": "Payment request found",
  "data": {
    "payment_request": {
      "id": "f461f152-1c89-418e-8a26-ec2f560683eb",
      "reference": "pvfb_89259283-8702-4472-af66-41edd8784f221729962149844",
      "third_party_reference": "101029928283737373636533",
      "status": "successful",
      "amount": 20000,
      "tag": "mazigraphql",
      "narration": "Success test",
      "product_name": "Chinex Electronics",
      "wallet_id": "3b8251aa-b373-495b-9525-1221fe799f31",
      "meta": null
    }
  }
}

Checkout (public key) — raw shape

When called with a public key (browser / checkout flow), the response follows the Pocket / service raw shape rather than the standard envelope. The status field reflects the Pocket-provider status string instead of a boolean. A representative shape:

Success Response (checkout)
(JSON)
{
  "status": "<from-pocket-provider>",
  "data": {
    "payment_request": {
      "id": "string",
      "reference": "string",
      "third_party_reference": "string",
      "status": "string",
      "amount": 0,
      "tag": "string",
      "narration": "string",
      "product_name": "string | null",
      "wallet_id": "string",
      "meta": null
    }
  }
}

Error Response (404)

Not Found
(JSON)
{
  "status": false,
  "message": "Payment request not found"
}

Error Response (500)

Internal Server Error
(JSON)
{
  "status": false,
  "message": "We are unable to process your request. please try again later or contact support"
}

Pending vs Success

PendingImmediately after initiate, or while payment_request.status is pending: the Pocket user may not yet have approved payment and the transfer has not settled.
SuccessAfter successful inflow processing: the wallet is credited and the request status is successful — settled per your business rules.

Status Values

The payment_request.status field in the response can be one of:

pendingStill processing. The Pocket user may not have accepted or rejected the request yet.
successfulCompleted successfully. Your account was credited.
failedTerminal failure. The Pocket user rejected the payment request.
partialBatch / split payment: not all legs succeeded (successful_split < total_split in batch context).