One2Pays

Retrieve Payment by referenceId

Retrieves the details of an existing payment 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 payment UUID returned in the create response.

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

Endpoint

GET /api/v1/payments/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 getPaymentByReference(referenceId: string) {
  const method = 'GET';
  const path = `/api/v1/payments/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('Payment 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 payment = await getPaymentByReference('order-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/payments/by-reference/order-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 Payment.

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "amount": "1000.00",
    "currency": "THB",
    "status": "succeeded",
    "paymentMethod": "promptpay",
    "referenceId": "order-12345",
    "description": "Payment for order #12345",
    "metadata": {
      "order_id": "12345"
    },
    "clientSecret": null,
    "nextAction": null,
    "confirmedAt": "2024-01-01T00:05:00.000Z",
    "capturedAt": "2024-01-01T00:05:00.000Z",
    "canceledAt": null,
    "expiresAt": "2024-01-01T01:00:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:05:00.000Z"
  }
}

Error Response (404 Not Found)

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

{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Payment 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 Payment.

On this page

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