Integración Checkout

Con SiPago Checkout cobrás a través de nuestro formulario web, desde cualquier dispositivo. Desde tu sistema creás una orden de pago y le mostrás al comprador el link para pagarla.

Antes de empezar necesitás un access_token. Si todavía no lo tenés, mirá Requisitos para integrar.

1. Creá la orden de pago

Atención: Desde tu backend

Este paso se hace en tu servidor: necesita el token y es donde se definen los precios. Si el precio viniera del navegador, el comprador podría modificarlo.

POST {base_url}/api/v2/orders, donde {base_url} es la URL de Checkout del ambiente que uses (Ambientes).

Headers:

Authorization: Bearer {access_token}
Content-Type: application/vnd.api+json

Cuerpo del pedido

Todos los datos van dentro de data.attributes:

{
  "data": {
    "attributes": {
      "currency": "032",
      "items": [
        {
          "id": 31,
          "name": "Silla Eames Base Madera",
          "unitPrice": { "currency": "032", "amount": 100000 },
          "quantity": 1
        }
      ],
      "redirect_urls": {
        "success": "https://mitienda.com/pago-ok",
        "failed": "https://mitienda.com/pago-fallido"
      },
      "webhookUrl": "https://mitienda.com/webhooks/sipago"
    }
  }
}

Campo	Tipo	Obligatorio	Descripción
`currency`	string	Recomendado	Moneda de la orden. `"032"` = pesos argentinos (código ISO 4217).
`items`	array	Sí	Productos que se cobran. Al menos uno.
`items[].id`	integer	No	El identificador del producto en tu sistema.
`items[].name`	string	Sí	Nombre que ve el comprador en el Checkout.
`items[].unitPrice.currency`	string	Sí	`"032"`.
`items[].unitPrice.amount`	integer	Sí	Precio unitario en centavos (ver abajo).
`items[].quantity`	integer	Sí	Cantidad.
`redirect_urls`	object	No	Adónde vuelve el comprador después de pagar. Ver más.
`webhookUrl`	string	No, pero recomendado	URL a la que te avisamos el resultado del pago. Ver más.
`shipping`	object	No	Costo de envío. Ver más.
`expireLimitMinutes`	integer	No	Minutos hasta que vence el link. Ver más.

Info: Los montos van en centavos

Todos los amount son números enteros en los que los dos últimos dígitos son los centavos:

Querés cobrar	`amount`
$1.000,00	`100000`
$200,69	`20069`
$6,01	`601`

Ejemplo

curl --request POST 'https://{base_url}/api/v2/orders' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
    "data": {
      "attributes": {
        "currency": "032",
        "items": [{
          "id": 31,
          "name": "Silla Eames Base Madera",
          "unitPrice": { "currency": "032", "amount": 100000 },
          "quantity": 1
        }],
        "redirect_urls": {
          "success": "https://mitienda.com/pago-ok",
          "failed": "https://mitienda.com/pago-fallido"
        },
        "webhookUrl": "https://mitienda.com/webhooks/sipago"
      }
    }
  }'

Respuesta

Si la orden se creó bien, la respuesta es 201 Created con la orden en estado PENDING. Abreviada:

{
  "data": {
    "id": "/api/v2/orders/7c7cb233-16fe-4be4-b7f6-4f8ef6b61904",
    "type": "Order",
    "attributes": {
      "uuid": "7c7cb233-16fe-4be4-b7f6-4f8ef6b61904",
      "orderNumber": "0000169-0000386917",
      "status": "PENDING",
      "price": { "currency": "032", "amount": 100000 },
      "links": {
        "checkout": "https://checkout-mpos-cabal.stg.geopagos.io/orders/7c7cb233-16fe-4be4-b7f6-4f8ef6b61904",
        "redirect_url": {
          "success": "https://mitienda.com/pago-ok",
          "failed": "https://mitienda.com/pago-fallido"
        }
      },
      "payment": null,
      "webhookUrl": "https://mitienda.com/webhooks/sipago"
    }
  }
}

Te sirven dos campos:

Campo	Para qué
`data.attributes.uuid`	Identifica la orden. Guardalo asociado a tu pedido: lo vas a necesitar para consultar el estado y para reconocer el webhook.
`data.attributes.links.checkout`	El link de pago que le mostrás al comprador.

Atención: Ojo con la ruta del link

El link está en data.attributes.links.checkout. La respuesta también trae un data.links, pero es un array y no conviene usarlo.

Errores

Si la orden no se puede crear, la API responde con un código 4xx. El campo detail explica el motivo, y violations indica qué campo falló:

{
  "title": "An error occurred",
  "detail": "items: Se debe incluir al menos un item en la orden de compra",
  "violations": [
    { "propertyPath": "items", "message": "Se debe incluir al menos un item en la orden de compra" }
  ]
}

Si el token falta, es inválido o venció, pedí uno nuevo (Obtener el token) y reintentá.

2. Mostrá el link de pago en tu sitio

En tu frontend, agregá el link de Checkout donde quieras: como botón o con una redirección automática.

<a href="https://checkout-mpos-cabal.stg.geopagos.io/orders/7c7cb233-...">Pagar con SiPago</a>

El link no vence, salvo que le pongas un tiempo límite con expireLimitMinutes.

3. El comprador paga

El comprador completa el pago en el Checkout de SiPago. Cuando termina:

Si configuraste webhookUrl, te avisamos el resultado a esa URL (Webhook).
Si configuraste redirect_urls, lo redirigimos a tu sitio (URL de retorno).
En cualquier momento podés consultar el estado de la orden (Estado de la orden).

Consejo: Checklist antes de pasar a producción

El token se pide desde el servidor y se reutiliza hasta que vence.
Los precios se calculan en el servidor, no vienen del navegador.
Guardás el uuid de cada orden junto a tu pedido.
Tu webhook responde rápido con 200 y es idempotente.
Antes de entregar el producto, confirmás el estado con GET /api/v2/orders/{uuid}.
Cambiaste las URLs y credenciales a las de producción.