Skip to main content

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​

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"
}
}
}
CampoTipoObligatorioDescripción
currencystringRecomendadoMoneda de la orden. "032" = pesos argentinos (código ISO 4217).
itemsarraySíProductos que se cobran. Al menos uno.
items[].idintegerNoEl identificador del producto en tu sistema.
items[].namestringSíNombre que ve el comprador en el Checkout.
items[].unitPrice.currencystringSí"032".
items[].unitPrice.amountintegerSíPrecio unitario en centavos (ver abajo).
items[].quantityintegerSíCantidad.
redirect_urlsobjectNoAdónde vuelve el comprador después de pagar. Ver más.
webhookUrlstringNo, pero recomendadoURL a la que te avisamos el resultado del pago. Ver más.
shippingobjectNoCosto de envío. Ver más.
expireLimitMinutesintegerNoMinutos hasta que vence el link. Ver más.
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 cobraramount
$1.000,00100000
$200,6920069
$6,01601

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:

CampoPara qué
data.attributes.uuidIdentifica la orden. Guardalo asociado a tu pedido: lo vas a necesitar para consultar el estado y para reconocer el webhook.
data.attributes.links.checkoutEl link de pago que le mostrás al comprador.
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á.

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:

  1. Si configuraste webhookUrl, te avisamos el resultado a esa URL (Webhook).
  2. Si configuraste redirect_urls, lo redirigimos a tu sitio (URL de retorno).
  3. En cualquier momento podés consultar el estado de la orden (Estado de la orden).
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.