Retrieve Payment

Retrieves the details of an existing payment by its ID.

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