Verify Transaction

Verify the status and authenticity of a transaction using its unique reference. This is a critical security endpoint that confirms payment completion before delivering goods or services to customers.

⚠️

Always verify transactions on your server before fulfilling orders. Never rely solely on client-side callbacks or redirects, as these can be manipulated.

Endpoint

GET https://api.budpay.com/api/v2/transaction/verify/:reference

Replace :reference with the transaction reference you want to verify.

Sample Request

curl https://api.budpay.com/api/v2/transaction/verify/BUD_1673600359168063493 \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-X GET

Sample Response (Success)

{
    "status": true,
    "message": "Transaction verified successfully",
    "data": {
        "id": 1404612,
        "currency": "NGN",
        "amount": "550",
        "reference": "BUD_1673600359168063493",
        "ip_address": "102.89.23.45",
        "channel": "transfer",
        "type": "transaction",
        "domain": "live",
        "fees": "50",
        "plan": null,
        "requested_amount": "500",
        "status": "success",
        "card_attempt": 0,
        "split_code": null,
        "message": "Payment successful",
        "gateway": "Wema",
        "transfer_details": null,
        "webhook_status": "sent",
        "webhook_url": "https://yourwebsite.com/webhook",
        "webhook_response": "200 OK",
        "metadata": "",
        "created_at": "2023-01-13T08:59:26.000000Z",
        "paid_at": "2023-01-13 10:06:29",
        "customer": {
            "id": 627321,
            "first_name": "Francis",
            "last_name": "Obadiah",
            "email": "francis@budpay.com",
            "phone": "+2348012345678",
            "domain": "live",
            "customer_code": "CUS_0q2htds3kf3zzrb",
            "metadata": "{}",
            "status": "active"
        }
    }
}

Try it out

Request Parameters

Header Parameters

Field Name	Description	Required
Authorization	Bearer token with your secret key	Yes

URL Parameters

Parameter	Type	Required	Description
`reference`	String	Yes	Unique transaction reference to verify

Response Fields

Root Level

Field	Type	Description
`status`	Boolean	Indicates if verification was successful
`message`	String	Response message
`data`	Object	Transaction data object

Transaction Data

Field	Type	Description
`id`	Integer	Internal transaction ID
`currency`	String	Currency code: `NGN`, `USD`, `GHS`, `KES`
`amount`	String	Total amount including fees
`reference`	String	Unique transaction reference
`ip_address`	String	Customer's IP address
`channel`	String	Payment channel: `card`, `transfer`, `mobile_money`
`type`	String	Transaction type
`domain`	String	Environment: `test` or `live`
`fees`	String	Transaction processing fees
`plan`	String	Subscription plan ID (if applicable)
`requested_amount`	String	Original amount before fees
`status`	String	Transaction status: `success`, `pending`, `failed`
`card_attempt`	Integer	Number of card authorization attempts
`split_code`	String	Split payment code (if applicable)
`message`	String	Transaction message or error description
`gateway`	String	Payment gateway used
`transfer_details`	Object	Bank transfer specific details
`webhook_status`	String	Webhook delivery status: `sent`, `pending`, `failed`
`webhook_url`	String	URL where webhook was sent
`webhook_response`	String	Response from webhook endpoint
`metadata`	String	Custom metadata attached to transaction
`created_at`	String	Timestamp when transaction was created
`paid_at`	String	Timestamp when payment was completed

Customer Data

Field	Type	Description
`id`	Integer	Customer ID in BudPay system
`first_name`	String	Customer's first name
`last_name`	String	Customer's last name
`email`	String	Customer's email address
`phone`	String	Customer's phone number
`domain`	String	Customer domain: `test` or `live`
`customer_code`	String	Unique customer code
`metadata`	String	Additional customer metadata
`status`	String	Customer account status

Transaction Status Values

Status	Description	Action Required
`success`	Payment completed successfully	Fulfill order immediately
`pending`	Payment initiated but not completed	Wait or notify customer
`failed`	Transaction failed or was declined	Request new payment
`abandoned`	Customer left without paying	Contact customer if needed

Verification Workflow

Here's the recommended workflow for verifying transactions:

1. Customer Completes Payment
         ↓
2. Receive Callback/Webhook
         ↓
3. Extract Transaction Reference
         ↓
4. Call Verify API (Server-Side)
         ↓
5. Check status === "success"
         ↓
6. Verify Amount Matches Expected
         ↓
7. Check Transaction Not Already Processed
         ↓
8. Fulfill Order/Deliver Service
         ↓
9. Mark Transaction as Processed

Error Handling

404 Not Found

{
    "status": false,
    "message": "Transaction not found"
}

Solution: The transaction reference doesn't exist. Verify the reference is correct.

401 Unauthorized

{
    "status": false,
    "message": "Authentication failed"
}

Solution: Check that your API key is valid and properly included in the Authorization header.

400 Bad Request

{
    "status": false,
    "message": "Invalid transaction reference format"
}

Solution: Ensure the reference format is correct.

Best Practices

Tip: Implement idempotency in your order fulfillment logic to safely handle duplicate verification calls for the same transaction.

Immediate Verification: Verify transactions immediately after receiving callbacks.
Idempotent Processing: Design your fulfillment logic to handle multiple verification calls safely.
Proper Logging: Log all verification attempts with timestamps and results.
Error Recovery: Implement retry logic with exponential backoff for failed verifications.
Database Transactions: Use database transactions when updating order status.
Customer Communication: Notify customers promptly after successful verification.
Reconciliation: Regularly reconcile verified payments with your records.
Monitoring: Set up monitoring and alerts for verification failures.

Try it out

Transaction Statement Overview