Introducción

Esta API está destinada a ser utilizada por los Bancos.

La API de pago Back Channel permite una comunicación segura de servidor a servidor entre un proveedor externo (TPP) y el proveedor de servicios de pago de administración de cuentas (ASPSP) para administrar operaciones relacionadas con pagos sin interacción directa del usuario.

Grant Type : CLIENT_CREDENTIALS (nota: es el tipo concesión requerido para el uso del API)

Esta sección proporciona una visión general sobre la integración de los bancos registrados en la plataforma de APIs de Redeban, para el flujo de SCA (Strong Customer Authentication) y Consentimiento, que incluye el Front channel (basado en navegador web) y el Back channel (basado en API).

1. Onboarding

El banco debe estar inscrito en el directorio de participantes de Redeban. Durante el proceso de onboarding, el banco puede optar por gestionar la experiencia de consentimiento (la pantalla de la interfaz de usuario que forma parte del flujo de SCA) o permitir que la plataforma de APIs de Redeban administre dicha experiencia tras una autenticación SCA exitosa con el banco.

2. Integración del Front channel (redirección basada en navegador) para el proceso de SCA/Consent.

Redirección HTTP desde la plataforma de APIs de Redeban a la URL de la aplicación SCA del banco.

Como parte del flujo de autorización iniciado por el TPP, la plataforma de APIs redirige al canal SCA del banco para que el cliente inicie sesión. La plataforma de APIs envía un JWT firmado y cifrado (codificado en base 64) como un parámetro de consulta (query parameter) en la URL SCA del banco.

El banco debe validar la firma y leer la información en el JWT para obtener el identificador del consentimiento de pago. Con esta información, el banco utiliza la API Back channel proporcionada por la plataforma de APIs para recuperar las instrucciones de pago y mostrarlas en la pantalla de inicio de sesión del cliente.

Ejemplo :

URL :

https://www.sca.bank1.com/signin?oAuthUrl=eyJraWQiOiJDNU9uTnhtbUk4WmlXVUpaYnZGMEFrbGQ1MDg9IiwidHlwIjoiSldUIiwiYWxnIjoiUFMyNTYifQ.eyJyZWZfaWQiOiIxMmFiNDI5Yy0wNGQ0LTRhN2UtODBjMS05YWVmZGUzMTVkOGUiLCJhdWQiOiIwODg4IiwibmJmIjoxNzYyNzc4MDYwLCJhY3QiOnsicmVnaXN0cmF0aW9uX25vIjoiU0MtNzUwMTlkZDctMWNkOS00YTQ5LTk2ZjYtYjA3YTU0ZjVkNGJkIiwic3ViIjoiRXZlclRydXN0IEZpbmFuY2lhbCBTZXJ2aWNlIn0sImlzcyI6Imh0dHBzOi8vYXV0aC5zdGFnZS5yZWRlYmFub3BlbmZpbmFuY2UuY29tIiwiY29ycmVsYXRpb25faWQiOiJjOTc4ZTU4My00YmIzLTQ5MjYtODFlNy01MTNlNjA1NTUwNjYiLCJleHAiOjE3NjI3ODEwNjAsImlhdCI6MTc2Mjc3ODA2MCwiZGVidG9yX2FjY291bnRfcHJlc2VudCI6dHJ1ZSwianRpIjoiZTJkNmU0M2QtM2FlMy00OTU0LTgwNWItZjA1OWVlYWMwN2Q4In0.Bm2nNfieO_nRy9g9jnEakZPtweKD2zUlayVpg_Thj8YteCECC5vdCjAViSykihRh7aYvNpqQG-FUjgTYppNE1fk_Hbhim0ZfU6bk0bg2uoYJt9SmG1MXPL6QsHF9GWZ-Vk2DjXJrs1-b2kj3q9B67acKsD3TzX0zzPMjtbLpLNsosPLfEBbV67YnRg4np4cYJKwFzZfuxek-9ZLtsW5kFfhfYU0V8hVmX5rsdjnyFpcWLbS3sfjN7Orm71lkdK3Y_RH68kAhTOaHJ-hw0cu_n0t8ChFRW7GJ4SJjYFdyhnqRBRjPvF3ouZbdjBI-FMbAgjf5vAzRmyOEK_zu_kkA3w

Estructura del JWT

Atributos del Header

Metadatos	Descripción
kid (Key ID)	Se mantendrá igual al parámetro "x5t" (Huella Digital SHA-1 del Certificado X.509) del certificado de firma. Es útil cuando el emisor tiene múltiples claves y el receptor necesita saber cuál usar para verificar la firma del token. ej. "kid": "UKuG8Os9MVy0s6sPia3HgeVy4EI="
typ (Type)	Debe estar configurado como JWT. Indica el tipo de token. En este caso, es un JSON Web Token. ej. "typ": "JWT"
alg (Algorithm)	Debe estar configurado como PS256. Especifica el algoritmo criptográfico utilizado para firmar el token. PS256 se refiere a RSASSA-PSS con SHA-256 como función hash. Es una variante más segura del algoritmo RSA. ej. "alg": "PS256"

Metadatos

Descripción

kid (Key ID)

Se mantendrá igual al parámetro "x5t" (Huella Digital SHA-1 del Certificado X.509) del certificado de firma. Es útil cuando el emisor tiene múltiples claves y el receptor necesita saber cuál usar para verificar la firma del token.

ej. "kid": "UKuG8Os9MVy0s6sPia3HgeVy4EI="

typ (Type)

Debe estar configurado como JWT. Indica el tipo de token. En este caso, es un JSON Web Token.
ej. "typ": "JWT"

alg (Algorithm)

Debe estar configurado como PS256. Especifica el algoritmo criptográfico utilizado para firmar el token. PS256 se refiere a RSASSA-PSS con SHA-256 como función hash. Es una variante más segura del algoritmo RSA.
ej. "alg": "PS256"

Claims del request

Claim	Descripción
iss	Entidad responsable de la redirección, es decir Redeban. ej. `"iss": "https://auth.stage.redebanopenfinance.com"`,
iat	Fecha de la petición. ej. "iat": 1723558658,
exp	Especifica la fecha y hora exactas en que se emitió el token. ej. "exp": 2123558658,
aud	ID del banco autorizador. ej. `"aud": "0888"`,
nbf	Marca de tiempo que indica el momento más temprano en que un token es válido para su procesamiento. ej. "nbf": 1751274882
jti	JWT ID. ej. "jti": "67751575-b5e6-4ef2-9ae9-76cc4c933a45"
debtor_account_present	Esta claim, si se establece como "true", indica que la cuenta del pagador está preseleccionada, lo que significa que se especifica en el consentimiento de pago creado por el TPP. Si se establece como "true", no se requieren el consentimiento explícito ni la selección de cuenta. Si se establece como "false", la plataforma API redirigirá a la aplicación de consentimiento para obtener el consentimiento explícito y la selección de cuenta del pagador. ej. "debtor_account_present": "true"
ref_id	Identificador de consentimiento de pago creado y almacenado en la base de datos de la plataforma API. ej. "ref_id": "aea16156-9b1f-4467-8530-6e1d5edd07d6",
act	Esto identifica al proveedor de servicios de pago (TPP) que solicita la autorización para este consentimiento de pago a través de la plataforma API. Incluye las siguientes subdeclaraciones: sub: nombre legal del TPP y número de registro: registro de la empresa. Tiene los siguientes sub-claims: sub* – Nombre legal del TPP. registration_no* – Identificador de registro de la empresa, client_id. ej: "act": { "sub" : "Company Name", "registration_no" : "SC-15e55bf8-be49-4e31-a12d-65acd396c337" },
correlation_id	Identificador único de correlación para esta interacción. El banco debe devolver el mismo valor en el JWT de respuesta a la plataforma API. Esto resulta útil para el registro de transacciones, la monitorización y la resolución de problemas. ej: "correlation_id": "857b6ed7-b74e-4b46-9bb6-a18b6515b9b3",
	Nota: el resto de los claims son estándar de JWT como aud, iss, etc.

Redirección HTTP desde el banco hacia la plataforma Redeban con JWT

Una vez completada la SCA con el banco, este envía las cuentas del ordenante y los saldos a la plataforma de APIs (siempre que la cuenta del ordenante no esté preseleccionada y requiera consentimiento explícito). El banco redirige al usuario a la URL del servidor de autenticación de la plataforma de APIs, enviando un JWT firmado y cifrado como parámetro de la URL.

Con base en los detalles del JWT, la plataforma de APIs lanza la aplicación de consentimiento (si se requiere consentimiento explícito) y emite un código de autorización al TPP. Si se detecta un error, se envía una respuesta de error al TPP.

Ejemplo :

URL :

https://auth.snd.redebanopenfinance.com/BANK1/authorization.sca.oauth2?oAuthUrl=eyJraWQiOiJ2QXp0WVAtdGFqQkM5dzVOd1l1WVVXbDF4SFU9IiwidHlwIjoiSldUIiwiYWxnIjoiUFMyNTYifQ.eyJyZWZfaWQiOiIwZmI3YTJhMi1iZThhLTQ5MWEtYWYyMi00NDliZGZmNjQ0NzEiLCJhdWQiOiJodHRwczovL2F1dGguc3RhZ2UucmVkZWJhbm9wZW5maW5hbmNlLmNvbSIsIm5iZiI6MTc2Mjc3NDM1Mywic3RhdHVzX2NvZGUiOiIyMDAiLCJiYW5rX2lkIjoiMDg4OCIsImlzcyI6IjA4ODgiLCJjb3JyZWxhdGlvbl9pZCI6IjJhM2ExNTU5LTNhYWItNDhlZi04ZTJkLWY3OGQwMGJmYmQ4MCIsImV4cCI6MTc2MzA3NDM1MywiaWF0IjoxNzYyNzc0MzUzLCJkZWJ0b3JfYWNjb3VudF9wcmVzZW50Ijp0cnVlLCJqdGkiOiJmZDBjOWNlYS0yODg3LTRhN2UtOTFjZi1kYTNhY2ZlYTBkZTUiLCJzdGF0dXMiOiJzdWNjZXNzIn0.YYn465o-5K_L8OUWQlbickeVcQnx6CL8P6xZJYNv0bSLhqE82Qz3rj_RJPRXMa_uxAtM6b_NVgskqKEk7xo5PT4vAajzmyZ2J6R4KAKTXsAc8c5y9LhNQKw_nHE3bAwlSMrjBBNlhDDSMP8rODZ4dnUVgzE-gCPE7faC6lNsunqWPqowoqOE8df0U3nygCPklGpg0yh6Wao9E5eAcK5hvwhO_nZxZtt8qtJj3ApaM447cs9iDxwr00lNK3QVL_BvWmSXBEiZHV9Syjx4Kus0jBpzh4m_zgeQ1DAk0BTfFQoydzER8vTu3PFZR1XsIu1iXpI24271wWmdVhj2jylyHA

Estructura del JWT

Atributos del Header

Metadatos	Descripción
kid (Key ID)	Se mantendrá igual al parámetro "x5t" (Huella Digital SHA-1 del Certificado X.509) del certificado de firma. Es útil cuando el emisor tiene múltiples claves y el receptor necesita saber cuál usar para verificar la firma del token. ej. "kid": "UKuG8Os9MVy0s6sPia3HgeVy4EI="
typ (Type)	Debe estar configurado como JWT. Indica el tipo de token. En este caso, es un JSON Web Token. ej. "typ": "JWT"
alg (Algorithm)	Debe estar configurado como PS256. Especifica el algoritmo criptográfico utilizado para firmar el token. PS256 se refiere a RSASSA-PSS con SHA-256 como función hash. Es una variante más segura del algoritmo RSA. ej. "alg": "PS256"

Metadatos

Descripción

kid (Key ID)

ej. "kid": "UKuG8Os9MVy0s6sPia3HgeVy4EI="

typ (Type)

Debe estar configurado como JWT. Indica el tipo de token. En este caso, es un JSON Web Token.
ej. "typ": "JWT"

alg (Algorithm)

Claims del request

Claim	Descripción
iss	Entidad responsable de la redirección, es decir el banco para este caso. ej. "iss": "https://sca.bank.com",
iat	Fecha de la petición. ej. "iat": 1723558658,
exp	Especifica la fecha y hora exactas en que se emitió el token. ej. "exp": 2123558658,
aud	Audiencia/Destinatario del Token, es decir Redeban. ej. `"aud": "https://auth.stage.redebanopenfinance.com"`
nbf	Marca de tiempo que indica el momento más temprano en que un token es válido para su procesamiento. ej. "nbf": 1751274882
jti	JWT ID. ej. "jti": "67751575-b5e6-4ef2-9ae9-76cc4c933a45"
debtor_account_present	Esta claim, si se establece como "true", indica que la cuenta del pagador está preseleccionada, lo que significa que se especifica en el consentimiento de pago creado por el TPP. Si se establece como "true", no se requieren el consentimiento explícito ni la selección de cuenta. Si se establece como "false", la plataforma API redirigirá a la aplicación de consentimiento para obtener el consentimiento explícito y la selección de cuenta del pagador. ej. "debtor_account_present": "true"
ref_id	Identificador de consentimiento de pago creado y almacenado en la base de datos de la plataforma API. ej. "ref_id": "aea16156-9b1f-4467-8530-6e1d5edd07d6",
status	En este identificador se refleja el estado del redireccionamiento dese el banco hacia el ecosistema para redireccionar al usuario al siguiente paso del flujo. ej. "status": "success"
correlation_id	Identificador único de correlación para esta interacción. El banco debe devolver el mismo valor en el JWT de respuesta a la plataforma API. Esto resulta útil para el registro de transacciones, la monitorización y la resolución de problemas. ej: "correlation_id": "857b6ed7-b74e-4b46-9bb6-a18b6515b9b3",
bank_id	Se utiliza para identificar el banco específico. ej. "bank_id": "0888"
status_code	Es el claim mediate el cual retorna el resultado de la interacción con el usuario e indica si fue fallido o exitoso. ej. "status_code": "200"
	Nota: el resto de los claims son estándar de JWT como aud, iss, etc.

3. Integración del Back channel

Por razones de seguridad, la plataforma de Redeban requiere que los bancos se integren con las APIs de Back channel para facilitar:

La recuperación de la información del consentimiento de pago desde la plataforma, de modo que el banco pueda utilizar esta información para mostrarla en la pantalla SCA.

Ejemplo :

Solicitud

curl --location 'https://api.snd.redebanopenfinance.com/BANCO/back-channel-auth/v1/754cbc56-8cf1-4415-8506-cb966275c616' \
--header 'Authorization: DPoP nFjKmCi1Ge7b6K0_KKJwqPEno4wGIluqYbiRdJX2ch4' \
--header 'DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IlBTMjU2Ii1' \
--header 'x-fapi-interaction-id: stxctsud8283' \
--header 'x-fapi-auth-date: Tue, 11 Sep 2012 19:43:31 GMT' \
--header 'x-fapi-customer-ip-address: 1.0.0.233' \

Respuesta

{
   "Data": {
       "ReadRefundAccount": "Yes",
       "Initiation": {
           "InstructionIdentification": null,
           "EndToEndIdentification": null,
           "InstructedAmount": {
               "Amount": "10.15",
               "Currency": "GBP"
           },
           "DebtorAccount": {
               "SchemeName": "UK.OBIE.IBAN",
               "Identification": "IE64IRCE92050112345678",
               "Name": "JESSICA",
               "SecondaryIdentification": "54988"
           },
           "CreditorAccount": {
               "SchemeName": "SortCodeAccountNumber",
               "Identification": "08080021325698",
               "Name": "Test user",
               "SecondaryIdentification": "0002"
           }
       },
       "Authorisation": {
           "AuthorisationType": "Any"
       }
   },
   "Risk": {
       "PaymentContextCode": "Other",
       "MerchantCategoryCode": "5967",
       "MerchantCustomerIdentification": "053598653254",
       "DeliveryAddress": {
           "AddressLine": [
               "Flat 7",
               "Acacia Lodge"
           ],
           "StreetName": "AcaciaAvenue",
           "BuildingNumber": "27",
           "PostCode": "7U31 2ZZ",
           "TownName": "Sparsholt",
           "Country": "Columbia"
       }
   }
}

Adicionalmente, si la cuenta del ordenante no está preseleccionada en el consentimiento de pago en el lado del TPP, durante el proceso de SCA/Consent, el banco puede invocar la API de Back channel para actualizar la lista de cuentas del pagador del usuario asociadas a este consentimiento. Esto permite que la plataforma de Redeban muestre la lista de cuentas y saldos en la pantalla de consentimiento, para que el usuario seleccione la cuenta para el pago y complete el proceso de consentimiento. Es importante tener en cuenta que, si el banco ha elegido gestionar la experiencia de la interfaz de usuario de consentimiento durante el onboarding, este solo necesita enviar la cuenta del pagador seleccionada a la plataforma de Redeban en lugar de la lista de cuentas utilizando la API de Back channel.

Ejemplo :

Solicitud

curl --location --request PUT 'https://api.snd.redebanopenfinance.com/stage/BANCO/back-channel-auth/v1/754cbc56-8cf1-4415-8506-cb966275c616' \
--header 'Authorization: DPoP nFjKmCi1Ge7b6K0_KKJwqPEno4wGIluqYbiRdJX2ch4' \
--header 'DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IlBTMjU2Ii' \
--header 'Content-Type: application/json' \
--header 'x-jws-signature: dfegregerg' \
--header 'x-fapi-interaction-id: stxctsud8283' \
--header 'x-fapi-auth-date: Tue, 11 Sep 2012 19:43:31 GMT' \
--header 'x-fapi-customer-ip-address: 1.0.0.233' \
--data '{
 
{
 "Data": {
    "BankId": "BOIUK",
    "ConsentId": "6716639433018b71060b83a1",
   "ConsentId": "6716639433018b71060b83a1",
   "Sub": "john",
   "DebtorAccount": [
     {
       "SchemeName": "IBAN",
       "Identification": "GB29NWBK60161331926818",
       "Balance": "22978250107",
       "Currency": "VWB",
       "SecondaryIdentification": "12345678"
     }
   ]
 }
}
}'

Respuesta

{
   "Data": {
       "BankId": "BOIUK",
       "ConsentId": "6716639433018b71060b83a1",
       "Sub": "john",
       "DebtorAccount": [
           {
               "SchemeName": "IBAN",
               "Identification": "GB29NWBK60161331926818",
               "Balance": "22978250107",
               "Currency": "VWB",
               "SecondaryIdentification": "12345678"
           }
       ]
   }
}

4. Resumen de los requerimientos de integración según el tipo de flujo de SCA/Consent iniciado por el TPP para el pago

Tipo de flujo de consentimiento	Integración bancaria
Implícito (La cuenta del pagador está preseleccionada por el usuario en la interfaz del TPP).	Se requiere recibir un JWT firmado desde la plataforma de Redeban como parte de la redirección del navegador a la aplicación SCA. Utilizar el ID de consentimiento en el JWT para obtener más detalles sobre el consentimiento invocando la API Back channel. GET /{BankId}/back-channel-auth/v1/{ConsentId} Mostrar información de pago en la pantalla SCA y realizar el proceso de SCA. Redirigir de vuelta a la URL de redirección de Redeban con un JWT firmado por el banco con la información de éxito o fallo.
Explícito (con la experiencia de la interfaz de usuario de consentimiento, gestionada por la plataforma de APIs de Redeban).	Se requiere recibir un JWT firmado desde la plataforma de Redeban como parte de la redirección del navegador a la aplicación SCA. Realizar el proceso de SCA con el usuario. Utilizar el ID de consentimiento en el JWT para actualizar la lista de cuentas del pagador y saldos, invocando la API Back channel. PUT /{BankId}/back-channel-auth/v1/{ConsentId} Redirigir de vuelta a la URL de redirección de Redeban con un JWT firmado por el banco con la información de éxito o fallo.
Explícito (con la experiencia de la interfaz de usuario de consentimiento gestionada por el banco registrado).	Se requiere recibir un JWT firmado desde la plataforma de Redeban como parte de la redirección del navegador a la aplicación SCA. Realizar el proceso de SCA con el usuario. Utilizar el ID de consentimiento en el JWT para obtener más detalles sobre el consentimiento invocando la API Back channel. GET /{BankId}/back-channel-auth/v1/{ConsentId} Mostrar la pantalla de consentimiento con la información del pago, lista de cuentas del pagador y saldos para que el usuario seleccione. Utilizar el ID de consentimiento en el JWT para actualizar la cuenta seleccionada invocando la API Back channel. PUT /{BankId}/back-channel-auth/v1/{ConsentId} Redirigir de vuelta a la URL de redirección de Redeban con un JWT firmado por el banco con la información de éxito o fallo.

Claims JWT del Estándar de Banca Abierta

Claim nombre	Descripción	Valor(s) de Ejemplo
iss	Issuer - La URL que identifica el servidor de autorización (AS) o el proveedor de OpenID (OP) que emitió el JWT. Este suele ser el endpoint o ruta para la autenticación/autorización segura del banco.	`https://auth.yourbank.com`
sub	Subject — El identificador único del usuario final (PSU - Usuario de Servicios de Pago) al que se refiere el JWT. Puede ser un ID de usuario interno, un número de cliente o una dirección de correo electrónico. Nunca utilice datos confidenciales como números de cuenta.	ex-john
aud	Audience — Identifica al destinatario previsto del JWT, normalmente el ID de cliente del proveedor externo (TPP) o la aplicación.	`http://www.sca.bank1/`
exp	Expiration Time — Cuándo expira el token, expresado en segundos desde la época UNIX (UTC). Por seguridad, los tokens deberían tener una vida útil corta.	1734037200 (2025-10-13 08:00:00 UTC) / 1734040800 (2025-10-13 09:00:00 UTC)
nbf	Not Before — El token no es válido antes de este tiempo (segundos de época). Opcional, pero recomendado por razones de seguridad.	1734033600 (2025-10-13 07:00:00 UTC) / 1734037150
iat	Issued At- Cuándo se emitió el token (segundos de época). Se utiliza para comprobar la frescura y repetir los ataques.	1734033650 (2025-10-13 07:00:50 UTC)/1734037200
jti	JWT ID- Un valor de cadena único y opaco para cada token. Suele ser un UUID o una referencia de transacción. Previene ataques de repetición al permitir el seguimiento de los tokens.	"jwt-1234abcd-20250811T0700"/"c5e1a8a1-4c93-4c8e-8bc0-3a1d55cb1a8b"