Update Ramp Intent Status

Manually update the status of a ramp intent. This is useful for cancelling intents from your frontend or marking them as completed after verifying a transaction.

PATCHhttps://api.zenpayz.com/payment/api/v1/ramp-intents/:intentId/status

Bearer · API key

Request

Headers

Header	Description
Content-Type REQUIRED	application/json
x-request-id OPTIONAL	Custom request ID for tracing

Public Endpoint

This endpoint does not require authentication headers.

Path Parameters

Parameter	Type	Description
intentId REQUIRED	string	The ramp intent ID

Body Parameters

Parameter	Type	Description
status REQUIRED	string	Target status: active, completed, or cancelled

Status Transitions

Only certain transitions are allowed. Attempting an invalid transition returns a 400 error.

Current Status	Allowed Transitions
created	active, cancelled, expired
active	completed, cancelled, expired
completed	— (terminal)
expired	— (terminal)
cancelled	— (terminal)

    ┌──────────┐
    │ created  │
    └──┬───┬───┘
       │   │
  active   cancelled / expired
       │
    ┌──▼──────┐
    │ active  │
    └──┬──┬───┘
       │  │
completed  cancelled / expired

  (completed, expired, cancelled are terminal)

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "intentId": "ri_1710345678000_a1b2c3d4e5f6g7h8",
    "status": "cancelled"
  },
  "message": "Ramp intent status updated"
}

Response Fields

Parameter	Type	Description
intentId OPTIONAL	string	The intent ID
status OPTIONAL	string	The updated status

Error Responses

Code	HTTP	Message
BAD_REQUEST	400	Invalid status transition (e.g. completed → active)
NOT_FOUND	404	Intent with the given ID does not exist

Examples

cURL

# Cancel an intent
curl -X PATCH https://api.zenpayz.com/payment/api/v1/ramp-intents/ri_1710345678000_a1b2c3d4e5f6g7h8/status \
  -H "Content-Type: application/json" \
  -d '{ "status": "cancelled" }'

# Mark as completed
curl -X PATCH https://api.zenpayz.com/payment/api/v1/ramp-intents/ri_1710345678000_a1b2c3d4e5f6g7h8/status \
  -H "Content-Type: application/json" \
  -d '{ "status": "completed" }'

JavaScript

const intentId = 'ri_1710345678000_a1b2c3d4e5f6g7h8';

// Cancel an intent (e.g. user clicks "Cancel" on your checkout page)
const response = await fetch(
  `https://api.zenpayz.com/payment/api/v1/ramp-intents/${intentId}/status`,
  {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ status: 'cancelled' }),
  }
);

const { data } = await response.json();
console.log(`Intent ${data.intentId} is now ${data.status}`);

Python

import requests

intent_id = "ri_1710345678000_a1b2c3d4e5f6g7h8"

response = requests.patch(
    f"https://api.zenpayz.com/payment/api/v1/ramp-intents/{intent_id}/status",
    json={"status": "cancelled"},
)

data = response.json()["data"]
print(f"Intent {data['intentId']} is now {data['status']}")

Next Steps

• Get Ramp Intent — Check current intent state
• List Ramp Intents — Browse all intents
• Create Ramp Intent — Create a new intent