Get a Payout Receipt

Once a payout completes, NextAPI generates a receipt — a structured record of the settled transaction including the bank reference number, rail used, and settled amount. Use receipts for audit trails, partner proof-of-payment requests, and dispute resolution.

Prerequisites

• A completed payout (status: completed)
• The payout_id or payout_request_id for the transaction

How to get the payout ID

When a payout settles, NextAPI fires a payout_request.completed webhook. The payload includes both payout_request_id and payout_id. Save both when you receive the webhook.

Fetch a receipt by payout ID

cURL

curl -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  "https://api.partners.nextpay.world/v2/payouts/YOUR_PAYOUT_ID/receipt"

Node.js

async function getPayoutReceipt(payoutId) {
  const response = await fetch(
    `https://api.partners.nextpay.world/v2/payouts/${payoutId}/receipt`,
    {
      headers: {
        'Authorization': 'Basic ' + Buffer.from('YOUR_CLIENT_ID:YOUR_CLIENT_SECRET').toString('base64'),
      },
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Failed to fetch receipt: ${error.message}`);
  }

  return response.json();
}

Python

import requests
import base64

def get_payout_receipt(payout_id):
    credentials = base64.b64encode(b'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET').decode()

    response = requests.get(
        f'https://api.partners.nextpay.world/v2/payouts/{payout_id}/receipt',
        headers={'Authorization': f'Basic {credentials}'},
    )

    response.raise_for_status()
    return response.json()

Response

{
  "payout_id": "pay_01HABC",
  "payout_request_id": "pr_01HXYZ",
  "status": "completed",
  "amount": 50000,
  "fee": 0,
  "net_amount": 50000,
  "currency": "PHP",
  "rail": "instapay",
  "bank_reference": "IBFT202511151800001234",
  "recipient": {
    "name": "Maria Santos",
    "bank_code": "BPI",
    "account_number_last4": "3210"
  },
  "settled_at": "2025-11-15T18:00:43Z",
  "created_at": "2025-11-15T17:59:55Z"
}

Key fields:

Field	Description
bank_reference	The bank's own transaction reference — use this for dispute resolution with the receiving bank
rail	instapay or pesonet — the payment rail used for settlement
net_amount	Amount that actually reached the recipient (after any fees)
settled_at	When the bank confirmed settlement
account_number_last4	Last 4 digits of the recipient account for verification

Look up a payout by payout request

If you only have the payout_request_id (the ID you received when you created the payout), first list payouts under that request:

curl -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  "https://api.partners.nextpay.world/v2/payout-requests/YOUR_PAYOUT_REQUEST_ID/payouts"

This returns the associated payout(s). Use the id from the response to fetch the receipt.

Split payouts

Large amounts routed via PESONet may be split into multiple payouts if they exceed rail limits. In this case, the payout request will have more than one associated payout, each with its own receipt.

Retrieve receipts in bulk (webhook pattern)

For high-volume platforms, store receipts as they arrive rather than fetching on demand. Handle the payout_request.completed webhook and fetch the receipt immediately:

// Express webhook handler
app.post('/webhooks/nextapi', async (req, res) => {
  const event = req.body;

  if (event.event === 'payout_request.completed') {
    const { payout_id, payout_request_id } = event.data;

    const receipt = await getPayoutReceipt(payout_id);

    // Store against your internal payout record
    await db.payouts.update({
      where: { nextapi_payout_request_id: payout_request_id },
      data: {
        bank_reference: receipt.bank_reference,
        rail: receipt.rail,
        settled_at: receipt.settled_at,
        receipt_json: JSON.stringify(receipt),
      },
    });
  }

  res.sendStatus(200);
});

When a receipt is not available

Receipts are only available for payouts with status: completed. If you request a receipt for a payout that is still pending or has failed, the API returns a 404.

Payout status	Receipt available
initiated	No
pending	No
processing	No
completed	Yes
failed	No
cancelled	No

Related

• Send a Single Payout — create a payout
• Handle Payout Failures — retry and failure recovery
• Payout Lifecycle — all payout states explained
• API Reference: Get Payout Receipt — full endpoint docs