Retrieve a Payment Intent

Retrieve the details of a Payment Intent to check its status and get updated information.

Endpoint

GET /api/v1/payment_intents/:id

Authentication

This endpoint supports both authentication methods:

• Bearer Token (JWT) - Authorization: Bearer YOUR_JWT_TOKEN
• API Key (Basic Auth) - Authorization: Basic base64(key:secret)

Request

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The ID of the Payment Intent to retrieve (e.g., 550e8400-e29b-41d4-a716-446655440000).

Response

Success Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "100.00",
  "currency": "usd",
  "status": "succeeded",
  "paymentMethodTypes": ["crypto"],
  "returnUrl": "https://merchant.example.com/return",
  "cancelUrl": "https://merchant.example.com/cancel",
  "description": "Payment for services",
  "metadata": {
    "order_id": "12345",
    "customer_id": "67890"
  },
  "paymentLink": {
    "id": 1,
    "link": "https://pay.orcarail.com/pay/pl_abc123"
  },
  "latestTransaction": {
    "id": "txn_1234567890",
    "status": "completed",
    "amount": "100.00",
    "currency": "usd",
    "hash": "0x1234567890abcdef...",
    "createdAt": "2024-01-01T00:00:00.000Z"
  },
  "expiresAt": null,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Response Fields

Field	Type	Description
id	string	Unique identifier for the Payment Intent.
amount	string	The amount charged.
currency	string	The currency code.
status	string	Current status of the Payment Intent. See Status Values below.
paymentMethodTypes	array	Array of payment method types used.
returnUrl	string	The return URL specified.
cancelUrl	string	The cancel URL (if specified).
description	string	The description (if provided).
metadata	object	The metadata (if provided).
paymentLink	object	The payment link object with pay URL.
latestTransaction	object	The most recent transaction associated with this Payment Intent.
latestTransaction.id	string	Transaction ID.
latestTransaction.status	string	Transaction status.
latestTransaction.amount	string	Transaction amount.
latestTransaction.currency	string	Transaction currency.
latestTransaction.hash	string	Blockchain transaction hash (if completed).
expiresAt	string | null	When the Payment Intent expires (if specified).
createdAt	string	When the Payment Intent was created.
updatedAt	string	When the Payment Intent was last updated.

Status Values

Status	Description
requires_payment_method	The PaymentIntent has been created, but no payment method has been attached yet.
requires_confirmation	The PaymentIntent has a payment method attached, but needs to be confirmed.
processing	The PaymentIntent is being processed on the blockchain.
succeeded	The PaymentIntent has succeeded and payment has been processed.
canceled	The PaymentIntent was canceled.

Example

cURL

curl https://api.orcarail.com/api/v1/payment_intents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

JavaScript (Node.js)

const paymentIntentId = '550e8400-e29b-41d4-a716-446655440000'

const response = await fetch(
  `https://api.orcarail.com/api/v1/payment_intents/${paymentIntentId}`,
  {
    headers: {
      Authorization: `Bearer ${jwtToken}`,
    },
  }
)

const paymentIntent = await response.json()

console.log('Status:', paymentIntent.status)
console.log('Amount:', paymentIntent.amount)

if (paymentIntent.status === 'succeeded') {
  console.log('Transaction Hash:', paymentIntent.latestTransaction?.hash)
}

Python

import requests

payment_intent_id = '550e8400-e29b-41d4-a716-446655440000'

response = requests.get(
    f'https://api.orcarail.com/api/v1/payment_intents/{payment_intent_id}',
    headers={
        'Authorization': f'Bearer {jwt_token}',
    },
)

payment_intent = response.json()

print(f"Status: {payment_intent['status']}")
print(f"Amount: {payment_intent['amount']}")

if payment_intent['status'] == 'succeeded':
    print(f"Transaction Hash: {payment_intent['latestTransaction']['hash']}")

Use Cases

Check Payment Status After Redirect

After a customer is redirected back to your return_url, retrieve the Payment Intent to check if the payment succeeded:

// Extract from URL query params
const urlParams = new URLSearchParams(window.location.search)
const paymentIntentId = urlParams.get('payment_intent')

if (paymentIntentId) {
  const response = await fetch(
    `https://api.orcarail.com/api/v1/payment_intents/${paymentIntentId}`,
    {
      headers: {
        Authorization: `Bearer ${jwtToken}`,
      },
    }
  )

  const paymentIntent = await response.json()

  switch (paymentIntent.status) {
    case 'succeeded':
      // Payment completed successfully
      showSuccessMessage()
      fulfillOrder(paymentIntent.metadata.order_id)
      break
    case 'processing':
      // Payment is being processed
      showProcessingMessage()
      break
    case 'canceled':
      // Payment was canceled
      showCanceledMessage()
      break
    default:
      // Handle other statuses
      showErrorMessage()
  }
}

Poll for Status Updates

If you're not using webhooks, you can poll the Payment Intent endpoint to check for status updates:

async function pollPaymentStatus(paymentIntentId, maxAttempts = 30) {
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.orcarail.com/api/v1/payment_intents/${paymentIntentId}`,
      {
        headers: {
          Authorization: `Bearer ${jwtToken}`,
        },
      }
    )

    const paymentIntent = await response.json()

    if (paymentIntent.status === 'succeeded') {
      return { success: true, paymentIntent }
    }

    if (paymentIntent.status === 'canceled') {
      return { success: false, paymentIntent }
    }

    // Wait 2 seconds before next poll
    await new Promise((resolve) => setTimeout(resolve, 2000))
  }

  return { success: false, error: 'Timeout' }
}

Next Steps

• Update a Payment Intent - Modify payment details before confirmation
• Set up Webhooks - Receive real-time status updates instead of polling