Consultas de estado

Cada pago en Cost+ esta representado por un pedido que contiene una o mas transacciones. Puedes consultar el estado actual de cualquier pedido mediante la API, ya sea por polling o mediante webhooks.

Consultar el estado del pedido

Envia una solicitud GET a /v1/orders/\{id\}/ para obtener el objeto completo del pedido, incluyendo su estado actual y todas las transacciones asociadas.

GET /v1/orders/b9ae6.../

Aunque el polling funciona para consultar el estado del pedido, los webhooks son el enfoque recomendado para integraciones en produccion. Proporcionan notificaciones en tiempo real sin la sobrecarga de llamadas repetidas a la API.

Estados del pedido

Un pedido progresa a traves de los siguientes estados:

Estado	Final	Descripcion
`new`	No	El pedido acaba de crearse. No se ha realizado ningun intento de pago.
`processing`	No	Un intento de pago esta en curso. El cliente puede estar completando 3D Secure u otro paso de verificacion.
`error`	No	El intento de pago fallo. El cliente puede reintentar con el mismo u otro metodo de pago.
`completed`	Si	El pago fue exitoso. Puedes procesar el pedido.
`cancelled`	Si	El pedido fue cancelado, ya sea por el cliente o a traves de la API.
`expired`	Si	El pedido expiro antes de que se realizara un pago exitoso. El periodo de expiracion predeterminado es de 30 minutos.

Solo los estados marcados como Final = Si son terminales. Los pedidos en estado new, processing o error aun pueden transicionar a completed.

Ejemplo: Pedido en procesamiento

Cuando un cliente ha iniciado el pago pero aun no se ha completado:

{
  "id": "b9ae6...",
  "project_id": "proj_abc123",
  "merchant_order_id": "my-order-id-1",
  "created": "2024-01-01T12:00:00.000000+00:00",
  "modified": "2024-01-01T12:01:30.000000+00:00",
  "completed": null,
  "expiration_period": "PT30M",
  "status": "processing",
  "currency": "EUR",
  "amount": 1295,
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "payment_url": "https://pay.costplus.com/...",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    {
      "id": "txn_001...",
      "payment_method": "credit-card",
      "payment_method_brand": "visa",
      "status": "processing",
      "amount": 1295,
      "currency": "EUR"
    }
  ],
  "flags": ["is-test"]
}

Ejemplo: Pedido completado

Una vez que el pago es exitoso, el pedido alcanza el estado completed:

{
  "id": "b9ae6...",
  "project_id": "proj_abc123",
  "merchant_order_id": "my-order-id-1",
  "created": "2024-01-01T12:00:00.000000+00:00",
  "modified": "2024-01-01T12:02:15.000000+00:00",
  "completed": "2024-01-01T12:02:15.000000+00:00",
  "expiration_period": "PT30M",
  "status": "completed",
  "currency": "EUR",
  "amount": 1295,
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "payment_url": "https://pay.costplus.com/...",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    {
      "id": "txn_001...",
      "payment_method": "credit-card",
      "payment_method_brand": "visa",
      "payment_method_details": {
        "card_last_four": "4242",
        "card_expiry_month": 12,
        "card_expiry_year": 2026,
        "card_holder_name": "J. Smith"
      },
      "status": "completed",
      "amount": 1295,
      "currency": "EUR"
    }
  ],
  "flags": ["is-test"]
}

Detalles de la transaccion

Cada transaccion dentro de un pedido contiene los siguientes campos clave:

Campo	Descripcion
`payment_method`	El metodo de pago utilizado (ej., `credit-card`, `ideal`, `apple-pay`)
`payment_method_brand`	La marca o emisor (ej., `visa`, `mastercard`, `amex`)
`payment_method_details`	Un objeto con detalles especificos del metodo, como los ultimos cuatro digitos de la tarjeta, caducidad y nombre del titular
`status`	El estado de esta transaccion especifica
`amount`	El importe de la transaccion en centimos
`currency`	La moneda de la transaccion

No confies unicamente en que el cliente sea redirigido a tu return_url como confirmacion de pago. Verifica siempre el estado del pedido a traves de la API o mediante un webhook antes de procesar un pedido.

Endpoints relacionados

Obtener pedido — obtener el objeto completo del pedido y su estado actual
Listar pedidos — listar pedidos con filtro por rango de fechas