Request to Pay (R2P) | Sipay Developers

tip

Antes de seguir leyendo, necesitarás conocer las siguientes secciones:

Request to Pay es un flujo de pago que permite a los comercios solicitar un pago directamente a través de la app bancaria del cliente. En lugar de introducir datos de pago en una web o app externa, el cliente recibe una notificación push en su aplicación bancaria y autoriza el pago desde ahí de forma segura y cómoda.

Paso 1: Petición inicial

POST /altp/v1/methods

API Request

amount (string, required): Importe de la operación en céntimos
currency (string, required): Será vida cualquier moneda definida según el ISO_4217 EUR. Para Bizum, la moneda siempre será EUR.
order (string): Ticket de la operación. No puede ser superior a 12 caracteres ni contener caracteres especiales. ^[a-zA-Z0-9]12$
phone_number (string, required): Número de teléfono del cliente +34600000000
policy_data (object): Datos de la política de pago {}
auto_confirm (boolean, required): Si la confirmación de la operación se realizará automáticamente false
notify.result (string, required): URL a la que se redireccionará cuando la operación sea completada. Se añadirá el request_id al final de la URL. https://www.example.com/. En el caso de Bizum R2P no se enviará ningun mensaje pero si debe estar presente el campo.

{
    "key": "{{key}}",
    "resource": "{{resource}}",
    "nonce": "{{nonce}}",
    "mode": "sha256",
    "payload": 
    {
	   "order": "{{order}}",
       "phone_number": "+34600000000",
	   "policy_data": {},
	   "amount": "50",
	   "currency": "EUR",
	   "notify": {
	       "result": "https://www.example.com/
	   },
       "auto_confirm": false
	}
}

API Response

uuid (string): Identificador único de la petición, imprescindible para la trazabilidad.
code (string): Código identificador del resultado. 0 es ok, todo lo demás debe ser tratado como un error.
request_id (string): Identificador único de la operación y necesario para realizar todas las operaciones posteriores.
payload.methods.bizum.enabled (boolean): Si el método de pago Bizum R2P está disponible para el cliente.
payload.methods.bizum.r2p_url (string): URL para el paso dos (GET).

{
    "type": "success",
    "code": "0",
    "detail": "payment_methods",
    "description": "Payment methods available",
    "payload": {
        "methods": {
            "bizum": {
                "url": "https://live.sipay.es/altp/v1/bizum/redirect/<request_id>/",
                "enabled": "true",
                "r2p_url": "https://live.sipay.es/altp/v1/bizum/init_r2p/<request_id>/"
            }
        }
    },
    "uuid": "1cace4e8-b9cc-4d36-a11e-f0609e0310ed",
    "request_id": "<request_id>"
}

Decidir entre `"auto_confirm"=true` y `"auto_confirm"=false`

Si realiza la integración con la confirmación automática ("auto_confirm"=true), la confirmación de la operación se realizará automáticamente y no se necesitará realizar ninguna llamada a la API de confirmación. Tendrá que realizar consultas frecuentes al endpoint de estado de la operación para verificar si la operación ha sido confirmada.

Si realiza la integración con la confirmación manual ("auto_confirm"=false), la confirmación de la operación se realizará manualmente y se necesitará realizar una llamada a la API de confirmación server-to-server. Tendrá que realizar una llamada a la API de confirmación server-to-server cuando el cliente haya confirmado la operación en la aplicación de Bizum. Para saber si el cliente ha autorizado la operación, tendrá que realizar una consulta al endpoint de estado de la operación.

Paso 2: Iniciar Request to Pay

GET /altp/v1/bizum/init_r2p/<request_id>/

API Request

Realice una petición GET a la URL proporcionada en el campo r2p_url del response de la petición inicial siempre y cuando venga a true el campo enabled en el response de la petición inicial.

API Response

{
  "type": "success",
  "code": "0",
  "detail": "bizum_init_r2p_ok",
  "description": "Bizum R2P operation initialized",
  "payload": {
    "id": "33m9ZrgilhQGjU1X77aqagCFykh",
    "store_id": "12345",
    "object": "payment",
    "amount": 50,
    "currency": "EUR",
    "order": "amg100925r2",
    "created": 1759911438,
    "authorization": null,
    "status": "requires_confirmation",
    "canceled_at": null,
    "cancellation_reason": null,
    "metadata": {},
    "phone": "+34600000000",
    "payment_method": "bizum",
    "operation_id": "62276626246072388252847933780633322",
    "truncated_account": null
  },
  "uuid": "1384f59d-a1f0-4b61-8f39-2066f244f312",
  "request_id": "<request_id>"
}

code (string): Código identificador del resultado. 0 es ok, todo lo demás debe ser tratado como un error.

Errores comunes

Un posible error común es no haber enviado un order correcto, que cumpla las restricciones. En estos casos la respuesta será:

{
  "type": "error",
  "code": "-1",
  "detail": "bizum_init_r2p_ko",
  "description": "Bizum R2P operation initialization error",
  "payload": {
    "type": "invalid_request_error",
    "message": "Validation failed for the request",
    "param": "('body', 'order') -> String should match pattern '^[a-zA-Z0-9]{4,12}$'"
  },
  "uuid": "92854831-ae3f-47f3-9743-0945101af701",
  "request_id": "<request_id>"
}

Paso 3: Consultar estado [auto_confirm=false]

POST /altp/v1/bizum/operation_status/

Se recomienda realizar consultas frecuentes al endpoint de estado de la operación para verificar si la operación ha sido confirmada.

El algoritmo para la consulta de estado de la operación dependerá del valor de "auto_confirm".

Si "auto_confirm"=true, se consulta cada segundo hasta obtener "code": "0" y "detail": "bizum_status_ok" para continuar con la confirmación, hasta un máximo de 180 segundos.
Si "auto_confirm"=false, se consulta cada segundo hasta obtener "code": "0" y "detail": "bizum_status_requires_confirmation" para continuar con la confirmación, hasta un máximo de 180 segundos.

API Request

{
    "key": "{{key}}",
    "resource": "{{resource}}",
    "nonce": "{{nonce}}",
    "mode": "sha256",
    "payload": {
      "request_id": "<request_id>",
      "type": "operation"
    }
}

API Response

✅ Estado después del GET inicial

{
    "type": "error",
    "code": "-1",
    "detail": "bizum_status_pending",
    "description": "Bizum R2P operation requires user action",
    "payload": {
        "status": "pending",
        "payment_id": "33m9ZrgilhQGjU1X77aqagCFykh",
        "amount": 50,
        "currency": "EUR",
        "order": "{{order}}",
        "phone_number": "+34600000000"
    },
    "uuid": "fd0d6833-0dd5-43da-b4a0-dd27eb005ad7",
    "request_id": "<request_id>"
}

✅ Estado después de que el usuario haya autorizado la operación en su móvil pero aún queda capturar los fondos con el `confirm`

{
    "type": "success",
    "code": "0",
    "detail": "bizum_status_requires_confirmation",
    "description": "Bizum R2P operation requires confirmation",
    "payload": {
        "status": "requires_confirmation",
        "payment_id": "33m9ZrgilhQGjU1X77aqagCFykh",
        "amount": 50,
        "currency": "EUR",
        "order": "{{order}}",
        "phone_number": "+34600000000"
    },
    "uuid": "2c3d97fb-71d6-4078-a4df-0cf8556d0b2c",
    "request_id": "<request_id>"
}

✅ Estado después de que el usuario haya autorizado la operación en su móvil y se haya capturado los fondos con el `confirm`

{
    "type": "info",
    "code": "0",
    "detail": "bizum_status_ok",
    "description": "Operation status retrieved",
    "payload": {
        "status": "succeeded",
        "payment_id": "33mAUWcWOKpdT3eAuUVpmDW8o8L",
        "amount": 50,
        "currency": "EUR",
        "order": "{{order}}",
        "phone_number": "+34600000000"
    },
    "uuid": "88f22ce5-c0c1-49ff-9f36-8f07b988007e",
    "request_id": "<request_id>"
}

❌ Estado que requiere que se haga el GET de la operación

{
    "type": "error",
    "code": "-1",
    "detail": "bizum_status_ko",
    "description": "Can't retrieve operation status from bizum",
    "payload": {},
    "uuid": "6767ec1a-d53d-4674-8933-64021b62b2de",
    "request_id": "<request_id>"
}

Paso 4: Confirmar operación [auto_confirm=false]

POST /altp/v1/bizum/confirm/

API Request

{
    "key": "{{key}}",
    "resource": "{{resource}}",
    "nonce": "{{nonce}}",
    "mode": "sha256",
    "payload": {
        "request_id": "<request_id>"
    }
}

API Response

{
    "type": "success",
    "code": "0",
    "detail": "Confirm successfull",
    "payload": {
        "id": "33m9ZrgilhQGjU1X77aqagCFykh",
        "store_id": "12345",
        "object": "payment",
        "amount": 50,
        "currency": "EUR",
        "order": "{{order}}",
        "created": 1759911438,
        "authorization": "061777",
        "status": "succeeded",
        "canceled_at": null,
        "cancellation_reason": null,
        "metadata": null,
        "phone": "+34600000000",
        "payment_method": "bizum",
        "operation_id": "62276626246072388252847933780633322",
        "truncated_account": "ES34XXXXXXXXXXXXXXXX0755",
        "code": "0",
        "status_code": "CJ00000"
    },
    "uuid": "c882e275-8d6d-4871-a171-3c4fca76c472",
    "request_id": "<request_id>"
}

Devoluciones

POST /altp/v1/bizum/refund/

API Request

amount (string, required): Importe de la operación en céntimos a devolver.
request_id (string, required): Identificador único de la operación.

{
    "key": "{{key}}",
    "resource": "{{resource}}",
    "nonce": "{{nonce}}",
    "mode": "sha256",
    "payload": {
        "request_id": "<request_id>",
        "amount": "50"
    }
}

API Response

code (string): Código identificador del resultado. 0 es ok, todo lo demás debe ser tratado como un error.

{
    "type": "success",
    "code": "0",
    "detail": "Refund successfull",
    "payload": {
        "id": "33mAAaJ0AkxutRXILGtVPw1t9qt",
        "object": "refund",
        "amount": 50,
        "currency": "EUR",
        "order": "{{order}}",
        "created": 1759911730,
        "payment_id": "33m9ZrgilhQGjU1X77aqagCFykh",
        "authorization": null,
        "status": "succeeded",
        "cancellation_reason": "requested",
        "metadata": {},
        "payment_method": "bizum",
        "operation_id": "824841ff-05c5-4250-b287-501a8927943",
        "code": "0",
        "status_code": "CJ00000"
    },
    "uuid": "cdcb4e8d-8f3e-4272-922e-c88e3c07fc24",
    "request_id": "<request_id>"
}

Paso 1: Petición inicial​

API Request​

API Response​

Decidir entre "auto_confirm"=true y "auto_confirm"=false​

Paso 2: Iniciar Request to Pay​

API Request​

API Response​

Paso 3: Consultar estado [auto_confirm=false]​

API Request​

API Response​

✅ Estado después del GET inicial​

✅ Estado después de que el usuario haya autorizado la operación en su móvil pero aún queda capturar los fondos con el confirm​

✅ Estado después de que el usuario haya autorizado la operación en su móvil y se haya capturado los fondos con el confirm​

❌ Estado que requiere que se haga el GET de la operación​

Paso 4: Confirmar operación [auto_confirm=false]​

API Request​

API Response​

Devoluciones​

API Request​

API Response​

Paso 1: Petición inicial

API Request

API Response

Decidir entre `"auto_confirm"=true` y `"auto_confirm"=false`

Paso 2: Iniciar Request to Pay

API Request

API Response

Paso 3: Consultar estado [auto_confirm=false]

API Request

API Response

✅ Estado después del GET inicial

✅ Estado después de que el usuario haya autorizado la operación en su móvil pero aún queda capturar los fondos con el `confirm`

✅ Estado después de que el usuario haya autorizado la operación en su móvil y se haya capturado los fondos con el `confirm`

❌ Estado que requiere que se haga el GET de la operación

Paso 4: Confirmar operación [auto_confirm=false]

API Request

API Response

Devoluciones

API Request

API Response