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
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. |
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
- Node.js
- PHP
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"
}
}
}'
// Node.js 18 o superior (fetch incluido)
const res = await fetch(`${BASE_URL}/api/v2/orders`, {
method: 'POST',
headers: {
Authorization: `Bearer ${accessToken}`,
'Content-Type': 'application/vnd.api+json',
},
body: JSON.stringify({
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',
},
},
}),
});
const order = (await res.json()).data.attributes;
// Guardá order.uuid junto a tu pedido y mostrale al comprador order.links.checkout
console.log(order.uuid, order.links.checkout);
<?php
$body = [
'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',
],
],
];
$curl = curl_init($baseUrl . '/api/v2/orders');
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $accessToken,
'Content-Type: application/vnd.api+json',
],
CURLOPT_POSTFIELDS => json_encode($body, JSON_UNESCAPED_SLASHES),
]);
$response = json_decode(curl_exec($curl), true);
curl_close($curl);
$order = $response['data']['attributes'];
// Guardá $order['uuid'] junto a tu pedido y mostrale al comprador $order['links']['checkout']
$checkoutUrl = $order['links']['checkout'];
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. |
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).
- 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
uuidde cada orden junto a tu pedido. - Tu webhook responde rápido con
200y 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.