Retrieve Payment

Retrieves the details of an existing payment by its UUID.

Don't have the UUID?

If you only stored your own referenceId (e.g., your invoice number) at create time, use GET /payments/by-reference/:referenceId instead.

Authentication

This endpoint requires HMAC Integration Authentication.

Path Parameters

Parameter	Type	Required	Description
`payment_id`	string	Yes	The UUID of the payment to retrieve

Example Request

import crypto from 'crypto';

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

async function getPayment(paymentId: string) {
  const method = 'GET';
  const path = `/api/v1/payments/${paymentId}`;
  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);
    console.log('Payment amount:', result.data.amount);
    return result.data;
  } else {
    console.error('Error:', result.error);
    throw new Error(result.error.message);
  }
}

// Get payment
const payment = await getPayment('550e8400-e29b-41d4-a716-446655440000');

Response

Success Response (200 OK)

{
  "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)

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

Payment Status

Payments can be in one of the following statuses:

Status	Description
`requires_payment_method`	Payment method needs to be attached
`requires_confirmation`	Payment needs to be confirmed (two-step payment flow)
`requires_action`	Additional action required from customer (e.g., 3D Secure)
`processing`	Payment is being processed
`requires_capture`	Payment is authorized and waiting to be captured
`succeeded`	Payment was completed successfully
`canceled`	Payment was cancelled by merchant or customer
`expired`	Payment expired before completion
`payment_failed`	Payment failed (e.g., insufficient funds, card declined)

Payment Status Flow

Status Transitions

Initial Status: Payments typically start as processing or requires_payment_method
Processing: Payment is being processed by the payment provider
Final Status:
- succeeded - Payment completed successfully
- canceled - Payment was cancelled
- expired - Payment expired
- payment_failed - Payment failed

Status Values

Some status values like requires_confirmation and requires_capture may appear in responses but are not currently actionable via API endpoints. Payments typically transition automatically through these statuses during processing.

Response Fields

Field	Type	Description
`id`	string	Payment UUID
`amount`	string	Amount as decimal string
`currency`	string	Currency code (THB)
`status`	string	Current payment status
`paymentMethod`	string	Payment method used (or null)
`referenceId`	string	Your reference ID
`description`	string	Payment description (or null)
`metadata`	object	Additional metadata (or null)
`clientSecret`	string	Client secret for payment processing (or null)
`nextAction`	object	Next action required (or null)
`confirmedAt`	string	ISO timestamp when payment was confirmed (or null)
`capturedAt`	string	ISO timestamp when payment was captured (or null)
`canceledAt`	string	ISO timestamp when payment was canceled (or null)
`expiresAt`	string	ISO timestamp when payment expires (or null)
`createdAt`	string	ISO timestamp when payment was created
`updatedAt`	string	ISO timestamp when payment was last updated

Endpoint