Saltar al contenido principal

Página prediseñada (HPP)

Inicio rápido​

El inicio rápido de la integración consiste en implementar la principal llamada API que devuelve un enlace web que lleva directamente a la selección de métodos de pago.

Este enlace tendrá tres finalizaciones posibles:

  • Procesamiento correcto "success"
  • Procesamiento fallido "failure"
  • El usuario canceló la operación "cancel"

En el caso de "success", el comercio siempre tendrá que ejecutar una llamada de confirmación para realizar la captura de fondos y así poder cerrar el pedido en el sistema de venta del comercio.

Primer paso: generar URL de cobro​

POST /payment/api/v1/

El objetivo de este paso es obtener un request_id que permita realizar una confirmación de la operación. Para obtener dicho valor, el proceso debe terminar en la URL del comercio preparada para recoger el estado OK. A nivel de integración esta URL se llama payload.redirect_after.success.

Petición de ejemplo para una operación 300€:

Body
{
  "key": "key-value",
  "resource": "resource-value",
  "mode": "sha256",
  "nonce": "1234567890",
  "payload": {
    "amount": 30000,
    "currency": "EUR",
    "redirect_after": {
      "cancel": "http://httpbin.org/get?status=cancel",
      "success": "http://httpbin.org/get?status=success",
      "failure": "http://httpbin.org/get?status=failure"
    }
}
ParámetroDescripción
keyIdentificador del comercio.
modesha256 o sha512 según el algoritmo de la firma hmac empleado.
resourceIdentificador del recurso de configuración del comercio.
nonceIdentificador único de la petición, permite controlar la duplicidad de datos. Se recomienda utilizar unix timestamp con el máximo nivel de precisión.
payloadObjeto con los parámetros específicos de cada petición.
payload.amountImporte en formato entero y céntimos en la moneda elegida. Si la moneda es euro y queremos reflejar 20,25€, multiplicaremos por 100 para obtener 2025.
payload.currencyAcrónimo ISO 4217 de la moneda. Ejemplo: EUR para euro. Ver más en https://es.wikipedia.org/wiki/ISO_4217.
payload.redirect_afterObjeto con los parámetros que controlan la redirección final al comercio y que permite conocer el estado de la operación para continuar con el proceso de cierre de pedido.
payload.redirect_after.successLa operación se ha completado con éxito y se puede proceder a la confirmación del cobro. La URL de este parámetro tendrá concatenado el valor de request_id en formto QueryString.
Ejemplo:
redirect_after.success=http://httpbin.org/get?status=success
url final=http://httpbin.org/get?status=success&request_id=abcdefgh1234
payload.redirect_after.failureLa operación ha tenido algúna fallo en el procesamiento. La URL de este parámetro tendrá concatenado el valor de request_id en formto QueryString.
Ejemplo:
redirect_after.success=http://httpbin.org/get?status=failure
url final=http://httpbin.org/get?status=failure&request_id=abcdefgh1234
payload.redirect_after.cancelEl usuario ha dado al botón de cancelar o de vuelta atrás en el formulario. La URL de este parámetro tendrá concatenado el valor de request_id en formto QueryString.
Ejemplo:
redirect_after.success=http://httpbin.org/get?status=cancel
url final=http://httpbin.org/get?status=cancel&request_id=abcdefgh1234

Respuesta de ejemplo (truncado y simplificado):

Body
{
    "type": "resource.status",
    "code": "0",
    "detail": "Successful payment request.",
    "payload": {
        "url": "https://sandbox.sipay.es/payment/api/v1/6269082af97d0740ef69ec66/fastpay",
        "payment_methods": {
            "card": {
                "url": "https://sandbox.sipay.es/payment/api/v1/6269082af97d0740ef69ec66/card",
                "supports_card_data": true,
                "supports_security_data": true,
                "supports_tokenization": true,
                "supports_recurring": true,
                "available_card_capturers": [
                    "gpay",
                    "apay"
                ],
                "supports_refund": true,
                "supports_direct_payment": false
            },
        }
    },
    "request_id": "6269082af97d0740ef69ec66",
    "uuid": "6269082af97d0740ef69ec66"
}

Deberemos utilizar el campo url y enviarlo al navegador para que el consumidor puede iniciar la selección del método de pago.
El valor del request_id es importante almacenarlo porque nos permitirá realizar operaciones posteriores como:

Puedes encontrar más información sobre el API en este enlace

Segundo paso: confirmar operación​

POST /payment/api/v1/{request_id}

Una vez que hemos recogido el valor del request_id en el url indicada en payload.redirect_after.success, programaremos esta petición API para confirmar la operación y capturar los fondos.

{
  "key": "key-value",
  "resource": "resource-value",
  "mode": "sha256",
  "nonce": "1234567890",
  "payload": {
    }
}
ParámetroDescripción
keyIdentificador del comercio.
modesha256 o sha512 según el algoritmo de la firma hmac empleado.
resourceIdentificador del recurso de configuración del comercio.
nonceIdentificador único de la petición, permite controlar la duplicidad de datos. Se recomienda utilizar unix timestamp con el máximo nivel de precisión.
payloadObjeto con los parámetros específicos de cada petición. En este caso irá vacío porque es el ejemplo del inicio rápido y no es necesario personalizar nada más.

Respuesta prototipo:

{
    "type": "resource.status",
    "code": "0",
    "detail": "Operation confirmed successfully",
    "payload": {
					...
        }
    },
    "request_id": "6242d085b19538c1ea4ccff1",
    "uuid": "6242d085b19538c1ea4ccff1"
}

El código 0 indicará que la operación se ha completado con éxito.

Respuesta completa de un cobro con tarjeta realizado con éxito
{
    "type": "resource.status",
    "code": "0",
    "detail": "Operation confirmed successfully",
    "payload": {
        "extra": {
            "code": "0",
            "amount": "15000",
            "currency": "EUR",
            "order": "92b2e95848fe403881973973438c44d9",
            "card_trade": "undefined",
            "card_type": "undefined",
            "masked_card": "6712 00** ****0205",
            "reconciliation": "",
            "transaction_id": "000027346264324805241",
            "cof_id": "009034153465",
            "authorizator": "BANCO SANTANDER, S.A.",
            "approval": "293950",
            "card_country": "undefined",
            "card_brand": "MAESTRO",
            "expiration": "1122"
        }
    },
    "request_id": "6242d8b356d30070b6798d3f",
    "uuid": "6242d8b356d30070b6798d3f"
}
precaución

Si confirmas dos o más veces un cobro ya realizado, recibirás este mensaje. Con el request_id podrás realizar una consulta para ver el resultado.

respuesta de un cobro ya confirmado
{
    "type": "resource.status",
    "code": "-1",
    "detail": "An error happened upon confirmation",
    "payload": {
        "extra": {
            "operation_status": "already_confirmed",
            "payload": {}
        }
    },
    "request_id": "6242d79756d30070b6798d2c",
    "uuid": "6242d79756d30070b6798d2c"
}

Si ejecutáramos la llamada API:

GET /payment/api/v1/6242d79756d30070b6798d2c?key=key-value&resource=resource-value&mode=sha256&nonce=1234567890

obtendríamos la siguiente respuesta:

consulta de una operación
{
    "type": "resource.status",
    "code": "0",
    "detail": "Operation status retrieved successfully",
    "payload": {
        "code": 0,
        "amount": 15000,
        "order": "92b2e95848fe403881973973438c44d9",
        "currency": "EUR",
        "payment_method_name": "not_started",
        "cart": {
            "items": [
                {
                    "sku": "MYSKU",
                    "tax": "11",
                    "name": "item name",
                    "quantity": "10",
                    "amount": 10,
                    "image": "https://assets.codepen.io/8146504/8E370E15-031D-491D-A388-C35101A271FC.jpeg"
                }
            ]
        },
        "events": {
            "create_session": [
                {
                    "triggered_at": "2022-10-31T16:30:46Z",
                    "extra": {}
                }
            ]
        },
        "extra": {}
    },
    "request_id": "6242d79756d30070b6798d2c",
    "uuid": "635fea26198fd062244ec736"
}

Puedes encontrar más información sobre el API en este enlace