Skip to main content
PATCH
/
payment_requests
/
{payment_request_id}
Update a payment request
curl --request PATCH \
  --url https://api.withacclaim.com/v1/payment_requests/{payment_request_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "Updated premium payment for policy #POL-2025-001",
  "reference": "ORD-2025-002",
  "amount": 20000,
  "currency": "USD",
  "requires_tokenization": true,
  "allows_tokenization": true,
  "expires_at": "2025-12-31T23:59:59Z",
  "payer_id": "pyr_AbC123XyZ",
  "payment_method_id": "pm_AbC123XyZ",
  "payment_method": {},
  "ip_address": "192.168.1.1",
  "user_agent": "Mozilla/5.0...",
  "metadata": {
    "custom_field": "value",
    "source": "api"
  }
}
'
{
  "id": "prq_AbC123XyZ",
  "status": "RequiresPaymentMethod",
  "amount": 125000,
  "currency": "USD",
  "payer_id": "pyr_AbC123XyZ",
  "description": "Premium payment for policy #POL-2025-001",
  "reference": "ORD-2025-001",
  "idempotency_key": "idem_ord_2025_001",
  "requires_tokenization": false,
  "allows_tokenization": false,
  "payment_method": {},
  "session_identifier": "prq_AbC123XyZ_abc123...",
  "shipping_address": {
    "country": "US",
    "address1": "123 Main St",
    "address2": "Suite 100",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001"
  },
  "failure_code": "card_declined",
  "failure_message": "Card was declined",
  "expires_at": "2025-12-31T23:59:59Z",
  "completed_at": "2025-10-08T18:25:00Z",
  "ip_address": "192.168.1.1",
  "user_agent": "Mozilla/5.0...",
  "metadata": {
    "custom_field": "value",
    "source": "api"
  },
  "created_at": "2025-10-08T18:20:31Z",
  "updated_at": "2025-10-08T18:25:00Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.withacclaim.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
payment_request_id
string
required

ID of the payment request.

Body

application/json
​
description
string | null

Description of the payment request

Maximum string length: 255
Example:

"Updated premium payment for policy #POL-2025-001"

​
reference
string | null

Client-supplied identifier for reconciliation

Maximum string length: 255
Example:

"ORD-2025-002"

​
amount
integer | null

Amount in smallest currency unit (must provide both amount and currency)

Required range: x >= 1
Example:

20000

​
currency
string | null

ISO 4217 currency code (3 uppercase letters, must provide both amount and currency)

Required string length: 3
Pattern: ^[A-Z]{3}$
Example:

"USD"

​
requires_tokenization
boolean

Whether this payment request requires tokenization of the payment method

​
allows_tokenization
boolean

Whether this payment request allows tokenization of the payment method

​
expires_at
string<date-time> | null

When the payment request expires (ISO 8601 date-time string)

Example:

"2025-12-31T23:59:59Z"

​
payer_id
string | null

ID of the payer to associate with this payment request

Example:

"pyr_AbC123XyZ"

​
payment_method_id
string | null

ID of an existing payment method to use (must belong to the payer if payer_id is provided)

Maximum string length: 255
Example:

"pm_AbC123XyZ"

​
payment_method
object

Payment method data (e.g., payment_token, payment_method type)

​
ip_address
string | null

IP address of the client making the payment

Example:

"192.168.1.1"

​
user_agent
string | null

User agent string of the client making the payment

Example:

"Mozilla/5.0..."

​
metadata
object

Optional metadata as key-value pairs

Example:
{ "custom_field": "value", "source": "api" }

Response

Payment request updated successfully.

​
id
string
Example:

"prq_AbC123XyZ"

​
status
enum<string>

Current status of the payment request

Available options:
RequiresPaymentMethod,
RequiresAction,
Processing,
Authorized,
Succeeded,
Failed,
Canceled
Example:

"RequiresPaymentMethod"

​
amount
integer

Amount in smallest currency unit

Example:

125000

​
currency
string

ISO 4217 currency code

Example:

"USD"

​
payer_id
string | null

ID of the payer associated with this payment request

Example:

"pyr_AbC123XyZ"

​
description
string
Example:

"Premium payment for policy #POL-2025-001"

​
reference
string

Client-supplied identifier

Example:

"ORD-2025-001"

​
idempotency_key
string | null

Client-supplied idempotency key set at creation

Maximum string length: 255
Example:

"idem_ord_2025_001"

​
requires_tokenization
boolean

Whether this payment request requires tokenization of the payment method

Example:

false

​
allows_tokenization
boolean

Whether this payment request allows tokenization of the payment method

Example:

false

​
payment_method
object

Payment method associated with this payment request

​
session_identifier
string

External session identifier for this payment request

Example:

"prq_AbC123XyZ_abc123..."

​
shipping_address
object

Shipping address for this payment request

​
failure_code
string | null

Error code if the payment request failed

Example:

"card_declined"

​
failure_message
string | null

Human-readable error message if the payment request failed

Example:

"Card was declined"

​
expires_at
string<date-time> | null

When the payment request expires

Example:

"2025-12-31T23:59:59Z"

​
completed_at
string<date-time> | null

When the payment request was completed

Example:

"2025-10-08T18:25:00Z"

​
ip_address
string | null

IP address of the client making the payment

Example:

"192.168.1.1"

​
user_agent
string | null

User agent string of the client making the payment

Example:

"Mozilla/5.0..."

​
metadata
object

Optional metadata as key-value pairs

Example:
{ "custom_field": "value", "source": "api" }
​
created_at
string<date-time>
Example:

"2025-10-08T18:20:31Z"

​
updated_at
string<date-time>
Example:

"2025-10-08T18:25:00Z"

Last modified on May 26, 2026