Skip to main content

Update a Payment Intent

Update a Payment Intent to modify its details before it's confirmed and paid.

Endpoint​

PATCH /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​

ParameterTypeRequiredDescription
idstringYesThe ID of the Payment Intent to update (e.g., 550e8400-e29b-41d4-a716-446655440000).

Request Body​

All fields are optional. Only include the fields you want to update.

{
  "amount": "150.00",
  "currency": "usd",
  "description": "Updated payment description",
  "metadata": {
    "order_id": "12345",
    "updated_at": "2024-01-01T12:00:00Z"
  },
  "return_url": "https://merchant.example.com/new-return",
  "cancel_url": "https://merchant.example.com/new-cancel",
  "withdrawal_addresses": { "evm": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" }
}

Parameters​

ParameterTypeRequiredDescription
amountstringNoUpdate the amount to charge. Must be a positive number.
currencystringNoUpdate the currency code.
descriptionstringNoUpdate the description.
metadataobjectNoUpdate the metadata. This will merge with existing metadata.
return_urlstringNoUpdate the return URL.
cancel_urlstringNoUpdate the cancel URL.
withdrawal_addressesobjectNoWithdrawal addresses by chain type. Omit to use your account default.

:::warning Note You can only update a Payment Intent if its status is requires_payment_method or requires_confirmation. Once a payment is processing or succeeded, it cannot be updated. :::

Response​

Success Response​

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "150.00",
  "currency": "usd",
  "status": "requires_payment_method",
  "paymentMethodTypes": ["crypto"],
  "returnUrl": "https://merchant.example.com/new-return",
  "cancelUrl": "https://merchant.example.com/new-cancel",
  "description": "Updated payment description",
  "metadata": {
    "order_id": "12345",
    "updated_at": "2024-01-01T12:00:00Z"
  },
  "paymentLink": {
    "id": 1,
    "link": "https://pay.orcarail.com/pay/pl_abc123"
  },
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Example​

cURL​

curl https://api.orcarail.com/api/v1/payment_intents/550e8400-e29b-41d4-a716-446655440000 \
  -X PATCH \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "150.00",
    "description": "Updated payment description"
  }'

JavaScript (Node.js)​

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

const response = await fetch(
  `https://api.orcarail.com/api/v1/payment_intents/${paymentIntentId}`,
  {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: '150.00',
      description: 'Updated payment description',
      metadata: {
        order_id: '12345',
        updated_at: new Date().toISOString(),
      },
    }),
  }
)

const updatedIntent = await response.json()
console.log('Updated Amount:', updatedIntent.amount)

Python​

import requests

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

response = requests.patch(
    f'https://api.orcarail.com/api/v1/payment_intents/{payment_intent_id}',
    headers={
        'Authorization': f'Bearer {jwt_token}',
        'Content-Type': 'application/json',
    },
    json={
        'amount': '150.00',
        'description': 'Updated payment description',
        'metadata': {
            'order_id': '12345',
            'updated_at': '2024-01-01T12:00:00Z',
        },
    },
)

updated_intent = response.json()
print(f"Updated Amount: {updated_intent['amount']}")

Use Cases​

Update Amount After Cart Changes​

If a customer modifies their cart before checkout, update the Payment Intent amount:

async function updateCartTotal(paymentIntentId, newAmount) {
  const response = await fetch(
    `https://api.orcarail.com/api/v1/payment_intents/${paymentIntentId}`,
    {
      method: 'PATCH',
      headers: {
        Authorization: `Bearer ${jwtToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        amount: newAmount.toFixed(2),
      }),
    }
  )

  return await response.json()
}

Add Metadata After Order Creation​

Add order information to the Payment Intent metadata:

async function addOrderMetadata(paymentIntentId, orderId) {
  const response = await fetch(
    `https://api.orcarail.com/api/v1/payment_intents/${paymentIntentId}`,
    {
      method: 'PATCH',
      headers: {
        Authorization: `Bearer ${jwtToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        metadata: {
          order_id: orderId,
          created_at: new Date().toISOString(),
        },
      }),
    }
  )

  return await response.json()
}

Error Handling​

If you try to update a Payment Intent that's already been paid or is processing, you'll receive an error:

{
  "statusCode": 400,
  "message": "Cannot update Payment Intent with status 'succeeded'",
  "error": "Bad Request"
}

Always check the Payment Intent status before attempting to update:

async function safeUpdatePaymentIntent(paymentIntentId, updates) {
  // First, retrieve the current Payment Intent
  const getResponse = await fetch(
    `https://api.orcarail.com/api/v1/payment_intents/${paymentIntentId}`,
    {
      headers: {
        Authorization: `Bearer ${jwtToken}`,
      },
    }
  )

  const currentIntent = await getResponse.json()

  // Check if update is allowed
  const allowedStatuses = ['requires_payment_method', 'requires_confirmation']
  if (!allowedStatuses.includes(currentIntent.status)) {
    throw new Error(
      `Cannot update Payment Intent with status '${currentIntent.status}'`
    )
  }

  // Proceed with update
  const updateResponse = await fetch(
    `https://api.orcarail.com/api/v1/payment_intents/${paymentIntentId}`,
    {
      method: 'PATCH',
      headers: {
        Authorization: `Bearer ${jwtToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(updates),
    }
  )

  return await updateResponse.json()
}

Next Steps​