One2Pays

Retrieve Withdraw by referenceId

Retrieves the details of an existing withdraw using the merchant-supplied referenceId (e.g., your invoice number). Use this when you only stored your own reference at create time and did not persist the withdraw UUID returned in the create response.

Scoped to the authenticated merchant: you can only retrieve your own withdraws. If no withdraw with that referenceId exists for your merchant, a 404 is returned.

Endpoint

GET /api/v1/withdraws/by-reference/{referenceId}

Authentication

This endpoint requires HMAC Integration Authentication.

Path Parameters

ParameterTypeRequiredDescription
referenceIdstringYesThe merchant-supplied reference you sent in the referenceId field of the create request. 1–255 characters; alphanumeric, _, -, . allowed.

Example Request

import crypto from 'crypto';

const API_KEY = process.env.PAYMENT_API_KEY!;
const API_SECRET = process.env.PAYMENT_API_SECRET!;

async function getWithdrawByReference(referenceId: string) {
  const method = 'GET';
  const path = `/api/v1/withdraws/by-reference/${encodeURIComponent(referenceId)}`;
  const body = '';
  const timestamp = Date.now().toString();

  const message = `${timestamp}.${body}`;
  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(message)
    .digest('hex');

  const response = await fetch(`https://api.example.com${path}`, {
    method,
    headers: {
      'X-API-Key': API_KEY,
      'X-Timestamp': timestamp,
      'X-Signature': `sha256=${signature}`,
    },
  });

  const result = await response.json();

  if (result.success) {
    console.log('Withdraw status:', result.data.status);
    return result.data;
  } else {
    console.error('Error:', result.error);
    throw new Error(result.error.message);
  }
}

// Look up by your invoice number
const withdraw = await getWithdrawByReference('payout-12345');
TIMESTAMP=$(date +%s%3N)
BODY=""
SIGNATURE=$(printf "%s.%s" "$TIMESTAMP" "$BODY" \
  | openssl dgst -sha256 -hmac "$PAYMENT_API_SECRET" -hex \
  | awk '{print $2}')

curl "https://api.example.com/api/v1/withdraws/by-reference/payout-12345" \
  -H "X-API-Key: $PAYMENT_API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: sha256=$SIGNATURE"

Response

Success Response (200 OK)

Identical to Retrieve Withdraw.

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "amount": "1000.00",
    "currency": "THB",
    "status": "paid",
    "referenceId": "payout-12345",
    "destinationType": "bank_account",
    "description": "Payout for order #12345",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:05:00.000Z"
  }
}

Error Response (404 Not Found)

Returned when no withdraw with that referenceId exists for your merchant.

{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Withdraw not found"
  }
}

Error Response (400 Bad Request)

Returned when the referenceId fails format validation (length or character set).

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "referenceId must contain only alphanumeric characters, underscores, hyphens, and dots (1-255 characters)"
  }
}

Notes

  • URL-encode referenceId if it contains . segments or other characters that some clients may treat specially in paths.
  • The response payload, including the status field and lifecycle timestamps, is the same as Retrieve Withdraw.

On this page

EndpointAuthenticationPath ParametersExample RequestResponseSuccess Response (200 OK)Error Response (404 Not Found)Error Response (400 Bad Request)NotesRelated Endpoints